Re: Proposal for key wrap/unwrap (ISSUE-35)


We didn't have time to discuss this on the call. I have updated the proposal at:

There are a few things we need to discuss. Perhaps we can make progress on over email. From the Overview:

We propose that key wrapping in the WebCrypto API be supported through the use of JWE-protected JWK objects [5] [6]. We propose specific algorithms for wrapping with AES keys and with RSA-OAEP keys.
The following issues require discussion with the Working Group:

  1.  Should the JWE object be passed to/from the UA in serialized form, or as a Javascript object ? In serialized form, it could be either the Compact Serialization or the JSON serialization. In object form, it would be a Javascript object that would JSON-serialize into the "JSON Serialization" of JWE
  2.  For wrapping with RSA-OAEP keys, JWE works by RSA-OAEP encrypting a symmetric Content Master Key which is then used to encrypt/integrity protect the payload. Where should we specify the encryption/integrity protection algorithm (likely A128CBC+HS256 or A128GCM) ? Possibly there should be an additional member in the parameters object used with generateKey when generating an RSA-OAEP wrapping key.
  3.  If the above parameter is added to the "RSA-OAEP wrapping" key type, how should it be encoded into JWK when such keys are exported ? (including when they themselves are wrapped)
  4.  For wrapping with RSA-OAEP keys, JWE allows the public key to be included in the JWE header, to assist in identification of the private key needed to perform unwrapping (in the jwk member of the header). How should we specify during wrapping whether to include the public key ? (Note that if the answer to (1) is object form, then we could always include the public key and the script could just remove it before serialization if it wanted to).
  5.  The compatibility and mapping between WebCrypto algorithm names and JOSE algorithm names needs to be defined (as it does for import/export as well)
  6.  The mapping between the WebCrypto Key attribute "extractable" and a JWK equivalent needs to be defined
  7.  The compatibility and mapping between WebCrypro Key attribute 'usages' and the JWK equivalent needs to be defined


On Mar 1, 2013, at 5:02 PM, Vijay Bharadwaj wrote:

Sounds like a reasonable approach.

From: Mark Watson []
Sent: Friday, March 1, 2013 4:36 PM
To: Vijay Bharadwaj
Cc: Ryan Sleevi;<> Group
Subject: Re: Proposal for key wrap/unwrap (ISSUE-35)

On Mar 1, 2013, at 9:53 AM, Vijay Bharadwaj wrote:

I've been looking at key wrap formats lately. My observations based on having maintained crypto APIs:

1. More wrapping formats means more confusion for developers and pain for vendors.
2. Having wrapAlgorithm be a separate option on the import interface leads to various opportunities for inconsistency, since key wrapping formats include varying amounts of metadata. It is better to have import only deal with formats that are self-describing.

So given that we generally look to JOSE for high-level formats, I'd like to propose using JWE encapsulation for the wrap/unwrap formats, and removing the wrapAlgorithm parameter (and perhaps keyAlgorithm, though this needs more thought) from createKeyImporter in Mark's proposal.

A good starting point seems to be the JWE-protected JWK I-D at

Three simple example usages of this format to illustrate what I expect will be the most common use cases:

1. For RSA wrapping: Proceed as in Section 5 of the above I-D. JWE header has alg set to RSA-OAEP, and jwk.kty set to RSA. Most people would likely use enc of A128CBC+HS256 or A128GCM.

2. For wrapping a key using AES: JWE header has alg set to dir, and enc as in #1. In this case the jwk element in the header is not necessary. This allows the use of any authenticated encryption mode, not just AES key wrap. This seems to be in line with the current consensus of the cryptographic community - NIST has also Approved the use of authenticated encryption modes for key wrapping:

3. For working with existing legacy formats such as PKCS#8: JWE header has alg set to dir, and enc set to the appropriate value (e.g. "pkcs-8" in this case).

IIUC, alg=dir means only that the symmetric Content Master Key (used to derive the Content Encryption Key for encrypting the JWE-payload) is pre-shared, rather than being encrypted and communicated in the JWE.

The enc parameter stands for "encryption" not "encoding", so it's assumed in JWE that the content is always encoded (either with a CEK derived from a pre-shared CMK - alg=dir - or with a CEK derived from a CMK communicated in encrypted form in the JWE itself).

So - at least based on my reading - it doesn't make sense to use JWE to carry unencrypted PKCS#8 format data for key import/export, though I guess you could specify enc = null - i.e. no encryption applied.

The data type of the payload carried by the JWE can be specified in the "cty" (Content Type) member, which can be a MIME type, but usually you assume that the recipient is expecting a given data type. For our wrap/unwrap this would be implicitly a (serialization of) JWK, but I suppose we could use cty values to indicate that the payload is a PKCS#8 object etc. But this all feels rather messy.

So, for the moment, I am leaning towards keeping import/export separate - with the import/export format indicated in a KeyFormat parameter. I'll update the proposal so that wrap/unwrap always expect a JWE: we will need to decide whether this is the Compact Serialization (passed as an ArrayBufferView) or the JSON Serialization (passed as an ArrayBufferView) or the JSON Serialization unserialized into a Javascript object (which could be defined in IDL as an explicit Dictionary Type that mirrors JWK-in-JWE).

If, after we have fleshed out wrap/unwrap, we can see a clean way to make plain import/export sub-cases of that, then we can consolidate the operations into one pair of methods.

Ryan makes a good point that translation between the different JWE serializations in Javascript is made ugly by the use of base64url (instead of plain base64). Another example of a simple data transformation function that is currently missing from the Web APIs. It would be nice to have zip as well...


The nice thing about this mechanism is that it's web-developer friendly, and adds minimal overhead for the case of the legacy formats.

Thoughts? If people are okay with the general idea, I can work with Mark to revise the proposal as per our action item from the last meeting.

-----Original Message-----
From: Ryan Sleevi []
Sent: Monday, February 25, 2013 1:51 PM
To: Mark Watson
Cc:<> Group
Subject: Re: Proposal for key wrap/unwrap (ISSUE-35)

On Mon, Feb 25, 2013 at 1:18 PM, Mark Watson <<>> wrote:

From: Ryan Sleevi [<>]
Sent: Wednesday, January 16, 2013 7:13 PM
To: Mark Watson
Cc:<> Group
Subject: Re: Proposal for key wrap/unwrap (ISSUE-35)

Can you provide more design rationale for choosing RSA-KEM, rather
than the much more widely supported RSA-OAEP (eg: RFC 3560). I don't
know of a single well-tested, CORRECT implementation of RSA-KEM in the
popular cryptographic libraries and bindings.

MW> Ryan, we looked in detail at RSA-OAEP key transport and there is an issue in that it does not support payloads of arbitrary size - as required for JWK format payloads. At least not without using RSA keys of arbitrary size.

I'm not sure I follow. In the JOSE space, you perform an RSA-OAEP transport of the CMK, and the CMK protects the message. This is conceptually similar to RSA-KEM.

Certainly, given that OAEP, but not KEM, is supported by JOSE, it seems more in line with your needs?

Do you have any other suggestions for RSA-based key wrap/unwrap ?

We also looked in detail at RSA-KEM and it doesn't look so bad after all. In fact it's much easier to understand than the RSA-OAEP documentation.


Received on Monday, 4 March 2013 21:03:32 UTC