GPG (GNU Privacy Guard)

gpg는 GnuPG의 OpenPGP 명령행 도구다. 공개키 암호화, 전자서명, 서명 검증과 keyring 관리를 제공한다.

• 공개키는 공유해도 되지만 secret key와 passphrase는 공개하거나 repository에 저장하면 안 된다.
• 암호화 전에 recipient key의 전체 fingerprint를 신뢰할 수 있는 별도 경로로 확인한다.
• 서명 검증의 성공은 file이 해당 key로 서명된 뒤 바뀌지 않았음을 뜻한다. 그 key가 올바른 사람의 것인지는 fingerprint와 trust를 별도로 확인해야 한다.
• GnuPG 2.x는 modern algorithm과 gpg-agent를 지원하므로 GnuPG 1.x보다 우선한다.

# Debian / Ubuntu
sudo apt update
sudo apt install gnupg
 
# Fedora / RHEL
sudo dnf install gnupg2
 
# macOS
brew install gnupg
 
# Windows: GnuPG가 안내하는 Gpg4win bundle
winget install --id GnuPG.Gpg4win --exact
 
# 설치 확인
gpg --version

• Debian/Ubuntu의 gnupg package는 gpg, gpg-agent, dirmngr 등 GnuPG 구성 요소를 설치하는 metapackage다.
• Fedora/RHEL 계열 package 이름은 gnupg2지만 executable은 보통 gpg다.
• Homebrew formula 이름은 gnupg이며 gpg, gpg2 alias를 제공한다.
• Gpg4win은 Windows용 GnuPG와 Kleopatra 등의 companion application을 포함한다. CLI만 필요해도 설치 후 gpg.exe를 사용할 수 있다.
• Source build보다 distribution package와 signed Windows installer를 우선한다. 최신 upstream release와 OS package version은 서로 다를 수 있다.

gpg [options] [files]

• gpg –list-keys [USER-ID]
• gpg –quick-generate-key USER-ID [ALGO [USAGE [EXPIRE]]]
• gpg –encrypt –recipient RECIPIENT FILE
• gpg –decrypt –output OUTPUT FILE
• gpg –detach-sign –local-user SIGNER FILE
• gpg –verify SIGNATURE [FILE]

USER-ID에는 이름, email, key ID, fingerprint 등을 쓸 수 있지만 script와 중요한 작업에서는 전체 fingerprint를 권장한다.

# 공개키와 fingerprint 확인
gpg --list-keys
gpg --fingerprint USER@example.com
 
# machine-readable inventory
gpg --batch --with-colons --fingerprint
 
# secret key가 있는 key 확인
gpg --list-secret-keys --keyid-format long

Interactive wizard는 algorithm, expiry와 identity를 단계별로 설정한다.

gpg --full-generate-key

Quick interface는 명시한 값을 바로 적용한다.

# 현재 GnuPG가 지원하는 기본 algorithm으로 생성
gpg --quick-generate-key "Example User <[email protected]>" default default 1y
 
# 생성 결과와 fingerprint 확인
gpg --list-secret-keys --keyid-format long
gpg --fingerprint "[email protected]"
 
# expiry 연장
gpg --quick-set-expire PRIMARY-FINGERPRINT 1y
 
# revocation certificate 생성
gpg --output revoke.asc --generate-revocation PRIMARY-FINGERPRINT

• ALGO, USAGE, EXPIRE 지원값은 GnuPG version과 policy에 따라 다르다.
• Primary key와 subkey의 역할을 분리하거나 hardware token을 쓸 때는 –full-generate-key, –edit-key, –quick-add-key를 함께 검토한다.
• Revocation certificate는 secret key와 분리해 offline backup하고 권한을 제한한다.

# ASCII-armored public key export
gpg --armor --output public-key.asc --export PRIMARY-FINGERPRINT
 
# file의 key 정보와 fingerprint를 먼저 확인
gpg --show-keys --with-fingerprint public-key.asc
 
# 확인 후 keyring에 import
gpg --import public-key.asc

# 안전한 offline 경로에만 secret key export
gpg --armor --output secret-key-backup.asc \
  --export-secret-keys PRIMARY-FINGERPRINT
 
# ownertrust 별도 backup
gpg --export-ownertrust > ownertrust.txt

복원은 격리된 GNUPGHOME에서 먼저 시험할 수 있다.

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

