diff options
Diffstat (limited to 'library/sodium-plus/docs')
21 files changed, 1512 insertions, 0 deletions
diff --git a/library/sodium-plus/docs/README.md b/library/sodium-plus/docs/README.md new file mode 100644 index 000000000..fad31de3d --- /dev/null +++ b/library/sodium-plus/docs/README.md @@ -0,0 +1,99 @@ +# Table of Contents + +* [Table of Contents](#table-of-contents) (you are here) +* [Getting Started](getting-started.md#getting-started) + * [CryptographyKey](getting-started.md#cryptographykey) + * [Sodium-Plus in the Browser](getting-started.md#sodium-plus-in-the-browser) +* [SodiumPlus Methods](SodiumPlus#sodiumplus-methods) + * [AEAD (XChaCha20-Poly1305)](SodiumPlus/AEAD.md#aead) + * [crypto_aead_xchacha20poly1305_ietf_decrypt](SodiumPlus/AEAD.md#crypto_aead_xchacha20poly1305_ietf_decrypt) + * [crypto_aead_xchacha20poly1305_ietf_encrypt](SodiumPlus/AEAD.md#crypto_aead_xchacha20poly1305_ietf_encrypt) + * [crypto_aead_xchacha20poly1305_ietf_keygen](SodiumPlus/AEAD.md#crypto_aead_xchacha20poly1305_ietf_keygen) + * [Example for crypto_aead_xchacha20poly1305_ietf_*](SodiumPlus/AEAD.md#example-for-crypto_aead_xchacha20poly1305_ietf_) + * [Shared-key authentication](SodiumPlus/shared-key-authentication.md) + * [crypto_auth](SodiumPlus/shared-key-authentication.md#crypto_auth) + * [crypto_auth_verify](SodiumPlus/shared-key-authentication.md#crypto_auth_verify) + * [crypto_auth_keygen](SodiumPlus/shared-key-authentication.md#crypto_auth_keygen) + * [Example for crypto_auth](SodiumPlus/shared-key-authentication.md#example-for-crypto_auth) + * [Authenticated public-key encryption](SodiumPlus/authenticated-public-key-encryption.md) + * [crypto_box](SodiumPlus/authenticated-public-key-encryption.md#crypto_box) + * [crypto_box_open](SodiumPlus/authenticated-public-key-encryption.md#crypto_box_open) + * [crypto_box_keypair](SodiumPlus/authenticated-public-key-encryption.md#crypto_box_keypair) + * [crypto_box_keypair_from_secretkey_and_secretkey](SodiumPlus/authenticated-public-key-encryption.md#crypto_box_keypair_from_secretkey_and_secretkey) + * [crypto_box_publickey](SodiumPlus/authenticated-public-key-encryption.md#crypto_box_publickey) + * [crypto_box_secretkey](SodiumPlus/authenticated-public-key-encryption.md#crypto_box_secretkey) + * [crypto_box_publickey_from_secretkey](SodiumPlus/authenticated-public-key-encryption.md#crypto_box_publickey_from_secretkey) + * [Example for crypto_box](SodiumPlus/authenticated-public-key-encryption.md#example-for-crypto_box) + * [Sealed boxes (anonymous public-key encryption)](SodiumPlus/sealed-boxes.md) + * [crypto_box_seal](SodiumPlus/sealed-boxes.md#crypto_box_seal) + * [crypto_box_seal_open](SodiumPlus/sealed-boxes.md#crypto_box_seal_open) + * [Example for crypto_box_seal](SodiumPlus/sealed-boxes.md#example-for-crypto_box_seal) + * [General-purpose cryptographic hash](SodiumPlus/general-purpose-cryptographic-hash.md) + * [crypto_generichash](SodiumPlus/general-purpose-cryptographic-hash.md#crypto_generichash) + * [crypto_generichash_init](SodiumPlus/general-purpose-cryptographic-hash.md#crypto_generichash_init) + * [crypto_generichash_update](SodiumPlus/general-purpose-cryptographic-hash.md#crypto_generichash_update) + * [crypto_generichash_final](SodiumPlus/general-purpose-cryptographic-hash.md#crypto_generichash_final) + * [crypto_generichash_keygen](SodiumPlus/general-purpose-cryptographic-hash.md#crypto_generichash_keygen) + * [Example for crypto_generichash](SodiumPlus/general-purpose-cryptographic-hash.md#example-for-crypto_generichash) + * [Key derivation](SodiumPlus/key-derivation.md) + * [crypto_kdf_derive_from_key](SodiumPlus/key-derivation.md#crypto_kdf_derive_from_key) + * [crypto_kdf_keygen](SodiumPlus/key-derivation.md#crypto_kdf_keygen) + * [Example for crypto_kdf](SodiumPlus/key-derivation.md#example-for-crypto_kdf) + * [Key exchange](SodiumPlus/key-exchange.md) + * [crypto_kx_keypair](SodiumPlus/key-exchange.md#crypto_kx_keypair) + * [crypto_kx_seed_keypair](SodiumPlus/key-exchange.md#crypto_kx_seed_keypair) + * [crypto_kx_client_session_keys](SodiumPlus/key-exchange.md#crypto_kx_client_session_keys) + * [crypto_kx_server_session_keys](SodiumPlus/key-exchange.md#crypto_kx_server_session_keys) + * [Example for crypto_kx](SodiumPlus/key-exchange.md#example-for-crypto_kx) + * [One-time authentication](SodiumPlus/one-time-authentication.md) + * [crypto_onetimeauth](SodiumPlus/one-time-authentication.md#crypto_onetimeauth) + * [crypto_onetimeauth_verify](SodiumPlus/one-time-authentication.md#crypto_onetimeauth_verify) + * [crypto_onetimeauth_keygen](SodiumPlus/one-time-authentication.md#crypto_onetimeauth_keygen) + * [Example for crypto_onetimeauth](SodiumPlus/one-time-authentication.md#example-for-crypto_onetimeauth) + * [Password-based key derivation](SodiumPlus/password-based-key-derivation.md) + * [crypto_pwhash](SodiumPlus/password-based-key-derivation.md#crypto_pwhash) + * [Example for crypto_pwhash](SodiumPlus/password-based-key-derivation.md#example-for-crypto_pwhash) + * [Password hashing and storage](SodiumPlus/password-hashing-and-storage.md) + * [crypto_pwhash_str](SodiumPlus/password-hashing-and-storage.md#crypto_pwhash_str) + * [crypto_pwhash_str_needs_rehash](SodiumPlus/password-hashing-and-storage.md#crypto_pwhash_str_needs_rehash) + * [crypto_pwhash_str_verify](SodiumPlus/password-hashing-and-storage.md#crypto_pwhash_str_verify) + * [Example for crypto_pwhash_str](SodiumPlus/password-hashing-and-storage.md#example-for-crypto_pwhash_str) + * [Scalar multiplication over Curve25519 (advanced)](SodiumPlus/scalar-multiplication.md) + * [crypto_scalarmult](SodiumPlus/scalar-multiplication.md#crypto_scalarmult) + * [crypto_scalarmult_base](SodiumPlus/scalar-multiplication.md#crypto_scalarmult_base) + * [Example for crypto_scalarmult](SodiumPlus/scalar-multiplication.md#example-for-crypto_scalarmult) + * [Shared-key authenticated encryption](SodiumPlus/shared-key-authenticated-encryption.md) + * [crypto_secretbox](SodiumPlus/shared-key-authenticated-encryption.md#crypto_secretbox) + * [crypto_secretbox_open](SodiumPlus/shared-key-authenticated-encryption.md#crypto_secretbox_open) + * [crypto_secretbox_keygen](SodiumPlus/shared-key-authenticated-encryption.md#crypto_secretbox_keygen) + * [Example for crypto_secretbox](SodiumPlus/shared-key-authenticated-encryption.md#example-for-crypto_secretbox) + * [Encrypted streams](SodiumPlus/encrypted-streams.md) + * [crypto_secretstream_xchacha20poly1305_init_push](SodiumPlus/encrypted-streams.md#crypto_secretstream_xchacha20poly1305_init_push) + * [crypto_secretstream_xchacha20poly1305_init_pull](SodiumPlus/encrypted-streams.md#crypto_secretstream_xchacha20poly1305_init_pull) + * [crypto_secretstream_xchacha20poly1305_push](SodiumPlus/encrypted-streams.md#crypto_secretstream_xchacha20poly1305_push) + * [crypto_secretstream_xchacha20poly1305_pull](SodiumPlus/encrypted-streams.md#crypto_secretstream_xchacha20poly1305_pull) + * [crypto_secretstream_xchacha20poly1305_keygen](SodiumPlus/encrypted-streams.md#crypto_secretstream_xchacha20poly1305_keygen) + * [crypto_secretstream_xchacha20poly1305_rekey](SodiumPlus/encrypted-streams.md#crypto_secretstream_xchacha20poly1305_rekey) + * [Example for crypto_secretstream_xchacha20poly1305](SodiumPlus/encrypted-streams.md#example-for-crypto_secretstream_xchacha20poly1305) + * [Short-input hashing](SodiumPlus/short-input-hashing.md) + * [crypto_shorthash](SodiumPlus/short-input-hashing.md#crypto_shorthash) + * [crypto_shorthash_keygen](SodiumPlus/short-input-hashing.md#crypto_shorthash_keygen) + * [Example for crypto_shorthash](SodiumPlus/short-input-hashing.md#example-for-crypto_shorthash) + * [Digital signatures](SodiumPlus/digital-signatures.md) + * [crypto_sign](SodiumPlus/digital-signatures.md#crypto_sign) + * [crypto_sign_open](SodiumPlus/digital-signatures.md#crypto_sign_open) + * [crypto_sign_detached](SodiumPlus/digital-signatures.md#crypto_sign_detached) + * [crypto_sign_verify_detached](SodiumPlus/digital-signatures.md#crypto_sign_verify_detached) + * [crypto_sign_keypair](SodiumPlus/digital-signatures.md#crypto_sign_keypair) + * [crypto_sign_publickey](SodiumPlus/digital-signatures.md#crypto_sign_publickey) + * [crypto_sign_secretkey](SodiumPlus/digital-signatures.md#crypto_sign_secretkey) + * [crypto_sign_ed25519_sk_to_curve25519](SodiumPlus/digital-signatures.md#crypto_sign_ed25519_sk_to_curve25519) + * [crypto_sign_ed25519_pk_to_curve25519](SodiumPlus/digital-signatures.md#crypto_sign_ed25519_pk_to_curve25519) + * [Example for crypto_sign](SodiumPlus/digital-signatures.md#example-for-crypto_sign) + * [Randomness](SodiumPlus/randomness.md) + * [randombytes_buf](SodiumPlus/randomness.md#randombytes_buf) + * [randombytes_uniform](SodiumPlus/randomness.md#randombytes_uniform) + * [Example for randombytes](SodiumPlus/randomness.md#example-for-randombytes) + * [Utilities](SodiumPlus/utilities.md) + * [sodium_bin2hex](SodiumPlus/utilities.md#sodium_bin2hex) + * [sodium_hex2bin](SodiumPlus/utilities.md#sodium_bin2hex) 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)); +})(); +``` diff --git a/library/sodium-plus/docs/getting-started.md b/library/sodium-plus/docs/getting-started.md new file mode 100644 index 000000000..d599f7928 --- /dev/null +++ b/library/sodium-plus/docs/getting-started.md @@ -0,0 +1,100 @@ +# Getting Started + +You always want to use `SodiumPlus` from within an asynchronous function. + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; +async function myFunction() { + if (!sodium) sodium = await SodiumPlus.auto(); + + // Now you can use sodium.FUNCTION_NAME_HERE() +} +``` + +When you use `await SodiumPlus.auto()`, this will automatically load in the best +backend available for your platform. This is the recommended way to use SodiumPlus. + +If you'd rather use a specific backend, you can do the following: + +```javascript +const { SodiumPlus, SodiumUtil, getBackendObject } = require('sodium-plus'); +let sodium; + +async function myFunction() { + if (!sodium) { + let backend = getBackendObject('LibsodiumWrappers'); + SodiumUtil.populateConstants(backend); + sodium = new SodiumPlus(backend); + } + + // Now you can use sodium.FUNCTION_NAME_HERE() +} +``` + +To discover what backend you're using at runtime, invoke the `getBackendName()` +method on the `SodiumPlus` object, like so: + + +```javascript +const { SodiumPlus } = require('sodium-plus'); +let sodium; +async function whichBackend() { + if (!sodium) sodium = await SodiumPlus.auto(); + + console.log(sodium.getBackendName()); +} +``` + +## CryptographyKey + +All cryptographic secrets are contained within a `CryptographyKey` object +(or one of its derived classes). You can create and access them like so: + +```javascript +const { CryptographyKey } = require('sodium-plus'); +let buf = Buffer.alloc(32); +let key = new CryptographyKey(buf); + +// If you do this, the internal buffer will not be visible! +console.log(key); +// CryptographyKey {} + +// You'll need to do this instead: +console.log(key.getBuffer()); +// <Buffer d9 ff 60 6b ff 96 f6 26 05 53 07 39 ef b5 a5 8b 26 0c 72 9e 1b b7 e4 97 fe 09 de 07 86 8a 0c b6> +``` + +The following classes inherit from `CryptographyKey`: + +* `Ed25519PublicKey` -- Ed25519 public key +* `Ed25519SecretKey` -- Ed25519 secret key +* `X25519PublicKey` -- X25519 public key +* `X25519SecretKey` -- X25519 secret key + +## Sodium-Plus in the Browser + +First, download [sodium-plus.min.js](../dist) (or find it on a CDN you trust). + +Next, include the following script tags in your web page: + +```html5 +<script src="sodium-plus.min.js"></script> +<script> +(async function() { + if (!window.sodium) window.sodium = await SodiumPlus.auto(); + + // You can now use the sodium object here. + + // Just some example code to ensure it's running: + let random = await sodium.randombytes_buf(32); + let hash = await sodium.crypto_generichash('hello world'); + console.log({ + 'random': random.toString('hex'), + 'hash': hash.toString('hex') + }); +})(); +</script> +``` + +You can then use the `sodium` API as documented. |