sodium

Comprehensive cryptographic library for Kit using libsodium

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-sodium.git

Usage

import Kit.Sodium

License

MIT License - see LICENSE for details.

Exported Functions & Types

init

Note: This module uses Kit's standard Result type (Ok a | Err String).

Initializes the crypto library.

This function must be called once at program start before using any other cryptographic functions. It initializes the libsodium library and ensures that all internal state is properly set up.

Returns: Result Int String: Ok on success, Err with message on failure

() -> Result Int String

match init()
  | Ok _ -> print "Sodium initialized"
  | Err msg -> print "Failed: ${msg}"

random-u32

Generates a cryptographically secure random unsigned 32-bit integer.

Uses libsodium's secure random number generator, which is suitable for cryptographic purposes (key generation, nonces, etc.).

Returns: Int: A random integer in the range [0, 2^32)

Security: Uses unpredictable randomness suitable for security-critical applications

() -> Int

rand = random-u32()
print "Random number: ${rand}"

random-int

Generates a cryptographically secure random integer in a specified range.

Returns a uniformly distributed random integer in the range [0, n). Uses rejection sampling to avoid modulo bias, ensuring true uniform distribution.

Parameters:

• n (Int) - Upper bound (exclusive). Must be positive.

Returns: Int: A random integer in [0, n), or 0 if n <= 0

Security: Uses rejection sampling to prevent modulo bias in range selection

Int -> Int

dice-roll = random-int 6  # Returns 0-5
print "You rolled: ${dice-roll + 1}"

random-bool?

Generates a cryptographically secure random boolean value.

Returns true or false with equal probability (50% each).

Returns: Bool: A random boolean value

() -> Bool

if random-bool?() then
  print "Heads"
else
  print "Tails"

sha256

Computes the SHA-256 hash of a message.

SHA-256 is a cryptographic hash function that produces a 256-bit (32-byte) hash value. It is part of the SHA-2 family and widely used for integrity verification and digital signatures.

Parameters:

• message (String) - The message to hash

Returns: String: The hash as a 64-character hexadecimal string

Security: SHA-256 is collision-resistant and suitable for most cryptographic purposes

String -> String

hash = sha256 "Hello, World!"
print "SHA-256: ${hash}"

sha512

Computes the SHA-512 hash of a message.

SHA-512 is a cryptographic hash function that produces a 512-bit (64-byte) hash value. It provides a higher security margin than SHA-256 and is faster on 64-bit processors.

Parameters:

• message (String) - The message to hash

Returns: String: The hash as a 128-character hexadecimal string

Security: SHA-512 provides higher security margin than SHA-256

String -> String

hash = sha512 "Hello, World!"
print "SHA-512: ${hash}"

hash

Computes the BLAKE2b hash of a message.

BLAKE2b is a cryptographic hash function that is faster than SHA-256 while providing at least the same level of security. It produces a 512-bit (64-byte) hash value and is optimized for 64-bit platforms.

Parameters:

• message (String) - The message to hash

Returns: String: The hash as a 128-character hexadecimal string

Security: BLAKE2b is faster than SHA-256 with equivalent or better security Recommended as the default hash function for general use

String -> String

hash = hash "Hello, World!"
print "BLAKE2b: ${hash}"

hmac-sha256

Computes HMAC-SHA256 authentication code.

HMAC (Hash-based Message Authentication Code) provides message authentication and integrity verification using a secret key. HMAC-SHA256 uses SHA-256 as the underlying hash function.

Parameters:

• message (String) - The message to authenticate
• key (String) - The secret key for authentication

Returns: String: 32 bytes of raw binary HMAC output

Security: The key should be at least 32 bytes for optimal security Use secure-compare? to verify HMAC values in constant time

String -> String -> String

mac = hmac-sha256 "message" "secret-key"
# Store mac for later verification

hmac-sha256-hex

Computes HMAC-SHA256 authentication code as hexadecimal.

Same as hmac-sha256 but returns the result as a hexadecimal string for easier storage and transmission.

Parameters:

• message (String) - The message to authenticate
• key (String) - The secret key for authentication

Returns: String: 64-character hexadecimal string representing the HMAC

String -> String -> String

mac = hmac-sha256-hex "message" "secret-key"
print "HMAC: ${mac}"

hmac-sha512

Computes HMAC-SHA512 authentication code.

HMAC (Hash-based Message Authentication Code) provides message authentication and integrity verification using a secret key. HMAC-SHA512 uses SHA-512 as the underlying hash function, providing a higher security margin.

Parameters:

• message (String) - The message to authenticate
• key (String) - The secret key for authentication

Returns: String: 64 bytes of raw binary HMAC output

Security: The key should be at least 64 bytes for optimal security Use secure-compare? to verify HMAC values in constant time

String -> String -> String

mac = hmac-sha512 "message" "secret-key"
# Store mac for later verification

hmac-sha512-hex

Computes HMAC-SHA512 authentication code as hexadecimal.

Same as hmac-sha512 but returns the result as a hexadecimal string for easier storage and transmission.

Parameters:

• message (String) - The message to authenticate
• key (String) - The secret key for authentication

Returns: String: 128-character hexadecimal string representing the HMAC

String -> String -> String

mac = hmac-sha512-hex "message" "secret-key"
print "HMAC: ${mac}"

hmac-sha256-size

Returns the HMAC-SHA256 output size in bytes.

Returns: Int: Always returns 32 (bytes)

() -> Int

hmac-sha512-size

Returns the HMAC-SHA512 output size in bytes.

Returns: Int: Always returns 64 (bytes)

() -> Int

hash-password

Hashes a password using Argon2id. Returns hash suitable for storage.

String -> Option String

verify-password?

Verifies a password against a stored hash.

String -> String -> Bool

key-size

Returns the encryption key size in bytes.

() -> Int

generate-key

Generates a new random encryption key as hex string.

() -> Option String

encrypt

Encrypts a message with a hex-encoded key. Returns base64-encoded ciphertext.

String -> String -> Option String

decrypt

Decrypts a message with a hex-encoded key. Returns plaintext or None.

String -> String -> Option String

secure-compare?

Performs constant-time string comparison for secure hash/key comparison.

String -> String -> Bool

sign-keypair

Generates an Ed25519 signing keypair.

() -> Option SignKeyPair

sign

Signs a message with a hex-encoded secret key. Returns hex-encoded signature.

String -> String -> Option String

verify-signature?

Verifies a signature against a message and public key.

String -> String -> String -> Bool

sign-public-key-size

Returns the public key size in bytes.

() -> Int

sign-secret-key-size

Returns the secret key size in bytes.

() -> Int

signature-size

Returns the signature size in bytes.

() -> Int

kx-keypair

Generates an X25519 key exchange keypair.

() -> Option KxKeyPair

kx-client-session-keys

Computes client session keys from client keypair and server public key.

KxKeyPair -> String -> Option SessionKeys

kx-server-session-keys

Computes server session keys from server keypair and client public key.

KxKeyPair -> String -> Option SessionKeys

kdf-keygen

Generates a master key for key derivation. Returns hex-encoded key.

() -> Option String

kdf-derive

Derives a subkey from a master key with unique ID and 8-char context.

String -> UInt64 -> String -> Option String

kdf-key-size

Returns the KDF master key size in bytes.

() -> Int