1 | # `blake2b`
|
2 |
|
3 | [![Build Status](https://travis-ci.org/emilbayes/blake2b.svg?branch=master)](https://travis-ci.org/emilbayes/blake2b)
|
4 |
|
5 | > Blake2b (64-bit version) in pure Javascript
|
6 |
|
7 | This module is based on @dcposch
|
8 | [implementation of BLAKE2b](https://github.com/dcposch/blakejs), with some changes:
|
9 |
|
10 | * This module requires you to pass in a `out` buffer, saving an allocation
|
11 | * This module allows you to set the `salt` and `personal` parameters
|
12 | * This module exports constants for the parameters in libsodium style
|
13 | * Uses a WASM version (where it is supported) for massive performance boosts
|
14 |
|
15 | All credit goes to @dcposch for doing the hard work of porting the
|
16 | implementation from C to Javascript.
|
17 |
|
18 | ## Usage
|
19 |
|
20 | ```js
|
21 | var blake2b = require('blake2b')
|
22 |
|
23 | var output = new Uint8Array(64)
|
24 | var input = Buffer.from('hello world')
|
25 |
|
26 | blake2b(output, input)
|
27 | ```
|
28 |
|
29 | ## API
|
30 |
|
31 | ### `var hash = blake2b(outLength, [key], [salt], [personal], [noAssert = false])`
|
32 |
|
33 | Create a new hash instance, optionally with `key`, `salt` and
|
34 | `personal`. Bypass input assertions by setting `noAssert` to `true`.
|
35 |
|
36 | All parameters must be `Uint8Array`, `Buffer` or another object with a compatible
|
37 | API. All parameters must also fulfill the following constraints, or an
|
38 | `AssertionError` will be thrown (unless `noAssert = true`):
|
39 |
|
40 | * `outLength` must within the byte ranges defined by the constants below.
|
41 | * `key` is optional, but must within the byte ranges defined by the constants
|
42 | below, if given. This value must be kept secret, and can be used to create
|
43 | prefix-MACs.
|
44 | * `salt` is optional, but must be exactly `SALTBYTES`, if given. You can use
|
45 | this parameter as a kind of per user id, or local versioning scheme. This
|
46 | value is not required to be secret.
|
47 | * `personal` is optional, but must be exactly `PERSONALBYTES`, if given. You can
|
48 | use this parameter as a kind of app id, or global versioning scheme. This
|
49 | value is not required to be secret.
|
50 |
|
51 | ### `var hash = hash.update(input)`
|
52 |
|
53 | Update the hash with new `input`. Calling this method after `.digest` will throw
|
54 | an error.
|
55 |
|
56 | ### `var out = hash.digest(out)`
|
57 |
|
58 | Finalise the the hash and write the digest to `out`. `out` must be exactly equal
|
59 | to `outLength` given in the `blake2b` method.
|
60 |
|
61 | Optionally you can pass `hex` to get the hash as a hex string or no arguments
|
62 | to have the hash return a new Uint8Array with the hash.
|
63 |
|
64 | ### Constants
|
65 |
|
66 | * `blake2b.BYTES_MIN` Minimum length of `out`
|
67 | * `blake2b.BYTES_MAX` Maximum length of `out`
|
68 | * `blake2b.BYTES` Recommended default length of `out`
|
69 | * `blake2b.KEYBYTES_MIN` Minimum length of `key`
|
70 | * `blake2b.KEYBYTES_MAX` Maximum length of `key`
|
71 | * `blake2b.KEYBYTES` Recommended default length of `key`
|
72 | * `blake2b.SALTBYTES` Required length of `salt`
|
73 | * `blake2b.PERSONALBYTES` Required length of `personal`
|
74 |
|
75 | ## Install
|
76 |
|
77 | ```sh
|
78 | npm install blake2b
|
79 | ```
|
80 |
|
81 | ## Test vectors
|
82 |
|
83 | This repository includes test vectors with
|
84 | `{outlen, out, input, key, salt, personal}` objects for testing conformance
|
85 | against the spec and other implementations:
|
86 |
|
87 | * Lines [2 - 257](test-vectors.json#L2-L257) are tests for hashing with no key, taken from [BLAKE2 test vectors](https://github.com/BLAKE2/BLAKE2/blob/5cbb39c9ef8007f0b63723e3aea06cd0887e36ad/testvectors/blake2-kat.json)
|
88 | * Lines [258 - 513](test-vectors.json#L258-L513) are tests for hashing with keys, taken from [BLAKE2 test vectors](https://github.com/BLAKE2/BLAKE2/blob/5cbb39c9ef8007f0b63723e3aea06cd0887e36ad/testvectors/blake2-kat.json)
|
89 | * Lines [514- 577](test-vectors.json#L514-L577) are tests for hashing with key, salt and personalisation, derived from the [libsodium tests](https://github.com/jedisct1/libsodium/blob/3a9c4c38f7dbe671d91dcfa267c919734b4923df/test/default/generichash3.c)
|
90 |
|
91 | ## License
|
92 |
|
93 | [ISC](LICENSE)
|