This document describes the security considerations and best practices for using VS Code GPG.

Private keys are stored in VS Code's global state, which is:

• Encrypted at rest on most platforms
• Protected by the operating system's user account permissions
• Backed up through VS Code's settings sync (if enabled)

Passphrases are stored using VS Code's secret storage API, which:

• Uses platform-specific secure storage (Keychain on macOS, Credential Manager on Windows, libsecret on Linux)
• Never stores passphrases in plain text
• Isolated from other extensions

• Always use a passphrase for your private keys
• Enable settings sync to back up your keys securely
• Use strong passphrases that are difficult to guess
• Never share your private keys with others

The extension uses:

• OpenPGP standard (RFC 4880)
• Elliptic Curve Cryptography (curve25519)
• AES-256 for symmetric encryption

When generating new keys:

• curve25519 is used by default
• Keys are generated locally on your machine
• No key material is sent over the network

Files are encrypted with:

• The recipient's public key
• AES-256 symmetric encryption
• The encrypted symmetric key is embedded in the file

Only someone with the matching private key can decrypt the file.

1. The encrypted file is read from disk
2. Your private keys are tried sequentially until one successfully decrypts the file
3. If the private key is passphrase-protected, you'll be prompted (unless the passphrase is stored)
4. The decrypted content is displayed in the editor

• Decrypted content is never written to disk
• The file on disk remains encrypted at all times
• Only the in-memory editor buffer contains decrypted content

┌─────────────┐
│  File on    │ (encrypted)
│    Disk     │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│ Extension readFile  │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│  Decrypt (OpenPGP)  │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│   Editor Buffer     │ (decrypted)
└─────────────────────┘

1. Back up your keys - Export your keys and store them in a secure location
2. Use different keys - Consider using different keys for different purposes
3. Rotate keys - Periodically generate new keys and re-encrypt sensitive files

1. Use strong passphrases - At least 12 characters, mixed case, numbers, symbols
2. Don't reuse passphrases - Use a unique passphrase for each key
3. Store passphrases securely - Only use VS Code's secure storage

1. Verify recipients - Always confirm you're encrypting for the right person
2. Check file extensions - Ensure only intended files are encrypted
3. Test decryption - Verify you can decrypt files after encrypting them

The extension uses openpgp.js, which may have compatibility issues with:

• Keys generated by GPG CLI with certain algorithms (e.g., cv25519/ed25519)
• Very old PGP implementations

If you encounter decryption issues:

1. Try using GPG CLI to decrypt: gpg --decrypt file.gpg
2. Consider re-encrypting with openpgp.js-compatible keys

The security of the extension depends on:

• The security of your operating system
• The security of VS Code's storage APIs
• The physical security of your machine

For maximum security:

• Keep your OS and VS Code updated
• Use full-disk encryption
• Lock your screen when away from your computer

If you discover a security vulnerability, please:

1. Do not create a public issue
2. Email details to the maintainer
3. Include steps to reproduce
4. Allow time for the issue to be fixed before disclosing