Module enacl

Module enacl implements bindings to the NaCl/libsodium crypto-library.

Description

Module enacl implements bindings to the NaCl/libsodium crypto-library

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.

Data Types

generichash_bytes()

generichash_bytes() = 10..64

pwhash_alg()

pwhash_alg() = default | argon2i13 | argon2id13 | pos_integer()

pwhash_limit()

pwhash_limit() = interactive | moderate | sensitive | pos_integer()

secretstream_xchacha20poly1305_tag()

secretstream_xchacha20poly1305_tag() = message | rekey | final | push | pos_integer()

sign_state()

sign_state() = reference()

Function Index

aead_chacha20poly1305_ietf_ABYTES/0aead_chacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_ietf_KEYBYTES/0aead_chacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_ietf_MESSAGEBYTES_MAX/0aead_chacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_ietf_NPUBBYTES/0aead_chacha20poly1305_NPUBBYTES/0 returns the number of bytes of the Nonce in AEAD ChaCha20 Poly1305 encryption/decryption.
aead_chacha20poly1305_ietf_decrypt/4aead_chacha20poly1305_decrypt/4 decrypts ciphertext CT with additional data AD using Key and Nonce.
aead_chacha20poly1305_ietf_encrypt/4aead_chacha20poly1305_encrypt/4 encrypts Message with additional data AD using Key and Nonce.
aead_xchacha20poly1305_ietf_ABYTES/0aead_xchacha20poly1305_ABYTES/0 returns the number of bytes of the MAC in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_KEYBYTES/0aead_xchacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_MESSAGEBYTES_MAX/0aead_xchacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_NPUBBYTES/0aead_xchacha20poly1305_NPUBBYTES/0 returns the number of bytes of the Nonce in AEAD XChaCha20 Poly1305 encryption/decryption.
aead_xchacha20poly1305_ietf_decrypt/4aead_xchacha20poly1305_decrypt/4 decrypts ciphertext CT with additional data AD using Key and Nonce.
aead_xchacha20poly1305_ietf_encrypt/4aead_xchacha20poly1305_encrypt/4 encrypts Message with additional data AD using Key and Nonce.
auth/2auth/2 produces an authenticator (MAC) for a message.
auth_BYTES/0auth_BYTES/0 returns the byte-size of the authenticator.
auth_KEYBYTES/0auth_KEYBYTES/0 returns the byte-size of the authentication key.
auth_verify/3auth_verify/3 verifies an authenticator for a message.
box/4box/4 encrypts+authenticates a message to another party.
box_NONCEBYTES/0box_NONCEBYTES()/0 return the byte-size of the nonce.
box_afternm/3box_afternm/3 works like box/4 but uses a precomputed key.
box_beforenm/2box_beforenm/2 precomputes a box shared key for a PK/SK keypair.
box_keypair/0box_keypair/0 creates a new Public/Secret keypair.
box_open/4box_open/4 decrypts+verifies a message from another party.
box_open_afternm/3box_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/2seal_box/2 encrypts an anonymous message to another party.
box_seal_open/3seal_box_open/3 decrypts+check message integrity from an unknown sender.
crypto_sign_ed25519_keypair/0crypto_sign_ed25519_keypair/0 creates a new Ed 25519 Public/Secret keypair.
crypto_sign_ed25519_public_size/0
crypto_sign_ed25519_public_to_curve25519/1crypto_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/1crypto_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/1crypto_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/1curve25519_scalarmult/1 avoids messing up arguments.
curve25519_scalarmult/2curve25519_scalarmult/2 does a scalar multiplication between the Secret and the BasePoint.
curve25519_scalarmult_base/1curve25519_scalarmult_base/1 compute the corresponding public key for a given secret key.
generichash/2generichash/2 creates a hash of the message.
generichash/3generichash/3 creates a hash of the message using a key.
generichash_final/1generichash_final/1 finalizes a multi-part hash.
generichash_init/2generichash_init/2 initializes a multi-part hash.
generichash_update/2generichash_update/2 updates a multi-part hash with new data.
hash/1hash/1 hashes data into a cryptographically secure checksum.
kdf_CONTEXTBYTES/0kdf_CONTEXTBYTES/0 returns the number of bytes required for context.
kdf_KEYBYTES/0kdf_KEYBYTES/0 returns the number of bytes required for master key.
kdf_derive_from_key/3kdf_derive_from_key/3 derive a key from a single high entropy key.
kx_PUBLICKEYBYTES/0kx_PUBLICKEYBYTES/0 returns the number of bytes of the public key used in key exchange.
kx_SECRETKEYBYTES/0kx_SECRETKEYBYTES/0 returns the number of bytes of the secret key used in key exchange.
kx_SESSIONKEYBYTES/0kx_SESSIONKEYBYTES/0 returns the number of bytes of the generated during key exchange session key.
kx_client_session_keys/3kx_client_session_keys/3 computes and returns shared keys for client session.
kx_keypair/0kx_keypair/0 creates a new Public/Secret keypair.
kx_server_session_keys/3kx_server_session_keys/3 computes and returns shared keys for server session.
onetime_auth/2onetime_auth/2 produces a ONE-TIME authenticator for a message.
onetime_auth_BYTES/0onetime_auth_BYTES/0 returns the number of bytes of the one-time authenticator.
onetime_auth_KEYBYTES/0onetime_auth_KEYBYTES/0 returns the byte-size of the onetime authentication key.
onetime_auth_verify/3onetime_auth_verify/3 verifies an ONE-TIME authenticator for a message.
pwhash/2pwhash/2 hash a password.
pwhash/4pwhash/4 hash a password.
pwhash/5pwhash/5 hash a password.
pwhash_SALTBYTES/0pwhash_SALTBYTES/0 returns the number of bytes required for salt.
pwhash_str/1pwhash_str/1 generates a ASCII encoded hash of a password.
pwhash_str/3pwhash_str/3 generates a ASCII encoded hash of a password.
pwhash_str_verify/2pwhash_str_verify/2 compares a password with a hash.
randombytes/1randombytes/1 produces a stream of random bytes of the given size.
randombytes_uint32/0randombytes_uint32/0 produces an integer in the 32bit range.
randombytes_uniform/1randombytes_uniform/1 produces a random integer in the space [0..N) That is with the upper bound excluded.
secretbox/3secretbox/3 encrypts a message with a key.
secretbox_KEYBYTES/0secretbox_KEYBYTES/0 returns the size of the secretbox key.
secretbox_NONCEBYTES/0secretbox_NONCEBYTES()/0 returns the size of the secretbox nonce.
secretbox_open/3secretbox_open/3 opens a sealed box.
secretstream_xchacha20poly1305_ABYTES/0secretstream_xchacha20poly1305_ABYTES/0 returns the number of bytes of the MAC used on secretstream encryption/decryption.
secretstream_xchacha20poly1305_HEADERBYTES/0secretstream_xchacha20poly1305_HEADERBYTES/0 returns the number of bytes for header used in secretstream encryption/decryption.
secretstream_xchacha20poly1305_KEYBYTES/0secretstream_xchacha20poly1305_KEYBYTES/0 returns the number of bytes of the key used in secretstream encryption/decryption.
secretstream_xchacha20poly1305_MESSAGEBYTES_MAX/0secretstream_xchacha20poly1305_MESSAGEBYTES_MAX/0 returns the max number of bytes allowed in a message in secretstream encryption/decryption.
secretstream_xchacha20poly1305_TAG_FINAL/0secretstream_xchacha20poly1305_TAG_FINAL/0 returns integer value of tag final.
secretstream_xchacha20poly1305_TAG_MESSAGE/0secretstream_xchacha20poly1305_TAG_MESSAGE/0 returns integer value of tag message.
secretstream_xchacha20poly1305_TAG_PUSH/0secretstream_xchacha20poly1305_TAG_PUSH/0 returns integer value of tag push.
secretstream_xchacha20poly1305_TAG_REKEY/0secretstream_xchacha20poly1305_TAG_REKEY/0 returns integer value of tag rekey.
secretstream_xchacha20poly1305_init_pull/2secretstream_xchacha20poly1305_init_pull/3 initializes a secretstream decryption context using Header and Key.
secretstream_xchacha20poly1305_init_push/1secretstream_xchacha20poly1305_init_push/1 initializes a secretstream encryption context using given key.
secretstream_xchacha20poly1305_keygen/0secretstream_xchacha20poly1305_keygen/0 returns new random key for secretsteam encryption.
secretstream_xchacha20poly1305_pull/3secretstream_xchacha20poly1305_pull/3 decrypts CipherText with additional data AD in referenced decryption context Ref.
secretstream_xchacha20poly1305_push/4secretstream_xchacha20poly1305_push/4 returns encrypted chunk binary.
secretstream_xchacha20poly1305_rekey/1secretstream_xchacha20poly1305_rekey/1 updates encryption/decryption context state.
shorthash/2shorthash/2 produces a short authenticator (MAC) for a message suitable for hashtables and refs.
shorthash_key_size/0shorthash_key_size/0 returns the byte-size of the authentication key.
shorthash_size/0shorthash_size/0 returns the byte-size of the authenticator.
sign/2sign/2 signs a message with a digital signature identified by a secret key.
sign_detached/2sign_detached/2 computes a digital signature given a message and a secret key.
sign_final_create/2sign_final_create/2 computes the signature for the previously supplied message(s) using the secret key SK.
sign_final_verify/3sign_final_verify/3 verify a chunked signature.
sign_init/0sign_init/0 initialize a multi-part signature state.
sign_keypair/0sign_keypair/0 returns a signature keypair for signing.
sign_open/2sign_open/2 opens a digital signature.
sign_seed_keypair/1sign_seed_keypair/1 returns a signature keypair based on seed for signing.
sign_update/2sign_update/2 update the signature state S with a new chunk of data M.
sign_verify_detached/3sign_verify_detached/3 verifies the given signature against the given message for the given public key.
stream/3stream/3 produces a cryptographic stream suitable for secret-key encryption.
stream_KEYBYTES/0stream_KEYBYTES/0 returns the byte size of the key for streams.
stream_NONCEBYTES/0stream_NONCEBYTES/0 returns the byte size of the nonce for streams.
stream_chacha20/3stream_chacha20/3 produces a cryptographic stream suitable for secret-key encryption.
stream_chacha20_KEYBYTES/0stream_chacha20_KEYBYTES/0 returns the byte size of the key for streams.
stream_chacha20_NONCEBYTES/0stream_chacha20_NONCEBYTES/0 returns the byte size of the nonce for streams.
stream_chacha20_xor/3stream_chacha20_xor/3 encrypts a plaintext message into ciphertext.
stream_xor/3stream_xor/3 encrypts a plaintext message into ciphertext.
unsafe_memzero/1unsafe_memzero/1 ipmlements guaranteed zero'ing of binary data.
verify/0Verify makes sure the constants defined in libsodium matches ours.
verify_16/2verify_16/2 implements constant time 16-byte binary() verification.
verify_32/2verify_32/2 implements constant time 32-byte iolist() verification.

