Bug 17682 - Clear Key: Document how keys and key IDs are associated
Clear Key: Document how keys and key IDs are associated
Status: RESOLVED FIXED
Product: HTML WG
Classification: Unclassified
Component: Encrypted Media Extensions
unspecified
All All
: P2 normal
: FPWD
Assigned To: David Dorwin
HTML WG Bugzilla archive list
:
Depends on: 17673
Blocks: 24419
  Show dependency treegraph
 
Reported: 2012-07-03 21:08 UTC by David Dorwin
Modified: 2014-05-28 23:23 UTC (History)
8 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description David Dorwin 2012-07-03 21:08:07 UTC
Most Key Systems will define a "license" format, which defines the data in the |key| parameter to addKey(). For Clear Key, the original plan was that |key| would be exactly a decryption key.

Assuming an addKey() call can be associated with a specific initData value [1], passing the exact decryption key as |key| works well for containers that use a standard (i.e. non-opaque) format for initData and provide exactly one key ID in each initData value. However, this will not work for containers that use opaque formats, don't include a key ID in the actual initData, or can specify multiple key IDs in an initData.

ISO BMFF using CENC is one of those [2]. In the CENC case, initData may be an opaque blob and represent multiple keys. Thus, |key| could not be associated with a specific key ID. (There is a related question in [2] related to providing a PSSH that Clear Key can use.)

We either need to overcome the above issue or figure out an alternative way to associate keys and key IDs for Clear Key. Ideally, Clear Key would work in the same way as other key systems while remaining easy to use and understand. It would also be nice if the Clear Key "license" format was consistent across containers, though that is probably less important.

[1] In v0.1 of the proposal, the keyId can be specified in the |initData| parameter. In the session object-based design, the |initData| parameter is removed from addKey() (see also https://www.w3.org/Bugs/Public/show_bug.cgi?id=16549), but there is still a direct correlation between addKey() and a single initData value.
[2] https://www.w3.org/Bugs/Public/show_bug.cgi?id=17673
Comment 1 David Dorwin 2012-07-10 17:17:29 UTC
A related issue is the following text from 6.1:
  message = a container-specific unique key identifier extracted from the initData parameter

The intent of this text was that the UA would do the work of converting a potentially opaque initData to a key ID that a simple application could use to look up a key. The problem is that this assumes that the initData:
 1) Contains a key ID
 2) Is associated with exactly one key

ISO BMFF using CENC is not compatible with these assumptions, so we'll need to come up with a solution for ISO and/or that works across containers.
Comment 2 Adrian Bateman [MSFT] 2012-08-14 14:58:37 UTC
Need to resolve bug 17673 before working on this.
Comment 3 David Dorwin 2012-08-17 06:04:49 UTC
With the removal of the initData parameter from addKey() in the object-oriented API (bug 16613), this issue now applies to all container formats.
Comment 4 johnsim 2012-10-02 14:56:28 UTC
How clear key works regarding initdata should be the same as with other CDMs. For example, since for ISOBMFF the InitData is proposed to be a pssh box or a concatenation of pssh boxes, for Clear Key when the media format is ISOBMFF, a Clear Key 'pssh' box should be defined. This box would contain a defined (W3C?) System ID which corresponds to the Clear Key CDM, and the Key ID. From this point forward processing would be strictly identical with other CDMs.
Comment 5 johnsim 2012-10-16 20:59:54 UTC
TWO PROBLEMS
1.Inconsistency - In the EME Examples section, the Clear Key examples are inconsistent with the desire that DRM CDMs and the Clear Key CDM function equivalently. These examples show addKey() being passed a Key, not a structured object (e.g. License) as is passed to the DRM CDMs. 

2. Multiple Keys per request - There is a desire that multiple keys can be returned to the Clear Key CDM with a single keymessage - a collection of (Key ID, Key) pairs. That scenario is not presently handled.

PROPOSED SOLUTION
What is needed is a standard Clear Key container that at a minimum would permit multiple (Key ID, Key) pairs to be passed to the Clear Key CDM.

The container would be defined using [RFC6030], the “Portable Symmetric Key Container (PSKC)” specification. [RFC6030] defines a container for transporting symmetric keys and key-related metadata.

The EME specification would only references [RFC6030] as the basis of the Clear Key Container. The precise container used would be media format specific, but all would be based on [RFC6030]. EME would include an example for ISOBMFF and WebM - perhaps identical - but permit the use of different Clear Key containers. 

