rsa

Kind	ffi-c
Capabilities	ffi
Categories	cryptography security ffi
Keywords	rsa crypto openssl jwt rs256 signing

RSA cryptographic operations for Kit using OpenSSL

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_rsa.c`	C FFI wrapper around OpenSSL RSA operations
`c/kit_rsa.h`	C header for FFI wrapper
`examples/algorithms.kit`	Example using RS256, RS384, and RS512 signing and verification
`examples/basic.kit`	Basic RS256 signing and verification example
`examples/error-types.kit`	RSA error type handling example
`examples/keys.kit`	Shared sample key pair for examples
`kit.toml`	Package manifest with native OpenSSL metadata
`src/rsa.kit`	Kit RSA API and error types
`tests/error-types.test.kit`	Tests for RSA error types and traits
`tests/rsa.test.kit`	Tests for RSA result and API shape

Dependencies

No Kit package dependencies.

Native dependencies:

OpenSSL 3
Kit FFI capability

Install OpenSSL headers and libraries:

brew install openssl@3
sudo apt install libssl-dev
sudo dnf install openssl-devel

Installation

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

Usage

import Kit.Rsa as RSA

main = fn =>
  private-key-pem = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  public-key-pem = "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  data = "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0"

  match RSA.sign-sha256 private-key-pem data
    | Ok signature ->
      println "Signature: ${signature}"

      match RSA.verify-sha256 public-key-pem data signature
        | Ok true -> println "Signature is valid"
        | Ok false -> println "Signature is invalid"
        | Err err -> println "Verify error: ${show err}"

    | Err err ->
      println "Sign error: ${show err}"

main

Available high-level functions:

RSA.sign-sha256, RSA.verify-sha256 for RS256
RSA.sign-sha384, RSA.verify-sha384 for RS384
RSA.sign-sha512, RSA.verify-sha512 for RS512

The signing functions return base64url-encoded signatures suitable for JWT signing input.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi
kit run examples/algorithms.kit --allow=ffi
kit run examples/error-types.kit --allow=ffi

The --allow=ffi flag is required because this package calls OpenSSL through a native C wrapper.

Compile examples to native binaries:

kit build examples/basic.kit --allow=ffi && ./basic
kit build examples/algorithms.kit --allow=ffi && ./algorithms

These examples exercise live OpenSSL FFI. If signing reports RSASignError or native builds fail with unresolved kit_rsa_* symbols, check the native wrapper and package linking configuration in kit.toml, c/kit_rsa.c, and c/kit_rsa.h.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

The current tests focus on Kit-side error types, traits, result handling, and function availability. They intentionally avoid live OpenSSL calls so type-level behavior can be tested without depending on platform FFI loading.

Running kit dev

Run the standard development workflow:

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc src/rsa.kit

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/rsa/, making it available for import as Kit.Rsa in other projects.

If you change c/kit_rsa.c, c/kit_rsa.h, src/rsa.kit, or native metadata in kit.toml, run kit install before testing examples that import Kit.Rsa. That refreshes the package cache used by package-style imports.

License

This package is released under the MIT License - see LICENSE for details.

OpenSSL is released under the Apache License 2.0.

Exported Functions & Types

`RSAError`

RSA error type with specific variants for different failure modes.

Variants

RSAParseError {message}

RSASignError {message}

RSAVerifyError {message}

`sign-sha256`

Sign data with RSA-SHA256 (RS256).

Creates a digital signature using the RSA-SHA256 algorithm. This is the standard algorithm used for JWT RS256 tokens.

Parameters:

pem-key (String) - RSA private key in PEM format
data (String) - Data to sign

Returns: Result String RSAError:- Ok signature: Base64url-encoded signature (suitable for JWT)- Err RSAError: Error with details about what went wrong

NonEmptyString -> String -> Result String RSAError

pem-key = File.read "private-key.pem"
data = "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0"
match sign-sha256 pem-key data
  | Ok signature -> print "Signature: ${signature}"
  | Err e -> print "Error: ${Show.show e}"

`sign-sha384`

Sign data with RSA-SHA384 (RS384).

Creates a digital signature using the RSA-SHA384 algorithm. This provides a higher security margin than RS256.

Parameters:

pem-key (String) - RSA private key in PEM format
data (String) - Data to sign

Returns: Result String RSAError:- Ok signature: Base64url-encoded signature (suitable for JWT)- Err RSAError: Error with details about what went wrong

NonEmptyString -> String -> Result String RSAError

match sign-sha384 pem-key data
  | Ok signature -> print signature
  | Err e -> print "Error: ${Show.show e}"

`sign-sha512`

Sign data with RSA-SHA512 (RS512).

Creates a digital signature using the RSA-SHA512 algorithm. This provides the highest security margin among the RS* algorithms.

Parameters:

pem-key (String) - RSA private key in PEM format
data (String) - Data to sign

Returns: Result String RSAError:- Ok signature: Base64url-encoded signature (suitable for JWT)- Err RSAError: Error with details about what went wrong

NonEmptyString -> String -> Result String RSAError

match sign-sha512 pem-key data
  | Ok signature -> print signature
  | Err e -> print "Error: ${Show.show e}"

`verify-sha256`

Verify data with RSA-SHA256 (RS256).

Verifies a digital signature using the RSA-SHA256 algorithm. This is the standard algorithm used for JWT RS256 token verification.

Parameters:

pem-key (String) - RSA public key in PEM format
data (String) - Data that was signed
signature (String) - Base64url-encoded signature to verify

Returns: Result Bool RSAError:- Ok true: Signature is valid- Ok false: Signature is invalid- Err RSAError: Error during verification (e.g., invalid key format)

NonEmptyString -> String -> String -> Result Bool RSAError

public-key = File.read "public-key.pem"
data = "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0"
signature = "..."
match verify-sha256 public-key data signature
  | Ok true -> print "Valid signature"
  | Ok false -> print "Invalid signature"
  | Err e -> print "Error: ${Show.show e}"

`verify-sha384`

Verify data with RSA-SHA384 (RS384).

Verifies a digital signature using the RSA-SHA384 algorithm.

Parameters:

pem-key (String) - RSA public key in PEM format
data (String) - Data that was signed
signature (String) - Base64url-encoded signature to verify

Returns: Result Bool RSAError:- Ok true: Signature is valid- Ok false: Signature is invalid- Err RSAError: Error during verification

NonEmptyString -> String -> String -> Result Bool RSAError

`verify-sha512`

Verify data with RSA-SHA512 (RS512).

Verifies a digital signature using the RSA-SHA512 algorithm.

Parameters:

pem-key (String) - RSA public key in PEM format
data (String) - Data that was signed
signature (String) - Base64url-encoded signature to verify

Returns: Result Bool RSAError:- Ok true: Signature is valid- Ok false: Signature is invalid- Err RSAError: Error during verification

NonEmptyString -> String -> String -> Result Bool RSAError