crypto

Kind	ffi-zig
Categories	cryptography security ffi
Keywords	crypto sha256 sha512 hmac hash zig

Cryptographic primitives for Kit using Zig std.crypto (no external deps)

Files

File	Description
`kit.toml`	Package manifest with metadata and dependencies
`src/crypto.kit`	SHA-256/512 hashing, HMAC, and secure comparison
`zig/crypto.zig`	FFI bindings using Zig std.crypto
`tests/crypto.test.kit`	Tests for init and HMAC size functions
`examples/crypto-hmac.kit`	API signing, webhook verification with HMAC
`examples/crypto-kdf.kit`	Key derivation for multi-tenant encryption
`examples/crypto-key-exchange.kit`	X25519 client-server session key exchange
`examples/crypto-signatures.kit`	Ed25519 digital signatures and verification
`examples/crypto.kit`	Hashing, encryption, and password operations
`LICENSE`	MIT license file

Dependencies

No Kit package dependencies.

Installation

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

Usage

import Kit.Crypto

License

MIT License - see LICENSE for details.

Exported Functions & Types

`init`

Initialize the crypto library.

This is a no-op provided for API compatibility with kit-sodium. The Zig-based implementation requires no initialization.

Returns: Ok 0 - Always succeeds

Unit -> Result Int a

match init()
  | Ok _ -> print "Crypto ready"
  | Err _ -> ()  # Never happens

`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 widely used for integrity verification and digital signatures.

Parameters:

message (String) - The message to hash

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

String -> String

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

`sha256-bytes`

Computes the SHA-256 hash and returns raw bytes.

Parameters:

message (String) - The message to hash

Returns: String: The hash as 32 raw bytes

String -> String

hash-bytes = sha256-bytes "Hello, World!"

`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.

Parameters:

message (String) - The message to hash

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

String -> String

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

`sha512-bytes`

Computes the SHA-512 hash and returns raw bytes.

Parameters:

message (String) - The message to hash

Returns: String: The hash as 64 raw bytes

String -> String

hash-bytes = sha512-bytes "Hello, World!"

`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"

`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-sha256-size`

Returns the HMAC-SHA256 output size in bytes.

Returns: Int: Always returns 32 (bytes)

Unit -> Int

`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"

`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-sha512-size`

Returns the HMAC-SHA512 output size in bytes.

Returns: Int: Always returns 64 (bytes)

Unit -> Int

`secure-compare?`

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

This function compares two strings in constant time to prevent timing attacks. Use this when comparing HMAC values, password hashes, or any security-sensitive data.

Parameters:

a (String) - First string to compare
b (String) - Second string to compare

Returns: Bool: true if the strings are equal, false otherwise

Security: The comparison time does not vary based on where strings differ, preventing timing side-channel attacks.

String -> String -> Bool

if secure-compare? computed-mac expected-mac then
  print "Valid"
else
  print "Invalid"