EME Changes
There would be a single KeyContainer entity which includes one or more KeyPackage entities. The KeyPackage entities would contain only a Key ID and a Key. The algorithm setting for the Key Package would be media format specific. 

1. Change to EME section 6.1, Clear Key, last paragraph
________________________________________
The key parameter of addKey() should be a Key Container with one or more Key Packages, as defined in [RFC6030]. 

The precise Key Container used may be media format specific. The default Clear Key container is shown below, where:
- “Id” uniquely identifies the clear key container being used
- “Key Id” is a Key Identifier
- “Algorithm” is the unique identifier for the PSKC algorithm profile to be used by the CDM for this media content
- “PlainValue” is the symmetric key, encoded according to section 4.2 of [RFC6030]

--------------
   <?xml version="1.0" encoding="UTF-8"?>
   <KeyContainer Version="1.0"
       Id="clearKeyExample1"
       xmlns="urn:ietf:params:xml:ns:keyprov:pskc">
       <KeyPackage>
           <Key Id="KeyId1"
               Algorithm={container specific value}>
               <Data>                            
                   <Secret>
                       <PlainValue>K34VFiiu0qar9xWICc9PPA==
                       </PlainValue>
                   </Secret>
               </Data>
           </Key>
       </KeyPackage>
   </KeyContainer>
--------------

2. Change to Examples, Example 8.1, to pass Clear Key Container instead of Key to addKey().
Comment 6 Mark Watson 2012-10-30 09:21:12 UTC
We could also look at JSON Web Key (JWK), or rather an extension thereof.

JWK (http://self-issued.info/docs/draft-ietf-jose-json-web-key.html) doesn't yet support symmetric keys, but they might be needed for WebCrypto.

If it did, then a JWK "KeySet" would look something like this:

{ "keys" : [
{ "alg" : "A256", "kid" : "f762trp28fg=", "key" : "iu287grf8d7p2g7=" },
{ "alg" : "A256", "kid" : "67ef0gd8pvfd0=", "key" : "U832Pivp8=" },
{ "alg" : "A256", "kid" : "86fp8yvi;8fo8=", "key" : "ubp99{((=" } ] }

JWK can be extended by registration of new values with IANA.
Comment 7 Adrian Bateman [MSFT] 2012-12-18 06:03:49 UTC
At TPAC (and then at the 12/11 telcon) we discussed:

* If we want to build a JSON syntax based on an extension to draft-ietf-jose-json-web-key then we should document this in an appendix to the spec and work with IETF to see if they will incorporate these extensions into one of their specs. If we are successful then we could remove the appendix and replace it with a normative reference as late as the CR->PR transition.

* By incorporating the details in an appendix to the EME spec we keep hold of our own destiny rather than making the spec dependent on another group.

* The next action is to propose actual spec text for a concrete JSON-based proposal.
Comment 8 Mark Watson 2013-01-08 01:53:27 UTC
There is now a draft format for symmetric keys in JWK in http://tools.ietf.org/html/draft-jones-jose-json-private-and-symmetric-key-00
Comment 9 johnsim 2013-01-14 21:46:14 UTC
1. Change to EME section 6.1, Clear Key, last paragraph.
________________________________________

The key parameter of addKey() should be a JSON Web Key (JWK) representation of the symmetric key to be used for decryption, as defined in the IETF Internet-draft JSON Private Key specification (http://tools.ietf.org/html/draft-jones-jose-json-private-and-symmetric-key). 

When the JWK ‘key type’ ("kty") member value is 'octet sequence' ("oct"), the 'key value' ("k") member will be a base64 encoding of the octet sequencing containing the symmetric key value. 

For example, the following contains a single symmetric key represented as a JWK, designated as being for use with the AES Key Wrap algorithm (line breaks for readability, only).

{ "keys": 
   {"kty":"oct",
    "alg":"AES128KW",
    "kid":""67ef0gd8pvfd0=",
    "k":" GawgguFyGrWKav7AX4VKUg"
   }
}

________________________________________
2. Change to Examples, Example 8.1, to pass this Clear Key JWK instead of Key to addKey().
Comment 10 Adrian Bateman [MSFT] 2013-01-15 00:51:24 UTC
Fixed in changeset https://dvcs.w3.org/hg/html-media/rev/db164d726dcd

Note that since update() takes a Uint8Array, I proposed that this be ASCII encoded as defined in HTML5.
Comment 11 David Dorwin 2013-09-04 01:40:43 UTC
Re-opening to get and track clarification on a few items.

1) The JSON is actually a JWK Set. I suggest the following changes:
 * "The key parameter of update() should be a JSON Web Key (JWK) _Set containing_ representation..."
 * Maybe something like "For each JWK, when the 'key type'..."
 * "For example, the following _is a JWK Set containing_ a single..."

2) We should require at least one key in the set. (Otherwise an error should be reported.)

