diff --git a/README.md b/README.md index 9c2e73f..9400191 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,8 @@ developers from security pitfalls. ## Overview +### UUID API + The UUID standard library provides an API for generating RFC 4122 identifiers. The default export of the UUID library is the @@ -51,8 +53,22 @@ representation _(as described in RFC-4122)_. uuid(); // "52e6953d-edbe-4953-be2e-65ed3836b2f0" ``` -All random values in UUIDs produced by this API must be generated from a **[cryptographically -secure][csprng]** source. +### `Math.getRandomValues()` + +`Math.getRandomValues()` exposes an identical API to the +[W3C `crypto.getRandomValues()`](https://www.w3.org/TR/WebCryptoAPI/#Crypto-method-getRandomValues) +recommendation. With the same guarantees, regarding the quality of randomness: + +> 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. +> +> - [WebCryptoAPI 10.1. Description](https://www.w3.org/TR/WebCryptoAPI/#Crypto-description) + +`Math.getRandomValues()` will act as the foundation for implementing UUID algorithms, providing a +single mockable (see [#25](https://github.com/tc39/proposal-uuid/issues/25)) source of randomness. ## Out of scope