sare-lib 0.1.1

Hybrid post-quantum encryption library providing SARE standard primitives and APIs.
Documentation

SARE Lib

Crates.io Version Crates.io License Crates.io Size Crates.io Total Downloads

SARE LIB IS IN BETA. IT IS QUICKLY EVOLVING AND NOT YET AUDITED FOR SECURITY. USE WITH CAUTION.

SARE Lib is the high-level library for building applications using the SARE cryptographic standard. It provides safe, modular, and user-friendly interfaces for encryption, decryption, signing, key management, and certificate handling, while relying on sare-core under the hood for low-level cryptography.

Core Principles

  • Hybrid Security: SARE Lib is secure against both classical and quantum attacks.

  • Modular Design: Easily integrate new algorithms for encryption, signing, or key derivation.

  • Human Rights Focused: Privacy and security are foundational rights. SARE empowers users to protect these rights online. Even when quantum-computers emerge.

This is not a roll-your-own-crypto project. Only audited, standard, and proven algorithms are used for all encryption, signing, and key encapsulation operations.

Installation

Using SARE Lib in a Rust Project

Add it to your dependencies in Cargo.toml:

[dependencies]
sare-lib = "0.1"

Using Cargo

Install via Cargo:

cargo add sare-lib

Example Usage

Encrypting and Decrypting Files

Symmetric Encryption

use sare_lib::{encryption::Encryptor, keys::{EncryptionAlgorithm, RECOMMENDED_PKDF_PARAMS}};
use secrecy::SecretVec;
use std::fs::File;

let input_file = File::open("message.txt")?;
let mut output_file = File::create("message.enc")?;
let passphrase = SecretVec::new(b"supersecret".to_vec());

// Generate key derivation function (KDF) using recommended parameters
let pkdf = Encryptor::get_pkdf(&passphrase, RECOMMENDED_PKDF_PARAMS, 1);

// Encrypt the file symmetrically using XChaCha20-Poly1305 AEAD
Encryptor::encrypt_with_passphrase(&mut input_file, &mut output_file, pkdf, EncryptionAlgorithm::XCHACHA20POLY1305)?;

Symmetric Decryption

use sare_lib::encryption::Decryptor;
use secrecy::SecretVec;
use std::fs::File;

let mut input_file = File::open("message.enc")?;
let mut output_file = File::create("message_decrypted.txt")?;
let passphrase = SecretVec::new(b"supersecret".to_vec());

Decryptor::decrypt_with_passphrase(passphrase, &mut input_file, &mut output_file)?;

Asymmetric Encryption

use sare_lib::{encryption::Encryptor, keys::{MasterKey, SharedPublicKey, EncryptionAlgorithm}};
use std::fs::File;

let input_file = File::open("document.txt")?;
let mut output_file = File::create("document.enc")?;

// Load master key and recipient public key
let master_key = MasterKey::load("MASTER_KEY.pem")?;
let recipient_key = SharedPublicKey::from_pem(std::fs::read_to_string("recipient.pem")?)?;

let encryptor = Encryptor::new(master_key);
encryptor.encrypt_with_recipient(&mut input_file, &mut output_file, &recipient_key, EncryptionAlgorithm::XCHACHA20POLY1305)?;

Asymmetric Decryption

use sare_lib::encryption::Decryptor;
use std::fs::File;

// Load your master key
let master_key = MasterKey::load("MASTER_KEY.pem")?;
let decryptor = Decryptor::new(master_key);

let mut input_file = File::open("document.enc")?;
let mut output_file = File::create("document_decrypted.txt")?;

// Decrypt the file
let signature = decryptor.decrypt_with_recipient(&mut input_file, &mut output_file)?;

if let Some(sig) = signature {
    println!("Signature attached: {:?}", sig.fullchain_fingerprint);
}

Signing and Verifying

Detached Signature

use sare_lib::signing::Signing;
use std::fs;