3) "kid" is not mentioned in the text.
 * It should mentioned in the text and be required.
 * We should require that it be base64-encoded. (The examples in the IETF document are not, and the format is not specified.) For our purposes, they will always be binary values and should be encoded.

4) Is base64 padding required for all base64 values?
 * I think we should require it because it's easy to add when encoding and simplifies the UAs.

5) Encoding: "The JSON string is encoded into the Uint8Array parameter using ASCII-compatible character encoding."
 * How does the UA know which encoding is used?
 * Is an "ASCII-compatible character encoding" really what we want? It seems that the definition [1] allows non-ASCII strings, which would require additional complexity to handle even though there isn't a practical application.
 * Should we just say "ASCII"?
 * Do we need to separately specify that the JSON should use UTF-8 encoding (vs. other supported encodings)?

6) The linked IETF document has expired. What is the implication of this?

7) We may want to link to the actual JWK [Set] spec [2] as well.
 
[1] http://www.w3.org/TR/html5/infrastructure.html#ascii-compatible-character-encoding
[2] http://tools.ietf.org/html/draft-jones-json-web-key
Comment 12 David Dorwin 2013-10-01 16:05:27 UTC
In the October 1 telecon, we agreed that I would implement the proposed changes to at least get us closer to a final solution.

re: #5
There are 12 instances of "ASCII-compatible character encoding" in http://www.w3.org/TR/html5/single-page.html. All seem related to input or metadata, which need such flexibility.

