Low level bindings for libsodium.
npm install sodium-native
The goal of this project is to be thin, stable, unopionated wrapper around libsodium.
All methods exposed are more or less a direct translation of the libsodium c-api. This means that most data types are buffers and you have to manage allocating return values and passing them in as arguments intead of receiving them as return values.
This makes this API harder to use than other libsodium wrappers out there, but also means that you'll be able to get a lot of perf / memory improvements as you can do stuff like inline encryption / decryption, re-use buffers etc.
This also makes this library useful as a foundation for more high level crypto abstractions that you want to make.
var sodium = require('sodium-native')
var nonce = new Buffer(sodium.crypto_secretbox_NONCEBYTES)
var key = new Buffer(sodium.crypto_secretbox_KEYBYTES)
var message = new Buffer('Hello, World!')
var cipher = new Buffer(message.length + sodium.crypto_secretbox_MACBYTES)
sodium.randombytes_buf(nonce) // insert random data into nonce
sodium.randombytes_buf(key) // insert random data into key
// encrypted message is stored in cipher.
sodium.crypto_secretbox_easy(cipher, message, nonce, key)
console.log('Encrypted message:', cipher)
var plainText = new Buffer(cipher.length - sodium.crypto_secretbox_MACBYTES)
if (!sodium.crypto_secretbox_open_easy(plainText, cipher, nonce, key)) {
console.log('Decryption failed!')
} else {
console.log('Decrypted message:', plainText, '(' + plainText.toString() + ')')
}
Loads the bindings. If you get an module version error you probably need to reinstall the module because you switched node versions.
Bindings to the secure memory API. See the libsodium "Securing memory allocations" docs for more information.
Zero out the data in buffer
.
Lock the memory contained in buffer
Unlock previously mlock
ed memory contained in buffer
. This will also memzero
buffer
Allocate a buffer of size
which is memory protected. See libsodium docs for details. Be aware that many Buffer methods may break the security guarantees of sodium.malloc
'ed memory.
Make buffer
allocated using sodium.malloc
inaccessible, crashing the process if any access is attempted.
Note that this will have no effect for normal Buffer
s.
Make buffer
allocated using sodium.malloc
read-only, crashing the process if any writing is attempted.
Note that this will have no effect for normal Buffer
s.
Make buffer
allocated using sodium.malloc
read-write, undoing mprotect_noaccess
or mprotect_readonly
.
Note that this will have no effect for normal Buffer
s.
Bindings to the random data generation API. See the libsodium randombytes_buf docs for more information.
Fill buffer
with random data.
Bindings for the crypto_sign API. See the libsodium crypto_sign docs for more information.
Create a new keypair based on a seed.
publicKey
should be a buffer with lengthcrypto_sign_PUBLICKEYBYTES
.secretKey
should be a buffer with lengthcrypto_sign_SECRETKEYBYTES
.seed
should be a buffer with lengthcrypto_sign_SEEDBYTES
.
The generated public and secret key will be stored in passed in buffers.
Create a new keypair.
publicKey
should be a buffer with lengthcrypto_sign_PUBLICKEYBYTES
.secretKey
should be a buffer with lengthcrypto_sign_SECRETKEYBYTES
.
The generated public and secret key will be stored in passed in buffers.
Sign a message.
signedMessage
should be a buffer with lengthcrypto_sign_BYTES + message.length
.message
should be a buffer of any length.secretKey
should be a secret key.
The generated signed message will be stored in signedMessage
.
Verify and open a message.
message
should be a buffer with lengthsignedMessage - crypto_sign_BYTES
.signedMessage
at leastcrypto_sign_BYTES
length.publicKey
should be a public key.
Will return true
if the message could be verified. Otherwise false
.
If verified the originally signed message is stored in the message
buffer.
Same as crypto_sign
except it only stores the signature.
signature
should be a buffer with lengthcrypto_sign_BYTES
.message
should be a buffer of any length.secretKey
should be a secret key.
The generated signature is stored in signature
.
Verify a signature.
signature
should be a buffer with lengthcrypto_sign_BYTES
.message
should be a buffer of any length.publicKey
should be a public key.
Will return true
if the message could be verified. Otherwise false
.
####`crypto_sign_ed25519_pk_to_curve25519(curve_pk, ed_pk)
convert a ed25519 public key to curve25519 (which can be used with box
and scalarmult
)
curve_pk
should be a buffer with lengthcrypto_box_PUBLICKEYBYTES
ed_pk
should be a buffer with lengthcrypto_sign_PUBLICKEYBYTES
####`crypto_sign_ed25519_sk_to_curve25519(curve_sk, ed_sk)
convert a ed25519 secret key to curve25519 (which can be used with box
and scalarmult
)
curve_sk
should be a buffer with lengthcrypto_box_SECRETKEYBYTES
ed_sk
should be a buffer with lengthcrypto_sign_SECRETKEYBYTES
Bindings for the crypto_generichash API. See the libsodium crypto_generichash docs for more information.
Hash a value with an optional key using the generichash method.
output
should be a buffer with length withincrypto_generichash_BYTES_MIN
-crypto_generichash_BYTES_MAX
.input
should be a buffer of any length.key
is an optional buffer of length withincrypto_generichash_KEYBYTES_MIN
-crypto_generichash_KEYBYTES_MAX
.
The generated hash is stored in output
.
Also exposes crypto_generichash_BYTES
and crypto_generichash_KEYBYTES
that can be used as "default" buffer sizes.
Same as crypto_generichash
except this hashes an array of buffers instead of a single one.
Create a generichash instance that can hash a stream of input buffers.
key
is an optional buffer as above.outputLength
the buffer size of your output.
Update the instance with a new piece of data.
input
should be a buffer of any size.
Finalize the instance.
output
should be a buffer as above with the same length you gave when creating the instance.
The generated hash is stored in output
.
Bindings for the crypto_box API. See the libsodium crypto_box docs for more information.
Create a new keypair based on a seed.
publicKey
should be a buffer with lengthcrypto_box_PUBLICKEYBYTES
.secretKey
should be a buffer with lengthcrypto_box_SECRETKEYBYTES
.seed
should be a buffer with lengthcrypto_box_SEEDBYTES
.
The generated public and secret key will be stored in passed in buffers.
Create a new keypair.
publicKey
should be a buffer with lengthcrypto_box_PUBLICKEYBYTES
.secretKey
should be a buffer with lengthcrypto_box_SECRETKEYBYTES
.
The generated public and secret key will be stored in passed in buffers.
Encrypt a message.
cipher
should be a buffer with lengthmessage.length
.mac
should be a buffer with lengthcrypto_box_MACBYTES
.message
should be a buffer of any length.nonce
should be a buffer with lengthcrypto_box_NONCEBYTES
.publicKey
should be a public key.secretKey
should be a secret key.
The encrypted message will be stored in cipher
and the authentification code will be stored in mac
.
Same as crypto_box_detached
except it encodes the mac in the message.
cipher
should be a buffer with lengthmessage.length + crypto_box_MACBYTES
.message
should be a buffer of any length.nonce
should be a buffer with lengthcrypto_box_NONCEBYTES
.publicKey
should be a public key.secretKey
should be a secret key.
The encrypted message and authentification code will be stored in cipher
.
Decrypt a message.
message
should be a buffer with lengthcipher.length
.mac
should be a buffer with lengthcrypto_box_MACBYTES
.cipher
should be a buffer of any length.nonce
should be a buffer with lengthcrypto_box_NONCEBYTES
.publicKey
should be a public key.secretKey
should be a secret key.
Returns true
if the message could be decrypted. Otherwise false
.
The decrypted message will be stored in message
.
Decrypt a message encoded with the easy method.
message
should be a buffer with lengthcipher.length
.cipher
should be a buffer with length at leastcrypto_box_MACBYTES
.nonce
should be a buffer with lengthcrypto_box_NONCEBYTES
.publicKey
should be a public key.secretKey
should be a secret key.
Returns true
if the message could be decrypted. Otherwise false
.
The decrypted message will be stored in message
.
Bindings for the crypto_box_seal API. See the libsodium crypto_box_seal docs for more information.
Keypairs can be generated with crypto_box_keypair()
or crypto_box_seed_keypair()
.
Encrypt a message in a sealed box using a throwaway keypair. The ciphertext cannot be associated with the sender due to the sender's key being a single use keypair that is overwritten during encryption.
cipher
should be a buffer with length at leastmessage.length + crypto_box_SEALBYTES
.message
should be a buffer with any length.publicKey
should be the receipent's public key.
Decrypt a message encoded with the sealed box method.
message
should be a buffer with length at leastcipher.length - crypto_box_SEALBYTES
.cipher
should be a buffer with length at leastcrypto_box_SEALBYTES
.publicKey
should be the receipient's public key.secretKey
should be the receipient's secret key.
Note: the keypair of the recipient is required here, both public and secret key.
This is because during encryption the recipient's public key is used to generate
the nonce. The throwaway public key generated by the sender is stored in the first
crypto_box_PUBLICKEYBYTE
's of the ciphertext.
Bindings for the crypto_secretbox API. See the libsodium crypto_secretbox docs for more information.
Encrypt a message.
cipher
should be a buffer with lengthmessage.length
.mac
should be a buffer with lengthcrypto_secretbox_MACBYTES
.message
should be a buffer of any length.nonce
should be a buffer with lengthcrypto_secretbox_NONCEBYTES
.secretKey
should be a secret key with legnthcrypto_secretbox_KEYBYTES
.
The encrypted message will be stored in cipher
and the authentification code will be stored in mac
.
Same as crypto_secretbox_detached
except it encodes the mac in the message.
cipher
should be a buffer with lengthmessage.length + crypto_secretbox_MACBYTES
.message
should be a buffer of any length.nonce
should be a buffer with lengthcrypto_secretbox_NONCEBYTES
.secretKey
should be a secret key with legnthcrypto_secretbox_KEYBYTES
.
Decrypt a message.
message
should be a buffer with lengthcipher.length
.mac
should be a buffer with lengthcrypto_secretbox_MACBYTES
.cipher
should be a buffer of any length.nonce
should be a buffer with lengthcrypto_secretbox_NONCEBYTES
.secretKey
should be a secret key.
Returns true
if the message could be decrypted. Otherwise false
.
The decrypted message will be stored in message
.
Decrypt a message encoded with the easy method.
message
should be a buffer with lengthcipher.length
.cipher
should be a buffer with length at leastcrypto_secretbox_MACBYTES
.nonce
should be a buffer with lengthcrypto_secretbox_NONCEBYTES
.secretKey
should be a secret key.
Returns true
if the message could be decrypted. Otherwise false
.
The decrypted message will be stored in message
.
Bindings for the crypto_stream API. See the libsodium crypto_stream docs for more information.
Generate random data based on a nonce and key into the cipher.
cipher
should be a buffer of any size.nonce
should be a buffer with lengthcrypto_stream_NONCEBYTES
.key
should be a secret key with lengthcrypto_stream_KEYBYTES
.
The generated data is stored in cipher
.
Encrypt, but not authenticate, a message based on a nonce and key
cipher
should be a buffer with lengthmessage.length
.message
should be a buffer of any size.nonce
should be a buffer with lengthcrypto_stream_NONCEBYTES
.key
should be a secret key with lengthcrypto_stream_KEYBYTES
.
The encrypted data is stored in cipher
. To decrypt, swap cipher
and message
.
Also supports in-place encryption where you use the same buffer as cipher
and message
.
Encryption defaults to XSalsa20, use crypto_stream_chacha20_xor
if you want
to encrypt/decrypt with ChaCha20 instead.
A streaming instance to the crypto_stream_xor
api. Pass a nonce and key in the constructor.
Encryption defaults to XSalsa20, use crypto_stream_chacha20_xor_instance
if
you want to encrypt/decrypt with ChaCha20 instead.
Encrypt the next message
Finalize the stream. Zeros out internal state.
Bindings for the crypto_auth API. See the libsodium crypto_auth docs for more information.
Create an authentication token.
output
should be a buffer of lengthcrypto_auth_BYTES
.input
should be a buffer of any size.key
should be a buffer of lenghtcrypto_auth_KEYBYTES
.
The generated token is stored in output
.
Verify a token.
output
should be a buffer of lengthcrypto_auth_BYTES
.input
should be a buffer of any size.key
should be a buffer of lenghtcrypto_auth_KEYBYTES
.
Returns true
if the token could be verified. Otherwise false
.
Bindings for the crypto_onetimeauth API. See the libsodium crypto_onetimeauth docs for more information.
Create a authentication token based on a onetime key.
output
should be a buffer of lengthcrypto_onetimauth_BYTES
.input
should be a buffer of any size.key
should be a buffer of lenghtcrypto_onetimeauth_KEYBYTES
.
The generated token is stored in output
.
Verify a token.
output
should be a buffer of lengthcrypto_onetimeauth_BYTES
.input
should be a buffer of any size.key
should be a buffer of lenghtcrypto_onetimeauth_KEYBYTES
.
Returns true
if the token could be verified. Otherwise false
.
Create an instance that create a token from a onetime key and a stream of input data.
key
should be a buffer of lengthcrypto_onetimeauth_KEYBYTES
.
Update the instance with a new piece of data.
input
should be a buffer of any size.
Finalize the instance.
output
should be a buffer of lengthcrypto_onetimeauth_BYTES
.
The generated hash is stored in output
.
Bindings for the crypto_pwhash API. See the libsodium crypto_pwhash docs for more information.
Create a password hash.
output
should be a buffer with length withincrypto_pwhash_BYTES_MIN
-crypto_pwhash_BYTES_MAX
.password
should be a buffer of any size.salt
should be a buffer with lengthcrypto_passwd_SALTBYTES
.opslimit
should a be number containing your ops limit setting in the rangecrypto_pwhash_OPSLIMIT_MIN
-crypto_pwhash_OPSLIMIT_MAX
.memlimit
should a be number containing your mem limit setting in the rangecrypto_pwhash_MEMLIMIT_MIN
-crypto_pwhash_OPSLIMIT_MAX
.algorithm
should be a number specifying the algorithm you want to use.
Available default ops and mem limits are
crypto_pwhash_OPSLIMIT_INTERACTIVE
crypto_pwhash_OPSLIMIT_MODERATE
crypto_pwhash_OPSLIMIT_SENSITIVE
crypto_pwhash_MEMLIMIT_INTERACTIVE
crypto_pwhash_MEMLIMIT_MODERATE
crypto_pwhash_MEMLIMIT_SENSITIVE
The available algorithms are
crypto_pwhash_ALG_DEFAULT
The generated hash will be stored in output
and the entire output
buffer will be used.
Create a password hash with a random salt.
output
should be a buffer with lengthcrypto_pwhash_STRBYTES
.password
should be a buffer of any size.opslimit
should a be number containing your ops limit setting in the rangecrypto_pwhash_OPSLIMIT_MIN
-crypto_pwhash_OPSLIMIT_MAX
.memlimit
should a be number containing your mem limit setting in the rangecrypto_pwhash_MEMLIMIT_MIN
-crypto_pwhash_OPSLIMIT_MAX
.
The generated hash, settings, salt, version and algorithm will be stored in output
and the entire output
buffer will be used.
Verify a password hash generated with the above method.
str
should be a buffer with lengthcrypto_pwhash_STRBYTES
.password
should be a buffer of any size.
Returns true
if the hash could be verified with the settings contained in str
. Otherwise false
.
Just like crypto_pwhash
but will run password hashing on a seperate worker so it will not block the event loop. callback(err)
will receive any errors from the hashing but all argument errors will throw
. The resulting hash is written to output
.
Just like crypto_pwhash_str
but will run password hashing on a seperate worker so it will not block the event loop. callback(err)
will receive any errors from the hashing but all argument errors will throw
. The resulting hash with parameters is written to output
.
Just like crypto_pwhash_str_verify
but will run password hashing on a seperate worker so it will not block the event loop. callback(err, bool)
will receive any errors from the hashing but all argument errors will throw
. If the verification succeeds bool
is true
, otherwise false
. Due to an issue with libsodium err
is currently never set.
Bindings for the crypto_scalarmult API. See the libsodium crypto_scalarmult docs for more information.
Create a scalar multiplication public key based on a secret key
publicKey
should be a buffer of lengthcrypto_scalarmult_BYTES
.secretKey
should be a buffer of lengthcrypto_scalarmult_SCALARBYTES
.
The generated public key is stored in publicKey
.
Derive a shared secret from a local secret key and a remote public key.
sharedSecret
shoudl be a buffer of lengthcrypto_scalarmult_BYTES
.secretKey
should be a buffer of lengthcrypto_scalarmult_SCALARBYTES
.remotePublicKey
should be a buffer of lengthcrypto_scalarmult_BYTES
.
The generated shared secret is stored in sharedSecret
.
Bindings for the crypto_shorthash API. See the libsodium crypto_shorthash docs for more information.
Hash a value to a short hash based on a key.
output
should be a buffer of lengthcrypto_shorthash_BYTES
.input
should be a buffer of any size.key
should be a buffer of lengthcrypto_shorthash_KEYBYTES
.
The generated short hash is stored in output
.
Bindings for the crypto_kdf API. See the libsodium crypto_kdf docs for more information.
Generate a new master key.
key
should be a buffer of lengthcrypto_kdf_KEYBYTES
Derive a new key from a master key.
subkey
should be a buffer betweencrypto_kdf_BYTES_MIN
andcrypto_kdf_BYTES_MAX
.subkeyId
should be an integer.context
should be a buffer of lengthcrypto_kdf_CONTEXTBYTES
key
should by a buffer of lengthcrypto_kdf_KEYBYTES
Hash a value to a short hash based on a key.
output
should be a buffer of lengthcrypto_hash_sha256_BYTES
.input
should be a buffer of any size.
The generated short hash is stored in output
.
Create an instance that has stream of input data to sha256.
Update the instance with a new piece of data.
input
should be a buffer of any size.
Finalize the instance.
output
should be a buffer of lengthcrypto_hash_sha256_BYTES
.
The generated hash is stored in output
.
Hash a value to a short hash based on a key.
output
should be a buffer of lengthcrypto_hash_sha512_BYTES
.input
should be a buffer of any size.
The generated short hash is stored in output
.
Create an instance that has stream of input data to sha512.
Update the instance with a new piece of data.
input
should be a buffer of any size.
Finalize the instance.
output
should be a buffer of lengthcrypto_hash_sha512_BYTES
.
The generated hash is stored in output
.
MIT