Crate dotseal 

Dotseal core: per-value AES-256-GCM sealing for dotenv files.

See FORMAT.md at the repository root for the envelope format, AAD construction, and cross-language compatibility guarantees. See CLI.md for the binary’s stability contract.

The two primary entry points are seal_value (encrypt) and decrypt_value (decrypt). parse_env / decrypt_env handle whole dotenv files. Plaintext wraps decrypt outputs in a zeroize-on-drop string.

Enums

Error

Constants

DEFAULT_SCOPE

Scope name used by the CLI when no -s/--scope flag is given.

KEY_LEN

Master key length, in bytes.

NONCE_LEN

Nonce length, in bytes, for AES-256-GCM in the v1 envelope.

VERSION

Envelope version emitted by seal_value and accepted by decrypt_value. Bumping this constant is a coordinated breaking change — see the Versioning section in FORMAT.md.

Functions

decrypt_env

Decrypt every encrypted entry in an env map produced by parse_env. Plaintext values pass through unchanged. Iteration order matches env (file order if env came from parse_env).

decrypt_value

Decrypt a enc:v1:<base64url> envelope. Returns a Plaintext which zero-fills its allocation on drop.

encode_key

Encode a 32-byte master key as base64url without padding. Pair with parse_key for round-tripping.

env_line_name

Extract the variable name from a single dotenv line. Returns None for blank, comment, or malformed lines.

generate_key

Generate a fresh 32-byte master key from the OS RNG. The returned Vec<u8> is unprotected — wrap it in your zeroizing container of choice if it will live longer than a single statement.

is_encrypted_value

Returns true if value carries the dotseal enc: prefix. This is a cheap-and-cheerful classifier — actual decryption is what authenticates the value.

is_valid_name

Pure predicate version of validate_name. Cheap to call from filter chains.

parse_env

Parse a dotenv-formatted string into (name, value) pairs.

parse_env_value

Parse the right-hand side of a single dotenv line (KEY=...) into a value string. The behavior is documented in FORMAT.md § Dotenv parsing and is part of the public commitment — changing it is a breaking change.

parse_key

Parse a master key. Accepts either base64url (with or without = padding) or 64-character hex. Anything else is rejected.

seal_value

Seal a plaintext into a enc:v1:<base64url> envelope using a fresh 96-bit random nonce.

seal_value_with_nonce

As seal_value but with a caller-supplied nonce. Used for deterministic test vectors. Production callers MUST use seal_value instead — AES-GCM nonce reuse is catastrophic and there is no in-band detection.

validate_name

Reject names that don’t match the env-name regex ([A-Za-z_][A-Za-z0-9_]*). Intended for seal-side input validation.

validate_scope

Reject scopes that don’t match the seal-side regex ([A-Za-z0-9_.-]+). The decrypt side uses a looser no-\n/\r rule — see decrypt_value.

Type Aliases

Plaintext

Plaintext output type. The underlying String is zeroed on drop so that the recovered secret does not linger in heap memory after the caller is done with it. Loaders in non-Rust languages cannot offer the same guarantee — see FORMAT.md for the documented divergence.

Result

Result alias parameterised over Error.