KeyWrap Notes July
The page contains notes on the differences between original key wrap/unwrap proposal and the June 25th working draft.
The original proposal was based on implementing direct support for JWE-encapsulated JWK objects within the UA. The wrap and unwrap methods would produce and consume (respectively) JWE objects.
The June working draft provides slightly more primitive wrap/unwrap operations that enable support for specific formats (including JWE-encapsulated JWK) to be built in Javascript. Specifically
- wrap is defined to be the combination of the existing export and encrypt operations, where the intermediate value (the output of the export and the input of the encrypt) is not exposed outside the UA.
- unwrap is defined to be the combination of the existing decrypt and import operations, where the intermediate value (the output of the decrypt and the input of the import) is not exposed outside the UA.
A JWE-encapsulated JWK object consists of a Content Encryption Key, which is encrypted using the wrapping key, and a payload encrypted with the Content Encryption Key. Construction of a JWE-encapsulated JWK (equivalent to the originally propose wrap operation) can be accomplished with the new operations in three steps:
- use generateKey to generate a Content Encryption Key
- use wrap to export and encrypt the key to be wrapped, using the Content Encryption Key for the encryption
- use wrap to export and encrypt the Content Encryption Key, using the wrapping key for the encryption
- combined the results into a JWE structure
This process can be reversed, to perform an unwrapping operation as originally defined (for extractable keys) as follows:
- extract the encrypted Content Encryption Key and encrypted payload from the JWE structure
- use unwrap to decrypt and import the Content Encryption Key, using the wrapping key for the decryption
- use unwrap to decrypt and import the payload key, using the Content Encryption Key for the decryption
Support for non-extractable keys
The original proposal, as required by the use-case, supported unwrapping of non-extractable keys. A non-extractable key, by definition, should not be exposed to the Javascript. A key could marked as non-extractable in the wrapped JWK structure using a new JWK attribute proposed to be defined in the WebCrypto specification. In this case, the originally proposed unwrap operation would respect this attribute over the extractable value specified in the unwrap call.
In order to support this functionality with the new API, it must be possible for the originator of a wrapped key to ensure that the Key object eventually created for the wrapped key has the extractable attribute set to false. In the two-step process defined above, this implies that the Key object for the Content Encryption Key must:
- have extractable set to false
- have usages that do not include "decrypt"
If either of the above were not true, the Content Encryption Key could be used to decrypt the JWE payload, returning the decrypted payload to the Javascript and thereby violating its non-extractability.
Given the existing JWE format, this could only be achieved by attaching special semantics to the wrapping key, or default behaviours to the unwrap operation for the case of key formats that do not carry attributes. This is because there is no information in the encoded JWE Content Encryption Key itself to indicate that it should be non-extractable with usage "unwrap".
However, an alternative, proposed, JWE format enables JWK to be used as a format for the Content Encryption Key. In this case, attributes could be defined as originally proposed to communicate the extractable and usages values for the Content Encryption Key.
Furthermore, the new wrap/unwrap methods may often be used alone, without the need for a more complex key wrapping format. This would be appropriate cases where either to key to be wrapped or the wrapping key is a symmetric key. The wrapped key is just the encrypted JWK of the key to be wrapped. A more complex format is only required for the case of wrapping an asymmetric key with another asymmetric key as in this case the payload may be too large to encrypt directly with the wrapping key and an intermediate Content Encryption Key is required.
Proposal
The proposal is to include the necessary attribute definitions in the WebCrypto specification along with requirements in the import/export procedures to respect/include these attributes (respectively).
JSON Web Key
Add some material on JSON Web Key to Section 14:
Implementations SHOULD support additional JSON Web Key use values of:
-
wrap(key wrapping)
Implementations SHOULD support additional JSON Web Key members of:
-
extractable(boolean indicating extractability)
TODO: Register the above values with IANA
Mapping between JOSE Algorithm names, specifically the JWK kty and optional alg fields and WebCrypto algorithms names is defined in the table below:
kty
|
alg
|
WebCrypto algorithm |
|---|---|---|
RSA
|
RSA1_5
|
RSAES-PKCS1-v1_5 |
RSA
|
RS256, RS384, RS512
|
RSASSA-PKCS1-v1_5 |
RSA
|
? | RSA-PSS |
RSA
|
RSA-OAEP
|
RSA-OAEP |
EC
|
ES256, ES384, ES512
|
ECDSA |
oct
|
A128CBC, A256CBC
|
AES-CBC |
oct
|
A128CTR, A256CTR
|
AES-CTR |
oct
|
A128KW, A256KW
|
AES-KeyWrap |
oct
|
A128GCM, A256GCM
|
AES-GCM |
oct
|
? | HMAC |
Note: the mapping above assumed that alg values defined for JWE and JWS can also be used in JWK.
The following table specifies mapping from WebCrypto KeyUsage values and the JWK use member:
KeyUsage
|
use
|
|---|---|
encrypt
|
enc
|
decrypt
|
enc
|
sign
|
sig
|
verify
|
sig
|
wrap
|
wrap
|
unwrap
|
wrap
|
Note: JWK does not provide the capability to distinguish between an operation and its inverse (or between sign and verify). When mapping from JWK uses to WebCrypto KeyUsages, both WebCrypto KeyUsages associated with the JOSE use are allowed.
Import
The importKey procedures (Section 14.2.8 - not yet drafted) should require that extractable and use attributes found in an imported JWK must be mapped according to the above tables to the extractable and usages attributes of the Key. These take precedance over any values specified in the function call.
Export
The exportKey procedures (Section 14.2.9 - not yet drafted) should require that the extractable and use attributes of an exported JWK be populated according to the above tables.
