Crate crabgraph 

CrabGraph: A safe, ergonomic cryptographic library for Rust.

⚠️ Security Warning

This library has NOT been audited by third-party cryptographic experts. While it uses audited primitives (RustCrypto, dalek-cryptography), mistakes in composition can still lead to vulnerabilities.

DO NOT use in production without a professional security audit.

Overview

CrabGraph provides high-level, safe-by-default cryptographic operations:

• Authenticated Encryption (AEAD): aead::AesGcm256, aead::ChaCha20Poly1305
• Key Derivation: kdf::argon2_derive, kdf::pbkdf2_derive, kdf::hkdf_extract_expand
• Digital Signatures: asym::Ed25519KeyPair, asym::RsaKeyPair (with rsa-support feature)
• Key Exchange: asym::X25519KeyPair
• Message Authentication: mac::hmac_sha256
• Hashing: hash::sha256, hash::sha512
• Secure Random: rand::secure_bytes

⚠️ RSA Security Warning (rsa-support feature)

The RSA implementation has a known vulnerability (RUSTSEC-2023-0071 - Marvin timing attack). Use Ed25519 for signatures and X25519+AEAD for encryption unless RSA is specifically required for compatibility with legacy systems.

Quick Start

Authenticated Encryption

use crabgraph::{aead::{AesGcm256, CrabAead}, CrabResult};

fn encrypt_example() -> CrabResult<()> {
    // Generate a key
    let key = AesGcm256::generate_key()?;
    let cipher = AesGcm256::new(&key)?;

    // Encrypt
    let plaintext = b"Secret message";
    let ciphertext = cipher.encrypt(plaintext, None)?;

    // Decrypt
    let decrypted = cipher.decrypt(&ciphertext, None)?;
    assert_eq!(decrypted, plaintext);

    Ok(())
}

Password Hashing

use crabgraph::{kdf::argon2_derive, CrabResult};

fn hash_password() -> CrabResult<()> {
    let password = b"user_password";
    let salt = crabgraph::rand::secure_bytes(16)?;
     
    let hash = argon2_derive(password, &salt, 32)?;
    // Store hash and salt in database

    Ok(())
}

Digital Signatures

use crabgraph::{asym::Ed25519KeyPair, CrabResult};

fn sign_example() -> CrabResult<()> {
    let keypair = Ed25519KeyPair::generate()?;
    let message = b"Important document";
     
    let signature = keypair.sign(message);
    assert!(keypair.verify(message, &signature)?);

    Ok(())
}

Design Principles

1. Safe by Default: AEAD modes, automatic nonce generation, memory zeroing
2. Audited Primitives: Built on RustCrypto and dalek-cryptography
3. Ergonomic API: Clear function names, comprehensive docs, helpful errors
4. Performance: Zero-copy operations, hardware acceleration support
5. Interoperable: Helpers for compatibility with CryptoJS and OpenSSL

Feature Flags

• default: Enables std support
• std: Standard library support
• alloc: Allocation without full std
• no_std: Embedded/bare-metal support
• extended-hashes: SHA-3 and BLAKE2
• rsa-support: RSA encryption/signatures
• serde-support: Serialization support
• zero-copy: High-performance bytes integration
• wasm: WebAssembly support

Re-exports

pub use aead::AesGcm256;

pub use aead::ChaCha20Poly1305;

pub use aead::Ciphertext;

pub use aead::CrabAead;

pub use asym::Ed25519KeyPair;

pub use asym::X25519KeyPair;

pub use errors::CrabError;

pub use errors::CrabResult;

pub use hash::sha256;

pub use hash::sha512;

pub use hash::blake2b_512;

pub use hash::blake2s_256;

pub use hash::blake3_hash;

pub use hash::blake3_hex;

pub use hash::sha3_256;

pub use hash::sha3_512;

pub use kdf::argon2_derive;

pub use kdf::hkdf_extract_expand;

pub use kdf::pbkdf2_derive;

pub use mac::hmac_sha256;

pub use mac::hmac_sha256_verify;

pub use secrets::SecretArray;

pub use secrets::SecretVec;

Modules

aead

Authenticated Encryption with Associated Data (AEAD).

asym

Asymmetric cryptography (public-key cryptography).

encoding

Encoding and decoding utilities (Base64, Hex).

errors

Error types for CrabGraph cryptographic operations.

hash

Hashing utilities using SHA-2, SHA-3, BLAKE2, and BLAKE3 families.

kdf

Key Derivation Functions (KDFs).

key_rotation

Key rotation and versioning utilities.

kw

AES Key Wrap (AES-KW) implementation per RFC 3394.

mac

Message Authentication Code (MAC) utilities.

prelude

Prelude module for convenient imports.

rand

Secure random number generation utilities.

secrets

Secure secret handling with automatic memory zeroing.

utils

Utility functions for cryptographic operations.

Constants

VERSION

Library version.