feat(crypto): add std/crypto wrapping and extending runtime WebCrypto

.github/workflows/ci.yml

@@ -99,6 +99,7 @@ jobs:
           # This must match the version in hash/_wasm/rust-toolchain:
           rust-version: 1.53.0
           targets: wasm32-unknown-unknown
+          components: rustfmt
 
       - name: Set up wasm-bindgen-cli
         run: |-

hash/README.md

@@ -1,86 +1,109 @@
 # std/hash
 
-hash is module to provide interfaces for hash functions.
+Provides implementations of several common cryptographic hash algorithms, behind
+a common interface.
 
 ## Usage
 
-### Creating new hash instance
+Hash inputs (messages) may be ArrayBuffers, TypedArrays, or strings (which will
+be encoded as UTF-8).
 
-You can create a new Hasher instance by calling `createHash` defined in mod.ts.
+### One-of digests
+
+You can call `digest` if you just need the binary digest of a value.
 
 ```ts
-import { createHash } from "https://deno.land/std@$STD_VERSION/hash/mod.ts";
+import * as hash from "https://deno.land/std@$STD_VERSION/hash/mod.ts";
 
-const hash = createHash("md5");
+const digest: Uint8Array = hash.digest("sha384", "hello world");
 // ...
 ```
 
-### Using hash instance
+### Creating new Hasher instance
 
-You can use `update` method to feed data into your hash instance. Call `digest`
-method to retrive final hash value in ArrayBuffer.
+If you need something more complicated, you can create a new Hasher instance by
+calling `createHasher`.
 
 ```ts
-import { createHash } from "https://deno.land/std@$STD_VERSION/hash/mod.ts";
+import { createHasher } from "https://deno.land/std@$STD_VERSION/hash/mod.ts";
 
-const hash = createHash("md5");
-hash.update("Your data here");
-const final = hash.digest(); // returns ArrayBuffer.
+const hash = createHasher("sha384");
+// ...
 ```
 
-Please note that `digest` invalidates the hash instance's internal state.
-Calling `digest` more than once will throw an Error.
+### Using Hasher instances
+
+You can use the `update` method as many times as neccessary to feed
+input/message data into your hasher instance. You can call the `digest` method
+to get the binary digest of the current state.
 
 ```ts
 import { createHash } from "https://deno.land/std@$STD_VERSION/hash/mod.ts";
 
-const hash = createHash("md5");
+const hash = createHash("sha384");
 hash.update("Your data here");
-const final1 = hash.digest(); // returns ArrayBuffer.
-const final2 = hash.digest(); // throws Error.
+const final = hash.digest(); // returns a Uint8Array.
 ```
 
-If you need final hash in string formats, call `toString` method with output
-format.
-
-Supported formats are `hex` and `base64` and default format is `hex`.
+You can get the digest as a hexadecimal or Base64 string with the `toString`
+method.
 
 ```ts
 import { createHash } from "https://deno.land/std@$STD_VERSION/hash/mod.ts";
 
-const hash = createHash("md5");
+const hash = createHash("sha384");
 hash.update("Your data here");
-const hashInHex = hash.toString(); // returns 5fe084ee423ff7e0c7709e9437cee89d
+const hashInHex = hash.toString();
+const hashInBase64 = hash.toString({ encoding: "base64" });
 ```
 