# recipient public key로 암호화
gpg --output document.txt.gpg \
  --encrypt --recipient RECIPIENT-FINGERPRINT document.txt
 
# 여러 recipient와 자신도 복호화할 수 있게 암호화
gpg --output document.txt.gpg --encrypt \
  --recipient RECIPIENT-FINGERPRINT \
  --recipient SELF-FINGERPRINT \
  document.txt
 
# 복호화
gpg --output document.txt --decrypt document.txt.gpg

• 보낸 사람도 나중에 복호화해야 하면 자신의 key를 recipient로 함께 지정한다.
• –armor를 더하면 binary 대신 ASCII-armored .asc 형태로 출력한다.
• –output 대상이 기존 file과 겹치지 않는지 확인한다.

gpg --symmetric --cipher-algo AES256 --output archive.tar.gpg archive.tar
gpg --output archive.tar --decrypt archive.tar.gpg

Passphrase는 command argument나 environment variable로 넘기지 말고 pinentry에서 입력한다. Recipient가 여러 명이거나 장기간 운영할 때는 passphrase 공유보다 public-key 방식이 관리하기 쉽다.

# 원본과 별도 signature 생성
gpg --local-user SIGNER-FINGERPRINT \
  --armor --detach-sign release.tar.gz
 
# signature와 원본을 함께 검증
gpg --verify release.tar.gz.asc release.tar.gz

Detached signature 검증은 signature file과 원본 file을 모두 명시한다. 원본을 생략하면 filename 추론 또는 stdin 동작에 의존할 수 있다.

gpg --local-user SIGNER-FINGERPRINT --clear-sign message.txt
gpg --verify message.txt.asc

gpg --local-user SIGNER-FINGERPRINT --sign document.txt
gpg --output document.txt --decrypt document.txt.gpg

# fingerprint로 keyserver에서 받기
gpg --keyserver hkps://keys.openpgp.org \
  --receive-keys FULL-FINGERPRINT
 
# Web Key Directory 등으로 email address의 key 찾기
gpg --locate-keys user@example.com
 
# 자신의 public key 전송
gpg --keyserver hkps://keys.openpgp.org \
  --send-keys FULL-FINGERPRINT

• Keyserver에서 받은 key도 신뢰된 key가 아니다. Fingerprint 검증이 별도로 필요하다.
• 공개 keyserver는 upload 후 삭제가 어렵거나 불가능할 수 있다. 자신의 key만 명시적으로 전송한다.
• –auto-key-retrieve는 검증 중 network lookup을 발생시켜 조회 대상, IP와 시각이 keyserver/WKD 운영자에게 드러날 수 있으므로 기본 활성화 전에 privacy 영향을 검토한다.

~/.gnupg/gpg.conf, dirmngr.conf, gpg-agent.conf, GNUPGHOME, file permission과 안전한 예시는 GPG configuration에서 다룬다.

gpgconf --list-dirs
gpgconf --check-options gpg
gpgconf --reload all

Human-readable message를 parsing하지 말고 machine interface를 사용한다.

gpg --batch --no-tty --status-fd 2 \
  --output OUTPUT --decrypt INPUT.gpg
 
gpg --batch --with-colons --list-keys

• –batch만으로 모든 TTY 접근이 사라지지 않을 수 있어 unattended 작업에는 –no-tty도 함께 검토한다.
• Secret이나 passphrase를 command line, process list, CI log에 노출하지 않는다.
• 검증 자동화는 exit status뿐 아니라 expected signer fingerprint를 machine-readable status에서 확인한다.
• CI에서는 ephemeral GNUPGHOME과 최소 권한의 별도 key를 사용하고 job 종료 후 안전하게 폐기한다.

서명자의 public key가 local keyring에 없다. 공식 source에서 fingerprint를 확인한 뒤 key를 import하거나 WKD/keyserver에서 받아 다시 fingerprint를 대조한다.

gpg --show-keys --with-fingerprint signer.asc
gpg --import signer.asc
gpg --verify artifact.sig artifact

Recipient key가 expired/revoked되었거나 encryption-capable subkey가 없을 수 있다.

gpg --list-options show-unusable-subkeys \
  --with-subkey-fingerprint --list-keys RECIPIENT

Remote shell이나 container에서 pinentry가 TTY를 찾지 못하는 경우가 많다.

export GPG_TTY="$(tty)"
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

GPG_TTY를 shell startup file에서 현재 terminal에 맞춰 설정하고, headless automation에서는 passphrase 전달 방식을 임의로 우회하지 말고 agent/pinentry와 secret injection 설계를 분리한다.

