GPG configuration

GnuPG home, gpg.conf, dirmngr.conf, gpg-agent.conf, 설정 우선순위와 안전한 검증 방법.

• 기본 GnuPG home은 Unix-like system에서 ~/.gnupg다.
• gpg.conf는 gpg, dirmngr.conf는 network/keyserver, gpg-agent.conf는 private key와 pinentry 동작을 제어한다.
• 설정 file에는 long option의 앞 –를 빼고 기록하며 option을 축약하지 않는다.
• Secret key, passphrase, API token을 config file에 기록하지 않는다.

gpgconf --list-dirs
gpgconf --list-components

Windows의 home 위치는 installation과 registry 설정에 따라 다를 수 있으므로 hard-code하지 말고 다음 명령으로 확인한다.

gpgconf --list-dirs homedir

일반적인 GnuPG home 선택 순서는 command line –homedir, environment GNUPGHOME, platform default 순이다.

# 한 command에만 격리된 home 적용
gpg --homedir /secure/path/to/gnupg --list-keys
 
# 현재 shell/session에 적용
export GNUPGHOME=/secure/path/to/gnupg
gpg --list-keys

• –homedir는 command line에서만 인식하며 config file 안에 두지 않는다.
• –options FILE은 다른 option file을 읽는다.
• –no-options는 기본 gpg.conf를 읽지 않는다.
• Command line option은 같은 설정의 config 값을 override하거나 누적할 수 있다. 반복 가능한 option은 동작을 별도로 확인한다.

새로운 isolated home은 owner만 접근하도록 만든다.

install -d -m 700 "$PWD/.gnupg-test"
GNUPGHOME="$PWD/.gnupg-test" gpg --list-keys

Existing home의 기본 permission을 확인한다.

stat -c '%a %U:%G %n' ~/.gnupg
find ~/.gnupg -maxdepth 2 -type f -printf '%m %u:%g %p\n'

다음은 표시 형식과 default signing key를 명확히 하는 보수적인 예다.

# ~/.gnupg/gpg.conf
keyid-format long
with-fingerprint
 
# 전체 fingerprint 사용
default-key 0123456789ABCDEF0123456789ABCDEF01234567
 
# 필요할 때만 명시적으로 활성화
# auto-key-locate local,wkd

• default-key: 기본 signing key. 전체 fingerprint를 권장하며 –local-user가 override한다.
• keyid-format long: 표시되는 key ID를 16 hexadecimal digit으로 확장한다. Security decision에는 여전히 전체 fingerprint를 쓴다.
• with-fingerprint: key listing에 fingerprint를 추가한다.
• auto-key-locate local,wkd: local keyring과 Web Key Directory 순서로 email address key를 찾는다.

자신도 암호화 file을 복호화해야 하는 workflow에서는 command마다 자신의 fingerprint를 recipient로 명시하는 방식이 가장 분명하다.

gpg --encrypt \
  --recipient RECIPIENT-FINGERPRINT \
  --recipient SELF-FINGERPRINT \
  --output message.gpg message.txt

default-recipient-self를 config에 넣으면 편리하지만 recipient 지정 누락을 숨길 수 있다. 팀 automation에서는 explicit recipient 목록을 우선한다.

Current GnuPG에서는 persistent keyserver를 gpg.conf가 아니라 dirmngr.conf에 둔다.

# ~/.gnupg/dirmngr.conf
keyserver hkps://keys.openpgp.org

적용 후 dirmngr를 reload한다.

gpgconf --reload dirmngr
gpg --receive-keys FULL-FINGERPRINT

• hkps를 사용해 transport encryption을 적용한다.
• Keyserver transport 보안은 key identity를 증명하지 않는다. 받은 key의 fingerprint를 별도 channel로 확인한다.
• Corporate proxy, TLS inspection, air-gapped 환경에서는 network policy와 CA trust를 함께 검토한다.

auto-key-retrieve는 signature 검증 중 missing key를 network에서 자동으로 가져올 수 있다. 편리하지만 verification 대상과 시간, client IP가 외부 service에 노출될 수 있다.

# privacy 영향을 이해한 경우에만 gpg.conf에 활성화
# auto-key-retrieve

Default no-auto-key-retrieve를 유지하고 필요할 때 fingerprint를 확인한 뒤 수동 import하는 편이 audit하기 쉽다.

Agent는 secret key operation과 passphrase cache를 중개하고 pinentry를 실행한다.

# ~/.gnupg/gpg-agent.conf
default-cache-ttl 600
max-cache-ttl 7200
 
