1# Key Attestation Overview and Algorithm Specifications 2 3<!--Kit: Universal Keystore Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @wutiantian-gitee--> 6<!--Designer: @HighLowWorld--> 7<!--Tester: @wxy1234564846--> 8<!--Adviser: @zengyawen--> 9 10HUKS provides attestation for the public keys of asymmetric key pairs. 11 12HUKS issues a certificate for the public key of an asymmetric key pair stored in HUKS using the public key infrastructure (PKI) certificate chain technology. The certificate can prove the validity of the public key. The service can use the root CA certificate provided by the system to verify the key certificates issued by HUKS level by level to ensure that the public key and private key in the certificates are from a trusted hardware device and stored in HUKS. 13 14> **NOTE** 15> 1. Key attestation is not supported if the caller is a system service with APL of **normal**. In this case, **processName** and **APL** are left empty. 16> 2. Key attestation is not supported in Emulator scenarios. 17> 3. <!--RP1-->Mini-system devices<!--RP1End--> do not support key attestation. 18> 4. Key attestation is available to both the keys generated and imported. The service side needs to check whether the key source meets the expectation based on the key source field in the service certificate on the server. 19 20The **Extensions** field is in the ASN.1 DER encoding format. The data structure is defined as follows: 21``` 22KeyAttestation ::= SEQUENCE { 23 version AttestationVersion DEFAULT v1, 24 claim1 AttestationClaim, 25 claim2 AttestationClaim, 26 claim3 AttestationClaim, 27 ... ... 28} 29AttestationVersion ::= INTEGER { v1(0) } 30AttestationClaim ::= SEQUENCE { 31 securityLevel SecurityLevel, 32 type AttestationType, 33 value AttestationValue 34} 35SecurityLevel ::= INTEGER 36AttestationType ::= OBJECT IDENTIFIER 37AttestationValue ::= ANY -- DEFINED BY AttestationType 38ApplicationIDType ::= SEQUENCE { 39 type OBJECT IDENTIFIER, 40 value OCT_STR 41} 42``` 43 44**AttestationClaim** types and values: 45| type (OID)| Data Type of value| securityLevel | Claim Description| 46| -------- | -------- | -------- | -------- | 47| 1.3.6.1.4.1.2011.2.376.2.1.4 | OCT_STR | Reserved.| Challenge passed in by the application.| 48| 1.3.6.1.4.1.2011.2.376.2.1.3 | ApplicationIDType | Reserved.| Application ID.| 49| 1.3.6.1.4.1.2011.2.376.2.1.5 | OCT_STR | Reserved.| Key source, which is generated or imported.| 50|<!--DelRow--> 1.3.6.1.4.1.2011.2.376.2.1.2 | OCT_STR | Reserved.| Key alias.| 51| 1.3.6.1.4.1.2011.2.376.2.2.4.8 | UTF8_STR | Reserved.| Product model, supported since API version 20.| 52 53<!--Del--> 54> **NOTE** 55> OEMs can decide whether to implement these fields based on their needs. 56<!--DelEnd--> 57 58ApplicationIDType types and values: 59| type (OID)| value| 60| -------- | -------- | 61| 1.3.6.1.4.1.2011.2.376.2.1.3.1 | Example: {appId:"xxx", bundleName:"xxx", appIdentifier:"xxx", appMode:"xxx"},<br>where **appIdentifier** and **appMode** are supported since API version 20.| 62| 1.3.6.1.4.1.2011.2.376.2.1.3.2 | Example: {processName:"xxx", APL:"system_basic \| system_core"} <br>APL is [Ability Privilege Level](../../security/AccessToken/app-permission-mgmt-overview.md#basic-concepts-in-the-permission-mechanism).| 63 64The key attestation process is as follows: 65 661. The service transfers the key alias and properties to HUKS. 67 682. HUKS issues an X.509 certificate chain, which consists of the root CA certificate, device CA certificate, device certificate, and key certificate in sequence, for the application. 69 703. The certificate chain is sent to a trusted server. The server parses the certificate chain and verifies the certificate chain validity and whether a single certificate is revoked. 71 72<!--RP2--> 73Currently, the system provides two key attestation modes. 74- Anonymous key attestation: This type of attestation will not disclose the device information, and the caller does not require any permission. Anonymous key attestation is available to all applications. To protect user device information, third-party applications can use anonymous attestation only. 75- Non-anonymous key attestation: The device information of the caller can be viewed, and the caller must have the [ohos.permission.ATTEST_KEY](../AccessToken/permissions-for-system-apps.md#ohospermissionattest_key) permission. 76<!--RP2End--> 77 78Currently, emulators <!--Del-->and developer boards <!--DelEnd-->support anonymous certificates. The certificate used in the debugging environment is not a real device certificate. You need to note this in cloud scenarios and avoid misuse. 79 80## Supported Algorithms 81 82The following table lists the supported key attestation specifications. 83<!--Del--> 84The key management service specifications include mandatory specifications and optional specifications. Mandatory specifications are algorithm specifications that must be supported. Optional specifications can be used based on actual situation. Before using the optional specifications, refer to the documents provided by the vendor to ensure that the specifications are supported. 85 86**You are advised to use mandatory specifications in your development for compatibility purposes.** 87<!--DelEnd--> 88 89<!--Del--> 90**Anonymous key attestation** 91<!--DelEnd--> 92 93| Algorithm| Description| API Version| <!--DelCol4-->Mandatory| 94| -------- | -------- | -------- | -------- | 95| RSA | The padding mode can be PSS or PKCS1_V1_5.| 11+ | Yes| 96| ECC | - | 11+ | Yes| 97| X25519 | - | 16+ | Yes| 98| ED25519 | - | 16+ | Yes| 99| SM2 | - | 11+ | Yes| 100 101<!--Del--> 102**Non-anonymous key attestation** 103 104| Algorithm| Description| API Version| Mandatory| 105| -------- | -------- | -------- | -------- | 106| RSA | The padding mode can be PSS or PKCS1_V1_5.| 8+ | Yes| 107| ECC | - | 8+ | Yes| 108| X25519 | - | 8+ | Yes| 109| ED25519 | - | 16+ | Yes| 110| SM2 | - | 8+ | Yes| 111<!--DelEnd--> 112