ctavan / proposal-arraybuffer-fillrandom

ArrayBuffer.fillRandom - Cryptographically Secure Random Number Generation for ECMAScript

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

ArrayBuffer.fillRandom - A CSPRNG for ECMAScript

This proposes the addition of a fillRandom static method to the global ArrayBuffer object that can be used to fill the portion of an ArrayBuffer associated with a TypedArray or DataView with cryptographically-secure pseudo-random values.

Portions of this proposal are derived from the Web Cryptography API

Status

Stage: 0
Champion: Ron Buckton (@rbuckton)

For detailed status of this proposal see TODO, below.

Authors

  • Ron Buckton (@rbuckton)

Motivations

One of the key issues for https://github.com/tc39/proposal-uuid is the lack of a "source of truth" for cryptographically secure pseudo-random numbers within the ECMAScript language. While hosts such as browsers and NodeJS provide implementations of CSPRNGs (Cryptographically Secure Pseudo-Random Number Generators), the ECMAScript language itself has no mechanism for supplying a CSPRNG that can be used by proposed APIs such as UUID.

Goals

  • Provide a single "source of truth" for generating cryptographically-secure pseudo-random values within the language.
  • Provides a single location for mocking the CSPRNG, vs a method on each TypedArray prototype.
  • Does not introduce a new global namespace for cryptography, as specifying a crypto global in ECMA-262 could cause complications with how to specify it such that the Web cryptography APIs could be layered on top.

Prior Art

Examples

TODO: Provide examples of the proposal.

const array = new Uint8Array(16);
ArrayBuffer.fillRandom(array);

API

ArrayBuffer.fillRandom(view)

When ArrayBuffer.fillRandom is called with argument view, the following steps are taken:

  1. Perform ? RequireInternalSlot(view, [[TypedArrayName]]).
  2. Assert: view has the [[ViewedArrayBuffer]], [[ByteLength]], and [[ByteOffset]] internal slots.
  3. If view.[[TypedArrayName]] is not one of "Int8Array", "Uint8Array", "Uint8ClampedArray", "Int16Array", "Uint16Array", "Int32Array", "Uint32Array", "BigInt64Array", or "BigUint64Array", throw a TypeError exception.
  4. Let buffer be view.[[ViewedArrayBuffer]].
  5. If ! IsDetachedBuffer(buffer) is true, throw a TypeError exception.
  6. Let byteLength be view.[[ByteLength]].
  7. If byteLength is greater than 65536, throw a RangeError exception.
  8. Let byteOffset be view.[[ByteOffset]].
  9. Let byteEndOffset be byteOffset + byteLength.
  10. Overwrite the elements of buffer from index byteOffset (inclusive) through index byteEndOffset (exclusive) with cryptographically random values.
  11. Return view.

Note
Implementations should generate cryptographically random values using well-established cryptographic pseudo-random number generators seeded with high-quality entropy, such as from an operating-system entropy source (e.g., "/dev/urandom"). This specification provides no lower-bound on the information theoretic entropy present in cryptographically random values, but implementations should make a best effort to provide as much entropy as practicable.

Note
This interface defines a synchronous method for obtaining cryptographically random values. While some devices and implementations may support truly random cryptographic number generators or provide interfaces that block when there is insufficient entropy, implementations are discouraged from using these sources when implementing getRandomValues, both for performance and to avoid depleting the system of entropy. Instead, these sources should be used to seed a cryptographic pseudo-random number generator that can then return suitable values efficiently.

References

Prior Discussion

TODO

The following is a high-level list of tasks to progress through each stage of the TC39 proposal process:

Stage 1 Entrance Criteria

  • Identified a "champion" who will advance the addition.
  • Prose outlining the problem or need and the general shape of a solution.
  • Illustrative examples of usage.
  • High-level API.

Stage 2 Entrance Criteria

Stage 3 Entrance Criteria

  • Complete specification text.
  • Designated reviewers have [signed off][Stage3ReviewerSignOff] on the current spec text.
  • The ECMAScript editor has [signed off][Stage3EditorSignOff] on the current spec text.

Stage 4 Entrance Criteria

  • Test262 acceptance tests have been written for mainline usage scenarios and [merged][Test262PullRequest].
  • Two compatible implementations which pass the acceptance tests: [[1]][Implementation1], [[2]][Implementation2].
  • A [pull request][Ecma262PullRequest] has been sent to tc39/ecma262 with the integrated spec text.
  • The ECMAScript editor has signed off on the [pull request][Ecma262PullRequest].

[Transpiler]: #todo [Stage3ReviewerSignOff]: #todo [Stage3EditorSignOff]: #todo [Test262PullRequest]: #todo [Implementation1]: #todo [Implementation2]: #todo [Ecma262PullRequest]: #todo

About

ArrayBuffer.fillRandom - Cryptographically Secure Random Number Generation for ECMAScript

License:BSD 3-Clause "New" or "Revised" License


Languages

Language:JavaScript 54.7%Language:HTML 45.3%