Function Details

aead_chacha20poly1305_ietf_ABYTES/0

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/0

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/0

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/0

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/4

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/4

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/0

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/0

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/0

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/0

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/4

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/4

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/2

auth(Msg, Key) -> Authenticator

auth/2 produces an authenticator (MAC) for a message

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.

auth_BYTES/0

auth_BYTES() -> pos_integer()

auth_BYTES/0 returns the byte-size of the authenticator

auth_KEYBYTES/0

auth_KEYBYTES() -> pos_integer()

auth_KEYBYTES/0 returns the byte-size of the authentication key

auth_verify/3

auth_verify(Authenticator, Msg, Key) -> boolean()

auth_verify/3 verifies an authenticator for a message

Given an Authenticator, 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/4

box(Msg, Nonce, PK, SK) -> CipherText

box/4 encrypts+authenticates a message to another party.

Encrypt a Msg 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/0

box_NONCEBYTES() -> pos_integer()

box_NONCEBYTES()/0 return the byte-size of the nonce

Used to obtain the size of the nonce.

box_afternm/3

box_afternm(Msg, Nonce, K) -> CipherText

box_afternm/3 works like box/4 but uses a precomputed key

Calling 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/2

box_beforenm(PK, SK) -> binary()

box_beforenm/2 precomputes a box shared key for a PK/SK keypair