# 설치된 pinentry executable이 필요한 경우에만 명시
# pinentry-program /usr/bin/pinentry-curses

• default-cache-ttl: 마지막 사용 후 일반 cache lifetime의 기본값(초).
• max-cache-ttl: 최초 cache 이후 유지할 수 있는 최대 lifetime(초).
• pinentry-program: 사용할 pinentry executable을 명시한다. 실제 설치 경로를 확인하고 설정한다.
• Cache는 passphrase 자체를 disk config에 저장하는 기능이 아니다.

설정 변경 후 agent를 reload한다.

gpgconf --reload gpg-agent
 
# reload로 반영되지 않을 때만 agent 재시작
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

Interactive terminal에서는 GPG_TTY가 현재 TTY를 가리키게 한다.

export GPG_TTY="$(tty)"

GPG_AGENT_INFO는 GnuPG 2.1 이전 agent discovery 방식의 obsolete variable이다.

Test, CI, project별 keyring을 운영 profile과 분리할 수 있다.

test_home="$(mktemp -d)"
chmod 700 "$test_home"
GNUPGHOME="$test_home" gpg --batch --import public-key.asc
GNUPGHOME="$test_home" gpg --batch --with-colons --list-keys

• Public-key-only verification profile에는 secret key를 import하지 않는다.
• Temporary home의 lifecycle과 secure deletion 한계를 이해하고 CI runner 자체를 ephemeral하게 운영한다.
• 실제 secret key를 넣은 temporary directory는 평문 workspace artifact나 cache로 upload하지 않는다.

Portable backup에는 public/secret key와 ownertrust를 명시적으로 export한다.

gpg --armor --output public-keys.asc --export
gpg --armor --output secret-keys.asc --export-secret-keys
gpg --output ownertrust.txt --export-ownertrust

복원 전 격리된 home에서 확인한다.

restore_home="$(mktemp -d)"
chmod 700 "$restore_home"
GNUPGHOME="$restore_home" gpg --import public-keys.asc
GNUPGHOME="$restore_home" gpg --import secret-keys.asc
GNUPGHOME="$restore_home" gpg --import-ownertrust ownertrust.txt
GNUPGHOME="$restore_home" gpg --list-secret-keys

# Component별 option file syntax 확인
gpgconf --check-options gpg
gpgconf --check-options dirmngr
gpgconf --check-options gpg-agent
 
# 실제 directory와 socket 확인
gpgconf --list-dirs
 
# 적용 결과 확인
gpg --version
gpg --list-options show-unusable-subkeys \
  --with-subkey-fingerprint --list-keys

gpgconf –check-options의 지원 범위는 installed version에 따라 다를 수 있다. 변경 전 config backup을 만들고 isolated GNUPGHOME에서 version별 동작을 시험한다.

1. gpgconf –list-dirs homedir로 실제 home을 확인한다.
2. GNUPGHOME과 command line –homedir가 예상과 다른 profile을 가리키는지 확인한다.
3. Config의 long option에서 앞 –를 제거했는지, option name을 축약하지 않았는지 확인한다.
4. gpgconf –check-options COMPONENT로 syntax를 확인한다.
5. 해당 component를 gpgconf –reload COMPONENT로 reload한다.

printf '%s\n' "$GPG_TTY"
tty
gpgconf --list-dirs agent-socket
gpgconf --launch gpg-agent

pinentry-program을 hard-code했다면 executable 존재 여부와 GUI/TTY session의 종류를 확인한다.

gpgconf --list-dirs homedir
printf 'GNUPGHOME=%s\n' "${GNUPGHOME:-<unset>}"
gpg --homedir ~/.gnupg --list-keys

Shell, IDE, service unit, container가 서로 다른 environment를 사용할 수 있다. Path를 추정하지 말고 각 execution context에서 확인한다.

• GnuPG 2.2는 주로 pubring.kbx와 private-keys-v1.d를 사용한다.
• Newer GnuPG는 common.conf의 use-keyboxd와 keyboxd database를 사용할 수 있다.
• GnuPG 1.x의 secring.gpg, –secret-keyring과 GPG_AGENT_INFO 기록을 modern configuration에 복사하지 않는다.
• Option availability와 default는 version에 따라 바뀔 수 있으므로 target host의 official manual과 gpg –version을 기준으로 검증한다.

• GPG
• Git config와 인증
• SOPS
• GnuPG 공식 configuration manual
• GnuPG 공식 gpgconf manual

• codex:: 2026-07-26 Added GnuPG home, gpg, dirmngr, agent, pinentry, backup, validation, and compatibility guidance.