HeroCrypt: Effortless Cryptography with HeroDB

HeroCrypt is a library that provides a simple and secure way to handle encryption and digital signatures by leveraging the power of HeroDB. It abstracts the underlying complexity of cryptographic operations, allowing you to secure your application's data with minimal effort.

What is HeroDB?

HeroDB is a high-performance, Redis-compatible database that offers built-in support for advanced cryptographic operations using the AGE encryption format. This integration makes it an ideal backend for applications requiring robust, end-to-end security.

Core Features of HeroCrypt

• Encryption & Decryption: Securely encrypt and decrypt data.
• Digital Signatures: Sign and verify messages to ensure their integrity and authenticity.
• Flexible Key Management: Choose between two modes for managing your cryptographic keys:

1. Key-Managed (Server-Side): Let HeroDB manage your keys. Keys are stored securely within the database and are referenced by a name. This is the recommended approach for simplicity and centralized key management.
2. Stateless (Client-Side): Manage your own keys on the client side. You pass the key material with every cryptographic operation. This mode is for advanced users who require full control over their keys.

To start a db see

https://git.ourworld.tf/herocode/herodb

to do:

hero git pull https://git.ourworld.tf/herocode/herodb
~/code/git.ourworld.tf/herocode/herodb/run.sh

Key-Managed Mode (Recommended)

In this mode, HeroDB generates and stores the keypairs for you. You only need to provide a name for your key.

Encryption

import incubaid.herolib.crypt.herocrypt

mut client := herocrypt.new_default()!

// Generate and persist a named encryption keypair
client.keygen('my_app_key')!

// Encrypt a message
message := 'This is a secret message.'
ciphertext := client.encrypt_by_name('my_app_key', message)!

// Decrypt the message
decrypted_message := client.decrypt_by_name('my_app_key', ciphertext)!
assert decrypted_message == message

Signing

import incubaid.herolib.crypt.herocrypt

mut client := herocrypt.new_default()!

// Generate and persist a named signing keypair
client.sign_keygen('my_signer_key')!

// Sign a message
message := 'This message needs to be signed.'
signature := client.sign_by_name('my_signer_key', message)!

// Verify the signature
is_valid := client.verify_by_name('my_signer_key', message, signature)!
assert is_valid

Stateless Mode (Advanced)

In this mode, you are responsible for generating and managing your own keys.

Encryption

import incubaid.herolib.crypt.herocrypt

mut client := herocrypt.new_default()!

// Generate an ephemeral encryption keypair
keypair := client.gen_enc_keypair()!
recipient_pub := keypair[0]
identity_sec := keypair[1]

// Encrypt a message
message := 'This is a secret message.'
ciphertext := client.encrypt(recipient_pub, message)!

// Decrypt the message
decrypted_message := client.decrypt(identity_sec, ciphertext)!
assert decrypted_message == message

Signing

import incubaid.herolib.crypt.herocrypt

mut client := herocrypt.new_default()!

// Generate an ephemeral signing keypair
keypair := client.gen_sign_keypair()!
verify_pub_b64 := keypair[0]
sign_sec_b64 := keypair[1]

// Sign a message
message := 'This message needs to be signed.'
signature := client.sign(sign_sec_b64, message)!

// Verify the signature
is_valid := client.verify(verify_pub_b64, message, signature)!
assert is_valid

fn new(url_ string) !&HeroCrypt

new returns a new HeroCrypt client url e.g. localhost:6381 (default) It pings the server to ensure a valid connection.

fn new_default() !&HeroCrypt

new_default returns a new HeroCrypt client with the default URL.

struct HeroCrypt {
pub mut:
	redis_client &redisclient.Redis
}

HeroCrypt provides a client for HeroDB's AGE cryptography features.

fn (mut self HeroCrypt) gen_enc_keypair() ![]string

gen_enc_keypair generates an ephemeral encryption keypair. Returns: [recipient_public_key, identity_secret_key]

fn (mut self HeroCrypt) encrypt(recipient_public_key string, message string) !string

encrypt encrypts a message with a recipient public key.

fn (mut self HeroCrypt) decrypt(identity_secret_key string, ciphertext_b64 string) !string

decrypt decrypts a ciphertext with an identity secret key.

fn (mut self HeroCrypt) gen_sign_keypair() ![]string

gen_sign_keypair generates an ephemeral signing keypair. Returns: [verify_public_key_b64, sign_secret_key_b64]

fn (mut self HeroCrypt) sign(sign_secret_key_b64 string, message string) !string

sign signs a message with a signing secret key.

fn (mut self HeroCrypt) verify(verify_public_key_b64 string, message string, signature_b64 string) !bool

verify verifies a signature with a public verification key.

fn (mut self HeroCrypt) keygen(name string) ![]string

keygen generates and persists a named encryption keypair.

fn (mut self HeroCrypt) encrypt_by_name(name string, message string) !string

encrypt_by_name encrypts a message using a named key.

fn (mut self HeroCrypt) decrypt_by_name(name string, ciphertext_b64 string) !string

decrypt_by_name decrypts a ciphertext using a named key.

fn (mut self HeroCrypt) sign_keygen(name string) ![]string

sign_keygen generates and persists a named signing keypair.

fn (mut self HeroCrypt) sign_by_name(name string, message string) !string

sign_by_name signs a message using a named signing key.

fn (mut self HeroCrypt) verify_by_name(name string, message string, signature_b64 string) !bool

verify_by_name verifies a signature with a named verification key.