box_keypair/0

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/4

box_open(CipherText, Nonce, PK, SK) -> {ok, Msg} | {error, failed_verification}

box_open/4 decrypts+verifies a message from another party.

Decrypt a CipherText 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/3

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/2

box_seal(Msg, PK) -> SealedCipherText

seal_box/2 encrypts an anonymous message to another party.

Encrypt a Msg 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/3

box_seal_open(SealedCipherText, PK, SK) -> {ok, Msg} | {error, failed_verification}

seal_box_open/3 decrypts+check message integrity from an unknown sender.

Decrypt a SealedCipherText 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/0

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/0

crypto_sign_ed25519_public_size() -> pos_integer()

crypto_sign_ed25519_public_to_curve25519/1

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/0

crypto_sign_ed25519_secret_size() -> pos_integer()

crypto_sign_ed25519_secret_to_curve25519/1

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/1

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/1

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/2

curve25519_scalarmult(Secret::binary(), BasePoint::binary()) -> binary()

curve25519_scalarmult/2 does a scalar multiplication between the Secret and the BasePoint.

curve25519_scalarmult_base/1

curve25519_scalarmult_base(Secret::binary()) -> binary()

curve25519_scalarmult_base/1 compute the corresponding public key for a given secret key.

generichash/2

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 bytes

