summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorShawn Willden2018-05-24 09:34:51 -0500
committerShawn Willden2018-05-30 17:20:48 -0500
commit5b60a1b72e261cd1799a487dd960ddf0cc2e06e5 (patch)
tree168a6aa3882641c8423950298b83361c774dde53
parent5ed6bca9162bb44e8b3d00019221ba2f37fe1bba (diff)
downloadplatform-hardware-interfaces-5b60a1b72e261cd1799a487dd960ddf0cc2e06e5.tar.gz
platform-hardware-interfaces-5b60a1b72e261cd1799a487dd960ddf0cc2e06e5.tar.xz
platform-hardware-interfaces-5b60a1b72e261cd1799a487dd960ddf0cc2e06e5.zip
Minor corrections to the Keymaster4 documentation.
Gramatical and punctuation corrections; addition of missing userSecureId to AuthorizationList schema and removal of extraneous rollbackResistant from same; correction of OS_PATCHLEVEL source property; and addition of missing TAG_UNLOCKED_DEVICE_REQUIRED documentation. Bug: 69550260 Test: N/A Change-Id: I04092b7df3af69201ba1467cddc09f6f44e861a8
-rw-r--r--current.txt4
-rw-r--r--keymaster/4.0/IKeymasterDevice.hal21
-rw-r--r--keymaster/4.0/types.hal49
3 files changed, 41 insertions, 33 deletions
diff --git a/current.txt b/current.txt
index 15b096b3..3f3bd534 100644
--- a/current.txt
+++ b/current.txt
@@ -347,8 +347,8 @@ dd83be076b6b3f10ed62ab34d8c8b95f2415961fb785200eb842e7bfb2b0ee92 android.hardwar
347675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth 347675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth
348434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback 348434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback
349c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types 349c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types
3505c8e06f9945276d1a9e8f7e37cf0ea8894bdb906fa80809cb06c36abb39afc4f android.hardware.keymaster@4.0::IKeymasterDevice 350201f9723353fdbd40bf3705537fb7e015e4c399879425e68688fe0f43606ea4d android.hardware.keymaster@4.0::IKeymasterDevice
3516695eb5744108035506004dd136068b1aaebe809cf9d4a69c2fe33b73058bb85 android.hardware.keymaster@4.0::types 3511b7d2090c0a28b229d37c4b96160796b1f0d703950ac6ccc163fccd280830503 android.hardware.keymaster@4.0::types
3526d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor 3526d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor
353b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager 353b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager
3544a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 android.hardware.media.bufferpool@1.0::IConnection 3544a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 android.hardware.media.bufferpool@1.0::IConnection
diff --git a/keymaster/4.0/IKeymasterDevice.hal b/keymaster/4.0/IKeymasterDevice.hal
index 6c09ef33..74d13d8b 100644
--- a/keymaster/4.0/IKeymasterDevice.hal
+++ b/keymaster/4.0/IKeymasterDevice.hal
@@ -217,8 +217,8 @@ interface IKeymasterDevice {
217 * must be a TEE Keymaster as well. The HMAC key used to MAC and verify authentication tokens 217 * must be a TEE Keymaster as well. The HMAC key used to MAC and verify authentication tokens
218 * (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be 218 * (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be
219 * shared between TEE and StrongBox so they can each validate tokens produced by the other. 219 * shared between TEE and StrongBox so they can each validate tokens produced by the other.
220 * This method is the first step in the process for for agreeing on a shared key. It is called 220 * This method is the first step in the process for agreeing on a shared key. It is called by
221 * by Android during startup. The system calls it on each of the HAL instances and collects the 221 * Android during startup. The system calls it on each of the HAL instances and collects the
222 * results in preparation for the second step. 222 * results in preparation for the second step.
223 * 223 *
224 * @return error ErrorCode::OK on success, ErrorCode::UNIMPLEMENTED if HMAC agreement is not 224 * @return error ErrorCode::OK on success, ErrorCode::UNIMPLEMENTED if HMAC agreement is not
@@ -324,7 +324,7 @@ interface IKeymasterDevice {
324 * sharingCheck = HMAC(H, "Keymaster HMAC Verification") 324 * sharingCheck = HMAC(H, "Keymaster HMAC Verification")
325 * 325 *
326 * The string is UTF-8 encoded, 27 bytes in length. If the returned values of all 326 * The string is UTF-8 encoded, 27 bytes in length. If the returned values of all
327 * IKeymasterDevice instances don't match, Keystore will assume that HMAC agreement 327 * IKeymasterDevice instances don't match, clients must assume that HMAC agreement
328 * failed. 328 * failed.
329 */ 329 */
330 computeSharedHmac(vec<HmacSharingParameters> params) 330 computeSharedHmac(vec<HmacSharingParameters> params)
@@ -718,16 +718,19 @@ interface IKeymasterDevice {
718 * AuthorizationList ::= SEQUENCE { 718 * AuthorizationList ::= SEQUENCE {
719 * purpose [1] EXPLICIT SET OF INTEGER OPTIONAL, 719 * purpose [1] EXPLICIT SET OF INTEGER OPTIONAL,
720 * algorithm [2] EXPLICIT INTEGER OPTIONAL, 720 * algorithm [2] EXPLICIT INTEGER OPTIONAL,
721 * keySize [3] EXPLICIT INTEGER OPTIONAL. 721 * keySize [3] EXPLICIT INTEGER OPTIONAL,
722 * blockMode [4] EXPLICIT SET OF INTEGER OPTIONAL, 722 * blockMode [4] EXPLICIT SET OF INTEGER OPTIONAL,
723 * digest [5] EXPLICIT SET OF INTEGER OPTIONAL, 723 * digest [5] EXPLICIT SET OF INTEGER OPTIONAL,
724 * padding [6] EXPLICIT SET OF INTEGER OPTIONAL, 724 * padding [6] EXPLICIT SET OF INTEGER OPTIONAL,
725 * callerNonce [7] EXPLICIT NULL OPTIONAL,
726 * minMacLength [8] EXPLICIT INTEGER OPTIONAL,
725 * ecCurve [10] EXPLICIT INTEGER OPTIONAL, 727 * ecCurve [10] EXPLICIT INTEGER OPTIONAL,
726 * rsaPublicExponent [200] EXPLICIT INTEGER OPTIONAL, 728 * rsaPublicExponent [200] EXPLICIT INTEGER OPTIONAL,
727 * rollbackResistance [303] EXPLICIT NULL OPTIONAL, 729 * rollbackResistance [303] EXPLICIT NULL OPTIONAL,
728 * activeDateTime [400] EXPLICIT INTEGER OPTIONAL 730 * activeDateTime [400] EXPLICIT INTEGER OPTIONAL,
729 * originationExpireDateTime [401] EXPLICIT INTEGER OPTIONAL 731 * originationExpireDateTime [401] EXPLICIT INTEGER OPTIONAL,
730 * usageExpireDateTime [402] EXPLICIT INTEGER OPTIONAL 732 * usageExpireDateTime [402] EXPLICIT INTEGER OPTIONAL,
733 * userSecureId [502] EXPLICIT INTEGER OPTIONAL,
731 * noAuthRequired [503] EXPLICIT NULL OPTIONAL, 734 * noAuthRequired [503] EXPLICIT NULL OPTIONAL,
732 * userAuthType [504] EXPLICIT INTEGER OPTIONAL, 735 * userAuthType [504] EXPLICIT INTEGER OPTIONAL,
733 * authTimeout [505] EXPLICIT INTEGER OPTIONAL, 736 * authTimeout [505] EXPLICIT INTEGER OPTIONAL,
@@ -735,15 +738,11 @@ interface IKeymasterDevice {
735 * trustedUserPresenceReq [507] EXPLICIT NULL OPTIONAL, 738 * trustedUserPresenceReq [507] EXPLICIT NULL OPTIONAL,
736 * trustedConfirmationReq [508] EXPLICIT NULL OPTIONAL, 739 * trustedConfirmationReq [508] EXPLICIT NULL OPTIONAL,
737 * unlockedDeviceReq [509] EXPLICIT NULL OPTIONAL, 740 * unlockedDeviceReq [509] EXPLICIT NULL OPTIONAL,
738 * allApplications [600] EXPLICIT NULL OPTIONAL,
739 * applicationId [601] EXPLICIT OCTET_STRING OPTIONAL,
740 * creationDateTime [701] EXPLICIT INTEGER OPTIONAL, 741 * creationDateTime [701] EXPLICIT INTEGER OPTIONAL,
741 * origin [702] EXPLICIT INTEGER OPTIONAL, 742 * origin [702] EXPLICIT INTEGER OPTIONAL,
742 * rollbackResistant [703] EXPLICIT NULL OPTIONAL,
743 * rootOfTrust [704] EXPLICIT RootOfTrust OPTIONAL, 743 * rootOfTrust [704] EXPLICIT RootOfTrust OPTIONAL,
744 * osVersion [705] EXPLICIT INTEGER OPTIONAL, 744 * osVersion [705] EXPLICIT INTEGER OPTIONAL,
745 * osPatchLevel [706] EXPLICIT INTEGER OPTIONAL, 745 * osPatchLevel [706] EXPLICIT INTEGER OPTIONAL,
746 * attestationChallenge [708] EXPLICIT OCTET_STRING OPTIONAL,
747 * attestationApplicationId [709] EXPLICIT OCTET_STRING OPTIONAL, 746 * attestationApplicationId [709] EXPLICIT OCTET_STRING OPTIONAL,
748 * attestationIdBrand [710] EXPLICIT OCTET_STRING OPTIONAL, 747 * attestationIdBrand [710] EXPLICIT OCTET_STRING OPTIONAL,
749 * attestationIdDevice [711] EXPLICIT OCTET_STRING OPTIONAL, 748 * attestationIdDevice [711] EXPLICIT OCTET_STRING OPTIONAL,
diff --git a/keymaster/4.0/types.hal b/keymaster/4.0/types.hal
index 85f181ac..94dfec55 100644
--- a/keymaster/4.0/types.hal
+++ b/keymaster/4.0/types.hal
@@ -460,6 +460,8 @@ enum Tag : uint32_t {
460 * called on one key with TRUSTED_USER_PRESENCE_REQUIRED, and another begin() comes in for that 460 * called on one key with TRUSTED_USER_PRESENCE_REQUIRED, and another begin() comes in for that
461 * key or another with TRUSTED_USER_PRESENCE_REQUIRED, Keymaster must return 461 * key or another with TRUSTED_USER_PRESENCE_REQUIRED, Keymaster must return
462 * ErrorCode::CONCURRENT_PROOF_OF_PRESENCE_REQUESTED. 462 * ErrorCode::CONCURRENT_PROOF_OF_PRESENCE_REQUESTED.
463 *
464 * Must be hardware-enforced.
463 */ 465 */
464 TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507, 466 TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507,
465 467
@@ -470,11 +472,17 @@ enum Tag : uint32_t {
470 * 472 *
471 * If an attempt to use a key with this tag does not have a cryptographically valid 473 * If an attempt to use a key with this tag does not have a cryptographically valid
472 * CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not 474 * CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not
473 * match the data described in the token, keymaster must return NO_USER_CONFIRMATION. */ 475 * match the data described in the token, keymaster must return NO_USER_CONFIRMATION.
476 *
477 * Must be hardware-enforced.
478 */
474 TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508, 479 TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508,
475 480
476 /** 481 /**
482 * Tag::UNLOCKED_DEVICE_REQUIRED specifies that the key may only be used when the device is
483 * unlocked.
477 * 484 *
485 * Must be software-enforced.
478 */ 486 */
479 UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509, 487 UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509,
480 488
@@ -490,7 +498,7 @@ enum Tag : uint32_t {
490 * access to the tag content to decrypt the key without brute-forcing the tag content, which 498 * access to the tag content to decrypt the key without brute-forcing the tag content, which
491 * applications can prevent by specifying sufficiently high-entropy content. 499 * applications can prevent by specifying sufficiently high-entropy content.
492 * 500 *
493 * Must be hardware-enforced. 501 * Must never appear in KeyCharacteristics.
494 */ 502 */
495 APPLICATION_ID = TagType:BYTES | 601, 503 APPLICATION_ID = TagType:BYTES | 601,
496 504
@@ -511,7 +519,7 @@ enum Tag : uint32_t {
511 * access to the tag content to decrypt the key without brute-forcing the tag content, which 519 * access to the tag content to decrypt the key without brute-forcing the tag content, which
512 * applications can prevent by specifying sufficiently high-entropy content. 520 * applications can prevent by specifying sufficiently high-entropy content.
513 * 521 *
514 * Must be hardware-enforced. 522 * Must never appear in KeyCharacteristics.
515 */ 523 */
516 APPLICATION_DATA = TagType:BYTES | 700, 524 APPLICATION_DATA = TagType:BYTES | 700,
517 525
@@ -557,11 +565,12 @@ enum Tag : uint32_t {
557 * key generated on Android version 4.0.3, the value would be 040003. 565 * key generated on Android version 4.0.3, the value would be 040003.
558 * 566 *
559 * The IKeymasterDevice HAL must read the current OS version from the system property 567 * The IKeymasterDevice HAL must read the current OS version from the system property
560 * ro.build.id and deliver it to the secure environment when the HAL is first loaded (mechanism 568 * ro.build.version.release and deliver it to the secure environment when the HAL is first
561 * is implementation-defined). The secure environment must not accept another version until 569 * loaded (mechanism is implementation-defined). The secure environment must not accept another
562 * after the next boot. If the content of ro.build.id has additional version information after 570 * version until after the next boot. If the content of ro.build.version.release has additional
563 * the sub-minor version number, it must not be included in Tag::OS_VERSION. If the content is 571 * version information after the sub-minor version number, it must not be included in
564 * non-numeric, the secure environment must use 0 as the system version. 572 * Tag::OS_VERSION. If the content is non-numeric, the secure environment must use 0 as the
573 * system version.
565 * 574 *
566 * Must be hardware-enforced. 575 * Must be hardware-enforced.
567 */ 576 */
@@ -659,8 +668,8 @@ enum Tag : uint32_t {
659 668
660 /** 669 /**
661 * Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in 670 * Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in
662 * Android, to attestKey(). This field is set only when requesting attestation of the device's 671 * Android, to attestKey(). This field must be set only when requesting attestation of the
663 * identifiers. 672 * device's identifiers.
664 * 673 *
665 * If the device does not support ID attestation (or destroyAttestationIds() was previously 674 * If the device does not support ID attestation (or destroyAttestationIds() was previously
666 * called and the device can no longer attest its IDs), any key attestation request that 675 * called and the device can no longer attest its IDs), any key attestation request that
@@ -672,8 +681,8 @@ enum Tag : uint32_t {
672 681
673 /** 682 /**
674 * Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in 683 * Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in
675 * Android, to attestKey(). This field is set only when requesting attestation of the device's 684 * Android, to attestKey(). This field must be set only when requesting attestation of the
676 * identifiers. 685 * device's identifiers.
677 * 686 *
678 * If the device does not support ID attestation (or destroyAttestationIds() was previously 687 * If the device does not support ID attestation (or destroyAttestationIds() was previously
679 * called and the device can no longer attest its IDs), any key attestation request that 688 * called and the device can no longer attest its IDs), any key attestation request that
@@ -685,7 +694,7 @@ enum Tag : uint32_t {
685 694
686 /** 695 /**
687 * Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT 696 * Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT
688 * in Android, to attestKey(). This field is set only when requesting attestation of the 697 * in Android, to attestKey(). This field must be set only when requesting attestation of the
689 * device's identifiers. 698 * device's identifiers.
690 * 699 *
691 * If the device does not support ID attestation (or destroyAttestationIds() was previously 700 * If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -697,7 +706,7 @@ enum Tag : uint32_t {
697 ATTESTATION_ID_PRODUCT = TagType:BYTES | 712, 706 ATTESTATION_ID_PRODUCT = TagType:BYTES | 712,
698 707
699 /** 708 /**
700 * Tag::ATTESTATION_ID_SERIAL the device's serial number. This field is set only when 709 * Tag::ATTESTATION_ID_SERIAL the device's serial number. This field must be set only when
701 * requesting attestation of the device's identifiers. 710 * requesting attestation of the device's identifiers.
702 * 711 *
703 * If the device does not support ID attestation (or destroyAttestationIds() was previously 712 * If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -710,7 +719,7 @@ enum Tag : uint32_t {
710 719
711 /** 720 /**
712 * Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey(). 721 * Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey().
713 * This field is set only when requesting attestation of the device's identifiers. 722 * This field must be set only when requesting attestation of the device's identifiers.
714 * 723 *
715 * If the device does not support ID attestation (or destroyAttestationIds() was previously 724 * If the device does not support ID attestation (or destroyAttestationIds() was previously
716 * called and the device can no longer attest its IDs), any key attestation request that 725 * called and the device can no longer attest its IDs), any key attestation request that
@@ -723,7 +732,7 @@ enum Tag : uint32_t {
723 732
724 /** 733 /**
725 * Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey(). 734 * Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey().
726 * This field will only be set when requesting attestation of the device's identifiers. 735 * This field must be set only when requesting attestation of the device's identifiers.
727 * 736 *
728 * If the device does not support ID attestation (or destroyAttestationIds() was previously 737 * If the device does not support ID attestation (or destroyAttestationIds() was previously
729 * called and the device can no longer attest its IDs), any key attestation request that 738 * called and the device can no longer attest its IDs), any key attestation request that
@@ -736,7 +745,7 @@ enum Tag : uint32_t {
736 745
737 /** 746 /**
738 * Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by 747 * Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by
739 * Build.MANUFACTURER in Android, to attstKey(). This field is set only when requesting 748 * Build.MANUFACTURER in Android, to attstKey(). This field must be set only when requesting
740 * attestation of the device's identifiers. 749 * attestation of the device's identifiers.
741 * 750 *
742 * If the device does not support ID attestation (or destroyAttestationIds() was previously 751 * If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -749,8 +758,8 @@ enum Tag : uint32_t {
749 758
750 /** 759 /**
751 * Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in 760 * Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in
752 * Android, to attestKey(). This field is set only when requesting attestation of the device's 761 * Android, to attestKey(). This field must be set only when requesting attestation of the
753 * identifiers. 762 * device's identifiers.
754 * 763 *
755 * If the device does not support ID attestation (or destroyAttestationIds() was previously 764 * If the device does not support ID attestation (or destroyAttestationIds() was previously
756 * called and the device can no longer attest its IDs), any key attestation request that 765 * called and the device can no longer attest its IDs), any key attestation request that
@@ -815,7 +824,7 @@ enum Tag : uint32_t {
815 * Tag::NONCE is used to provide or return a nonce or Initialization Vector (IV) for AES-GCM, 824 * Tag::NONCE is used to provide or return a nonce or Initialization Vector (IV) for AES-GCM,
816 * AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption. This tag is provided to begin during 825 * AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption. This tag is provided to begin during
817 * encryption and decryption operations. It is only provided to begin if the key has 826 * encryption and decryption operations. It is only provided to begin if the key has
818 * Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV will be randomly generated by 827 * Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV must be randomly generated by
819 * Keymaster and returned from begin. 828 * Keymaster and returned from begin.
820 * 829 *
821 * The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend on the mode: 830 * The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend on the mode: