seal-crypto

seal-crypto is the underlying cryptographic engine for the seal-kit ecosystem, providing a set of pure, trait-based cryptographic capability abstractions and implementations.

中文文档 (Chinese Version)

⚠️ Important Note on Usage

While seal-crypto provides a powerful and flexible trait-based cryptographic engine, it is a low-level library. For most applications, we strongly recommend using the high-level wrapper, seal-crypto-wrapper.

The wrapper library offers a safer and more user-friendly API by tightly binding algorithm information with keys, which helps prevent common cryptographic misuses (e.g., using a key with the wrong algorithm). It is designed for ease of use without sacrificing security.

Core Philosophy

seal-crypto is designed to be clear, modern, and aligned with Rust API best practices. Its core principles are:

1. Trait-Based Abstraction: The library is built around a set of traits that define fundamental cryptographic operations (e.g., encryption, signing, key generation). This approach cleanly separates the interface (what you want to do) from the implementation (how it's done).
2. Modular & Composable: Specific cryptographic algorithms (like AES, RSA, Kyber) are implemented as independent units that fulfill these traits. Users can enable only the algorithms they need via Cargo features, resulting in a smaller, more focused application.
3. Security-First:
   • Memory Safety: All sensitive data, such as PrivateKey, SymmetricKey, and SharedSecret, are wrapped using the zeroize crate. This ensures that the memory they occupy is securely wiped when they go out of scope, significantly reducing the risk of key material leakage.
   • Explicit Error Handling: Each cryptographic domain has its own specific, descriptive error types (e.g., SignatureError, KemError) to allow for clear and robust error handling.
4. Ease of Use: A prelude module is provided. A simple use seal_crypto::prelude::* brings all essential traits and types into scope, streamlining development.

Quick Start

Add seal-crypto to your Cargo.toml. You can enable the full feature to include all supported algorithms, or select individual algorithm features as needed.

[dependencies]
# Enable all features
seal-crypto = { version = "0.1.0", features = ["full"] }

# Or, enable only specific algorithms
# seal-crypto = { version = "0.1.0", features = ["rsa", "aes-gcm", "kyber"] }

Example Usage

Here is a quick example of signing and verifying a message using RSA-4096 with SHA-256.

use seal_crypto::prelude::*;
use seal_crypto::schemes::asymmetric::traditional::rsa::Rsa4096;
// use seal_crypto::schemes::hash::Sha256;

fn main() -> Result<(), CryptoError> {
    // 1. Define the scheme by key parameters.
    // By default, RsaScheme uses Sha256 as the hash function.
    type MyRsaScheme = Rsa4096;

    // 2. Generate a key pair.
    let (public_key, private_key) = MyRsaScheme::generate_keypair()?;
    println!("Successfully generated RSA-4096 key pair.");

    // 3. Prepare a message and sign it.
    let message = b"This is an important message.";
    let signature = MyRsaScheme::sign(&private_key, message)?;
    println!("Message signed successfully.");

    // 4. Verify the signature.
    MyRsaScheme::verify(&public_key, message, &signature)?;
    println!("Signature verification successful!");

    Ok(())
}

For more detailed examples, check out the examples directory. You can run them using cargo:

# Run the hybrid encryption example
cargo run --example hybrid_encryption --features "full"

# Run the digital signature example
cargo run --example digital_signature --features "full"

Trait Design Philosophy

The power and clarity of seal-crypto come from its layered, consistent, and single-responsibility trait architecture. This design makes the library both easy to use for common tasks and flexible enough for advanced generic programming.

The hierarchy can be visualized as follows:

graph TD
    subgraph "Top Layer: Algorithm Identity"
        Z["Algorithm<br/><i>The top-level trait for all schemes,<br/>provides a 'NAME' constant.</i>"]
    end

    subgraph "Layer 1: Core Capabilities"
        subgraph "Core Cryptographic Schemes"
            C["AsymmetricKeySet"]
            D["SymmetricKeySet"]

            F["KeyGenerator<br/><i>'generate_keypair'</i>"]
            G["Signer / Verifier<br/><i>'sign'/'verify'</i>"]
            H["Kem<br/><i>'encapsulate'/'decapsulate'</i>"]
            M["KeyAgreement<br/><i>'agree'</i>"]
            
            I["SymmetricKeyGenerator<br/><i>'generate_key'</i>"]
            J["AeadEncryptor / Decryptor<br/><i>'encrypt'/'decrypt'</i>"]
        end
        
        subgraph "Derivation Schemes"
            N_BASE["Derivation<br/><i>Top-level trait for derivation</i>"]
            N_KEY["KeyBasedDerivation<br/><i>For high-entropy keys</i>"]
            N_PASS["PasswordBasedDerivation<br/><i>For low-entropy passwords</i>"]
            N_XOF["XofDerivation<br/><i>For streamable output (XOFs)</i>"]
        end
    end
    
    subgraph "Layer 2: Scheme Bundles (for convenience)"
        K["SignatureScheme<br/><i>Bundles KeyGenerator, Signer, Verifier.</i>"]
        L["AeadScheme<br/><i>Bundles SymmetricKeySet, SymmetricKeyGenerator, etc.</i>"]
    end

    Z --> C
    Z --> D
    Z --> N_BASE
    
    C --> F
    C --> G
    C --> H
    C --> M
    
    F & G --> K

    D --> I
    D --> J
    I & J --> L

    N_BASE --> N_KEY
    N_BASE --> N_PASS
    N_BASE --> N_XOF

Here's a breakdown of the layers:

1. Top Layer: Algorithm Identity (Algorithm): This is the unified top-level trait for all cryptographic schemes.
2. Layer 1: Core Capabilities: This layer is the heart of the library, linking scheme sets like AsymmetricKeySet to their capability traits (Signer, Kem, etc.).
3. Layer 2: Scheme Bundles: For user convenience, we provide "supertraits" like SignatureScheme that bundle relevant capabilities.

This layered approach ensures that every trait has a clear purpose. The detailed key inheritance model is shown in the next diagram.

Parameterization Design

seal-crypto employs a flexible parameterization strategy to accommodate the needs of different types of cryptographic algorithms. At the core of this strategy is a set of Params traits defined in src/traits/params.rs.

• SchemeParams: Provides a base trait for cryptographic schemes that use the "marker dispatch" pattern (e.g., AES-GCM, Kyber). Specific parameter sets (like Aes128GcmParams) inherit from this trait and are passed as generic arguments to the schemes themselves (e.g., AesGcmScheme<P: AesGcmParams>).
• PrimitiveParams: Offers a unified interface for underlying cryptographic primitives like hash functions and XOFs, defining NAME and ID_OFFSET. Traits like Hasher and Xof inherit from it.
• Parameterized: Provides an introspection interface for schemes whose parameters are configured at runtime (like Argon2) or composed from multiple generics (like RSA). Through the get_type_params() and get_instance_params() methods, one can query the full parameter configuration of a scheme at runtime.

The relationship between these parameter traits can be summarized as follows:

graph TD
    subgraph "Parameter Traits"
        SchemeParams -- "Inherited by" --> SpecificParams["AesGcmParams, KyberParams, etc."]
        PrimitiveParams -- "Inherited by" --> Primitives["Hasher, Xof"]
        
        SpecificParams -- "As generic constraint for" --> Schemes1["AesGcmScheme, KyberScheme, etc."]
        Primitives -- "As generic constraint for" --> Schemes2["HkdfScheme, ShakeScheme, etc."]
        
        Parameterized -- "Implemented by" --> Schemes3["Argon2Scheme, Pbkdf2Scheme, RsaScheme, etc."]
    end

Key Inheritance Detail

To keep the main diagram clean, the relationship between scheme sets, their associated key types, and the base Key trait is detailed below. This illustrates how the specific keys used by a scheme are defined and how they build upon the fundamental Key primitive.

graph TD
    subgraph "Key Inheritance Model"
        A["Key<br/><i>Defines basic key behaviors<br/>like serialization.</i>"]
        C["AsymmetricKeySet"]
        D["SymmetricKeySet"]
        
        PK["(type PublicKey)"]
        SK["(type PrivateKey)"]
        SymK["(type Key)"]

        C -. "defines" .-> PK
        C -. "defines" .-> SK
        D -. "defines" .-> SymK
        
        PK -- "inherits" --> A
        SK -- "inherits" --> A
        SymK -- "inherits" --> A
    end

This layered approach ensures that every trait has a clear purpose, preventing ambiguity and making the entire library highly consistent and predictable.

Supported Algorithms

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0). See the LICENSE file for details.