-```ts
-import { createHash } from "https://deno.land/std@$STD_VERSION/hash/mod.ts";
-
-const hash = createHash("md5");
-hash.update("Your data here");
-const hashInBase64 = hash.toString("base64"); // returns X+CE7kI/9+DHcJ6UN87onQ==
-```
+Other methods are described
+[in the docs](https://doc.deno.land/https/deno.land/std/hash/mod.ts).
 
 ### Supported algorithms
 
-Following algorithms are supported.
-
-- md2
-- md4
-- md5
-- ripemd160
-- ripemd320
-- sha1
-- sha224
-- sha256
-- sha384
-- sha512
-- sha3-224
-- sha3-256
-- sha3-384
-- sha3-512
-- keccak224
-- keccak256
-- keccak384
-- keccak512
-- blake3
+> ⚠️ **Warning:** Many of these supported algorithms have known security
+> weaknesses, but are included in this module as they may be required for
+> compatibility with existing systems. If you are free to pick an algorithm, be
+> sure you're using one that doesn't have any known weaknesses that could
+> compromise your design. If you're not sure, `sha384` is usually a safe choice:
+> it's one of the most widely-supported algorithms that is still believed to be
+> generally secure.
+
+The following hash algorithms are supported:
+
+- [`sha1`][FIPS-180-4]
+- [`sha224`][FIPS-180-4]
+- [`sha256`][FIPS-180-4]
+- [`sha384`][FIPS-180-4]
+- [`sha512`][FIPS-180-4]
+- [`sha3-224`][FIPS-202]
+- [`sha3-256`][FIPS-202]
+- [`sha3-384`][FIPS-202]
+- [`sha3-512`][FIPS-202]
+- [`shake128`][FIPS-202] (supports variable-length digests)
+- [`shake256`][FIPS-202] (supports variable-length digests)
+- [`keccak224`][KECCAK]
+- [`keccak256`][KECCAK]
+- [`keccak384`][KECCAK]
+- [`keccak512`][KECCAK]
+- [`blake2b`][BLAKE2]
+- [`blake2b-256`][BLAKE2]
+- [`blake2b-384`][BLAKE2]
+- [`blake2s`][BLAKE2]
+- [`blake3`][BLAKE3] (supports variable-length digests)
+- [`md2`][RFC-1319]
+- [`md4`][RFC-1186]
+- [`md5`][RFC-1321]
+- [`ripemd160`][RIPEMD-160]
+- [`ripemd320`][RIPEMD-160]
+
+[BLAKE2]: https://www.blake2.net/
+[BLAKE3]: https://blake3.io/
+[FIPS-180-4]: http://dx.doi.org/10.6028/NIST.FIPS.180-4
+[FIPS-202]: http://dx.doi.org/10.6028/NIST.FIPS.202
+[KECCAK]: https://keccak.team/keccak.html
+[RFC-1186]: https://www.rfc-editor.org/rfc/rfc1186.html
+[RFC-1319]: https://www.rfc-editor.org/rfc/rfc1319.html
+[RFC-1321]: https://www.rfc-editor.org/rfc/rfc1321.html
+[RIPEMD-160]: https://homes.esat.kuleuven.be/~bosselae/ripemd160/pdf/AB-9601/AB-9601.pdf

hash/_wasm/Cargo.toml

@@ -4,23 +4,25 @@ version = "0.1.0"
 authors = ["the Deno authors"]
 edition = "2018"
 license = "MIT"
-repository = "https://github.com/denoland/deno"
+repository = "https://github.com/denoland/deno_std"
 
 [lib]
 crate-type = ["cdylib"]
 
 [dependencies]
+blake2 = "0.9.1"
+blake3 = "0.3.8"
 digest = "0.9.0"
+js-sys = "0.3.51"
+md-5 = "0.9.1"
 md2 = "0.9.0"
 md4 = "0.9.0"
-md-5 = "0.9.1"
 ripemd160 = "0.9.1"
 ripemd320 = "0.9.0"
-sha-1 = "0.9.1"
-sha2 = "0.9.1"
+sha-1 = "0.9.6"
+sha2 = "0.9.5"
 sha3 = "0.9.1"
 wasm-bindgen = "0.2.74"
-blake3 = "0.3.8"
 
 [profile.release]
 lto = true

hash/_wasm/README.md

@@ -2,7 +2,7 @@
 
 ## Prerequisite
 
-`wasm-bindgen` is required.
+Requires Rust's WASM target and the wasm-bindgen CLI.
 
 ```sh
 cargo build --target wasm32-unknown-unknown
@@ -15,7 +15,8 @@ cargo install -f wasm-bindgen-cli --version 0.2.74
 ## Build
 
 ```sh
-deno run --allow-all build.ts
+deno run --allow-all ./_wasm/build.ts
 ```
 
-`wasm.js` will be generated.
+This will regenerate `./_wasm/wasm_file.ts` and `./_wasm/wasm_bindings.ts` from
+the Rust source.