Cryptographic Primitives

Explore the cryptographic foundation of ZeroEcho, focusing on AES configuration, password-based key derivation, and the secure encapsulation of cryptographic parameters. These primitives provide a flexible yet safe abstraction over Bouncy Castle's crypto backend.

AES Key Sizes

AES encryption is supported in multiple key sizes, encapsulated by the AesMode enum:

public enum AesMode {
    AES_128(128),
    AES_192(192),
    AES_256(256);

    …
}

Each variant defines its key length in bits (128, 192, or 256). The corresponding key byte length is derived internally for convenience.

AES Cipher Modes

The actual AES transformation type (block mode and padding scheme) is represented by the AesCipherType enum:

public enum AesCipherType {
    CBC("AES/CBC/PKCS7Padding"),
    GCM("AES/GCM/NoPadding"),
    CTR("AES/CTR/NoPadding");

    …
}

Each mode instantiates a specific BouncyCastle cipher implementation. CBC provides standard block encryption with padding, GCM offers authenticated encryption, and CTR behaves as a stream cipher.

AES Parameter Models

Two main AES parameter containers are available, both implementing the AesParameters interface:

• BasicAesParameters — used for key material explicitly specified or externally managed.
• DerivedAesParameters — used when key material is derived from a password and salt.

public record BasicAesParameters(
    AesMode mode,
    KeyParameter key,
    byte[] iv,
    AesCipherType cipherType
) implements AesParameters { … }

public record DerivedAesParameters(
    AesMode mode,
    KeyParameter key,
    byte[] iv,
    byte[] salt,
    int iterations,
    AesCipherType cipherType
) implements AesParameters {
    public BasicAesParameters toBasicParameters() {
        return new BasicAesParameters(mode, key, iv, cipherType);
    }
}

Both types ensure strict validation of input lengths and structural consistency.

Password-Derived Parameters

The DerivedAesParameters implementation captures the metadata used to reconstruct a cryptographic context from a password. Key derivation is performed using PBKDF2 (or similar KDF), and both the salt and the number of iterations are stored.

This allows deterministic derivation and ensures compatibility across sessions or devices without the need to persist key material.

Embedded Metadata for Stateless Decryption

When encryption is performed via password, the PasswordBasedAesEncryptor (or SecretDerivedAesParameters) class writes a compact header in front of the ciphertext. This enables self-contained streams.

The header layout is:

+----------------------+-------------------+------------------------+
| Salt Length (varint) | Salt (raw bytes)  | Iterations (varint)    |
+----------------------+-------------------+------------------------+

Java pseudocode that writes this header:

IOUtil.writePack7I(header, salt.length);
header.write(salt);
IOUtil.writePack7I(header, iterations);

This header allows the decryptor to reconstruct DerivedAesParameters without any external data, making streams portable and secure by design.

Summary

ZeroEcho's cryptographic model combines clear encapsulation of AES settings with secure defaults and metadata-aware streaming. This ensures robust encryption while simplifying usage across use cases like file encryption, messaging, or session tokens.