GnuPG home과 secret file의 owner/permission을 확인한다.

chmod 700 ~/.gnupg
find ~/.gnupg -type f -exec chmod 600 {} \;

Shared directory나 network filesystem에 secret keyring을 두지 않는다. Existing socket 등 일부 entry는 file이 아니므로 무조건 재귀 chmod하지 않는다.

• 이 페이지의 live help는 repository base environment의 gpg (GnuPG) 2.2.20에서 확인했다.
• 2026-07-26 공식 stable release는 2.5 계열이지만 distribution package는 LTS/security patch 정책에 따라 다른 version을 제공할 수 있다.
• GnuPG 2.4/2.5의 key storage, default algorithm과 option은 2.2와 다를 수 있다. Automation은 target host의 gpg –version과 gpgconf –list-components를 확인한다.
• gpg2 executable 이름은 일부 distribution의 compatibility alias다. Script에서는 실제 설치된 command를 확인한다.

• GnuPG 1.4는 modern feature가 부족한 legacy branch다. PGP-2 호환 같은 특별한 이유가 아니면 GnuPG 2.x를 사용한다.
• secring.gpg와 –secret-keyring은 GnuPG 2.1 이후 secret key storage 방식에서 obsolete다.
• pubring.gpg는 legacy public keyring format이다. Modern GnuPG는 pubring.kbx 또는 keyboxd를 사용할 수 있다.
• GPG_AGENT_INFO는 GnuPG 2.1 이전 방식의 obsolete environment variable이다.
• gpg –keyserver URL의 persistent 설정은 deprecated다. Current GnuPG에서는 dirmngr.conf의 keyserver를 사용한다.

gpg --help (GnuPG 2.2.20)

Syntax: gpg [options] [files]
Sign, check, encrypt or decrypt
Default operation depends on the input data
 
Commands:
 -s, --sign                  make a signature
     --clear-sign            make a clear text signature
 -b, --detach-sign           make a detached signature
 -e, --encrypt               encrypt data
 -c, --symmetric             encryption only with symmetric cipher
 -d, --decrypt               decrypt data (default)
     --verify                verify a signature
 -k, --list-keys             list keys
     --list-signatures       list keys and signatures
     --check-signatures      list and check key signatures
     --fingerprint           list keys and fingerprints
 -K, --list-secret-keys      list secret keys
     --generate-key          generate a new key pair
     --quick-generate-key    quickly generate a new key pair
     --quick-add-uid         quickly add a new user-id
     --quick-revoke-uid      quickly revoke a user-id
     --quick-set-expire      quickly set a new expiration date
     --full-generate-key     full featured key pair generation
     --generate-revocation   generate a revocation certificate
     --delete-keys           remove keys from the public keyring
     --delete-secret-keys    remove keys from the secret keyring
     --quick-sign-key        quickly sign a key
     --quick-lsign-key       quickly sign a key locally
     --sign-key              sign a key
     --lsign-key             sign a key locally
     --edit-key              sign or edit a key
     --change-passphrase     change a passphrase
     --export                export keys
     --send-keys             export keys to a keyserver
     --receive-keys          import keys from a keyserver
     --search-keys           search for keys on a keyserver
     --refresh-keys          update all keys from a keyserver
     --import                import/merge keys
     --card-status           print the card status
     --edit-card             change data on a card
     --change-pin            change a card's PIN
     --update-trustdb        update the trust database
     --print-md              print message digests
 
Options:
 -a, --armor                 create ascii armored output
 -r, --recipient USER-ID     encrypt for USER-ID
 -u, --local-user USER-ID    use USER-ID to sign or decrypt
 -z N                        set compress level to N (0 disables)
     --textmode              use canonical text mode
 -o, --output FILE           write output to FILE
 -v, --verbose               verbose
 -n, --dry-run               do not make any changes
 -i, --interactive           prompt before overwriting
     --openpgp               use strict OpenPGP behavior
 
(See the man page for a complete listing of all commands and options)

• GPG configuration
• Git config와 인증
• SOPS
• age
• OpenSSL
• GnuPG 공식 manual
• GnuPG 공식 download

• codex:: 2026-07-26 Corrected the folded Help block syntax.
• codex:: 2026-07-26 Added GPG installation, key management, encryption, signing, verification, automation, compatibility, and safety guidance.