Merge "Clean up keymint ProtectedData documentation" into tm-dev (1e8fc75b) · Commits · e / os / android_hardware_interfaces

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

+95 −54

Original line number	Original line	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		* 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		* @hide
	*/		*/
	@VintfStability		@VintfStability
	parcelable ProtectedData {		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		* ProtectedData = [ // COSE_Encrypt
	* protected: bstr .cbor {		* protected: bstr .cbor {
	@@ -34,13 +41,18 @@ parcelable ProtectedData {
	* 5 : bstr .size 12 // IV		* 5 : bstr .size 12 // IV
	* },		* },
	* ciphertext: bstr, // AES-GCM-256(K, .cbor ProtectedDataPayload)		* 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 : [		* recipients : [
	* [ // COSE_Recipient		* [ // COSE_Recipient
	* protected : bstr .cbor {		* protected : bstr .cbor {
	* 1 : -25 // Algorithm : ECDH-ES + HKDF-256		* 1 : -25 // Algorithm : ECDH-ES + HKDF-256
	* },		* },
	* unprotected : {		* unprotected : {
	* -1 : PubKeyX25519 / PubKeyEcdhP256 // Of the sender		* -1 : PubKeyX25519 / PubKeyEcdhP256 // Ephemeral_pub
	* 4 : bstr, // KID : EEK ID		* 4 : bstr, // KID : EEK ID
	* },		* },
	* ciphertext : nil		* ciphertext : nil
	@@ -48,14 +60,14 @@ parcelable ProtectedData {
	* ]		* ]
	* ]		* ]
	*		*
	* K = HKDF-256(ECDH(EEK_pub, Ephemeral_priv), 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 = [ // COSE_KDF_Context		* Context = [
	* AlgorithmID : 3 // AES-GCM 256		* AlgorithmID : 3 // AES-GCM 256
	* PartyUInfo : [		* PartyUInfo : [
	* identity : bstr "client"		* identity : bstr "client"
	* nonce : bstr .size 0,		* nonce : bstr .size 0,
	* other : bstr // Ephemeral pubkey		* other : bstr // Ephemeral_pub
	* ],		* ],
	* PartyVInfo : [		* PartyVInfo : [
	* identity : bstr "server",		* identity : bstr "server",
	@@ -68,40 +80,52 @@ parcelable ProtectedData {
	* ]		* ]
	* ]		* ]
	*		*
			* // The data that is encrypted and included in ProtectedData ciphertext (see above).
	* ProtectedDataPayload [		* ProtectedDataPayload [
	* SignedMac,		* SignedMac,
	* Bcc,		* Bcc,
	* ? AdditionalDKSignatures,		* ? 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 = {		* AdditionalDKSignatures = {
	* + SignerName => DKCertChain		* + SignerName => DKCertChain
	* }		* }
	*		*
			* // SignerName is a string identifier that indicates both the signing authority as
			* // well as the format of the DKCertChain
	* SignerName = tstr		* SignerName = tstr
	*		*
	* DKCertChain = [		* DKCertChain = [
	* 2* Certificate // Root -> Leaf. Root is the vendor		* 2* X509Certificate // Root -> ... -> Leaf. "Root" is the vendor self-signed
	* // self-signed cert, leaf contains DK_pub		* // cert, "Leaf" contains DK_pub. There may also be
			* // intermediate certificates between Root and Leaf.
	* ]		* ]
	*		*
	* Certificate = COSE_Sign1 of a public key		* // A bstr containing a DER-encoded X.509 certificate (RSA, NIST P-curve, or edDSA)
			* X509Certificate = bstr
	*		*
			* // The SignedMac, which authenticates the MAC key that is used to authenticate the
			* // keysToSign.
	* SignedMac = [ // COSE_Sign1		* SignedMac = [ // COSE_Sign1
	* bstr .cbor { // Protected params		* bstr .cbor { // Protected params
	* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm		* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm
	* },		* },
	* {}, // Unprotected params		* {}, // Unprotected params
	* bstr .size 32, // MAC key		* bstr .size 32, // Payload: MAC key
	* bstr // PureEd25519(KM_priv, bstr .cbor SignedMac_structure) /		* bstr // PureEd25519(KM_priv, bstr .cbor SignedMac_structure) /
	* // ECDSA(KM_priv, bstr .cbor SignedMac_structure)		* // ECDSA(KM_priv, bstr .cbor SignedMac_structure)
	* ]		* ]
	*		*
	* SignedMac_structure = [		* SignedMac_structure = [ // COSE Sig_structure
	* "Signature1",		* "Signature1",
	* bstr .cbor { // Protected params		* bstr .cbor { // Protected params
	* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm		* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm
	* },		* },
	* bstr .cbor SignedMacAad		* bstr .cbor SignedMacAad,
	* bstr .size 32 // MAC key		* bstr .size 32 // MAC key
	* ]		* ]
	*		*
	@@ -114,31 +138,48 @@ parcelable ProtectedData {
	* // the signature.		* // 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 = [		* Bcc = [
	* PubKeyEd25519 / PubKeyECDSA256, // DK_pub		* PubKeyEd25519 / PubKeyECDSA256, // DK_pub
	* + BccEntry, // Root -> leaf (KM_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		* 1 : tstr, // Issuer
	* 2 : tstr, // Subject		* 2 : tstr, // Subject
	* // See the Open Profile for DICE for details on these fields.		* -4670552 : bstr .cbor PubKeyEd25519 /
	* ? -4670545 : bstr, // Code Hash		* 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		* ? -4670546 : bstr, // Code Descriptor
	* ? -4670547 : bstr, // Configuration Hash		* ? -4670547 : bstr, // Configuration Hash
	* ? -4670548 : bstr .cbor { // Configuration Descriptor		* -4670548 : bstr .cbor { // Configuration Descriptor
	* ? -70002 : tstr, // Component name		* ? -70002 : tstr, // Component name
	* ? -70003 : int, // Firmware version		* ? -70003 : int, // Firmware version
	* ? -70004 : null, // Resettable		* ? -70004 : null, // Resettable
	* },		* },
	* ? -4670549 : bstr, // Authority Hash		* -4670549 : bstr, // Authority Hash
	* ? -4670550 : bstr, // Authority Descriptor		* ? -4670550 : bstr, // Authority Descriptor
	* ? -4670551 : bstr, // Mode		* -4670551 : bstr, // Mode
	* -4670552 : bstr .cbor PubKeyEd25519 /
	* bstr .cbor PubKeyECDSA256 // Subject Public Key
	* -4670553 : bstr // Key Usage
	* }		* }
	*		*
			* // Each entry in the Bcc is a BccPayload signed by the key from the previous entry
			* // in the Bcc array.
	* BccEntry = [ // COSE_Sign1 (untagged)		* BccEntry = [ // COSE_Sign1 (untagged)
	* protected : bstr .cbor {		* protected : bstr .cbor {
	* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm		* 1 : AlgorithmEdDSA / AlgorithmES256, // Algorithm
	@@ -159,8 +200,8 @@ parcelable ProtectedData {
	* payload: bstr .cbor BccPayload		* 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		* PubKeyX25519 = { // COSE_Key
	* 1 : 1, // Key type : Octet Key Pair		* 1 : 1, // Key type : Octet Key Pair
	* -1 : 4, // Curve : X25519		* -1 : 4, // Curve : X25519