@very-amused/argon2-wasm
v0.3.5
Published
Implementation of the argon2 key derivation function using WebAssembly and Typescript, to be run clientside in web applications.
Downloads
19
Readme
@very-amused/argon2-wasm
WebAssembly/Typescript Bindings for Biryukov, Dinu, and Khovratovich's Argon2 key derivation function for clientside use in web applications. For documentation see docs.
Argon2 Modes
Argon2i, Argon2d, and Argon2id are all supported. If unsure, Argon2i is recommended because of its security against side-channel attacks due to data-independent memory access.
Security
This library zeroes all memory used by default, but it is still required that users of this library understand and implement secure memory handling for returned data. Hash output should be zeroed a minimum of 3 times after use.
Web Worker
These bindings are called entirely by channel-based communication with a Web Worker. The compiled code for this worker is located in build/worker.js (and build/worker.min.js for production), these files must be self-hosted at a path on the origin where argon2 will be used. It may be desired to deliver a Content-Security-Policy header along with the script, as no CSP from the origin is enforced by default for Web Workers.
Errors
The web worker will never return an error through anything other than a standard message. To check if a message is an error, check if the code
property is not equal to 0. Non-zero codes correspond to different errors, most of which are identical to argon2 upstream. See the ErrorCodes
enum for details.
Usage
import { Argon2 } from '@very-amused/argon2-wasm'
import { makeSalt, base64 } from 'cs-crypto'
// 1. Open a connection to a new argon2 worker thread
const argon2 = new Argon2.WorkerConnection(
new Worker('/argon2/worker.js') // Change to worker.min.js in production
)
// 2. Load the Argon2 WebAssembly
{
const message = await argon2.postMessage({
method: Argon2.Methods.LoadArgon2,
params: {
wasmRoot: '/argon2',
simd: true, /* The worker will test SIMD support by validating {wasmRoot}/simd-test.wasm,
and load a build with SIMD instructions if possible */
pthread: false /* The worker will test shared memory support,
and load a build with pthread/multithreading instructions if possible */
}
})
if (message.code !== 0) {
throw new Error(`failed to load argon2: code ${message.code}`)
}
}
// 3. Collect input
const password = document.querySelector('input#password').value
// 4. Generate a cryptographically random 16 byte salt
const salt = makeSalt(16)
// 5. Determine time and memory costs
const timeCost = 3 // a 3 pass minimum is recommended by Dmitry Khovratovich
const memoryCost = 1024 * 128 // Memory cost is in # of KiB, i.e m = 1024 = 1MiB
// 6. Run argon2i
const result = await argon2.postMessage({
method: Argon2.Methods.Hash2i, // Use Hash2d for argon2d, Hash2id for argon2id
params: {
password,
salt,
timeCost,
memoryCost,
threads: 1, // Number of threads to utilize, clamped to 1 on non-pthread builds
hashLen: 32 // Desired output size (in bytes)
}
})
if (result.code !== 0) {
throw new Error(`failed to run argon2i: code ${result.code}`)
}
// 7. The hash result will be stored in the body property of the result
console.log(`hash result: ${base64.encode(result.body)}`)
// 8. Terminate the worker thread (this will also free resources associated with the wasm instance)
argon2.terminate()