add key attestations

openid-4-verifiable-credential-issuance-1_0.md

@@ -2166,6 +2166,88 @@ The following is a non-normative example of a Credential Response containing a C
 
 <{{examples/credential_response_sd_jwt_vc.txt}}
 
+# Key Attestations {#keyattestation}
+
+A key attestation is an interoperable, verifiable statement that provides evidence of the authenticity and security properties of a key and its storage component. Keys can be stored in various key storage components, which differ in their ability to protect the private key against extraction and duplication, as well as in the methods used for End-User authentication to unlock key operations. These key storage components may be software-based or hardware-based, and can be located on the same device as the Wallet, on external security tokens, or on remote services that enable cryptographic key operations.
+
+A Wallet MAY provide key attestations to inform the Credential Issuer about the properties of the provided cryptographic public keys. Credential Issuers may want to evaluate these key attestations to determine whether the keys meet their own security requirements, which can result from the trust framework in use, regulatory requirements, laws, or internal design decisions. An Issuer SHOULD communicate this requirement to evaluate key attestations through its metadata or using some sort of out-of-band mechanism.
+
+Since the key attestations may have large audience as many Credential Issuers that not necessarly uses the same trust framework or internal design decisions, it is required to use a common approach to facilitate interoperability. Therefore, key attestations SHOULD use a common format,allowing Issuers to develop consistent evaluation processes, reducing complexity and potential errors. Common formats makes easy for Issuers to demonstrate compliance with regulatory requirements across different jurisdictions, they also facilitate the development of shared best practices and security benchmarks.
+
+todo: explain usage of this within proof type or DPoP Proof
+
+## Key Attestation in JWT format
+
+The JWT is signed by the Wallet Provider or the Wallet's key storage component itself and contains the following elements:
+
+* in the JOSE header,
+  * `alg`: REQUIRED. A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry [@IANA.JOSE.ALGS]. It MUST NOT be `none` or an identifier for a symmetric algorithm (MAC).
+  * `typ`: REQUIRED. MUST be `keyattestation+jwt`, which explicitly types the key proof JWT as recommended in Section 3.11 of [@!RFC8725].
+
+The key attestation may use `x5c`, `kid`, `trust_chain` or other mechanisms to convey the public key and the associated trust mechanism to sign the key attestation.
+
+* in the JWT body,
+  * `iat`: REQUIRED (number). Integer for the time at which the key attestation was issued using the syntax defined in [@!RFC7519].
+  * `exp`: REQUIRED (number). Integer for the time at which the key attestation expires using the syntax defined in [@!RFC7519].
+  * `attested_keys` : REQUIRED. Array of attested keys using the syntax of JWK as defined in [@!RFC7517].
+  * `key_type` : OPTIONAL. String that asserts the key storage component and its security mechanism of attested keys from `keys`. This specification defines initial values in (#keyattestation-keytypes).
+  * `user_authentication` : OPTIONAL. String that asserts the security mechanism the key storage component uses to authenticate the End-User to authorize access to the private key from `keys`. This specification defines initial values in (#keyattestation-auth).
+  * `apr` : OPTIONAL. String that asserts the resistance to a certain attack potential as described
+  * `nonce`: OPTIONAL. String that represents a nonce provided by the Issuer to proof that a key attestation was freshly generated.
+  * `status`: OPTIONAL. JSON Object representing the supported revocation check mechanisms, such as the one defined in [status list]
+
+The Credential Issuer MUST validate that the JWT used as a proof is actually signed by a key identified in the JOSE Header.
+
+This is an example of a Key Attestation:
+
+```json
+{
+  "typ": "keyattestation+jwt",
+  "alg": "ES256",
+  "kid": "1"
+}
+.
+{
+  "iss": "<identifier of the issuer of this key attestation>",
+  "iat": 1516247022,
+  "exp": 1541493724,
+  "key_type": "strong_box",
+  "user_authentication": "system_pin",
+  "apr" : "https://trust-list.eu/apr/high",
+  "attested_keys": [
+    {
+      "kty": "EC",
+      "crv": "P-256",
+      "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc",
+      "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ"
+    }
+  ]
+}
+```
+
+## Key Types {#keyattestation-keytypes}
+
+This specification defines the following values for `key_type`:
+
+* `software`: It MUST be used when the Wallet uses software-based key management.
+* `tee`: It SHOULD be used when the Wallet uses the Trusted Execution Environment for key management.
+* `secure_enclave`: It SHOULD be used when the Wallet uses the Secure Enclave for key management.
+* `strong_box`: It SHOULD be used when the Wallet uses the Strongbox for key management.
+* `secure_element`: It SHOULD be used when the Wallet uses a Secure Element for key management.
+* `hsm`: It SHOULD be used when the Wallet uses Hardware Security Module (HSM).
+
+## User Authentication Types {#keyattestation-auth}
+
+This specification defines the following values for `user_authentication`:
+
+* `system_biometry`: It MUST be used when the key usage is authorized by the operating system using a biometric factor, such as the one provided by mobile devices.
+* `system_pin`: It MUST be used when the key usage is authorized by the mobile operating system using personal identification number (PIN).
+* `internal_biometry`: It MUST be used when the key usage is authorized by the Wallet using a biometric factor.
+* `internal_pin`: It MUST be used when the key usage is authorized by the Wallet using PIN.
+* `secure_element_pin` It MUST be used when the key usage is authorized by the secure element managing the key itself using PIN.
+
+todo: text about Level of assurance and attack potential resistance
+
 # IANA Considerations
 
 ## Sub-Namespace Registration