Module encryption 

AEAD encryption for key material at rest.

This module provides ChaCha20-Poly1305 AEAD encryption with Argon2id key derivation for protecting secret key material at rest.

Security Properties

• Authenticated Encryption: ChaCha20-Poly1305 provides both confidentiality and integrity protection. Any tampering with the ciphertext will be detected during decryption.

• Key Derivation: Argon2id is used to derive encryption keys from passphrases, providing resistance against both GPU/ASIC attacks (memory-hard) and side-channel attacks (data-independent memory access in the second phase).

• Random Salt and Nonce: Each encryption operation generates fresh random salt and nonce using the operating system’s secure RNG, ensuring that:

  • The same passphrase produces different ciphertexts
  • Nonce reuse is avoided

• Zeroization: Derived encryption keys are zeroized immediately after use.

Encrypted Key Format

The encrypted key is serialized as follows (77 bytes total):

┌─────────────────────────────────────┐
│ version: 1 (1 byte)                 │
│ salt: [u8; 16]                      │
│ nonce: [u8; 12]                     │
│ ciphertext: [u8; 32]                │
│ tag: [u8; 16]                       │
└─────────────────────────────────────┘

The ciphertext and tag are combined in the serialized format (48 bytes total for 32-byte plaintext + 16-byte authentication tag).

Example

use txgate_crypto::keys::SecretKey;
use txgate_crypto::encryption::{encrypt_key, decrypt_key};

// Generate a key to encrypt
let secret_key = SecretKey::generate();
let passphrase = "my secure passphrase";

// Encrypt the key
let encrypted = encrypt_key(&secret_key, passphrase).expect("encryption failed");

// Serialize for storage
let bytes = encrypted.to_bytes();

// Later, deserialize and decrypt
use txgate_crypto::encryption::EncryptedKey;
let encrypted = EncryptedKey::from_bytes(&bytes).expect("invalid format");
let decrypted = decrypt_key(&encrypted, passphrase).expect("decryption failed");

Security Considerations

• Use strong, unique passphrases for each key
• Store the encrypted key file with appropriate file system permissions
• The passphrase should be obtained securely (e.g., from a secure input mechanism)
• Do not log or display the passphrase or decrypted key material

Structs

EncryptedKey

An encrypted secret key container.

Constants

ENCRYPTED_KEY_LEN

Total length of the encrypted key file in bytes.

ENCRYPTION_VERSION

Current encryption format version.

NONCE_LEN

Length of the nonce in bytes.

PLAINTEXT_LEN

Length of the plaintext secret key in bytes.

SALT_LEN

Length of the salt in bytes.

TAG_LEN

Length of the authentication tag in bytes.

Functions

decrypt_key

Decrypt a secret key with a passphrase.

encrypt_key

Encrypt a secret key with a passphrase.