envr/zig-vendor/age-ffi/README.md

age-ffi

A Rust FFI wrapper for the age encryption library, with Zig bindings.

Overview

This library provides C-compatible FFI bindings for the age encryption library, making it easy to use age encryption from other languages. It includes comprehensive Zig bindings and examples.

Features

• X25519 encryption - Standard age public key encryption (age1...)
• SSH key support - Encrypt to SSH keys (ssh-ed25519, ssh-rsa)
• Plugin support - Full support for age plugins including:
  • age-plugin-se (Secure Enclave on macOS)
  • age-plugin-yubikey
  • Any other age-compatible plugin
• Passphrase encryption - Scrypt-based passphrase encryption
• Multiple recipients - Encrypt to multiple recipients at once
• Armor format - ASCII-armored output support
• File operations - Direct file encryption/decryption
• Memory-safe API - Proper error handling and memory management
• Comprehensive test suite

Supported Identity/Recipient Types

Type	Recipient Format	Identity Format
X25519	age1...	AGE-SECRET-KEY-1...
SSH	ssh-ed25519 ..., ssh-rsa ...	SSH private key file
Plugin	age1<plugin>1...	AGE-PLUGIN-<NAME>-1...
Passphrase	N/A	Passphrase string

Building

Rust Library

cargo build --release

This produces target/release/libage_ffi.a (static library).

Zig Bindings

cd zig
zig build

Run the example:

cd zig
zig build run

Run tests:

cd zig
zig build test

Usage

Zig

const age = @import("age");

// Generate a keypair
var keypair = try age.generateKeypair();
defer keypair.deinit();

// Encrypt data
const plaintext = "Hello, World!";
var encrypted = try age.encrypt(plaintext, keypair.getPublicKey());
defer encrypted.deinit();

// Decrypt data
var decrypted = try age.decrypt(encrypted.toSlice(), keypair.getPrivateKey());
defer decrypted.deinit();

// File operations with plugin support
try age.encryptToFile(plaintext, "age1se1...", "/path/to/output.age");
var content = try age.decryptFile("/path/to/file.age", "/path/to/identities");
defer content.deinit();

C

#include <age_ffi.h>

// Generate keypair
AgeKeypair keypair;
age_generate_keypair(&keypair);

// Encrypt
AgeBuffer encrypted;
age_encrypt(plaintext, plaintext_len, keypair.public_key, &encrypted);

// Decrypt
AgeBuffer decrypted;
age_decrypt(encrypted.data, encrypted.len, keypair.private_key, &decrypted);

// Free resources
age_free_buffer(&encrypted);
age_free_buffer(&decrypted);
age_free_keypair(&keypair);

Plugin Support

This library supports the age plugin protocol, allowing encryption and decryption with hardware-backed keys and other plugin-based identities.

Requirements

• The plugin binary must be in your $PATH (e.g., age-plugin-se)
• For Secure Enclave: macOS with Touch ID or Apple Watch

Example with Secure Enclave

# Install the plugin
brew install age-plugin-se

# Generate a Secure Enclave identity
age-plugin-se --generate -o ~/.age/se-identity.txt

# The library will automatically use the plugin when it sees:
# - Recipients starting with age1se1...
# - Identities starting with AGE-PLUGIN-SE-...

API Reference

Key Generation

• age_generate_keypair() - Generate X25519 keypair
• age_generate_x25519() - Generate X25519 keypair (alias)
• age_x25519_to_public() - Derive public key from private key

Encryption

• age_encrypt() - Encrypt to a single recipient
• age_encrypt_multi() - Encrypt to multiple recipients
• age_encrypt_armor() - Encrypt with ASCII armor
• age_encrypt_passphrase() - Encrypt with passphrase
• age_encrypt_to_file() - Encrypt directly to file

Decryption

• age_decrypt() - Decrypt with identity string
• age_decrypt_multi() - Decrypt with multiple identities
• age_decrypt_file() - Decrypt file using identity file (supports plugins)
• age_decrypt_passphrase() - Decrypt with passphrase

Utilities

• age_armor() - Wrap binary data in ASCII armor
• age_dearmor() - Unwrap ASCII-armored data
• age_validate_recipient() - Check if recipient string is valid
• age_validate_identity() - Check if identity string is valid
• age_version() - Get library version

License

This project is dual-licensed under MIT and Apache-2.0, matching the age library.