Clean up keymint ProtectedData documentation am: 1d389acec8 (19eff513) · Commits · e / os / android_hardware_interfaces

security/keymint/aidl/android/hardware/security/keymint/ProtectedData.aidl

+97 −54

Original line number	Diff line number	Diff line
		@@ -18,13 +18,20 @@ package android.hardware.security.keymint;

		/**
		* ProtectedData contains the encrypted BCC and the ephemeral MAC key used to
		* authenticate the keysToSign (see keysToSignMac output argument).
		* authenticate the keysToSign (see keysToSignMac output argument of
		* IRemotelyProvisionedComponent.generateCertificateRequest).
		* @hide
		*/
		@VintfStability
		parcelable ProtectedData {
		/**
		* ProtectedData is a COSE_Encrypt structure, specified by the following CDDL
		* ProtectedData is a COSE_Encrypt structure, encrypted with an AES key that is agreed upon
		* using Elliptic-curve Diffie-Hellman. The contents of the structure are specified by the
		* following CDDL [RFC8610].
		*
		* Notes:
		* - None of the CBOR in ProtectedData uses CBOR tags. If an implementation includes
		* tags, parsers may reject the data.
		*
		* ProtectedData = [ // COSE_Encrypt
		* protected: bstr .cbor {
		@@ -34,13 +41,18 @@ parcelable ProtectedData {
		* 5 : bstr .size 12 // IV
		* },
		* ciphertext: bstr, // AES-GCM-256(K, .cbor ProtectedDataPayload)
		* // Where the encryption key 'K' is derived as follows:
		* // ikm = ECDH(EEK_pub, Ephemeral_priv)
		* // salt = null
		* // info = .cbor Context (see below)
		* // K = HKDF-SHA-256(ikm, salt, info)
		* recipients : [
		* [ // COSE_Recipient
		* protected : bstr .cbor {
		* 1 : -25 // Algorithm : ECDH-ES + HKDF-256
		* },
		* unprotected : {
		* -1 : PubKeyX25519 / PubKeyEcdhP256 // Of the sender
		* -1 : PubKeyX25519 / PubKeyEcdhP256 // Ephemeral_pub
		* 4 : bstr, // KID : EEK ID
		* },
		* ciphertext : nil
		@@ -48,14 +60,14 @@ parcelable ProtectedData {
		* ]
		* ]
		*
		* K = HKDF-256(ECDH(EEK_pub, Ephemeral_priv), Context)
		*
		* Context = [ // COSE_KDF_Context
		* // The COSE_KDF_Context that is used to derive the ProtectedData encryption key with
		* // HKDF. See details on use in ProtectedData comments above.
		* Context = [
		* AlgorithmID : 3 // AES-GCM 256
		* PartyUInfo : [
		* identity : bstr "client"
		* nonce : bstr .size 0,
		* other : bstr // Ephemeral pubkey
		* other : bstr // Ephemeral_pub
		* ],
		* PartyVInfo : [
		* identity : bstr "server",
		@@ -68,40 +80,54 @@ parcelable ProtectedData {
		* ]
		* ]
		*
		* // The data that is encrypted and included in ProtectedData ciphertext (see above).
		* ProtectedDataPayload [
		* SignedMac,
		* Bcc,
		* ? AdditionalDKSignatures,
		* ]
		*
		* // AdditionalDKSignatures allows the platform to provide additional certifications
		* // for the DK_pub. For example, this could be provided by the hardware vendor, who
		* // certifies all of their devices. The SignerName is a free-form string describing
		* // who generated the signature.
		* AdditionalDKSignatures = {
		* + SignerName => DKCertChain
		* }
		*
		* // SignerName is a string identifier that indicates both the signing authority as
		* // well as the format of the DKCertChain
		* SignerName = tstr
		*
		* DKCertChain = [
		* 2* Certificate // Root -> Leaf. Root is the vendor
		* // self-signed cert, leaf contains DK_pub
		* 2* Certificate // Root -> ... -> Leaf. "Root" is the vendor self-signed
		* // cert, "Leaf" contains DK_pub. There may also be
		* // intermediate certificates between Root and Leaf.
		* ]
		*
		* Certificate = COSE_Sign1 of a public key
		* // Certificates may be either:
		* // 1. COSE_Sign1, with payload containing PubKeyEd25519 or PubKeyECDSA256
		* // 2. a bstr containing a DER-encoded X.509 certificate (RSA, NIST P-curve, or edDSA)
		* Certificate = COSE_Sign1 / bstr
		*
		* // The SignedMac, which authenticates the MAC key that is used to authenticate the
		* // keysToSign.
		* SignedMac = [ // COSE_Sign1
		* bstr .cbor { // Protected params
		* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm
		* },
		* {}, // Unprotected params
		* bstr .size 32, // MAC key
		* bstr .size 32, // Payload: MAC key
		* bstr // PureEd25519(KM_priv, bstr .cbor SignedMac_structure) /
		* // ECDSA(KM_priv, bstr .cbor SignedMac_structure)
		* ]
		*
		* SignedMac_structure = [
		* SignedMac_structure = [ // COSE Sig_structure
		* "Signature1",
		* bstr .cbor { // Protected params
		* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm
		* },
		* bstr .cbor SignedMacAad
		* bstr .cbor SignedMacAad,
		* bstr .size 32 // MAC key
		* ]
		*
		@@ -114,31 +140,48 @@ parcelable ProtectedData {
		* // the signature.
		* ]
		*
		* VerifiedDeviceInfo = DeviceInfo // See DeviceInfo.aidl
		*
		* // The BCC is the boot certificate chain, containing measurements about the device
		* // boot chain. The BCC generally follows the Open Profile for DICE specification at
		* // https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md.
		* //
		* // The first entry in the Bcc is the DK_pub, encoded as a COSE_key. All entries after
		* // the first describe a link in the boot chain (e.g. bootloaders: BL1, BL2, ... BLN).
		* // Note that there is no BccEntry for DK_pub, only a "bare" COSE_key.
		* Bcc = [
		* PubKeyEd25519 / PubKeyECDSA256, // DK_pub
		* + BccEntry, // Root -> leaf (KM_pub)
		* ]
		*
		* BccPayload = { // CWT
		* // This is the signed payload for each entry in the Bcc. Note that the "Configuration
		* // Input Values" described by the Open Profile are not used here. Instead, the Bcc
		* // defines its own configuration values for the Configuration Descriptor field. See
		* // the Open Profile for DICE for more details on the fields. All hashes are SHA256.
		* BccPayload = { // CWT [RFC8392]
		* 1 : tstr, // Issuer
		* 2 : tstr, // Subject
		* // See the Open Profile for DICE for details on these fields.
		* ? -4670545 : bstr, // Code Hash
		* -4670552 : bstr .cbor PubKeyEd25519 /
		* bstr .cbor PubKeyECDSA256, // Subject Public Key
		* -4670553 : bstr // Key Usage
		*
		* // NOTE: All of the following fields may be omitted for a "Degenerate BCC", as
		* // described by IRemotelyProvisionedComponent.aidl.
		* -4670545 : bstr, // Code Hash
		* ? -4670546 : bstr, // Code Descriptor
		* ? -4670547 : bstr, // Configuration Hash
		* ? -4670548 : bstr .cbor { // Configuration Descriptor
		* -4670548 : bstr .cbor { // Configuration Descriptor
		* ? -70002 : tstr, // Component name
		* ? -70003 : int, // Firmware version
		* ? -70004 : null, // Resettable
		* },
		* ? -4670549 : bstr, // Authority Hash
		* -4670549 : bstr, // Authority Hash
		* ? -4670550 : bstr, // Authority Descriptor
		* ? -4670551 : bstr, // Mode
		* -4670552 : bstr .cbor PubKeyEd25519 /
		* bstr .cbor PubKeyECDSA256 // Subject Public Key
		* -4670553 : bstr // Key Usage
		* -4670551 : bstr, // Mode
		* }
		*
		* // Each entry in the Bcc is a BccPayload signed by the key from the previous entry
		* // in the Bcc array.
		* BccEntry = [ // COSE_Sign1 (untagged)
		* protected : bstr .cbor {
		* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm
		@@ -159,8 +202,8 @@ parcelable ProtectedData {
		* payload: bstr .cbor BccPayload
		* ]
		*
		* VerifiedDeviceInfo = DeviceInfo // See DeviceInfo.aidl
		*
		* // The following section defines some types that are reused throughout the above
		* // data structures.
		* PubKeyX25519 = { // COSE_Key
		* 1 : 1, // Key type : Octet Key Pair
		* -1 : 4, // Curve : X25519