Share a Secret

Goal

Share an encrypted secret with a teammate so they can decrypt it with their own GPG key.

Prerequisites

• dotsecenv configured with secrets (Your First Secret)
• Teammate’s GPG public key imported into your keyring

Steps

1. Get your teammate’s GPG public key

   Your teammate exports their public key:

   # Teammate runs this
   gpg --armor --export teammate@example.com > teammate-public.asc

   They send you the teammate-public.asc file (this is safe to share publicly).

2. Import their public key

   gpg --import teammate-public.asc

   Verify the import:

   gpg --list-keys teammate@example.com

   Note the fingerprint (40-character hex string).

3. Share specific secrets

   The secret share command automatically adds the identity to the vault if needed:

   Share a single secret:

   dotsecenv secret share DATABASE_PASSWORD TEAMMATE_FINGERPRINT

   Or share multiple secrets:

   dotsecenv secret share API_KEY TEAMMATE_FINGERPRINT

4. Send the vault file

   The vault is now encrypted for both of you. Commit and push:

   git add vault
   git commit -m "Share secrets with teammate"
   git push

   Or send the vault file directly.

5. Teammate sets up access

   Your teammate:

   # Pull the updated vault
   git pull
   
   # Configure dotsecenv to use the vault
   dotsecenv init config
   dotsecenv login THEIR_FINGERPRINT
   
   # Retrieve the shared secret
   dotsecenv secret get DATABASE_PASSWORD

Expected Result

After sharing:

• The secret is encrypted with both your key and your teammate’s key
• Either of you can decrypt it independently
• The vault shows both identities in available_to

dotsecenv vault describe
# Vault 1 (~/.config/dotsecenv/vault):
#   Identities:
#     - You <you@example.com> (YOUR_FINGERPRINT)
#     - Teammate <teammate@example.com> (TEAMMATE_FINGERPRINT)
#   Secrets:
#     - DATABASE_PASSWORD

Variations

Share multiple secrets at once

Share all secrets in a namespace:

# Share all prod secrets
dotsecenv secret share "prod::*" TEAMMATE_FINGERPRINT

Share with multiple teammates

Share with each teammate (identities are added automatically):

dotsecenv secret share DATABASE_PASSWORD ALICE_FINGERPRINT
dotsecenv secret share DATABASE_PASSWORD BOB_FINGERPRINT

Verify GPG key trust

Before sharing, verify the key is trusted:

gpg --edit-key TEAMMATE_FINGERPRINT
# At the gpg> prompt, type: trust
# Select trust level 4 (full) or 5 (ultimate)
# Type: quit

Important: Sharing is permanent

Once you share a secret with someone, they can decrypt that specific value forever—even if you later revoke their access.

Revoking prevents access to future values only. See Revoke Access for details.

Sharing workflow for teams

Recommended workflow:

1. One person initializes the vault with all secrets
2. Collect GPG public keys from all team members
3. Add identities for each team member
4. Share secrets with appropriate team members
5. Commit the vault to version control
6. Team members pull and configure their local setup

---

How It Works

When you share a secret:

1. dotsecenv decrypts the secret value using your GPG key
2. Generates a new random session key (AES-256-GCM)
3. Encrypts the value with the session key
4. Encrypts the session key for each authorized identity
5. Appends the new encrypted entry to the vault

The original value remains unchanged—a new entry is added. This is the append-only design.

---

Troubleshooting

“Key not found” error

Make sure the key is imported:

gpg --list-keys FINGERPRINT

If missing, ask your teammate to send their public key again.

“Not trusted” warning

Sign the key to trust it:

gpg --sign-key FINGERPRINT

Teammate can’t decrypt

Verify they’re using the correct fingerprint:

# Teammate runs:
gpg --list-secret-keys --keyid-format long

The fingerprint must match exactly.

---

Next Steps

• Revoke Access — Remove someone’s access to secrets
• Security Model — Understand the encryption model