let master_key = MasterKey::load("MASTER_KEY.pem")?;
let signer = Signing::new(master_key);

let message = fs::read("report.txt")?;
let signature = signer.sign_detached(&message);
fs::write("report.sig", signature.encode_with_magic_byte())?;

Verifying a Detached Signature

use sare_lib::signing::Signing;
use sare_lib::format::signature::SignatureHeaderFormat;
use std::fs;

let signed_file = fs::read("report.sig")?;
let original_file = fs::read("report.txt")?;

let signature_header = SignatureHeaderFormat::decode_with_magic_byte(&signed_file)?;
let is_valid = Signing::verify_detached(&signature_header, &original_file)?;

println!("Signature valid: {}", is_valid);

Master Key Management

Generate a Master Key

use sare_lib::keys::{MasterKey, HybridKEMAlgorithm, HybridSignAlgorithm};

let master_key = MasterKey::generate(
    HybridKEMAlgorithm::default(),
    HybridSignAlgorithm::default()
);

// Export the master key (optionally encrypted with a passphrase)
master_key.export(Some("supersecret".as_bytes().to_vec().into()), &mut std::fs::File::create("MASTER_KEY.pem")?)?;

// Export public key
master_key.export_public(&mut std::fs::File::create("PUB_KEY.pem")?)?;

Inspect a Master Key

let master_key = MasterKey::load("MASTER_KEY.pem")?;
println!("Master Key Fingerprint: {:?}", master_key.get_fullchain_public_fingerprint());
println!("Mnemonic Seed: {}", master_key.to_mnemonic().expose_secret());

Revoke a Master Key

use sare_lib::{certificate::Certificate, format::certificate::Issuer, format::certificate::RevocationReason};

let master_key = MasterKey::load("MASTER_KEY.pem")?;
let issuer = Issuer::new("Your Name", "your@email.com");

let revocation_cert = Certificate::new_revocation(master_key, 1682611200, issuer, RevocationReason::NoReasonSpecified);
revocation_cert.export(std::fs::File::create("REVOC_KEY.asc")?)?;

Recipient Management

use sare_lib::keys::SharedPublicKey;

// Add a recipient
let recipient_key = SharedPublicKey::from_pem(std::fs::read_to_string("recipient.pem")?)?;
recipient_key.export(std::fs::File::create("RECIPIENT.pem")?)?;

// Load and list recipients
let recipient_key = SharedPublicKey::from_pem(std::fs::read_to_string("RECIPIENT.pem")?)?;
println!("Recipient fingerprint: {:?}", recipient_key.fullchain_public_key.calculate_fingerprint());

For more detailed documentation on the underlying processes and formatting happening behind the scenes, please read our documentation book at https://sareproject.github.io/docs

Core Components

  • Keys: Generate master keys, export/import keys, derive subkeys for encryption/signing

  • Encryption & Decryption: Symmetric (password-based) and asymmetric (recipient-based) encryption engines

  • Signing: Hybrid post-quantum + classical signatures with attached or detached message support

  • Certificates: Validation and revocation certificates

  • Modular Cryptography: Easily extendable to new algorithms

SARE Lib is designed to make application development straightforward while letting sare-core handle the complexity of cryptography in the background.

Security Notice

SARE is built to use audited and standard cryptographic algorithms at the low-level encryption, signing, and encapsulation layers.

However, SARE itself still needs to be audited to be considered secure. Please use it at your own risk and do not use it for critical use cases.

If you've found security vulnerabilities, please follow our security policy for reporting. Do not report them in the GitHub issues or announce them publicly until we have released a fix for the issue: https://github.com/SareProject/sare/security/policy

Support

If you want to help SARE grow, the best way is financially. Please check out our donation page: https://sareproject.github.com/docs/support

But a share on social media, a star on our GitHub repo, or even a simple supporting message is enough motivation for us to keep going.

License

SARE Lib is released under a combination of the MIT License and the Apache License.