Web Crypto Streams

1. Introduction

This section is non-normative.

Introduction!

2. Use Cases

This section is non-normative.

Elaborate on use cases here.

3. Terminology

A chunk is a piece of data. In the case of EncryptionStream and VerificationStream, the output chunk type is Uint8Array. They accept any BufferSource type as input.

A stream represents an ordered sequence of chunks. The terms ReadableStream and WritableStream are defined in [WHATWG-STREAMS].

A encryption context is the internal state maintained by a encryption algorithm. The contents of a encryption context depend on the algorithm and implementation in use. From the point of view of this specification, it is an opaque object. A encryption context is initially in a start state such that it anticipates the first byte of input.

4. Interface EncryptionStream

Note: The EncryptionStream class complements SubtleCrypto.encrypt(). The constructor takes the same arguments as SubtleCrypto.encrypt() except for the data argument.

[Exposed=*]
interface EncryptionStream {
  constructor(AlgorithmIdentifier algorithm, CryptoKey key);
};
EncryptionStream includes GenericTransformStream;

A EncryptionStream has an associated algorithm, key and encryption context context.

The new EncryptionStream(algorithm, key) steps are:

1. Let normalizedAlgorithm be the result of normalizing an algorithm, with alg set to algorithm and op set to "encrypt".

   • normalize an algorithm doesn’t link correctly (needs to be exported in Web Crypto API).

2. Set this's algorithm to normalizedAlgorithm.

3. Set this's key to key.

4. Let transformAlgorithm be an algorithm which takes a chunk argument and runs the encrypt and enqueue a chunk algorithm with this and chunk.

5. Let flushAlgorithm be an algorithm which takes no argument and runs the encrypt flush and enqueue algorithm with this.

6. Set this's transform to a new TransformStream.

7. Set up this's transform with transformAlgorithm set to transformAlgorithm and flushAlgorithm set to flushAlgorithm.

The encrypt and enqueue a chunk algorithm, given a EncryptionStream object stream and a chunk, runs these steps:

1. If chunk is not a BufferSource type, then throw a TypeError.

2. Let buffer be the result of encrypting chunk with stream's algorithm and context.

3. If buffer is empty, return.

4. Split buffer into one or more non-empty pieces and convert them into Uint8Arrays.

5. For each Uint8Array array, enqueue array in stream's transform.

The encrypt flush and enqueue algorithm, which handles the end of data from the input ReadableStream object, given a EncryptionStream object stream, runs these steps:

1. Let buffer be the result of encrypting an empty input with stream's algorithm and context, with the finish flag.

2. If buffer is empty, return.

3. Split buffer into one or more non-empty pieces and convert them into Uint8Arrays.

4. For each Uint8Array array, enqueue array in stream's transform.