crypto

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

Files

Dependencies

No Kit package dependencies.

Installation

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

Usage

import Kit.Crypto as Crypto

main = fn =>
  message = "Hello, Kit!"
  secret-key = "my-secret-key"

  # Hash messages with SHA-256 or SHA-512
  sha256-hash = Crypto.sha256 message
  sha512-hash = Crypto.sha512 message

  println "SHA-256: ${sha256-hash}"
  println "SHA-512: ${sha512-hash}"

  # Create HMAC tags for message authentication
  tag = Crypto.hmac-sha256-hex message secret-key
  println "HMAC-SHA256: ${tag}"

  # Verify tags with constant-time comparison
  expected = Crypto.hmac-sha256-hex message secret-key
  is-valid? = Crypto.secure-compare? tag expected
  println "Valid tag: ${is-valid?}"

  # HMAC size helpers return byte counts
  println "HMAC-SHA256 size: ${Crypto.hmac-sha256-size} bytes"
  println "HMAC-SHA512 size: ${Crypto.hmac-sha512-size} bytes"

main

Development

Running Examples

Run examples with the interpreter:

kit run --allow=ffi examples/crypto.kit

Compile examples to a native binary:

kit build examples/crypto.kit --allow=ffi && ./crypto

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (build native library, format, check, test):

kit dev

This will:

1. Build the Zig native library
2. Format and check source files in src/
3. Check examples in examples/
4. Run tests in tests/ with coverage

Running Parity Checks

Check that interpreted examples and compiled examples produce matching output:

kit parity

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/crypto/, making it available for import as Kit.Crypto in other projects.

License

This package is released under the 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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"