8. Appendix B: recipients.fbs¶

namespace ee.cyber.cdoc2.fbs.recipients;

//server recipient type
union KeyDetailsUnion {
    EccKeyDetails, RsaKeyDetails
}

// Elliptic curve type enum for ECCPublicKey recipient
enum EllipticCurve:byte {
    UNKNOWN,
    secp384r1
}

// KDF algorithm identifier enum
enum KDFAlgorithmIdentifier:byte {
    UNKNOWN,
    PBKDF2WithHmacSHA256
}

table RsaKeyDetails {
    //RSA pub key in DER - RFC8017 RSA Public Key Syntax (A.1.1) https://www.rfc-editor.org/rfc/rfc8017#page-54
    recipient_public_key:   [ubyte] (required);
}

table EccKeyDetails {
    // Elliptic curve type enum
    curve:                 EllipticCurve = UNKNOWN;

    //EC pub key in TLS 1.3 format https://datatracker.ietf.org/doc/html/rfc8446#section-4.2.8.2
    //for secp384r1 curve: 0x04 + X 48 coord bytes + Y coord 48 bytes)
    recipient_public_key:  [ubyte] (required);
}

// ECC public key recipient
table ECCPublicKeyCapsule {
    curve:                 EllipticCurve = UNKNOWN;
    recipient_public_key:  [ubyte] (required);
    sender_public_key:     [ubyte] (required);
}

table RSAPublicKeyCapsule {
    recipient_public_key:  [ubyte] (required);
    encrypted_kek:         [ubyte] (required);
}

// recipient where ephemeral key material is download from server (server scenarios)
table KeyServerCapsule {
    // recipient id - key type specific. For public key cryptography this is usually recipient public key
    recipient_key_details: KeyDetailsUnion;
    keyserver_id:          string (required);
    transaction_id:        string (required);
}

// symmetric long term crypto
table SymmetricKeyCapsule {
    salt:                 [ubyte] (required);
}

// KDF algorithm identifier enum
enum KDFAlgorithmIdentifier:byte {
    UNKNOWN,
    PBKDF2WithHmacSHA256
}

// password derived key
table PBKDF2Capsule {
    // HKDF salt to derive KEK
    salt:                     [ubyte] (required);
    password_salt:            [ubyte] (required);
    kdf_algorithm_identifier: KDFAlgorithmIdentifier = UNKNOWN;
    kdf_iterations:           int32;
}

// KeyShare url. Response KeyShare is defined https://github.com/open-eid/cdoc2-openapi/blob/55a0b02adae0d8c61f2589a47555a93e4cf31971/cdoc2-key-shares-openapi.yaml#L144
table KeyShare {
    //full url of key share, ex https://cdoc2-keyserver.dev.riaint.ee:8443/key-shares/SS0123456789ABCDEF
    // is defined as server_base_url
    // https://cdoc2-keyserver.dev.riaint.ee:8443/
    server_base_url: string (required);

    // and share_id SS0123456789ABCDEF
    share_id:  string (required);
}

enum KeyShareRecipientType:byte {
    UNKNOWN,
    SID_MID
}

enum SharesScheme:byte {
    UNKNOWN,
    N_OF_N
}

// SymmetricKey that is split between cdoc2-shares-servers
table KeySharesCapsule {
    shares:               [KeyShare] (required);
    salt:                 [ubyte] (required);
    recipient_type:       KeyShareRecipientType = UNKNOWN;
    shares_scheme:        SharesScheme = UNKNOWN;

    // recipient identifier, prefixed with type ("etsi/"). Part after "etsi/" must match subject/serialnumber in recipient certificate
    // provided with auth token https://github.com/open-eid/cdoc2-openapi/blob/55a0b02adae0d8c61f2589a47555a93e4cf31971/cdoc2-key-shares-openapi.yaml#L54
    // example recipient_id "etsi/PNOEE-48010010101" where string after "etsi/" is ETSI Semantics Identifier defined in "ETSI EN 319 412-1"
    // In future might support other identifiers in format "private/VENDOR/identifier"
    recipient_id:         string (required);
}