diff options
Diffstat (limited to 'library/sodium-plus/docs/SodiumPlus')
19 files changed, 1313 insertions, 0 deletions
diff --git a/library/sodium-plus/docs/SodiumPlus/AEAD.md b/library/sodium-plus/docs/SodiumPlus/AEAD.md new file mode 100644 index 000000000..4a70d50e5 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/AEAD.md @@ -0,0 +1,64 @@ +## AEAD + +> **See also:** [Libsodium's documentation on its AEAD features](https://download.libsodium.org/doc/secret-key_cryptography/aead/chacha20-poly1305/xchacha20-poly1305_construction). + +### crypto_aead_xchacha20poly1305_ietf_decrypt + +Decrypt a message (and optional associated data) with XChaCha20-Poly1305. + +**Parameters and their respective types**: + +1. `{string|Buffer}` Ciphertext +2. `{string|Buffer}` nonce (must be 24 bytes) +3. `{CryptographyKey}` key +4. `{string|Buffer}` assocData + +Returns a `Promise` that resolves to a `Buffer`. +Throws a `SodiumError` on decryption failure. + +### crypto_aead_xchacha20poly1305_ietf_encrypt + +Encrypt a message (and optional associated data) with XChaCha20-Poly1305. + +**Parameters and their respective types**: + +1. `{string|Buffer}` Plaintext +2. `{string|Buffer}` nonce (must be 24 bytes) +3. `{CryptographyKey}` key +4. `{string|Buffer}` assocData + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_aead_xchacha20poly1305_ietf_keygen + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_aead_xchacha20poly1305_ietf_` API. + +### Example for crypto_aead_xchacha20poly1305_ietf_* + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let plaintext = 'Your message goes here'; + let key = await sodium.crypto_aead_xchacha20poly1305_ietf_keygen(); + let nonce = await sodium.randombytes_buf(24); + let ciphertext = await sodium.crypto_aead_xchacha20poly1305_ietf_encrypt( + plaintext, + nonce, + key + ); + + console.log(ciphertext.toString('hex')); + + let decrypted = await sodium.crypto_aead_xchacha20poly1305_ietf_decrypt( + ciphertext, + nonce, + key + ); + + console.log(decrypted.toString()); +})(); +```
\ No newline at end of file diff --git a/library/sodium-plus/docs/SodiumPlus/README.md b/library/sodium-plus/docs/SodiumPlus/README.md new file mode 100644 index 000000000..f341b8be4 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/README.md @@ -0,0 +1,99 @@ +# SodiumPlus Methods + +This describes the methods in the public API for Sodium-Plus. +If you're not sure which method to use, please refer to the +[Libsodium Quick Reference](https://paragonie.com/blog/2017/06/libsodium-quick-reference-quick-comparison-similar-functions-and-which-one-use) +for guidance. + +* [AEAD (XChaCha20-Poly1305)](AEAD.md#aead) + * [crypto_aead_xchacha20poly1305_ietf_decrypt](AEAD.md#crypto_aead_xchacha20poly1305_ietf_decrypt) + * [crypto_aead_xchacha20poly1305_ietf_encrypt](AEAD.md#crypto_aead_xchacha20poly1305_ietf_encrypt) + * [crypto_aead_xchacha20poly1305_ietf_keygen](AEAD.md#crypto_aead_xchacha20poly1305_ietf_keygen) + * [Example for crypto_aead_xchacha20poly1305_ietf_*](AEAD.md#example-for-crypto_aead_xchacha20poly1305_ietf_) +* [Shared-key authentication](shared-key-authentication.md) + * [crypto_auth](shared-key-authentication.md#crypto_auth) + * [crypto_auth_verify](shared-key-authentication.md#crypto_auth_verify) + * [crypto_auth_keygen](shared-key-authentication.md#crypto_auth_keygen) + * [Example for crypto_auth](shared-key-authentication.md#example-for-crypto_auth) +* [Authenticated public-key encryption](authenticated-public-key-encryption.md) + * [crypto_box](authenticated-public-key-encryption.md#crypto_box) + * [crypto_box_open](authenticated-public-key-encryption.md#crypto_box_open) + * [crypto_box_keypair](authenticated-public-key-encryption.md#crypto_box_keypair) + * [crypto_box_keypair_from_secretkey_and_secretkey](authenticated-public-key-encryption.md#crypto_box_keypair_from_secretkey_and_secretkey) + * [crypto_box_publickey](authenticated-public-key-encryption.md#crypto_box_publickey) + * [crypto_box_secretkey](authenticated-public-key-encryption.md#crypto_box_secretkey) + * [crypto_box_publickey_from_secretkey](authenticated-public-key-encryption.md#crypto_box_publickey_from_secretkey) + * [Example for crypto_box](authenticated-public-key-encryption.md#example-for-crypto_box) +* [Sealed boxes (anonymous public-key encryption)](sealed-boxes.md) + * [crypto_box_seal](sealed-boxes.md#crypto_box_seal) + * [crypto_box_seal_open](sealed-boxes.md#crypto_box_seal_open) + * [Example for crypto_box_seal](sealed-boxes.md#example-for-crypto_box_seal) +* [General-purpose cryptographic hash](general-purpose-cryptographic-hash.md) + * [crypto_generichash](general-purpose-cryptographic-hash.md#crypto_generichash) + * [crypto_generichash_init](general-purpose-cryptographic-hash.md#crypto_generichash_init) + * [crypto_generichash_update](general-purpose-cryptographic-hash.md#crypto_generichash_update) + * [crypto_generichash_final](general-purpose-cryptographic-hash.md#crypto_generichash_final) + * [crypto_generichash_keygen](general-purpose-cryptographic-hash.md#crypto_generichash_keygen) + * [Example for crypto_generichash](general-purpose-cryptographic-hash.md#example-for-crypto_generichash) +* [Key derivation](key-derivation.md) + * [crypto_kdf_derive_from_key](key-derivation.md#crypto_kdf_derive_from_key) + * [crypto_kdf_keygen](key-derivation.md#crypto_kdf_keygen) + * [Example for crypto_kdf](key-derivation.md#example-for-crypto_kdf) +* [Key exchange](key-exchange.md) + * [crypto_kx_keypair](key-exchange.md#crypto_kx_keypair) + * [crypto_kx_seed_keypair](key-exchange.md#crypto_kx_seed_keypair) + * [crypto_kx_client_session_keys](key-exchange.md#crypto_kx_client_session_keys) + * [crypto_kx_server_session_keys](key-exchange.md#crypto_kx_server_session_keys) + * [Example for crypto_kx](key-exchange.md#example-for-crypto_kx) +* [One-time authentication](one-time-authentication.md) + * [crypto_onetimeauth](one-time-authentication.md#crypto_onetimeauth) + * [crypto_onetimeauth_verify](one-time-authentication.md#crypto_onetimeauth_verify) + * [crypto_onetimeauth_keygen](one-time-authentication.md#crypto_onetimeauth_keygen) + * [Example for crypto_onetimeauth](one-time-authentication.md#example-for-crypto_onetimeauth) +* [Password-based key derivation](password-based-key-derivation.md) + * [crypto_pwhash](password-based-key-derivation.md#crypto_pwhash) + * [Example for crypto_pwhash](password-based-key-derivation.md#example-for-crypto_pwhash) +* [Password hashing and storage](password-hashing-and-storage.md) + * [crypto_pwhash_str](password-hashing-and-storage.md#crypto_pwhash_str) + * [crypto_pwhash_str_needs_rehash](password-hashing-and-storage.md#crypto_pwhash_str_needs_rehash) + * [crypto_pwhash_str_verify](password-hashing-and-storage.md#crypto_pwhash_str_verify) + * [Example for crypto_pwhash_str](password-hashing-and-storage.md#example-for-crypto_pwhash_str) +* [Scalar multiplication over Curve25519 (advanced)](scalar-multiplication.md) + * [crypto_scalarmult](scalar-multiplication.md#crypto_scalarmult) + * [crypto_scalarmult_base](scalar-multiplication.md#crypto_scalarmult_base) + * [Example for crypto_scalarmult](scalar-multiplication.md#example-for-crypto_scalarmult) +* [Shared-key authenticated encryption](shared-key-authenticated-encryption.md) + * [crypto_secretbox](shared-key-authenticated-encryption.md#crypto_secretbox) + * [crypto_secretbox_open](shared-key-authenticated-encryption.md#crypto_secretbox_open) + * [crypto_secretbox_keygen](shared-key-authenticated-encryption.md#crypto_secretbox_keygen) + * [Example for crypto_secretbox](shared-key-authenticated-encryption.md#example-for-crypto_secretbox) +* [Encrypted streams](encrypted-streams.md) + * [crypto_secretstream_xchacha20poly1305_init_push](encrypted-streams.md#crypto_secretstream_xchacha20poly1305_init_push) + * [crypto_secretstream_xchacha20poly1305_init_pull](encrypted-streams.md#crypto_secretstream_xchacha20poly1305_init_pull) + * [crypto_secretstream_xchacha20poly1305_push](encrypted-streams.md#crypto_secretstream_xchacha20poly1305_push) + * [crypto_secretstream_xchacha20poly1305_pull](encrypted-streams.md#crypto_secretstream_xchacha20poly1305_pull) + * [crypto_secretstream_xchacha20poly1305_keygen](encrypted-streams.md#crypto_secretstream_xchacha20poly1305_keygen) + * [crypto_secretstream_xchacha20poly1305_rekey](encrypted-streams.md#crypto_secretstream_xchacha20poly1305_rekey) + * [Example for crypto_secretstream_xchacha20poly1305](encrypted-streams.md#example-for-crypto_secretstream_xchacha20poly1305) +* [Short-input hashing](short-input-hashing.md) + * [crypto_shorthash](short-input-hashing.md#crypto_shorthash) + * [crypto_shorthash_keygen](short-input-hashing.md#crypto_shorthash_keygen) + * [Example for crypto_shorthash](short-input-hashing.md#example-for-crypto_shorthash) +* [Digital signatures](digital-signatures.md) + * [crypto_sign](digital-signatures.md#crypto_sign) + * [crypto_sign_open](digital-signatures.md#crypto_sign_open) + * [crypto_sign_detached](digital-signatures.md#crypto_sign_detached) + * [crypto_sign_verify_detached](digital-signatures.md#crypto_sign_verify_detached) + * [crypto_sign_keypair](digital-signatures.md#crypto_sign_keypair) + * [crypto_sign_publickey](digital-signatures.md#crypto_sign_publickey) + * [crypto_sign_secretkey](digital-signatures.md#crypto_sign_secretkey) + * [crypto_sign_ed25519_sk_to_curve25519](digital-signatures.md#crypto_sign_ed25519_sk_to_curve25519) + * [crypto_sign_ed25519_pk_to_curve25519](digital-signatures.md#crypto_sign_ed25519_pk_to_curve25519) + * [Example for crypto_sign](digital-signatures.md#example-for-crypto_sign) +* [Randomness](randomness.md) + * [randombytes_buf](randomness.md#randombytes_buf) + * [randombytes_uniform](randomness.md#randombytes_uniform) + * [Example for randombytes](randomness.md#example-for-randombytes) +* [Utilities](utilities.md) + * [sodium_bin2hex](utilities.md#sodium_bin2hex) + * [sodium_hex2bin](utilities.md#sodium_bin2hex) diff --git a/library/sodium-plus/docs/SodiumPlus/authenticated-public-key-encryption.md b/library/sodium-plus/docs/SodiumPlus/authenticated-public-key-encryption.md new file mode 100644 index 000000000..0ac312e5a --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/authenticated-public-key-encryption.md @@ -0,0 +1,99 @@ +## Authenticated public-key encryption + +> **See also**: [Libsodium's documentation on its public-key authenticated encryption features](https://download.libsodium.org/doc/public-key_cryptography/authenticated_encryption). + +### crypto_box + +Public-key authenticated encryption. + +**Parameters and their respective types**: + +1. `{string|Buffer}` plaintext +2. `{Buffer}` nonce (must be 24 bytes) +3. `{X25519SecretKey}` secret key +4. `{X25519PublicKey}` public key + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_box_open + +Public-key authenticated encryption. + +**Parameters and their respective types**: + +1. `{Buffer}` ciphertext +2. `{Buffer}` nonce (must be 24 bytes) +3. `{X25519SecretKey}` secret key +4. `{X25519PublicKey}` public key + +Returns a `Promise` that resolves to a `Buffer`. +Throws a `SodiumError` on decryption failure. + +### crypto_box_keypair + +Returns a `Promise` that resolves to a `CryptographyKey` containing a 64-byte +`Buffer`. The first 32 bytes are your X25519 secret key, the latter 32 are your +X25519 public key. + +### crypto_box_keypair_from_secretkey_and_secretkey + +Combine two X25519 keys (secret, public) into a keypair object. + +**Parameters and their respective types**: + +1. `{X25519SecretKey}` secret key +2. `{X25519PublicKey}` public key + +Returns a `Promise` that resolves to a `CryptographyKey`. + +### crypto_box_publickey + +**Parameters and their respective types**: + +1. `{CryptographyKey}` (buffer must be 64 bytes long) + +Returns a `Promise` that resolves to a `X25519PublicKey`. + +### crypto_box_secretkey + +**Parameters and their respective types**: + +1. `{CryptographyKey}` (buffer must be 64 bytes long) + +Returns a `Promise` that resolves to a `X25519SecretKey`. + +### crypto_box_publickey_from_secretkey + +Derive the public key from a given X25519 secret key. + +**Parameters and their respective types**: + +1. `{X25519SecretKey}` + +Returns a `Promise` that resolves to a `X25519PublicKey`. + +### Example for crypto_box + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let aliceKeypair = await sodium.crypto_box_keypair(); + let aliceSecret = await sodium.crypto_box_secretkey(aliceKeypair); + let alicePublic = await sodium.crypto_box_publickey(aliceKeypair); + let bobKeypair = await sodium.crypto_box_keypair(); + let bobSecret = await sodium.crypto_box_secretkey(bobKeypair); + let bobPublic = await sodium.crypto_box_publickey(bobKeypair); + + let plaintext = 'Your message goes here'; + let nonce = await sodium.randombytes_buf(24); + + let ciphertext = await sodium.crypto_box(plaintext, nonce, aliceSecret, bobPublic); + console.log(ciphertext); + + let decrypted = await sodium.crypto_box_open(ciphertext, nonce, bobSecret, alicePublic); + console.log(decrypted.toString()); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/digital-signatures.md b/library/sodium-plus/docs/SodiumPlus/digital-signatures.md new file mode 100644 index 000000000..d1bfee5b3 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/digital-signatures.md @@ -0,0 +1,134 @@ +## Digital signatures + +> **See also**: [Libsodium's documentation on its public-key signature features](https://download.libsodium.org/doc/public-key_cryptography/public-key_signatures). + +### crypto_sign + +> See also: [the detached API](#crypto_sign_detached) below. + +Sign a message with Ed25519, returning a signed message (prefixed with the signature). + +**Parameters and their respective types**: + +1. `{string|Buffer}` message +2. `{Ed25519SecretKey}` secretKey + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_sign_open + +Verify a signed message with Ed25519, returning the original message if the signature +is valid. + +**Parameters and their respective types**: + +1. `{string|Buffer}` signedMessage +2. `{Ed25519SecretKey}` publicKey + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_sign_detached + +Returns the Ed25519 signature of the message, for the given secret key. + +**Parameters and their respective types**: + +1. `{string|Buffer}` message +2. `{Ed25519SecretKey}` secretKey + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_sign_verify_detached + +Returns true if the Ed25519 signature is valid for a given message and public key. + +**Parameters and their respective types**: + +1. `{string|Buffer}` message +2. `{Ed25519PublicKey}` publicKey +3. `{Buffer}` signature + +Returns a `Promise` that resolves to a `boolean`. + +### crypto_sign_keypair + +Returns a `Promise` that resolves to a `CryptographyKey` containing a 96-byte +`Buffer`. The first 64 bytes are your Ed25519 secret key, the latter 32 are your +Ed25519 public key. + +### crypto_sign_seed_keypair + +**Parameters and their respective types**: + +1. `{Buffer}` 32 byte seed + +Returns a `Promise` that resolves to a `CryptographyKey` containing a 96-byte +`Buffer`. The first 64 bytes are your Ed25519 secret key, the latter 32 are your +Ed25519 public key. + +### crypto_sign_publickey + +**Parameters and their respective types**: + +1. `{CryptographyKey}` (buffer must be 96 bytes long) + +Returns a `Promise` that resolves to a `Ed25519PublicKey`. + + +### crypto_sign_secretkey + +**Parameters and their respective types**: + +1. `{CryptographyKey}` (buffer must be 96 bytes long) + +Returns a `Promise` that resolves to a `Ed25519SecretKey`. + +### crypto_sign_ed25519_sk_to_curve25519 + +Obtain a birationally equivalent X25519 secret key, given an Ed25519 secret key. + +**Parameters and their respective types**: + +1. `{Ed25519SecretKey}` + +Returns a `Promise` that resolves to an `X25519SecretKey`. + +### crypto_sign_ed25519_pk_to_curve25519 + +Obtain a birationally equivalent X25519 public key, given an Ed25519 public key. + +**Parameters and their respective types**: + +1. `{Ed25519PublicKey}` + +Returns a `Promise` that resolves to an `X25519PublicKey`. + +### Example for crypto_sign + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let aliceKeypair = await sodium.crypto_sign_keypair(); + let aliceSecret = await sodium.crypto_sign_secretkey(aliceKeypair); + let alicePublic = await sodium.crypto_sign_publickey(aliceKeypair); + + let message = 'This is something I need to sign publicly.'; + + // Detached mode: + let signature = await sodium.crypto_sign_detached(message, aliceSecret); + console.log(signature.toString('hex')); + if (await sodium.crypto_sign_verify_detached(message, alicePublic, signature)) { + console.log("Signature is valid."); + } else { + console.error("Invalid signature!"); + } + + // NaCl (crypto_sign / crypto_sign_open): + let signed = await sodium.crypto_sign(message, aliceSecret); + let opened = await sodium.crypto_sign_open(signed, alicePublic); + console.log(opened.toString()); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/encrypted-streams.md b/library/sodium-plus/docs/SodiumPlus/encrypted-streams.md new file mode 100644 index 000000000..25ed5039c --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/encrypted-streams.md @@ -0,0 +1,138 @@ +## Encrypted Streams + +> **See also:** [Libsodium's documentation on its encrypted streams feature](https://download.libsodium.org/doc/secret-key_cryptography/secretstream) + +### crypto_secretstream_xchacha20poly1305_init_push() + +Initialize a stream for streaming encryption. + +**Parameters and their respective types**: + +1. `{CryptographyKey}` key + +Returns a `Promise` that resolves to an `array` with 2 elements: + +1. A 24-byte header that should be included in the encrypted stream. +2. A backend-specific `state`: + * `LibsodiumWrappers` returns a `number` (a pointer to an internal buffer) + * `SodiumNative` returns a `CryptoSecretstreamXchacha20poly1305StateWrap` + object + +The `{state}` type annotation below refers to one of the backend-specific state +types. + +You'll typically want to use it with list unpacking syntax, like so: + +``` +[state, header] = await sodium.crypto_secretstream_xchacha20poly1305_init_push(key); +``` + +### crypto_secretstream_xchacha20poly1305_init_pull() + +Initialize a stream for streaming decryption. + +**Parameters and their respective types**: + +1. `{CryptographyKey}` key +2. `{Buffer}` header (must be 24 bytes) + +Returns a `Promise` that resolves to a backend-specific `state`: + +* `LibsodiumWrappers` returns a `number` (a pointer to an internal buffer) +* `SodiumNative` returns a `CryptoSecretstreamXchacha20poly1305StateWrap` + object + +The `{state}` type annotation below refers to one of the backend-specific state +types. + +### crypto_secretstream_xchacha20poly1305_push() + +Encrypt some data in a stream. + +**Parameters and their respective types**: + +1. `{state}` state +2. `{string|Buffer}` message +3. `{string|Buffer}` (optional) additional associated data +4. `{number}` tag (default = 0, see libsodium docs) + +Returns a `Promise` that resolves to a `Buffer` containing the ciphertext. + +### crypto_secretstream_xchacha20poly1305_pull() + +Decrypt some data in a stream. + +**Parameters and their respective types**: + +1. `{state}` state +2. `{string|Buffer}` ciphertext +3. `{string|Buffer}` (optional) additional associated data +4. `{number}` tag (default = 0, see libsodium docs) + +Returns a `Promise` that resolves to a `Buffer` containing +decrypted plaintext. + +### crypto_secretstream_xchacha20poly1305_keygen() + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_secretstream` API. + +### crypto_secretstream_xchacha20poly1305_rekey() + +Deterministic re-keying of the internal state. + +**Parameters and their respective types**: + +1. `{state}` state + +Returns a `Promise` that resolves to `undefined`. Instead, +the `state` variable is overwritten in-place. + +### Example for crypto_secretstream_xchacha20poly1305 + +```javascript +const fsp = require('fs').promises; +const path = require('path'); +const { SodiumPlus } = require('sodium-plus'); + +let sodium; +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + + let key = await sodium.crypto_secretstream_xchacha20poly1305_keygen(); + let pushState, pullState, header; + [pushState, header] = await sodium.crypto_secretstream_xchacha20poly1305_init_push(key); + + // Get a test input from the text file. + let longText = await fsp.readFile(path.join(__dirname, 'encrypted-streams.md')); + let chunk, readUntil; + let ciphertext = Buffer.concat([header]); + + // How big are our chunks going to be? + let PUSH_CHUNK_SIZE = await sodium.randombytes_uniform(longText.length - 32) + 32; + let PULL_CHUNK_SIZE = PUSH_CHUNK_SIZE + sodium.CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES; + + // Encryption... + for (let i = 0; i < longText.length; i += PUSH_CHUNK_SIZE) { + readUntil = (i + PUSH_CHUNK_SIZE) > longText.length ? longText.length : i + PUSH_CHUNK_SIZE; + chunk = await sodium.crypto_secretstream_xchacha20poly1305_push( + pushState, + longText.slice(i, readUntil) + ); + ciphertext = Buffer.concat([ciphertext, chunk]); + } + + pullState = await sodium.crypto_secretstream_xchacha20poly1305_init_pull(key, header); + // Decrypt, starting at 24 (after the header, which we already have) + let decrypted = Buffer.alloc(0); + for (let i = 24; i < ciphertext.length; i += PULL_CHUNK_SIZE) { + readUntil = (i + PULL_CHUNK_SIZE) > ciphertext.length ? ciphertext.length : i + PULL_CHUNK_SIZE; + chunk = await sodium.crypto_secretstream_xchacha20poly1305_pull( + pullState, + ciphertext.slice(i, readUntil) + ); + decrypted = Buffer.concat([decrypted, chunk]); + } + console.log(decrypted.toString()); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/general-purpose-cryptographic-hash.md b/library/sodium-plus/docs/SodiumPlus/general-purpose-cryptographic-hash.md new file mode 100644 index 000000000..12e762b5e --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/general-purpose-cryptographic-hash.md @@ -0,0 +1,82 @@ +## General-purpose cryptographic hash + +> **See also**: [Libsodium's documentation on its generic hashing features](https://download.libsodium.org/doc/hashing/generic_hashing). + +### crypto_generichash + +General-purpose cryptographic hash (powered by BLAKE2). + +**Parameters and their respective types**: + +1. `{Buffer}` message +2. `{CryptographyKey|null}` key (optional) +3. `{number}` output length (optional, defaults to 32) + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_generichash_keygen + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_generichash` API. + +### crypto_generichash_init + +Initialize a BLAKE2 hash context for stream hashing. + +**Parameters and their respective types**: + +1. `{CryptographyKey|null}` key (optional) +2. `{number}` output length (optional, defaults to 32) + +Returns a `Promise` that resolves to... well, that depends on your backend. + +* sodium-native returns a `CryptoGenericHashWrap` object. +* libsodium-wrappers returns a number (a buffer's memory address) + +### crypto_generichash_update + +Update the BLAKE2 hash state with a block of data. + +**Parameters and their respective types**: + +1. `{*}` hash state (see [crypto_generichash_init()](#crypto_generichash_init)) +2. `{string|Buffer}` message chunk + +Returns a `Promise` that resolves to `void`. Instead, `state` is updated in-place. + +### crypto_generichash_final + +Obtain the final BLAKE2 hash output. + +**Parameters and their respective types**: + +1. `{*}` hash state (see [crypto_generichash_init()](#crypto_generichash_init)) +2. `{number}` output length (optional, defaults to 32) + +Returns a `Promise` that resolves to a `Buffer`. + +### Example for crypto_generichash + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let message = 'Any message can go here'; + let hashed = await sodium.crypto_generichash(message); + console.log(hashed.toString('hex')); + + let key = await sodium.crypto_generichash_keygen(); + let hash2 = await sodium.crypto_generichash(message, key, 64); + let state = await sodium.crypto_generichash_init(key, 64); + + await sodium.crypto_generichash_update(state, 'Any message '); + await sodium.crypto_generichash_update(state, 'can go here'); + let hash3 = await sodium.crypto_generichash_final(state, 64); + if (!await sodium.sodium_memcmp(hash2, hash3)) { + throw new Error('Implementation is broken. You should never see this.'); + } + console.log(hash2.toString('hex')); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/key-derivation.md b/library/sodium-plus/docs/SodiumPlus/key-derivation.md new file mode 100644 index 000000000..72ae3c3c4 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/key-derivation.md @@ -0,0 +1,45 @@ +## Key derivation + +> **See also**: [Libsodium's documentation on its key derivation features](https://download.libsodium.org/doc/key_derivation). + +### crypto_kdf_derive_from_key + +Derive a subkey from a master key. + +**Parameters and their respective types**: + +1. `{number}` output length (typically you want `32`) +2. `{number}` subkey ID +3. `{string|Buffer}` context (must be a string/buffer of length 8) +4. `{CryptographyKey}` master key + +Returns a `Promise` that resolves to a `CryptographyKey`. + +### crypto_kdf_keygen + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_kdf` API. + +### Example for crypto_kdf + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let masterKey = await sodium.crypto_kdf_keygen(); + let context = 'Sodium++'; + + let subkey1 = await sodium.crypto_kdf_derive_from_key(32, 1, context, masterKey); + let subkey2 = await sodium.crypto_kdf_derive_from_key(32, 2, context, masterKey); + let subkey3 = await sodium.crypto_kdf_derive_from_key(32, 3, context, masterKey); + + console.log({ + 'master-key': masterKey.getBuffer().toString('hex'), + 'subkey1': subkey1.getBuffer().toString('hex'), + 'subkey2': subkey2.getBuffer().toString('hex'), + 'subkey3': subkey3.getBuffer().toString('hex') + }); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/key-exchange.md b/library/sodium-plus/docs/SodiumPlus/key-exchange.md new file mode 100644 index 000000000..20521edad --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/key-exchange.md @@ -0,0 +1,94 @@ +## Key exchange + +> **See also**: [Libsodium's documentation on its key exchange features](https://download.libsodium.org/doc/key_exchange). + +### crypto_kx_keypair + +This is functionally identical to [`crypto_box_keypair()`](#crypto_box_keypair). + +Returns a `Promise` that resolves to a `CryptographyKey` with 64 bytes. + +### crypto_kx_seed_keypair + +Generate an X25519 keypair from a seed. Unlike `crypto_kx_seedpair()`, this is +deterministic from your seed. + +**Parameters and their respective types**: + +1. `{string|Buffer}` seed + +Returns a `Promise` that resolves to a `CryptographyKey` with 64 bytes. + +### crypto_kx_client_session_keys + +Perform a key exchange from the client's perspective. + +Returns an array of two CryptographyKey objects: + + * The first is meant for data sent from the server to the client (incoming decryption). + * The second is meant for data sent from the client to the server (outgoing encryption). + +**Parameters and their respective types**: + +1. `{X25519PublicKey}` client public key (yours) +2. `{X25519SecretKey}` client secret key (yours) +1. `{X25519PublicKey}` server public key (theirs) + +Returns a `Promise` that resolves to an array of two `CryptographyKey` objects. + +### crypto_kx_server_session_keys + +Perform a key exchange from the server's perspective. + +Returns an array of two CryptographyKey objects: + + * The first is meant for data sent from the client to the server (incoming decryption). + * The second is meant for data sent from the server to the client (outgoing encryption). + +**Parameters and their respective types**: + +1. `{X25519PublicKey}` server public key (yours) +2. `{X25519SecretKey}` server secret key (yours) +1. `{X25519PublicKey}` client public key (theirs) + +Returns a `Promise` that resolves to an array of two `CryptographyKey` objects. + +### Example for crypto_kx + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let clientKeypair = await sodium.crypto_box_keypair(); + let clientSecret = await sodium.crypto_box_secretkey(clientKeypair); + let clientPublic = await sodium.crypto_box_publickey(clientKeypair); + let serverKeypair = await sodium.crypto_kx_seed_keypair('Your static input goes here'); + let serverSecret = await sodium.crypto_box_secretkey(serverKeypair); + let serverPublic = await sodium.crypto_box_publickey(serverKeypair); + let clientIKey, clientOKey, serverIKey, serverOKey; + + [clientIKey, clientOKey] = await sodium.crypto_kx_client_session_keys( + clientPublic, + clientSecret, + serverPublic + ); + [serverIKey, serverOKey] = await sodium.crypto_kx_server_session_keys( + serverPublic, + serverSecret, + clientPublic + ); + + console.log({ + 'client-sees': { + 'incoming': clientIKey.getBuffer().toString('hex'), + 'outgoing': clientOKey.getBuffer().toString('hex') + }, + 'server-sees': { + 'incoming': serverIKey.getBuffer().toString('hex'), + 'outgoing': serverOKey.getBuffer().toString('hex') + } + }); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/one-time-authentication.md b/library/sodium-plus/docs/SodiumPlus/one-time-authentication.md new file mode 100644 index 000000000..16c11d0c8 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/one-time-authentication.md @@ -0,0 +1,52 @@ +## One-time authentication + +> **See also**: [Libsodium's documentation on its one-time authentication features](https://download.libsodium.org/doc/advanced/poly1305). + +### crypto_onetimeauth + +Get an authenticator for a message for a given key. + +**Important:** In order to be secure, keys must be: + +1. Secret. +2. Unpredictable. +3. Unique. + +**Parameters and their respective types**: + +1. `{string|Buffer}` message +2. `{CryptographyKey}` key + +Return a `Promise` that resolves to a `Buffer`. + +### crypto_onetimeauth_verify + +Verify an authenticator for a message for a given key. + +**Parameters and their respective types**: + +1. `{string|Buffer}` message +2. `{CryptographyKey}` key +2. `{Buffer}` tag + +Return a `Promise` that resolves to a `boolean`. + +### crypto_onetimeauth_keygen + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_auth` API. + +### Example for crypto_onetimeauth + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let plaintext = 'Your message goes here'; + let key = await sodium.crypto_onetimeauth_keygen(); + let tag = await sodium.crypto_onetimeauth(plaintext, key); + console.log(await sodium.crypto_onetimeauth_verify(plaintext, key, tag)); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/password-based-key-derivation.md b/library/sodium-plus/docs/SodiumPlus/password-based-key-derivation.md new file mode 100644 index 000000000..b5c596e42 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/password-based-key-derivation.md @@ -0,0 +1,45 @@ +## Password-based key derivation + +> **See also**: [Libsodium's documentation on Argon2](https://download.libsodium.org/doc/password_hashing/the_argon2i_function). + +### crypto_pwhash + +Derive a cryptography key from a password and salt. + +**Parameters and their respective types**: + +1. `{number}` output length +2. `{string|Buffer}` password +3. `{Buffer}` salt (16 bytes) +4. `{number}` opslimit (recommeded minimum: `2`) +5. `{number}` memlimit (recommended mimimum: `67108864` a.k.a. 64MiB) +6. `{number|null}` algorithm (recommended: `this.CRYPTO_PWHASH_ALG_DEFAULT`) + +Returns a `Promise` that resolves to a `CryptographyKey`. + +### Example for crypto_pwhash + +This example is for key derivation. Look [below](#example-for-crypto_pwhash_str) +for information about password storage/verification. + +```javascript + +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + + let password = 'correct horse battery staple'; + let salt = await sodium.randombytes_buf(16); + + let key = await sodium.crypto_pwhash( + 32, + password, + salt, + sodium.CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, + sodium.CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE + ); + console.log(key.getBuffer().toString('hex')); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/password-hashing-and-storage.md b/library/sodium-plus/docs/SodiumPlus/password-hashing-and-storage.md new file mode 100644 index 000000000..b3efd3baa --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/password-hashing-and-storage.md @@ -0,0 +1,74 @@ +## Password hashing and storage + +> **See also**: [Libsodium's documentation on its password hashing features](https://download.libsodium.org/doc/password_hashing). + +### crypto_pwhash_str + +Get a password hash (in a safe-for-storage format). + +**Parameters and their respective types**: + +1. `{string|Buffer}` password +2. `{number}` opslimit (recommeded minimum: `2`) +3. `{number}` memlimit (recommended mimimum: `67108864` a.k.a. 64MiB) + +Returns a `Promise` that resolves to a `string`. + +### crypto_pwhash_str_needs_rehash + +Does this password need to be rehashed? (i.e. have the algorithm parameters +we want changed since the hash was generated?) + +**Parameters and their respective types**: + +1. `{string}` password hash +2. `{number}` opslimit (recommeded minimum: `2`) +3. `{number}` memlimit (recommended mimimum: `67108864` a.k.a. 64MiB) + +Returns a `Promise` that resolves to a `boolean`. + +### crypto_pwhash_str_verify + +Verify a password against a known password hash. + +1. `{string|Buffer}` password +2. `{string}` password hash + +Returns a `Promise` that resolves to a `boolean`. + +### Example for crypto_pwhash_str + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let password = 'correct horse battery staple'; + + // Generating a password hash + let pwhash = await sodium.crypto_pwhash_str( + password, + sodium.CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, + sodium.CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE + ); + console.log(pwhash); + + // Check that we don't need to rotate hashes + let stale = await sodium.crypto_pwhash_str_needs_rehash( + pwhash, + sodium.CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, + sodium.CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE + ); + if (stale) { + console.warn('Password needs to be rehashed'); + } + + // Password validation + if (await sodium.crypto_pwhash_str_verify(password, pwhash)) { + console.log("Password valid"); + } else { + console.error("Incorrect password"); + } +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/randomness.md b/library/sodium-plus/docs/SodiumPlus/randomness.md new file mode 100644 index 000000000..182753c10 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/randomness.md @@ -0,0 +1,43 @@ + +## Randomness + +> **See also:** [Libsodium's documentation on its random data features](https://download.libsodium.org/doc/generating_random_data). + +### randombytes_buf + +Obtain a buffer filled with random bytes. + +**Parameters and their respective types**: + +1. `{number}` Size of buffer to return + +Returns a `Promise` that resolves to a `Buffer` + +### randombytes_uniform + +Generate an integer between 0 and upperBound (non-inclusive). + +For example, randombytes_uniform(10) returns an integer between 0 and 9. + +**Parameters and their respective types**: + +1. `{number}` Upper bound + +Returns a `Promise` that resolves to a `number`. + +### Example for randombytes + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + + let someBuf = await sodium.randombytes_buf(32); + console.log(someBuf.toString('hex')); + + let someInt = await sodium.randombytes_uniform(65536); + console.log(someInt); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/scalar-multiplication.md b/library/sodium-plus/docs/SodiumPlus/scalar-multiplication.md new file mode 100644 index 000000000..07c20f6b5 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/scalar-multiplication.md @@ -0,0 +1,49 @@ +## Scalar multiplication over Curve25519 + +> **See also**: [Libsodium's documentation on its scalar multiplication features](https://download.libsodium.org/doc/advanced/scalar_multiplication). + +### crypto_scalarmult + +Elliptic Curve Diffie-Hellman key exchange over Curve25519. +You probably don't want to ever use this directly. + +**Parameters and their respective types**: + +1. `{X25519SecretKey}` your secret key +2. `{X25519PublicKey}` their public key + +Returns a `Promise` that resolves to a `CryptographyKey`. + +### crypto_scalarmult_base + +Generate an X25519PublicKey from an X25519SecretKey. + +**Parameters and their respective types**: + +1. `{X25519SecretKey}` your secret key + +Returns a `Promise` that resolves to an `X25519PublicKey`. + +### Example for crypto_scalarmult + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let aliceKeypair = await sodium.crypto_box_keypair(); + let aliceSecret = await sodium.crypto_box_secretkey(aliceKeypair); + let alicePublic = await sodium.crypto_box_publickey(aliceKeypair); + let bobKeypair = await sodium.crypto_box_keypair(); + let bobSecret = await sodium.crypto_box_secretkey(bobKeypair); + let bobPublic = await sodium.crypto_scalarmult_base(bobSecret); + + let aliceToBob = await sodium.crypto_scalarmult(aliceSecret, bobPublic); + let bobToAlice = await sodium.crypto_scalarmult(bobSecret, alicePublic); + console.log({ + 'alice-to-bob': aliceToBob.getBuffer().toString('hex'), + 'bob-to-alice': bobToAlice.getBuffer().toString('hex') + }); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/sealed-boxes.md b/library/sodium-plus/docs/SodiumPlus/sealed-boxes.md new file mode 100644 index 000000000..54ce8bb50 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/sealed-boxes.md @@ -0,0 +1,48 @@ +## Sealed boxes + +> **See also**: [Libsodium's documentation on its sealed boxes features](https://download.libsodium.org/doc/public-key_cryptography/sealed_boxes). + +### crypto_box_seal + +Anonymous public-key encryption. (Message integrity is still assured.) + +**Parameters and their respective types**: + +1. `{string|Buffer}` plaintext +2. `{X25519PublicKey}` public key + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_box_seal_open + +Anonymous public-key decryption. (Message integrity is still assured.) + +**Parameters and their respective types**: + +1. `{Buffer}` ciphertext +2. `{X25519PublicKey}` public key +3. `{X25519SecretKey}` secret key + +Returns a `Promise` that resolves to a `Buffer`. + +### Example for crypto_box_seal + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let aliceKeypair = await sodium.crypto_box_keypair(); + let aliceSecret = await sodium.crypto_box_secretkey(aliceKeypair); + let alicePublic = await sodium.crypto_box_publickey(aliceKeypair); + + let plaintext = 'Your message goes here'; + + let ciphertext = await sodium.crypto_box_seal(plaintext, alicePublic); + console.log(ciphertext); + + let decrypted = await sodium.crypto_box_seal_open(ciphertext, alicePublic, aliceSecret); + console.log(decrypted.toString()); +})(); +```
\ No newline at end of file diff --git a/library/sodium-plus/docs/SodiumPlus/shared-key-authenticated-encryption.md b/library/sodium-plus/docs/SodiumPlus/shared-key-authenticated-encryption.md new file mode 100644 index 000000000..688570933 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/shared-key-authenticated-encryption.md @@ -0,0 +1,62 @@ +## Shared-key authenticated encryption + +> **See also**: [Libsodium's documentation on its shared-key authenticated encryption features](https://download.libsodium.org/doc/secret-key_cryptography/secretbox). + +### crypto_secretbox + +Shared-key authenticated encryption. + +**Parameters and their respective types**: + +1. `{string|Buffer}` Plaintext +2. `{string|Buffer}` nonce (must be 24 bytes) +3. `{CryptographyKey}` key + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_secretbox_open + +Shared-key authenticated decryption. + +**Parameters and their respective types**: + +1. `{string|Buffer}` Ciphertext +2. `{string|Buffer}` nonce (must be 24 bytes) +3. `{CryptographyKey}` key + +Returns a `Promise` that resolves to a `Buffer`. +Throws a `SodiumError` on decryption failure. + +### crypto_secretbox_keygen + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_secretbox` API. + +### Example for crypto_secretbox + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let plaintext = 'Your message goes here'; + let key = await sodium.crypto_secretbox_keygen(); + let nonce = await sodium.randombytes_buf(24); + let ciphertext = await sodium.crypto_secretbox( + plaintext, + nonce, + key + ); + + console.log(ciphertext.toString('hex')); + + let decrypted = await sodium.crypto_secretbox_open( + ciphertext, + nonce, + key + ); + + console.log(decrypted.toString()); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/shared-key-authentication.md b/library/sodium-plus/docs/SodiumPlus/shared-key-authentication.md new file mode 100644 index 000000000..8dbd9a6a6 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/shared-key-authentication.md @@ -0,0 +1,46 @@ +## Shared-key authentication + +> **See also**: [Libsodium's documentation on its shared-key authentication features](https://download.libsodium.org/doc/secret-key_cryptography/secret-key_authentication). + +### crypto_auth + +Get an authenticator for a message for a given key. + +**Parameters and their respective types**: + +1. `{string|Buffer}` message +2. `{CryptographyKey}` key + +Return a `Promise` that resolves to a `Buffer`. + +### crypto_auth_verify + +Verify an authenticator for a message for a given key. + +**Parameters and their respective types**: + +1. `{string|Buffer}` message +2. `{CryptographyKey}` key +2. `{Buffer}` mac + +Return a `Promise` that resolves to a `boolean`. + +### crypto_auth_keygen + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_auth` API. + +### Example for crypto_auth + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let plaintext = 'Your message goes here'; + let key = await sodium.crypto_auth_keygen(); + let mac = await sodium.crypto_auth(plaintext, key); + console.log(await sodium.crypto_auth_verify(plaintext, key, mac)); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/short-input-hashing.md b/library/sodium-plus/docs/SodiumPlus/short-input-hashing.md new file mode 100644 index 000000000..54c910afe --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/short-input-hashing.md @@ -0,0 +1,39 @@ +## Short-input hashing + +> **See also**: [Libsodium's documentation on its short-input hashing features](https://download.libsodium.org/doc/hashing/short-input_hashing). + +### crypto_shorthash + +Calculate a fast hash for short inputs. + +**Parameters and their respective types**: + +1. `{string|Buffer}` input +3. `{CryptographyKey}` key + +Returns a `Promise` that resolves to a `Buffer`. + +### crypto_shorthash_keygen + +Returns a `CryptographyKey` object containing a key appropriate +for the `crypto_shorthash` API. + +### Example for crypto_shorthash + +> **Warning:** You probably want [`crypto_generichash()`](general-purpose-cryptographic-hash.md) +> for most use-cases. `crypto_shorthash()` does not offer collision resistance. + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let key = await sodium.crypto_shorthash_keygen(); + let mapped = {}; + mapped['foo'] = (await sodium.crypto_shorthash('foo', key)).toString('hex'); + mapped['bar'] = (await sodium.crypto_shorthash('bar', key)).toString('hex'); + mapped['baz'] = (await sodium.crypto_shorthash('baz', key)).toString('hex'); + console.log(mapped); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/stream-ciphers.md b/library/sodium-plus/docs/SodiumPlus/stream-ciphers.md new file mode 100644 index 000000000..3dc8d47b1 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/stream-ciphers.md @@ -0,0 +1,55 @@ +## Stream Ciphers + +> **See also**: [Libsodium's documentation on its stream cipher features](https://download.libsodium.org/doc/advanced/stream_ciphers/xsalsa20). + +### crypto_stream + +Obtain an arbitrary-length stream of pseudorandom bytes from a given +nonce and key. + +**Parameters and their respective types**: + +1. `{number}` length +2. `{Buffer}` nonce (must be 24 bytes) +3. `{CryptographyKey}` key + +Returns a `Promise` that resolves to a `Buffer` containing +the pseudorandom bytes. + +### crypto_stream_xor + +Encrypt a message with a given nonce and key. + +> [**Danger: Unauthenticated encryption!**](https://tonyarcieri.com/all-the-crypto-code-youve-ever-written-is-probably-broken) +> Without a subsequent message authentication strategy, this is vulnerable to +> chosen-ciphertext attacks. Proceed with caution! + +**Parameters and their respective types**: + +1. `{string|Buffer}` plaintext +2. `{Buffer}` nonce (must be 24 bytes) +3. `{CryptographyKey}` key + +Returns a `Promise` that resolves to a `Buffer` containing +the encrypted bytes. + +### Example for crypto_stream + +```javascript +const { SodiumPlus } = require('sodium-plus'); + +let sodium; +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let key = await sodium.crypto_stream_keygen(); + let iv = await sodium.randombytes_buf(24); + let output = await sodium.crypto_stream(64, iv, key); + console.log(output); + + iv = await sodium.randombytes_buf(24); + let plaintext = 'This is a secret message'; + let ciphertext = await sodium.crypto_stream_xor(plaintext, iv, key); + let decrypted = await sodium.crypto_stream_xor(ciphertext, iv, key); + console.log(decrypted.toString()); +})(); +``` diff --git a/library/sodium-plus/docs/SodiumPlus/utilities.md b/library/sodium-plus/docs/SodiumPlus/utilities.md new file mode 100644 index 000000000..43d493b88 --- /dev/null +++ b/library/sodium-plus/docs/SodiumPlus/utilities.md @@ -0,0 +1,45 @@ +## Utilities + +### sodium_bin2hex + +Encode data into a hexadecimal string. + +**Parameters and their respective types**: + +1. `{string|Buffer}` non-hex-encoded input + +Returns a `Promise` that resolves to a `string`. + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let buf = await sodium.randombytes_buf(32); + + console.log(await sodium.sodium_bin2hex(buf)); +})(); +``` + +### sodium_hex2bin + +Decode data from a hexadecimal string to a `Buffer`. + +**Parameters and their respective types**: + +1. `{string|Buffer}` hex-encoded input + +Returns a `Promise` that resolves to a `Buffer`. + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; + +(async function () { + if (!sodium) sodium = await SodiumPlus.auto(); + let hex = '491d40c4924ba547d6f0bda9da77a539391decdc'; + + console.log(await sodium.sodium_hex2bin(hex)); +})(); +``` |