Re: Low-Level API naming (was: Strawman proposal for the low-level API)

On Wed, Jul 18, 2012 at 12:58 PM, Wan-Teh Chang <wtc@google.com> wrote:

> Re: the clone() method
>
> For the NSS C crypto library, I remember crypto operation contexts are
> only cloned in the SSL/TLS implementation, and only hash contexts are
> cloned (for the handshake message hashes).
>
> The clone methods are backed by the underlying PKCS #11
> C_GetOperationState and C_SetOperationState methods.
>
> Wan-Teh
>

I think there are two types of .clone() we're talking about.

Karen's example, as interpreted by Vijay, demonstrates using .clone() to
clone initialization parameters, but not necessarily state. That is,
.clone() always happened after an error.

In terms of state machine, it would be:
UN-INIT -> [INIT, ERROR] -> [PROCESSING, ERROR] -> [COMPLETE, ERROR]

.clone() transitions an object from [COMPLETE, ERROR] back to UN-INIT,
which allows it to be re-initialized, with an entirely new context (eg: no
saved state)

The example you provide allows .clone() to happen at both the INIT and the
PROCESSING states (eg: when there is some cryptographic state in the
buffer). Perhaps the best example of this is HMAC. For performance reasons,
it's "nice" to clone to the internal ipad/opad state, after they have been
initialized with the key data, rather than having to keep the actual keying
material around.

I'm not sure whether this second form is something that is reliably
implemented across various cryptographic libraries. If the underlying
implementation did not, and clonability at the PROCESSING stage was
included, than either an UA implementation would likely to have to track
all of the data up to that point, so that it can properly .clone(), or
.clone() would have to sometimes fail. If .clone() is not implemented, or
may conditionally fail, then it's likely that either no application will
use .clone(), or they will try to synthesize their own .clone(), keeping
track of all state at the application layer.

.clone() from the [COMPLETE, ERROR] stage (eg: as I understand
Karen-via-Vijay to be proposing) is something "fine", in as much as it's
just caching initialization parameters.

Functionally, I suspect the following pseudo-code examples are equivalent:
  // Example 1
  var b = a.clone();

  // Example 2
  // If the CryptoOperation exposes properties about its creation
  var b = a.operation(a.algorithm, a.key);

  // Example 3
  var someCurriedFactoryFunction =
window.crypto.encrypt.apply([a.algorithm, a.key]);
  var a = someCurriedFactoryFunction();
  var b = someCurriedFactoryFunction();


If the above is true, then an implementation could implement
CrypoOperation.clone() simply by having the creation function (eg:
window.crypto.encrypt) curry itself into the CryptoOperation's prototype.