| 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: It is necessary to apply the primitives here correctly. Wrong application may result in severely reduced strength of the cryptography. Take some time to make sure this is the case before using.
Note: All functions will fail with a badarg error if given incorrect
parameters. Also, if something is wrong internally, they will raise an error of
the form enacl_internal_error. There is usually no way to continue gracefully
from either of these. A third error is enacl_finalized, raised when you try
re-using an already finalized state for multi-part messages.
generichash_bytes() = 10..64
pwhash_alg() = default | argon2i13 | argon2id13 | pos_integer()
pwhash_limit() = interactive | moderate | sensitive | pos_integer()
secretstream_xchacha20poly1305_tag() = message | rekey | final | push | pos_integer()
sign_state() = reference()
| aead_chacha20poly1305_ietf_ABYTES/0 | aead_chacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD ChaCha20 Poly1305 encryption/decryption. |
| aead_chacha20poly1305_ietf_KEYBYTES/0 | aead_chacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD ChaCha20 Poly1305 encryption/decryption. |
| aead_chacha20poly1305_ietf_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_ietf_NPUBBYTES/0 | aead_chacha20poly1305_NPUBBYTES/0 returns the number of bytes of the Nonce in AEAD ChaCha20 Poly1305 encryption/decryption. |
| aead_chacha20poly1305_ietf_decrypt/4 | aead_chacha20poly1305_decrypt/4 decrypts ciphertext CT with additional
data AD using Key and Nonce. |
| aead_chacha20poly1305_ietf_encrypt/4 | aead_chacha20poly1305_encrypt/4 encrypts Message with additional data
AD using Key and Nonce. |
| aead_xchacha20poly1305_ietf_ABYTES/0 | aead_xchacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD XChaCha20 Poly1305 encryption/decryption. |
| aead_xchacha20poly1305_ietf_KEYBYTES/0 | aead_xchacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD XChaCha20 Poly1305 encryption/decryption. |
| aead_xchacha20poly1305_ietf_MESSAGEBYTES_MAX/0 | aead_xchacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in AEAD XChaCha20 Poly1305 encryption/decryption. |
| aead_xchacha20poly1305_ietf_NPUBBYTES/0 | aead_xchacha20poly1305_NPUBBYTES/0 returns the number of bytes of the Nonce in AEAD XChaCha20 Poly1305 encryption/decryption. |
| aead_xchacha20poly1305_ietf_decrypt/4 | aead_xchacha20poly1305_decrypt/4 decrypts ciphertext CT with additional
data AD using Key and Nonce. |
| aead_xchacha20poly1305_ietf_encrypt/4 | aead_xchacha20poly1305_encrypt/4 encrypts Message with additional data
AD using Key and Nonce. |
| auth/2 | auth/2 produces an authenticator (MAC) for a message. |
| auth_BYTES/0 | auth_BYTES/0 returns the byte-size of the authenticator. |
| auth_KEYBYTES/0 | auth_KEYBYTES/0 returns the byte-size of the authentication key. |
| auth_verify/3 | auth_verify/3 verifies an authenticator for a message. |
| box/4 | box/4 encrypts+authenticates a message to another party. |
| box_NONCEBYTES/0 | box_NONCEBYTES()/0 return the byte-size of the nonce. |
| 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_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. |
| crypto_sign_ed25519_sk_to_pk/1 | crypto_sign_ed25519_sk_to_pk/1 derives an ed25519 public key from a secret key The ed25519 signatures secret keys contains enough information to dervice its corresponding public 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_final/1 finalizes a multi-part hash. |
| generichash_init/2 | generichash_init/2 initializes a multi-part hash. |
| generichash_update/2 | generichash_update/2 updates a multi-part hash with new data. |
| hash/1 | hash/1 hashes data into a cryptographically secure checksum. |
| kdf_CONTEXTBYTES/0 | kdf_CONTEXTBYTES/0 returns the number of bytes required for context. |
| kdf_KEYBYTES/0 | kdf_KEYBYTES/0 returns the number of bytes required for master key. |
| kdf_derive_from_key/3 | kdf_derive_from_key/3 derive a key from a single high entropy key. |
| kx_PUBLICKEYBYTES/0 | kx_PUBLICKEYBYTES/0 returns the number of bytes of the public key used in key exchange. |
| kx_SECRETKEYBYTES/0 | kx_SECRETKEYBYTES/0 returns the number of bytes of the secret key used in key exchange. |
| kx_SESSIONKEYBYTES/0 | kx_SESSIONKEYBYTES/0 returns the number of bytes of the generated during key exchange session key. |
| 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_server_session_keys/3 | kx_server_session_keys/3 computes and returns shared keys for server session. |
| onetime_auth/2 | onetime_auth/2 produces a ONE-TIME authenticator for a message. |
| onetime_auth_BYTES/0 | onetime_auth_BYTES/0 returns the number of bytes of the one-time authenticator. |
| onetime_auth_KEYBYTES/0 | onetime_auth_KEYBYTES/0 returns the byte-size of the onetime authentication key. |
| onetime_auth_verify/3 | onetime_auth_verify/3 verifies an ONE-TIME authenticator for a message. |
| pwhash/2 | pwhash/2 hash a password. |
| pwhash/4 | pwhash/4 hash a password. |
| pwhash/5 | pwhash/5 hash a password. |
| pwhash_SALTBYTES/0 | pwhash_SALTBYTES/0 returns the number of bytes required for salt. |
| pwhash_str/1 | pwhash_str/1 generates a ASCII encoded hash of a password. |
| pwhash_str/3 | pwhash_str/3 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. |
| randombytes_uint32/0 | randombytes_uint32/0 produces an integer in the 32bit range. |
| randombytes_uniform/1 | randombytes_uniform/1 produces a random integer in the space [0..N) That is with the upper bound excluded. |
| secretbox/3 | secretbox/3 encrypts a message with a key. |
| secretbox_KEYBYTES/0 | secretbox_KEYBYTES/0 returns the size of the secretbox key. |
| secretbox_NONCEBYTES/0 | secretbox_NONCEBYTES()/0 returns the size of the secretbox nonce. |
| secretbox_open/3 | secretbox_open/3 opens a sealed box. |
| secretstream_xchacha20poly1305_ABYTES/0 | secretstream_xchacha20poly1305_ABYTES/0 returns the number of bytes of the MAC used on secretstream encryption/decryption. |
| secretstream_xchacha20poly1305_HEADERBYTES/0 | secretstream_xchacha20poly1305_HEADERBYTES/0 returns the number of bytes for header used in secretstream encryption/decryption. |
| secretstream_xchacha20poly1305_KEYBYTES/0 | secretstream_xchacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in secretstream encryption/decryption. |
| secretstream_xchacha20poly1305_MESSAGEBYTES_MAX/0 | secretstream_xchacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in secretstream encryption/decryption. |
| secretstream_xchacha20poly1305_TAG_FINAL/0 | secretstream_xchacha20poly1305_TAG_FINAL/0 returns integer value
of tag final. |
| secretstream_xchacha20poly1305_TAG_MESSAGE/0 | secretstream_xchacha20poly1305_TAG_MESSAGE/0 returns integer value
of tag message. |
| secretstream_xchacha20poly1305_TAG_PUSH/0 | secretstream_xchacha20poly1305_TAG_PUSH/0 returns integer value
of tag push. |
| secretstream_xchacha20poly1305_TAG_REKEY/0 | secretstream_xchacha20poly1305_TAG_REKEY/0 returns integer value
of tag rekey. |
| secretstream_xchacha20poly1305_init_pull/2 | secretstream_xchacha20poly1305_init_pull/3
initializes a secretstream decryption context using Header and Key. |
| secretstream_xchacha20poly1305_init_push/1 | secretstream_xchacha20poly1305_init_push/1
initializes a secretstream encryption context using given key. |
| secretstream_xchacha20poly1305_keygen/0 | secretstream_xchacha20poly1305_keygen/0 returns new random key for secretsteam encryption. |
| secretstream_xchacha20poly1305_pull/3 | secretstream_xchacha20poly1305_pull/3 decrypts CipherText
with additional data AD in referenced decryption context Ref. |
| secretstream_xchacha20poly1305_push/4 | secretstream_xchacha20poly1305_push/4 returns encrypted chunk binary. |
| secretstream_xchacha20poly1305_rekey/1 | secretstream_xchacha20poly1305_rekey/1 updates encryption/decryption context state. |
| 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_final_create/2 | sign_final_create/2 computes the signature for the previously supplied
message(s) using the secret key SK. |
| sign_final_verify/3 | sign_final_verify/3 verify a chunked signature. |
| sign_init/0 | sign_init/0 initialize a multi-part signature state. |
| sign_keypair/0 | sign_keypair/0 returns a signature keypair for signing. |
| sign_open/2 | sign_open/2 opens a digital signature. |
| sign_seed_keypair/1 | sign_seed_keypair/1 returns a signature keypair based on seed for signing. |
| sign_update/2 | sign_update/2 update the signature state S with a new chunk of data M. |
| 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_KEYBYTES/0 | stream_KEYBYTES/0 returns the byte size of the key for streams. |
| stream_NONCEBYTES/0 | stream_NONCEBYTES/0 returns the byte size of the nonce for streams. |
| stream_chacha20/3 | stream_chacha20/3 produces a cryptographic stream suitable for secret-key encryption. |
| stream_chacha20_KEYBYTES/0 | stream_chacha20_KEYBYTES/0 returns the byte size of the key for streams. |
| stream_chacha20_NONCEBYTES/0 | stream_chacha20_NONCEBYTES/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_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_ietf_ABYTES() -> pos_integer()
aead_chacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_ietf_KEYBYTES() -> pos_integer()
aead_chacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_ietf_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_ietf_NPUBBYTES() -> pos_integer()
aead_chacha20poly1305_NPUBBYTES/0 returns the number of bytes of the Nonce in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_ietf_decrypt(CT, AD, Nonce, Key) -> 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_ietf_encrypt(Msg, AD, Nonce, Key) -> binary()
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.
aead_xchacha20poly1305_ietf_ABYTES() -> pos_integer()
aead_xchacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_KEYBYTES() -> pos_integer()
aead_xchacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_MESSAGEBYTES_MAX() -> pos_integer()
aead_xchacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_NPUBBYTES() -> pos_integer()
aead_xchacha20poly1305_NPUBBYTES/0 returns the number of bytes of the Nonce in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_decrypt(CT, AD, Nonce, Key) -> binary() | {error, term()}
aead_xchacha20poly1305_decrypt/4 decrypts ciphertext CT with additional
data AD using Key and Nonce. Note: CipherText should contain
aead_xchacha20poly1305_ABYTES/0 bytes that is the MAC. Returns the decrypted
message.
aead_xchacha20poly1305_ietf_encrypt(Msg, AD, Nonce, Key) -> binary()
aead_xchacha20poly1305_encrypt/4 encrypts Message with additional data
AD using Key and Nonce. Returns the encrypted message followed by
aead_xchacha20poly1305_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_BYTES() -> pos_integer()
auth_BYTES/0 returns the byte-size of the authenticator
auth_KEYBYTES() -> pos_integer()
auth_KEYBYTES/0 returns the byte-size of the authentication key
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_NONCEBYTES() -> pos_integer()
box_NONCEBYTES()/0 return the byte-size of the nonce
Used to obtain the size of the nonce.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_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.
crypto_sign_ed25519_sk_to_pk(Secret::binary()) -> binary()
crypto_sign_ed25519_sk_to_pk/1 derives an ed25519 public key from a secret key The ed25519 signatures secret keys contains enough information to dervice its corresponding public key. This function extracts the public key from the secret if needed.
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()) -> binary()
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()) -> binary()
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(State::reference()) -> binary()
generichash_final/1 finalizes a multi-part hash.
generichash_init(HashSize::generichash_bytes(), Key::binary()) -> reference()
generichash_init/2 initializes a multi-part hash.
generichash_update(State::reference(), Message::iodata()) -> reference()
generichash_update/2 updates a multi-part hash with new data.
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
kdf_CONTEXTBYTES() -> pos_integer()
kdf_CONTEXTBYTES/0 returns the number of bytes required for context.
kdf_KEYBYTES() -> pos_integer()
kdf_KEYBYTES/0 returns the number of bytes required for master key.
kdf_derive_from_key(MasterKey, Context, Id) -> binary()
kdf_derive_from_key/3 derive a key from a single high entropy key
kx_PUBLICKEYBYTES() -> pos_integer()
kx_PUBLICKEYBYTES/0 returns the number of bytes of the public key used in key exchange.
kx_SECRETKEYBYTES() -> pos_integer()
kx_SECRETKEYBYTES/0 returns the number of bytes of the secret key used in key exchange.
kx_SESSIONKEYBYTES() -> pos_integer()
kx_SESSIONKEYBYTES/0 returns the number of bytes of the generated during key exchange session key.
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_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.
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_BYTES() -> pos_integer()
onetime_auth_BYTES/0 returns the number of bytes of the one-time authenticator
onetime_auth_KEYBYTES() -> pos_integer()
onetime_auth_KEYBYTES/0 returns the byte-size of the onetime authentication key
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()) -> binary()
pwhash/2 hash a password
This function generates a fixed size salted hash of a user defined password. Defaults to interactive/interactive limits.pwhash(Password, Salt, Ops, Mem) -> binary()
pwhash/4 hash a password
This function generates a fixed size salted hash of a user defined password given Ops and Mem limits.pwhash(Password, Salt, Ops, Mem, Alg) -> binary()
pwhash/5 hash a password
This function generates a fixed size salted hash of a user defined password given Ops and Mem limits.pwhash_SALTBYTES() -> pos_integer()
pwhash_SALTBYTES/0 returns the number of bytes required for salt.
pwhash_str(Password::iodata()) -> iodata()
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. Defaults to interactive/interactive limits.pwhash_str(Password, Ops, Mem) -> iodata()
pwhash_str/3 generates a ASCII encoded hash of a password
This function generates a fixed size, salted, ASCII encoded hash of a user defined password given Ops and Mem limits.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.randombytes_uint32() -> integer()
randombytes_uint32/0 produces an integer in the 32bit range
randombytes_uniform(N) -> any()
randombytes_uniform/1 produces a random integer in the space [0..N) That is with the upper bound excluded. Fails for integers above 32bit size
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_KEYBYTES() -> any()
secretbox_KEYBYTES/0 returns the size of the secretbox key
When encrypting with a secretbox, the key must have this sizesecretbox_NONCEBYTES() -> any()
secretbox_NONCEBYTES()/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}.
secretstream_xchacha20poly1305_ABYTES() -> pos_integer()
secretstream_xchacha20poly1305_ABYTES/0 returns the number of bytes of the MAC used on secretstream encryption/decryption
secretstream_xchacha20poly1305_HEADERBYTES() -> pos_integer()
secretstream_xchacha20poly1305_HEADERBYTES/0 returns the number of bytes for header used in secretstream encryption/decryption.
secretstream_xchacha20poly1305_KEYBYTES() -> pos_integer()
secretstream_xchacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in secretstream encryption/decryption.
secretstream_xchacha20poly1305_MESSAGEBYTES_MAX() -> pos_integer()
secretstream_xchacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in secretstream encryption/decryption.
secretstream_xchacha20poly1305_TAG_FINAL() -> pos_integer()
secretstream_xchacha20poly1305_TAG_FINAL/0 returns integer value
of tag final. Indicates that the message is the last message in
the secretstream.
secretstream_xchacha20poly1305_TAG_MESSAGE() -> pos_integer()
secretstream_xchacha20poly1305_TAG_MESSAGE/0 returns integer value
of tag message. The most common tag, that doesn't add any information
about the nature of the message.
secretstream_xchacha20poly1305_TAG_PUSH() -> pos_integer()
secretstream_xchacha20poly1305_TAG_PUSH/0 returns integer value
of tag push.
This tag indicates that the message marks the end of a set of messages, but not the end of the stream.
For example, a huge JSON string sent as multiple chunks can use this tag to indicate to the application that the string is complete and that it can be decoded. But the stream itself is not closed, and more data may follow.secretstream_xchacha20poly1305_TAG_REKEY() -> pos_integer()
secretstream_xchacha20poly1305_TAG_REKEY/0 returns integer value
of tag rekey. Indicates that next messages will derive new keys.
secretstream_xchacha20poly1305_init_pull(Header, Key) -> reference()
secretstream_xchacha20poly1305_init_pull/3
initializes a secretstream decryption context using Header and Key.
Returns reference to decryption context.
secretstream_xchacha20poly1305_init_push(Key) -> {binary(), reference()}
secretstream_xchacha20poly1305_init_push/1
initializes a secretstream encryption context using given key.
Returns Header and reference to encryption context.
secretstream_xchacha20poly1305_keygen() -> binary()
secretstream_xchacha20poly1305_keygen/0 returns new random key for secretsteam encryption.
secretstream_xchacha20poly1305_pull(Ref, CipherText, AD) -> {binary(), secretstream_xchacha20poly1305_tag()} | {error, failed_verification}
secretstream_xchacha20poly1305_pull/3 decrypts CipherText
with additional data AD in referenced decryption context Ref.
secretstream_xchacha20poly1305_push(Ref, Message, AD, Tag) -> binary()
secretstream_xchacha20poly1305_push/4 returns encrypted chunk binary.
Updates a secretstream context referenced by Ref with Message data,
given Tag and additional data AD.
secretstream_xchacha20poly1305_rekey(Ref) -> ok
secretstream_xchacha20poly1305_rekey/1 updates encryption/decryption context state. This doesn't add any information about key update to stream. If this function is used to create an encrypted stream, the decryption process must call that function at the exact same stream location.
shorthash(Msg, Key) -> Authenticator
shorthash/2 produces a short authenticator (MAC) for a message suitable for hashtables and refs
Given a Msg 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_final_create/2 computes the signature for the previously supplied
message(s) using the secret key SK.
sign_final_verify/3 verify a chunked signature
Verifies thatSIG is a valid signature for the message whose content has
been previously supplied using sign_update/2 using the public key PK.
sign_init() -> sign_state()
sign_init/0 initialize a multi-part signature state.
This state must be passed to all future calls tosign_update/2,
sign_final_create/2 and sign_final_verify/3.
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_seed_keypair(S) -> #{atom() => binary()}
sign_seed_keypair/1 returns a signature keypair based on seed for signing
The returned value is a map in order to make it harder to misuse keys.sign_update/2 update the signature state S with a new chunk of data M.
sign_verify_detached(SIG, M, PK) -> boolean()
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; false otherwise.
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_KEYBYTES() -> '?CRYPTO_STREAM_KEYBYTES'
stream_KEYBYTES/0 returns the byte size of the key for streams
stream_NONCEBYTES() -> '?CRYPTO_STREAM_NONCEBYTES'
stream_NONCEBYTES/0 returns the byte size of the nonce for streams
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_KEYBYTES() -> '?CRYPTO_STREAM_CHACHA20_KEYBYTES'
stream_chacha20_KEYBYTES/0 returns the byte size of the key for streams
stream_chacha20_NONCEBYTES() -> '?CRYPTO_STREAM_CHACHA20_NONCEBYTES'
stream_chacha20_NONCEBYTES/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_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