generichash/3

generichash(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 bytes

generichash_final/1

generichash_final(State::reference()) -> binary()

generichash_final/1 finalizes a multi-part hash.

generichash_init/2

generichash_init(HashSize::generichash_bytes(), Key::binary()) -> reference()

generichash_init/2 initializes a multi-part hash.

generichash_update/2

generichash_update(State::reference(), Message::iodata()) -> reference()

generichash_update/2 updates a multi-part hash with new data.

hash/1

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/0

kdf_CONTEXTBYTES() -> pos_integer()

kdf_CONTEXTBYTES/0 returns the number of bytes required for context.

kdf_KEYBYTES/0

kdf_KEYBYTES() -> pos_integer()

kdf_KEYBYTES/0 returns the number of bytes required for master key.

kdf_derive_from_key/3

kdf_derive_from_key(MasterKey, Context, Id) -> binary()

kdf_derive_from_key/3 derive a key from a single high entropy key

kx_PUBLICKEYBYTES/0

kx_PUBLICKEYBYTES() -> pos_integer()

kx_PUBLICKEYBYTES/0 returns the number of bytes of the public key used in key exchange.

kx_SECRETKEYBYTES/0

kx_SECRETKEYBYTES() -> pos_integer()

kx_SECRETKEYBYTES/0 returns the number of bytes of the secret key used in key exchange.

kx_SESSIONKEYBYTES/0

kx_SESSIONKEYBYTES() -> pos_integer()

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(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/0

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/3

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/2

onetime_auth(Msg, Key) -> Authenticator

onetime_auth/2 produces a ONE-TIME authenticator for a message

This function works like auth/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/0

onetime_auth_BYTES() -> pos_integer()

onetime_auth_BYTES/0 returns the number of bytes of the one-time authenticator

onetime_auth_KEYBYTES/0

onetime_auth_KEYBYTES() -> pos_integer()

onetime_auth_KEYBYTES/0 returns the byte-size of the onetime authentication key

onetime_auth_verify/3

onetime_auth_verify(Authenticator, Msg, Key) -> boolean()

onetime_auth_verify/3 verifies an ONE-TIME authenticator for a message

Given an Authenticator, 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/2

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/4

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/5

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/0

pwhash_SALTBYTES() -> pos_integer()

pwhash_SALTBYTES/0 returns the number of bytes required for salt.

pwhash_str/1

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/3

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/2

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 otherwise

randombytes/1

randombytes(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/0

randombytes_uint32() -> integer()

randombytes_uint32/0 produces an integer in the 32bit range

randombytes_uniform/1

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/3

secretbox(Msg, Nonce, Key) -> Box

secretbox/3 encrypts a message with a key

Given a Msg, 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/0

secretbox_KEYBYTES() -> any()

secretbox_KEYBYTES/0 returns the size of the secretbox key

When encrypting with a secretbox, the key must have this size

secretbox_NONCEBYTES/0

secretbox_NONCEBYTES() -> any()

secretbox_NONCEBYTES()/0 returns the size of the secretbox nonce

When encrypting with a secretbox, the nonce must have this size

secretbox_open/3

secretbox_open(CipherText, Nonce, Key) -> {ok, Msg} | {error, failed_verification}

secretbox_open/3 opens a sealed box.

Given a boxed CipherText 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/0

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/0

secretstream_xchacha20poly1305_HEADERBYTES() -> pos_integer()

secretstream_xchacha20poly1305_HEADERBYTES/0 returns the number of bytes for header used in secretstream encryption/decryption.

secretstream_xchacha20poly1305_KEYBYTES/0

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/0

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/0

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/0

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/0

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/0

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/2

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/1

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/0

secretstream_xchacha20poly1305_keygen() -> binary()

secretstream_xchacha20poly1305_keygen/0 returns new random key for secretsteam encryption.

secretstream_xchacha20poly1305_pull/3

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/4

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/1

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/2

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.

The intended use is to generate a random key and use it as a hash table or bloom filter function. This avoids an enemy their ability to predict where a collision would occur in the data structure, since they don't know the key.

shorthash_key_size/0

shorthash_key_size() -> pos_integer()

shorthash_key_size/0 returns the byte-size of the authentication key

shorthash_size/0

shorthash_size() -> pos_integer()

shorthash_size/0 returns the byte-size of the authenticator

sign/2

sign(M, SK) -> SM

sign/2 signs a message with a digital signature identified by a secret key.

Given a message M and a secret key SK the function will sign the message and return a signed message SM.

sign_detached/2

sign_detached(M, SK) -> DS

sign_detached/2 computes a digital signature given a message and a secret key.

Given a message M and a secret key SK the function will compute the digital signature DS.

sign_final_create/2

sign_final_create(S, SK) -> {ok, binary()} | {error, atom()}

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(S, SIG, PK) -> boolean()

sign_final_verify/3 verify a chunked signature

Verifies that SIG is a valid signature for the message whose content has been previously supplied using sign_update/2 using the public key PK.

sign_init/0

sign_init() -> sign_state()

sign_init/0 initialize a multi-part signature state.

This state must be passed to all future calls to sign_update/2, sign_final_create/2 and sign_final_verify/3.

sign_keypair/0

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/2

sign_open(SM, PK) -> {ok, M} | {error, failed_verification}

sign_open/2 opens a digital signature

Given a signed message SM 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/1

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

sign_update(S, M) -> sign_state() | {error, sign_update_error}

sign_update/2 update the signature state S with a new chunk of data M.

sign_verify_detached/3

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 signature SIG, a message M, and a public key PK, the function computes true iff the SIG is valid for M and PK; false otherwise.

stream/3

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/0

stream_KEYBYTES() -> '?CRYPTO_STREAM_KEYBYTES'

stream_KEYBYTES/0 returns the byte size of the key for streams

stream_NONCEBYTES/0

stream_NONCEBYTES() -> '?CRYPTO_STREAM_NONCEBYTES'

stream_NONCEBYTES/0 returns the byte size of the nonce for streams

stream_chacha20/3

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/0

stream_chacha20_KEYBYTES() -> '?CRYPTO_STREAM_CHACHA20_KEYBYTES'

stream_chacha20_KEYBYTES/0 returns the byte size of the key for streams

stream_chacha20_NONCEBYTES/0

stream_chacha20_NONCEBYTES() -> '?CRYPTO_STREAM_CHACHA20_NONCEBYTES'

stream_chacha20_NONCEBYTES/0 returns the byte size of the nonce for streams

stream_chacha20_xor/3

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 the stream_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/3

stream_xor(Msg, Nonce, Key) -> CipherText

stream_xor/3 encrypts a plaintext message into ciphertext

The stream_xor/3 function works by using the stream/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/1

unsafe_memzero(X::binary()) -> atom()

unsafe_memzero/1 ipmlements guaranteed zero'ing of binary data.

WARNING: Take great care. This way be dragons.

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/0

verify() -> any()

Verify makes sure the constants defined in libsodium matches ours

verify_16/2

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/2

verify_32(X::binary(), Y::binary()) -> boolean()

verify_32/2 implements constant time 32-byte iolist() verification

This function works as verify_16/2 but does so on 32 byte strings. Same caveats apply.


Generated by EDoc