| Overview |  |
This module implements NIF bindings to the library known as NaCl (pronounced "salt"). The NaCl library provides a sane cryptographic interface to the world in an attempt to make it harder to abuse and misuse cryptographic primitives.
This module implements an Erlang-idiomatic API to the underlying library. If in doubt about a primitive, always consult the underlying documentation.
There are two libraries in existence: NaCl and libsodium, the latter being a more portable variant of the NaCl library. The C-level API is interchangeable so we can run on any of these underlying libraries as seen from the Erlang world. We simply have to restrict ourselves to the portion of the code base which is overlapping.
Warning: The cryptographic strength of your implementation is no stronger than plaintext cryptography unless you take care in using these primitives correctly. Hence, implementors should use these primitives with that in mind.
Note: All functions will fail with a badarg error if given incorrect
parameters.
generichash_bytes() = 10..64
| aead_chacha20poly1305_ABYTES/0 | aead_chacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD ChaCha20 Poly1305 encryption/decryption. |
| aead_chacha20poly1305_KEYBYTES/0 | aead_chacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD ChaCha20 Poly1305 encryption/decryption. |
| aead_chacha20poly1305_MESSAGEBYTES_MAX/0 | aead_chacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in AEAD ChaCha20 Poly1305 encryption/decryption. |
| aead_chacha20poly1305_NONCEBYTES/0 | aead_chacha20poly1305_NONCEBYTES/0 returns the number of bytes of the Nonce in AEAD ChaCha20 Poly1305 encryption/decryption. |
| aead_chacha20poly1305_decrypt/4 | aead_chacha20poly1305_decrypt/4 decrypts ciphertext CT with additional
data AD using Key and Nonce. |
| aead_chacha20poly1305_encrypt/4 | aead_chacha20poly1305_encrypt/4 encrypts Message with additional data
AD using Key and Nonce. |
| auth/2 | auth/2 produces an authenticator (MAC) for a message. |
| auth_key_size/0 | auth_key_size/0 returns the byte-size of the authentication key. |
| auth_size/0 | auth_size/0 returns the byte-size of the authenticator. |
| auth_verify/3 | auth_verify/3 verifies an authenticator for a message. |
| box/4 | box/4 encrypts+authenticates a message to another party. |
| box_afternm/3 | box_afternm/3 works like box/4 but uses a precomputed key. |
| box_beforenm/2 | box_beforenm/2 precomputes a box shared key for a PK/SK keypair. |
| box_keypair/0 | box_keypair/0 creates a new Public/Secret keypair. |
| box_nonce_size/0 | box_nonce_size/0 return the byte-size of the nonce. |
| box_open/4 | box_open/4 decrypts+verifies a message from another party. |
| box_open_afternm/3 | box_open_afternm/3 works like box_open/4` but uses a precomputed key
Calling `box_open_afternm(M, Nonce, K) for a precomputed key K = box_beforenm(PK, SK) works exactly as
if you had called box_open(M, Nonce, PK, SK). |
| box_seal/2 | seal_box/2 encrypts an anonymous message to another party. |
| box_seal_open/3 | seal_box_open/3 decrypts+check message integrity from an unknown sender. |
| crypto_sign_ed25519_keypair/0 | crypto_sign_ed25519_keypair/0 creates a new Ed 25519 Public/Secret keypair. |
| crypto_sign_ed25519_public_size/0 | |
| crypto_sign_ed25519_public_to_curve25519/1 | crypto_sign_ed25519_public_to_curve25519/1 converts a given Ed 25519 public key to a Curve 25519 public key. |
| crypto_sign_ed25519_secret_size/0 | |
| crypto_sign_ed25519_secret_to_curve25519/1 | crypto_sign_ed25519_secret_to_curve25519/1 converts a given Ed 25519 secret key to a Curve 25519 secret key. |
| curve25519_scalarmult/1 | curve25519_scalarmult/1 avoids messing up arguments. |
| curve25519_scalarmult/2 | curve25519_scalarmult/2 does a scalar multiplication between the Secret and the BasePoint. |
| curve25519_scalarmult_base/1 | curve25519_scalarmult_base/1 compute the corresponding public key for a given secret key. |
| generichash/2 | generichash/2 creates a hash of the message. |
| generichash/3 | generichash/3 creates a hash of the message using a key. |
| generichash_final/1 | |
| generichash_init/2 | |
| generichash_update/2 | |
| hash/1 | hash/1 hashes data into a cryptographically secure checksum. |
| kx_client_session_keys/3 | kx_client_session_keys/3 computes and returns shared keys for client session. |
| kx_keypair/0 | kx_keypair/0 creates a new Public/Secret keypair. |
| kx_public_key_size/0 | kx_public_key_size/0 returns the number of bytes of the public key used in key exchange. |
| kx_secret_key_size/0 | kx_secret_key_size/0 returns the number of bytes of the secret key used in key exchange. |
| kx_server_session_keys/3 | kx_server_session_keys/3 computes and returns shared keys for server session. |
| kx_session_key_size/0 | kx_session_key_size/0 returns the number of bytes of the generated during key exchange session key. |
| onetime_auth/2 | onetime_auth/2 produces a ONE-TIME authenticator for a message. |
| onetime_auth_key_size/0 | onetime_auth_key_size/0 returns the byte-size of the onetime authentication key. |
| onetime_auth_size/0 | onetime_auth_size/0 returns the number of bytes of the one-time authenticator. |
| onetime_auth_verify/3 | onetime_auth_verify/3 verifies an ONE-TIME authenticator for a message. |
| pwhash/2 | pwhash/2 hash a password. |
| pwhash_str/1 | pwhash_str/1 generates a ASCII encoded hash of a password. |
| pwhash_str_verify/2 | pwhash_str_verify/2 compares a password with a hash. |
| randombytes/1 | randombytes/1 produces a stream of random bytes of the given size. |
| secretbox/3 | secretbox/3 encrypts a message with a key. |
| secretbox_key_size/0 | secretbox_key_size/0 returns the size of the secretbox key. |
| secretbox_nonce_size/0 | secretbox_nonce_size/0 returns the size of the secretbox nonce. |
| secretbox_open/3 | secretbox_open/3 opens a sealed box. |
| shorthash/2 | shorthash/2 produces a short authenticator (MAC) for a message suitable for hashtables and refs. |
| shorthash_key_size/0 | shorthash_key_size/0 returns the byte-size of the authentication key. |
| shorthash_size/0 | shorthash_size/0 returns the byte-size of the authenticator. |
| sign/2 | sign/2 signs a message with a digital signature identified by a secret key. |
| sign_detached/2 | sign_detached/2 computes a digital signature given a message and a secret key. |
| sign_keypair/0 | sign_keypair/0 returns a signature keypair for signing. |
| sign_open/2 | sign_open/2 opens a digital signature. |
| sign_verify_detached/3 | sign_verify_detached/3 verifies the given signature against the given message for the given public key. |
| stream/3 | stream/3 produces a cryptographic stream suitable for secret-key encryption. |
| stream_chacha20/3 | stream_chacha20/3 produces a cryptographic stream suitable for secret-key encryption. |
| stream_chacha20_key_size/0 | stream_key_size/0 returns the byte size of the key for streams. |
| stream_chacha20_nonce_size/0 | stream_chacha20_nonce_size/0 returns the byte size of the nonce for streams. |
| stream_chacha20_xor/3 | stream_chacha20_xor/3 encrypts a plaintext message into ciphertext. |
| stream_key_size/0 | stream_key_size/0 returns the byte size of the key for streams. |
| stream_nonce_size/0 | stream_nonce_size/0 returns the byte size of the nonce for streams. |
| stream_xor/3 | stream_xor/3 encrypts a plaintext message into ciphertext. |
| unsafe_memzero/1 | unsafe_memzero/1 ipmlements guaranteed zero'ing of binary data. |
| verify/0 | Verify makes sure the constants defined in libsodium matches ours. |
| verify_16/2 | verify_16/2 implements constant time 16-byte binary() verification. |
| verify_32/2 | verify_32/2 implements constant time 32-byte iolist() verification. |
aead_chacha20poly1305_ABYTES() -> pos_integer()
aead_chacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_KEYBYTES() -> pos_integer()
aead_chacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_MESSAGEBYTES_MAX() -> pos_integer()
aead_chacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_NONCEBYTES() -> pos_integer()
aead_chacha20poly1305_NONCEBYTES/0 returns the number of bytes of the Nonce in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_decrypt(Key, Nonce, AD, CT) -> binary() | {error, term()}
aead_chacha20poly1305_decrypt/4 decrypts ciphertext CT with additional
data AD using Key and Nonce. Note: CipherText should contain
aead_chacha20poly1305_ABYTES/0 bytes that is the MAC. Returns the decrypted
message.
aead_chacha20poly1305_encrypt(Key, Nonce, AD, Msg) -> binary() | {error, term()}
aead_chacha20poly1305_encrypt/4 encrypts Message with additional data
AD using Key and Nonce. Returns the encrypted message followed by
aead_chacha20poly1305_ABYTES/0 bytes of MAC.
auth(Msg, Key) -> Authenticator
auth/2 produces an authenticator (MAC) for a message
Given aMsg and a Key produce a MAC/Authenticator for that message. The key can be reused for several such Msg/Authenticator pairs.
An eavesdropper will not learn anything extra about the message structure.
auth_key_size() -> pos_integer()
auth_key_size/0 returns the byte-size of the authentication key
auth_size() -> pos_integer()
auth_size/0 returns the byte-size of the authenticator
auth_verify(Authenticator, Msg, Key) -> boolean()
auth_verify/3 verifies an authenticator for a message
Given anAuthenticator, a Msg and a Key; verify that the MAC for the pair {Msg, Key} is really Authenticator. Returns
the value true if the verfication passes. Upon failure, the function returns false.
box(Msg, Nonce, PK, SK) -> CipherText
box/4 encrypts+authenticates a message to another party.
Encrypt aMsg to the party identified by public key PK using your own secret key SK to
authenticate yourself. Requires a Nonce in addition. Returns the ciphered message.
box_afternm(Msg, Nonce, K) -> CipherText
box_afternm/3 works like box/4 but uses a precomputed key
box_afternm(M, Nonce, K) for a precomputed key K = box_beforenm(PK, SK) works exactly as
if you had called box(M, Nonce, PK, SK). Except that it avoids computations in the elliptic curve Curve25519,
and thus is a much faster operation.
box_beforenm(PK, SK) -> binary()
box_beforenm/2 precomputes a box shared key for a PK/SK keypair
box_keypair() -> #{atom() => binary()}
box_keypair/0 creates a new Public/Secret keypair.
Generates and returns a new key pair for the Box encryption scheme. The return value is a map in order to avoid using the public key as a secret key and vice versa.box_nonce_size() -> pos_integer()
box_nonce_size/0 return the byte-size of the nonce
Used to obtain the size of the nonce.box_open(CipherText, Nonce, PK, SK) -> {ok, Msg} | {error, failed_verification}
box_open/4 decrypts+verifies a message from another party.
Decrypt aCipherText into a Msg given the other partys public key PK and your secret
key SK. Also requires the same nonce as was used by the other party. Returns the plaintext
message.
box_open_afternm(CT, Nonce, K) -> {ok, Msg} | {error, failed_verification}
box_open_afternm/3 works like box_open/4` but uses a precomputed key
Calling `box_open_afternm(M, Nonce, K) for a precomputed key K = box_beforenm(PK, SK) works exactly as
if you had called box_open(M, Nonce, PK, SK). Except the operation is much faster as it avoids costly
computations in the elliptic curve Curve25519.
box_seal(Msg, PK) -> SealedCipherText
seal_box/2 encrypts an anonymous message to another party.
Encrypt aMsg to a party using his public key, PK. This generates an ephemeral
keypair and then uses box. Ephemeral public key will sent to other party. Returns the
enciphered message SealedCipherText which includes ephemeral public key at head.
box_seal_open(SealedCipherText, PK, SK) -> {ok, Msg} | {error, failed_verification}
seal_box_open/3 decrypts+check message integrity from an unknown sender.
Decrypt aSealedCipherText which contains an ephemeral public key from another party
into a Msg using that key and your public and secret keys, PK and SK. Returns the
plaintext message.
crypto_sign_ed25519_keypair() -> #{atom() => binary()}
crypto_sign_ed25519_keypair/0 creates a new Ed 25519 Public/Secret keypair.
Generates and returns a new key pair for the Ed 25519 signature scheme. The return value is a map in order to avoid using the public key as a secret key and vice versa.crypto_sign_ed25519_public_size() -> pos_integer()
crypto_sign_ed25519_public_to_curve25519(PublicKey::binary()) -> binary()
crypto_sign_ed25519_public_to_curve25519/1 converts a given Ed 25519 public key to a Curve 25519 public key.
crypto_sign_ed25519_secret_size() -> pos_integer()
crypto_sign_ed25519_secret_to_curve25519(SecretKey::binary()) -> binary()
crypto_sign_ed25519_secret_to_curve25519/1 converts a given Ed 25519 secret key to a Curve 25519 secret key.
curve25519_scalarmult(X1) -> any()
curve25519_scalarmult/1 avoids messing up arguments.
Takes as input a map #{ secret := Secret, base_point := BasePoint } in order to avoid
messing up the calling order.
curve25519_scalarmult(Secret::binary(), BasePoint::binary()) -> binary()
curve25519_scalarmult/2 does a scalar multiplication between the Secret and the BasePoint.
curve25519_scalarmult_base(Secret::binary()) -> binary()
curve25519_scalarmult_base/1 compute the corresponding public key for a given secret key.
generichash(HashSize::generichash_bytes(), Message::iodata()) -> {ok, binary()} | {error, term()}
generichash/2 creates a hash of the message.
This function generates a hash of the message. The hash size is either 16, 32 or 64 bytesgenerichash(HashSize::generichash_bytes(), Message::iodata(), Key::binary()) -> {ok, binary()} | {error, term()}
generichash/3 creates a hash of the message using a key.
This function generates a hash of the message using a key. The hash size is either 16, 32 or 64 bytesgenerichash_final(X1) -> any()
generichash_init(HashSize, Key) -> any()
generichash_update(X1, Message) -> any()
hash(Data) -> Checksum
hash/1 hashes data into a cryptographically secure checksum.
Given an iodata(), Data of any size, run a cryptographically secure hash algorithm to
produce a checksum of the data. This can be used to verify the integrity of a data block
since the checksum have the properties of cryptographic hashes in general.
The currently selected primitive (Nov. 2014) is SHA-512
kx_client_session_keys(ClientPk, ClientSk, ServerPk) -> #{atom() => binary()}
kx_client_session_keys/3 computes and returns shared keys for client session.
Compute two shared keys using the server's public key ServerPk and the client's secret key ClientPk.
Returns map with two keys client_rx and client_tx.
client_rx will be used by the client to receive data from the server,
client_tx will by used by the client to send data to the server.
kx_keypair() -> #{atom() => binary()}
kx_keypair/0 creates a new Public/Secret keypair.
Generates and returns a new key pair for the key exchange. The return value is a map in order to avoid using the public key as a secret key and vice versa.kx_public_key_size() -> pos_integer()
kx_public_key_size/0 returns the number of bytes of the public key used in key exchange.
kx_secret_key_size() -> pos_integer()
kx_secret_key_size/0 returns the number of bytes of the secret key used in key exchange.
kx_server_session_keys(ServerPk, ServerSk, ClientPk) -> #{atom() => binary()}
kx_server_session_keys/3 computes and returns shared keys for server session.
Compute two shared keys using the client's public key ClientPk and the server's secret key ServerSk.
Returns map with two keys server_rx and server_tx.
server_rx will be used by the server to receive data from the client,
server_tx will be used by the server to send data to the client.
kx_session_key_size() -> pos_integer()
kx_session_key_size/0 returns the number of bytes of the generated during key exchange session key.
onetime_auth(Msg, Key) -> Authenticator
onetime_auth/2 produces a ONE-TIME authenticator for a message
This function works likeauth/2 except that the key must not be used again for subsequent messages. That is, the pair
{Msg, Key} is unique and only to be used once. The advantage is noticably faster execution.
onetime_auth_key_size() -> pos_integer()
onetime_auth_key_size/0 returns the byte-size of the onetime authentication key
onetime_auth_size() -> pos_integer()
onetime_auth_size/0 returns the number of bytes of the one-time authenticator
onetime_auth_verify(Authenticator, Msg, Key) -> boolean()
onetime_auth_verify/3 verifies an ONE-TIME authenticator for a message
Given anAuthenticator, a Msg and a Key; verify that the MAC for the pair {Msg, Key} is really Authenticator. Returns
the value true if the verification passes. Upon failure, the function returns false. Note the caveat from onetime_auth/2
applies: you are not allowed to ever use the same key again for another message.
pwhash(Password::iodata(), Salt::binary()) -> {ok, binary()} | {error, term()}
pwhash/2 hash a password
This function generates a fixed size salted hash of a user defined password.pwhash_str(Password::iodata()) -> {ok, iodata()} | {error, term()}
pwhash_str/1 generates a ASCII encoded hash of a password
This function generates a fixed size, salted, ASCII encoded hash of a user defined password.pwhash_str_verify(HashPassword::binary(), Password::iodata()) -> boolean()
pwhash_str_verify/2 compares a password with a hash
This function verifies that the hash is generated from the password. The function returns true if the verifcate succeeds, false otherwiserandombytes(N::non_neg_integer()) -> binary()
randombytes/1 produces a stream of random bytes of the given size
The security properties of the random stream are that of the libsodium library. Specifically, we use:
* RtlGenRandom() on Windows systems * arc4random() on OpenBSD and Bitrig * /dev/urandom on other Unix environments
It is up to you to pick a system with a appropriately strong (P)RNG for your purpose. We refer you to the underlying system implementations for random data.secretbox(Msg, Nonce, Key) -> Box
secretbox/3 encrypts a message with a key
Given aMsg, a Nonce and a Key encrypt the message with the Key while taking the
nonce into consideration. The function returns the Box obtained from the encryption.
secretbox_key_size() -> any()
secretbox_key_size/0 returns the size of the secretbox key
When encrypting with a secretbox, the key must have this sizesecretbox_nonce_size() -> any()
secretbox_nonce_size/0 returns the size of the secretbox nonce
When encrypting with a secretbox, the nonce must have this sizesecretbox_open(CipherText, Nonce, Key) -> {ok, Msg} | {error, failed_verification}
secretbox_open/3 opens a sealed box.
Given a boxedCipherText and given we know the used Nonce and Key we can open the box
to obtain the Msg` within. Returns either `{ok, Msg} or {error, failed_verification}.
shorthash(Msg, Key) -> Authenticator
shorthash/2 produces a short authenticator (MAC) for a message suitable for hashtables and refs
Given aMsg and a Key produce a MAC/Authenticator for that message. The key can be reused for several such Msg/Authenticator pairs.
An eavesdropper will not learn anything extra about the message structure.
shorthash_key_size() -> pos_integer()
shorthash_key_size/0 returns the byte-size of the authentication key
shorthash_size() -> pos_integer()
shorthash_size/0 returns the byte-size of the authenticator
sign(M, SK) -> SM
sign/2 signs a message with a digital signature identified by a secret key.
Given a messageM and a secret key SK the function will sign the message and return a signed message SM.
sign_detached(M, SK) -> DS
sign_detached/2 computes a digital signature given a message and a secret key.
Given a messageM and a secret key SK the function will compute the digital signature DS.
sign_keypair() -> #{atom() => binary()}
sign_keypair/0 returns a signature keypair for signing
The returned value is a map in order to make it harder to misuse keys.sign_open(SM, PK) -> {ok, M} | {error, failed_verification}
sign_open/2 opens a digital signature
Given a signed messageSM and a public key PK, verify that the message has the
right signature. Returns either {ok, M} or {error, failed_verification} depending
on the correctness of the signature.
sign_verify_detached(SIG, M, PK) -> {ok, M} | {error, failed_verification}
sign_verify_detached/3 verifies the given signature against the given message for the given public key.
Given a signatureSIG, a message M, and a public key PK, the function computes
true iff the SIG is valid for M and PK.
stream(Len, Nonce, Key) -> CryptoStream
stream/3 produces a cryptographic stream suitable for secret-key encryption
Given a positive Len a Nonce and a Key, the stream/3 function will return an unpredictable cryptographic stream of bytes
based on this output. In other words, the produced stream is indistinguishable from a random stream. Using this stream one
can XOR it with a message in order to produce a encrypted message.
Note: You need to use different Nonce values for different messages. Otherwise the same stream is produced and thus the messages will have predictability which in turn makes the encryption scheme fail.
stream_chacha20(Len, Nonce, Key) -> CryptoStream
stream_chacha20/3 produces a cryptographic stream suitable for secret-key encryption
Given a positive Len a Nonce and a Key, the stream_chacha20/3 function will return an unpredictable cryptographic stream of bytes
based on this output. In other words, the produced stream is indistinguishable from a random stream. Using this stream one
can XOR it with a message in order to produce a encrypted message.
Note: You need to use different Nonce values for different messages. Otherwise the same stream is produced and thus the messages will have predictability which in turn makes the encryption scheme fail.
stream_chacha20_key_size() -> '?CRYPTO_STREAM_CHACHA20_KEYBYTES'
stream_key_size/0 returns the byte size of the key for streams
stream_chacha20_nonce_size() -> '?CRYPTO_STREAM_CHACHA20_NONCEBYTES'
stream_chacha20_nonce_size/0 returns the byte size of the nonce for streams
stream_chacha20_xor(Msg, Nonce, Key) -> CipherText
stream_chacha20_xor/3 encrypts a plaintext message into ciphertext
The stream_chacha20_xor/3 function works by using thestream_chacha20/3 api to XOR a message with the cryptographic stream. The same
caveat applies: the nonce must be new for each sent message or the system fails to work.
stream_key_size() -> '?CRYPTO_STREAM_KEYBYTES'
stream_key_size/0 returns the byte size of the key for streams
stream_nonce_size() -> '?CRYPTO_STREAM_NONCEBYTES'
stream_nonce_size/0 returns the byte size of the nonce for streams
stream_xor(Msg, Nonce, Key) -> CipherText
stream_xor/3 encrypts a plaintext message into ciphertext
The stream_xor/3 function works by using thestream/3 api to XOR a message with the cryptographic stream. The same
caveat applies: the nonce must be new for each sent message or the system fails to work.
unsafe_memzero(X::binary()) -> atom()
unsafe_memzero/1 ipmlements guaranteed zero'ing of binary data.
This is verify unsafe. If any copies of the binary have been made they are unaffected. This is intended for use with cryptographic keys where they are only shared within a running process without copies. This allows removing, eg, symmetric session keys.
verify() -> any()
Verify makes sure the constants defined in libsodium matches ours
verify_16(X::binary(), Y::binary()) -> boolean()
verify_16/2 implements constant time 16-byte binary() verification
A subtle problem in cryptographic software are timing attacks where an attacker exploits early exist in string verification if the strings happen to mismatch. This allows the attacker to time how long verification took and thus learn the structure of the desired string to use. The verify_16/2 call will check two 16 byte strings for equality while guaranteeing the equality operation is constant time.
If the strings are not exactly 16 bytes, the comparison function will fail with badarg.
The functions take binary() values and not iolist() values since the latter would convert in non-constant time
Verification returns a boolean. true if the strings match, false otherwise.
verify_32(X::binary(), Y::binary()) -> boolean()
verify_32/2 implements constant time 32-byte iolist() verification
This function works asverify_16/2 but does so on 32 byte strings. Same caveats apply.
Generated by EDoc