(In reply to Kelsey Cairns from comment #0)
> It isn't clear whether key objects are intended to persist after a
> session is closed. If they do, how are they re-identified? Will the
> browser guarantee they always get the same handle? If not, are you
> supposed to re-key each time?

Also fairly certain this is an INVALID bug.

That is, each question seems to stem from a lack of understanding about the language or operating environment. I'm curious if there is a concrete proposal to reduce this confusion, but at the same time, the spec should be able to reasonably assume familiarity with it's normative dependencies.

1) Do Key objects persist after a session is closed?

No, ECMAScript makes it quite clear the lifetime of objects, and HTML/DOM make it quite clear how that applies to the top level browsing context.

Changing the top level browsing context by definition invalidates all objects.

2) If they do, how are they re-identified?

The specification provides a definition for Structured Clone Algorithm of DOM. Structured Clone can be used with a variety of other APIs, such as Message Ports / Message Channels / postMessage (from the DOM spec), or with storage APIs such as IndexedDB.

The identification of Key objects is left to callers, who can apply their own semantics (IDB storage key, associated meta-data in a postMessage)

3) Will the browser guarantee they always get the same handle?

The spec is clear that they will refer to the same cryptographic key material - https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#key-interface-clone - and present the same observable object.

However, Structured Clone is quite clear that it does not require the same equivalence in a language sense.

So I guess the larger problem is not so much confusion at the level of how behaves. In my mind it's branching into two new directions which should possibly be different bugs. 

I still need to think about the how-keys-behave direction. But the lack-of-clarity direction is more a matter of discrepancy between the actual API spec and what the use cases and structure would lead one to think. 


If you want an example of what I'm thinking, consider the word "import" with respect to keys. There are many possible interpretations here, but it seems to me that a very natural one suggests transferring a key from the outside world into some local storage for many keys. The semantics WebCrypto has chosen is different in that the container into which a key is imported is more of a wrapper -- something that holds a single key in a way to make it useable with the rest of the API. Both interpretations make sense; The chosen language (import/export) doesn't imply that we're *not* talking about a general keystore.

Okay. So the phrase "agnostic to underlying key storage mechanism" is near the top of the spec somewhere. Really, anyone who reads that shouldn't be confused by the import/export language.

Now consider all the use cases. The first use case mentioned dives into a description that very implies that users can authenticate in later sessions. The phrase "proving that the user has access to some secret keying material" implies persistent keys. The use cases continue, suggesting (and even relying on) persist storage but glossing over the details.

So all in all, here's my conclusion: yes, the API specifically states how keys work. But the surrounding language and discussion aren't consistent with what is specified by the API and what is out of scope. Given that it's an English language document and its readers are humans, I think this might be one of the things causing so much general confusion.

(In reply to Kelsey Cairns from comment #2)
> So I guess the larger problem is not so much confusion at the level of how
> behaves. In my mind it's branching into two new directions which should
> possibly be different bugs. 
> 
> I still need to think about the how-keys-behave direction. But the
> lack-of-clarity direction is more a matter of discrepancy between the actual
> API spec and what the use cases and structure would lead one to think. 
> 
> 
> If you want an example of what I'm thinking, consider the word "import" with
> respect to keys. There are many possible interpretations here, but it seems
> to me that a very natural one suggests transferring a key from the outside
> world into some local storage for many keys. The semantics WebCrypto has
> chosen is different in that the container into which a key is imported is
> more of a wrapper -- something that holds a single key in a way to make it
> useable with the rest of the API. Both interpretations make sense; The
> chosen language (import/export) doesn't imply that we're *not* talking about
> a general keystore.
> 
> Okay. So the phrase "agnostic to underlying key storage mechanism" is near
> the top of the spec somewhere. Really, anyone who reads that shouldn't be
> confused by the import/export language.
> 
> Now consider all the use cases. The first use case mentioned dives into a
> description that very implies that users can authenticate in later sessions.
> The phrase "proving that the user has access to some secret keying material"
> implies persistent keys. The use cases continue, suggesting (and even
> relying on) persist storage but glossing over the details.
> 
> So all in all, here's my conclusion: yes, the API specifically states how
> keys work. But the surrounding language and discussion aren't consistent
> with what is specified by the API and what is out of scope. Given that it's
> an English language document and its readers are humans, I think this might
> be one of the things causing so much general confusion.

So, trying to unpack this a bit...

As a result of the TAG review, I'm adding a section that introduces and explains some of the terminology used in the document - cryptographic providers, key handles, etc. It sounds like an addition to this (non-normative, informative) section, a basic description of how key storage works with the API and how it conceptually maps to these APIs might mitigate the concern.

That is, explicitly (re-stating) that storage of keys is not provided by this API, but it can be implemented using a variety of ways. One way is using IndexedDB, which is a per-origin storage mechanism that accepts objects that support Structured Clone. Implementations can store, query, and delete Key objects from IndexedDB, and these Key objects will only be accessible to their origin by virtue of IndexedDB's security restrictions.

They can also share keys with other origins, but it must be done explicitly (at the script's request), using techniques like postMessage, which allow you to send any Structured Clone-able object to another origin, provided you have a handle to that origin (eg: a cross-origin iframe)

Cool. I'm really looking forward to seeing that.

(In reply to Ryan Sleevi from comment #3)
> (In reply to Kelsey Cairns from comment #2)
> > So I guess the larger problem is not so much confusion at the level of how
> > behaves. In my mind it's branching into two new directions which should
> > possibly be different bugs. 
> > 
> > I still need to think about the how-keys-behave direction. But the
> > lack-of-clarity direction is more a matter of discrepancy between the actual

> So, trying to unpack this a bit...
> 
> As a result of the TAG review, I'm adding a section that introduces and
> explains some of the terminology used in the document - cryptographic
> providers, key handles, etc. It sounds like an addition to this
> (non-normative, informative) section, a basic description of how key storage
> works with the API and how it conceptually maps to these APIs might mitigate
> the concern.
> 
> That is, explicitly (re-stating) that storage of keys is not provided by
> this API, but it can be implemented using a variety of ways. One way is
> using IndexedDB, which is a per-origin storage mechanism that accepts
> objects that support Structured Clone. Implementations can store, query, and
> delete Key objects from IndexedDB, and these Key objects will only be
> accessible to their origin by virtue of IndexedDB's security restrictions.
> 
> They can also share keys with other origins, but it must be done explicitly
> (at the script's request), using techniques like postMessage, which allow
> you to send any Structured Clone-able object to another origin, provided you
> have a handle to that origin (eg: a cross-origin iframe)

I think adding an informative section on how key storage works would be very helpful to users of the API.  I am really looking forward to this.

I also would be happy to see text added to help in the understanding of how the working group intended key storage to work.  This will be helpful in future discussions related to alternate key storage proposals.

https://dvcs.w3.org/hg/webcrypto-api/rev/7a79e816e31b