Libsodium18/23 wrapper
Memory-unsafe operations are not exposed.
Please always refer to libsodium upstream documentation and ensure that you are using the library in a secure way.
Types
SodiumError = object of Exception
- Source Edit
GenericHash = tuple[state: string, out_len: int]
- Source Edit
HMACSHA256State = tuple[state: string]
- Source Edit
Consts
libsodium_fn = "libsodium.so(.18|.23)"
- Source Edit
Procs
proc randombytes(size: int): string {...}{.raises: [], tags: [].}
- Source Edit
proc randombytes_stir() {...}{.importc, dynlib: libsodium_fn.}
- Reseeds the pseudorandom number generator - if supported. Source Edit
proc memcmp(a, b: string): bool {...}{.raises: [], tags: [].}
- Constant-time test for equality Source Edit
proc is_zero(data: string): bool {...}{.raises: [], tags: [].}
- Returns true if a byte string contains only zeros. Time constant for a given length. Source Edit
proc bin2hex(data: string): string {...}{.raises: [], tags: [].}
- Source Edit
proc hex2bin(data: string; ignore = ""): string {...}{.raises: [], tags: [].}
- Source Edit
proc crypto_secretbox_keygen(): string {...}{.raises: [], tags: [].}
- Generates a random key of length crypto_secretbox_KEYBYTES Source Edit
proc crypto_secretbox_easy(key: string; msg: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
-
Encrypt + sign a variable len string with a preshared key A random nonce is generated from /dev/urandom and prepended to the output
Examples:
let msg = "hello there" key = crypto_secretbox_keygen() ciphertext = crypto_secretbox_easy(key, msg) decrypted = crypto_secretbox_open_easy(key, ciphertext) assert decrypted == msg
Source Edit proc crypto_secretbox_open_easy(key: string; bulk: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Decrypt + sign a variable len string with a preshared key A nonce is expected at the beginning of the input string Source Edit
proc crypto_auth(message, key: string): string {...}{.raises: [SodiumError, ValueError], tags: [].}
- Source Edit
proc crypto_auth_verify(mac, message, key: string): bool {...}{.raises: [], tags: [].}
- Source Edit
proc verify_message(key: string; msg: string; signature: string) {...}{.raises: [], tags: [].}
- verify a message signed using ed25519 if the signature is not provided, it is assumed that it is found at the beginning of the message Source Edit
proc sign_message(key, message: string): string {...}{.raises: [], tags: [].}
- sign a message using ed25519 Source Edit
proc crypto_box_keypair(): (CryptoBoxPublicKey, CryptoBoxSecretKey) {...}{. raises: [SodiumError, ValueError], tags: [].}
- Source Edit
proc crypto_box_easy(message, nonce: string; public_key: CryptoBoxPublicKey; secret_key: CryptoBoxSecretKey): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Source Edit
proc crypto_box_open_easy(ciphertext, nonce: string; public_key: CryptoBoxPublicKey; secret_key: CryptoBoxSecretKey): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Source Edit
proc crypto_sign_keypair(): (PublicKey, SecretKey) {...}{. raises: [SodiumError, ValueError], tags: [].}
- Generate a random public and secret key Source Edit
proc crypto_sign_seed_keypair(seed: string): (PublicKey, SecretKey) {...}{. raises: [SodiumError, ValueError], tags: [].}
- Deterministically generate a public and secret key from a seed Source Edit
proc crypto_sign_detached(secret_key: SecretKey; message: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Source Edit
proc crypto_sign_verify_detached(public_key: PublicKey; message, signature: string) {...}{. raises: [SodiumError, ValueError], tags: [].}
- Source Edit
proc crypto_sign_ed25519_sk_to_seed(secret_key: SecretKey): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Extract the seed from a secret key Source Edit
proc crypto_sign_ed25519_sk_to_pk(secret_key: SecretKey): PublicKey {...}{. raises: [SodiumError, ValueError], tags: [].}
- Extract the public key from a secret key Source Edit
proc crypto_box_seal(message: string; public_key: CryptoBoxPublicKey): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Encrypt a message using the receiver public key Source Edit
proc crypto_box_seal_open(ciphertext: string; public_key: CryptoBoxPublicKey; secret_key: CryptoBoxSecretKey): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Decrypt a ciphertext using a public and secret key Source Edit
proc crypto_generichash(data: string; hashlen: int = crypto_generichash_bytes().int; key: string = ""): string {...}{.raises: [SodiumError, ValueError], tags: [].}
- Generate a hash of "data" of len "hashlen" using an optional key hashlen defaults to crypto_generichash_BYTES Source Edit
proc new_generic_hash(key: string; out_len: int = crypto_generichash_bytes().int): GenericHash {...}{. raises: [SodiumError, ValueError], tags: [].}
- Create a new multipart hash, returns a GenericHash. The GenericHash is to be updated with .update() Upon calling .finalize() on it it will return a hash value of length "out_len" Source Edit
proc update(self: GenericHash; data: string) {...}{.raises: [SodiumError, ValueError], tags: [].}
- Update the multipart hash with more data Source Edit
proc finalize(self: GenericHash): string {...}{.raises: [SodiumError, ValueError], tags: [].}
- Finish the multipart hash and return the hash value as a string Source Edit
proc crypto_shorthash(data: string; key: ShortHashKey): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Hash optimized for short inputs Source Edit
proc generate_key_for_short_hash(): ShortHashKey {...}{.raises: [], tags: [].}
- Source Edit
proc crypto_scalarmult_base(secret_key: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Source Edit
proc crypto_scalarmult(secret_key, public_key: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Compute a shared secret given a secret key and another user's public key. The Sodium library recommends not using the shared secred directly, rather a hash of the shared secred concatenated with the public keys from both users Source Edit
proc crypto_onetimeauth(message, key: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- One-time authentication using Poly1305 Warning: Use unpredictable, secret, unique keys Source Edit
proc crypto_onetimeauth_verify(tok, message, key: string): bool {...}{.raises: [], tags: [].}
- Verify onetimeauth Source Edit
proc crypto_auth_hmacsha256(message, key: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- HMAC SHA256 Source Edit
proc crypto_auth_hmacsha256_verify(mac, message, key: string): bool {...}{.raises: [], tags: [].}
- HMAC SHA256 verification Source Edit
proc new_crypto_auth_hmacsha256(key: string): HMACSHA256State {...}{. raises: [SodiumError, ValueError], tags: [].}
- Create multipart SHA256 HMAC Create a new multipart hash, returns a HMACSHA256State The HMACSHA256State is to be updated with .update() Upon calling .finalize() on it it will return a hash value Source Edit
proc update(self: HMACSHA256State; data: string) {...}{.raises: [SodiumError, ValueError], tags: [].}
- Update the multipart hash with more data Source Edit
proc finalize(self: HMACSHA256State): string {...}{.raises: [SodiumError, ValueError], tags: [].}
- Finish the multipart hash and return the hash value as a string Source Edit
proc crypto_stream_salsa20(nonce, key: string; length: int): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- Salsa20 stream cypher. nonce requires length of crypto_stream_salsa20_NONCEBYTES (64 bits) key requires crypto_stream_salsa20_KEYBYTES (256 bits) Returns length bytes. Source Edit
proc crypto_stream_salsa20_xor(nonce, key, msg: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- encrypts msg. nonce requires length of crypto_stream_salsa20_NONCEBYTES key requires crypto_stream_salsa20_KEYBYTES Source Edit
proc crypto_stream_salsa20_xor_ic(nonce, key, msg: string; ic: uint): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- encrypts msg. nonce requires length of crypto_stream_salsa20_NONCEBYTES key requires crypto_stream_salsa20_KEYBYTES ic is the initial value for the block counter. Source Edit
proc crypto_stream_salsa20_keygen(): string {...}{.raises: [], tags: [].}
- Returns crypto_stream_salsa20_KEYBYTES random bytes. Source Edit
proc crypto_stream(nonce, key: string; length: int): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- XSalsa20 stream cypher. nonce requires length of crypto_stream_xsalsa20_NONCEBYTES (192 bits) key requires crypto_stream_xsalsa20_KEYBYTES (256 bits) Returns length bytes. Source Edit
proc crypto_stream_xor(nonce, key, msg: string): string {...}{. raises: [SodiumError, ValueError], tags: [].}
- encrypts msg using XSalsa20. nonce requires length of crypto_stream_xsalsa20_NONCEBYTES key requires crypto_stream_xsalsa20_KEYBYTES Source Edit
proc crypto_stream_keygen(): string {...}{.raises: [], tags: [].}
- Returns crypto_stream_xsalsa20_KEYBYTES random bytes. To be used with crypto_stream or crypto_stream_xor Source Edit