re: #6
Part of the normal spec process is to verify all normative references, so we'll need to revisit this and do not need a specific issue.
In the near term, paulc will contact the author or the two IETF documents to find out the status (i.e. whether we're relying on something that nobody is using).
http://tools.ietf.org/html/draft-jones-json-web-key
http://http://tools.ietf.org/html/draft-jones-jose-json-private-and-symmetric-key
Comment 13 Paul Cotton 2013-10-01 19:15:28 UTC
(In reply to David Dorwin from comment #11)
> 6) The linked IETF document has expired. What is the implication of this?
...
> [2] http://tools.ietf.org/html/draft-jones-json-web-key

The content from [2] is now published at:

1. http://tools.ietf.org/html/draft-ietf-jose-json-web-key-16,  and 
2. http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-16 

These two drafts are close to working group last call.  

We should use one or both of these references instead.

/paulc
Comment 14 David Dorwin 2013-10-02 20:24:01 UTC
(In reply to Paul Cotton from comment #13)
> (In reply to David Dorwin from comment #11)
> > 6) The linked IETF document has expired. What is the implication of this?
> ...
> > [2] http://tools.ietf.org/html/draft-jones-json-web-key
> 
> The content from [2] is now published at:
> 
> 1. http://tools.ietf.org/html/draft-ietf-jose-json-web-key-16,  and 
> 2. http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-16 
> 
> These two drafts are close to working group last call.  
> 
> We should use one or both of these references instead.
> 
> /paulc

Thanks, Paul. We were using the URLs without the "-##" suffix; these appeared to redirect to the latest version, but the redirects appear to not have been updated. Can you verify this is the intent and ask them to update redirects if so? That way EME will always point at the latest version.
Comment 15 David Dorwin 2013-10-02 20:33:38 UTC
The first draft defines "Base64url Encoding" [1], and the second draft says the "k" value " is represented as the base64url encoding of the octet sequence..."

We should use "base64url encoding" in EME for consistency. This includes for my proposed additional restrictions on "kid" since it will be easiser for everyone if "k" and "kid" follow similar rules.

The definition also addresses the character set issue, making the "ASCII-compatible character encoding" discussion obsolete.

The "Base64url Encoding" also says that "all trailing '=' characters [are] omitted." This means that for "k" and any other fields we specify "base64url encoding", padding is disallowed (rather than required, as I had proposed). While UAs will need to add padding, at least there is no need to support both cases.

[1] http://tools.ietf.org/html/draft-ietf-jose-json-web-key-16#section-2
[2] http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-16#section-5.4.1
Comment 16 Paul Cotton 2013-10-02 22:12:13 UTC
(In reply to David Dorwin from comment #14)
> (In reply to Paul Cotton from comment #13)
> > (In reply to David Dorwin from comment #11)
> > > 6) The linked IETF document has expired. What is the implication of this?
> > ...
> > > [2] http://tools.ietf.org/html/draft-jones-json-web-key
> > 
> > The content from [2] is now published at:
> > 
> > 1. http://tools.ietf.org/html/draft-ietf-jose-json-web-key-16,  and 
> > 2. http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-16 
> > 
> > These two drafts are close to working group last call.  
> > 
> > We should use one or both of these references instead.
> > 
> > /paulc
> 
> Thanks, Paul. We were using the URLs without the "-##" suffix; these
> appeared to redirect to the latest version, but the redirects appear to not
> have been updated. Can you verify this is the intent and ask them to update
> redirects if so? That way EME will always point at the latest version.

Please note that the old URL of http://tools.ietf.org/html/draft-jones-json-web-key contains "draft-jones" and the URLs I proposed instead contain "draft-ietf".  

Both 
http://tools.ietf.org/html/draft-ietf-jose-json-web-key and http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms 
definitely redirect to the current versions.
Comment 17 David Dorwin 2013-10-02 22:57:44 UTC
Thanks - I had not noticed that. I'll use the new "ietf" redirecting URLs.
Comment 18 Adrian Bateman [MSFT] 2013-10-15 14:39:51 UTC
Updated the link in changeset https://dvcs.w3.org/hg/html-media/rev/91feb120903c
Comment 19 David Dorwin 2013-12-07 01:26:41 UTC
(In reply to David Dorwin from comment #1)
> A related issue is the following text from 6.1:
>   message = a container-specific unique key identifier extracted from the
> initData parameter
> 
> The intent of this text was that the UA would do the work of converting a
> potentially opaque initData to a key ID that a simple application could use
> to look up a key. The problem is that this assumes that the initData:
>  1) Contains a key ID
>  2) Is associated with exactly one key
> 
> ISO BMFF using CENC is not compatible with these assumptions, so we'll need
> to come up with a solution for ISO and/or that works across containers.

I filed bug 24027 to track a solution for using Clear Key with ISO BMFF and/or CENC.

This bug is now entirely focused on the format of the license passed to update().
Comment 20 David Dorwin 2013-12-09 21:04:29 UTC
(In reply to David Dorwin from comment #15)
> The "Base64url Encoding" also says that "all trailing '=' characters [are]
> omitted." This means that for "k" and any other fields we specify "base64url
> encoding", padding is disallowed (rather than required, as I had proposed).
> While UAs will need to add padding, at least there is no need to support
> both cases.

The JavaScript btoa() method adds padding, so any application using btoa() for "Base64url Encoding" fields in JWK will need to strip the padding. It seems unfortunate that a JS function and JSON Web Key don't have the same expectations.

Unless the JWK spec changes, though, we'll inherit this problem.
Comment 21 Mark Watson 2013-12-09 21:16:55 UTC
Don't the JS btoa() and atob() functions use base64, not base64url ?

In that case you have to map to/from base64url anyway and hamdling the padding in that mapping should not be a huge deal.
Comment 22 David Dorwin 2013-12-09 21:30:54 UTC
Yes, nevermind the padding issue. We should call out these differences clearly in a non-normative note.
Comment 23 Adrian Bateman [MSFT] 2013-12-12 22:35:45 UTC
Assigned to David.
Comment 24 David Dorwin 2014-04-29 21:46:55 UTC
(In reply to David Dorwin from comment #11)
> 5) Encoding: "The JSON string is encoded into the Uint8Array parameter using
> ASCII-compatible character encoding."
>  * How does the UA know which encoding is used?
>  * Is an "ASCII-compatible character encoding" really what we want? It seems
> that the definition [1] allows non-ASCII strings, which would require
> additional complexity to handle even though there isn't a practical
> application.
>  * Should we just say "ASCII"?
>  * Do we need to separately specify that the JSON should use UTF-8 encoding
> (vs. other supported encodings)?

We should use the Encoding API: http://www.w3.org/TR/encoding/
Comment 25 David Dorwin 2014-05-28 23:23:23 UTC
I implemented all of the changes discussed starting in comment #11 in https://dvcs.w3.org/hg/html-media/rev/676bb18f8118. This changeset also includes other definitions of key system-specific behaviors for Clear Key.