{{tag>[cli sops secrets encryption age]}} ====== SOPS (Secrets OPerationS) ====== ''sops''는 YAML, JSON, dotenv, binary 파일을 부분 단위로 암호화하면서 Git 친화적인 형태를 유지하는 secret 관리 도구다. ===== Summary ===== * ''**sops**''는 파일 전체를 opaque blob으로 바꾸지 않고 구조를 유지한 채 암호화한다. * 이 저장소 맥락에서는 ''**age**'' recipient 기반 구성이 가장 단순하다. * 새 파일 암호화에는 recipient/KMS 지정이 필요하지만, 기존 ''sops'' 파일 편집과 복호화는 파일 내부 메타데이터를 사용한다. ===== Usage =====


sops encrypt --age age1example... secret.yaml
sops decrypt secret.enc.yaml
sops edit secret.enc.yaml
sops updatekeys -y secret.enc.yaml

* ''**sops** encrypt [options] FILE'' * ''**sops** decrypt [options] FILE'' * ''**sops** edit [options] FILE'' * ''**sops** updatekeys [options] FILE'' ===== Options ===== * ''**--age**'', ''**-a**'': 새 문서를 암호화할 age recipient 목록. ''SOPS_AGE_RECIPIENTS''로도 지정 가능. * ''**--pgp**'', ''**-p**'': PGP fingerprint 기반 암호화. * ''**--kms**'', ''**-k**'': AWS KMS ARN 목록. * ''**--in-place**'', ''**-i**'': stdout 대신 원본 파일에 다시 기록. * ''**--input-type**'', ''**--output-type**'': 확장자로 타입을 판별하기 어렵거나 stdin을 쓸 때 형식을 고정. * ''**--unencrypted-regex**'': 정규식에 맞는 key만 평문으로 남긴다. * ''**--encrypted-regex**'': 정규식에 맞는 key만 암호화한다. * ''**--mac-only-encrypted**'': MAC 계산 범위를 실제로 암호화되는 값으로 제한한다. * ''**--ignore-mac**'': 복호화 시 Message Authentication Code 검증 실패를 무시한다. 복구/조사 목적이 아니면 평소에는 권장되지 않는다. * ''**--extract**'': decrypt 시 특정 키/브랜치만 추출. * ''**--filename-override**'': stdin 사용 시 설정 로딩과 파일 타입 판별용 파일명을 강제로 지정. * ''**--decryption-order**'': 복호화 시도 순서를 제어. ===== Examples =====


# age 공개키 recipient로 새 YAML 암호화
sops encrypt --age age1exampleexampleexampleexampleexampleexample secret.yaml > secret.enc.yaml

# 복호화해서 stdout으로 확인
sops decrypt secret.enc.yaml

# 원본 파일을 직접 편집
sops edit secret.enc.yaml

# 특정 값만 추출
sops decrypt --extract '["database"]["password"]' secret.enc.yaml

# .env 파일을 제자리 암호화
sops --encrypt --in-place secrets.env

# 특정 key만 암호화하고 나머지는 평문 유지
sops encrypt --encrypted-regex '^(data|stringData)$' secret.yaml > secret.enc.yaml

# MAC 오류를 무시하고 강제로 확인
sops decrypt --ignore-mac secret.enc.yaml

# .sops.yaml 정책 변경 후 key metadata 재정렬
sops updatekeys -y secret.enc.yaml

===== Config =====


creation_rules:
  - path_regex: \.prod\.yaml$
    age: age1exampleexampleexampleexampleexampleexample
  - path_regex: \.env$
    age: >-
      age1exampleexampleexampleexampleexampleexample,
      age1secondrecipientexampleexampleexampleexample

* 기본 설정 파일은 ''.sops.yaml''이다. * ''creation_rules''는 새 문서를 암호화할 때 어떤 key provider를 붙일지 결정한다. * ''encrypted_regex''와 ''unencrypted_regex''는 어떤 key를 암호화 대상으로 볼지 정교하게 제한할 때 쓴다. * team 단위 운영에서는 recipient를 파일마다 직접 넣기보다 ''.sops.yaml''으로 중앙 관리하는 편이 안전하다.


creation_rules:
  - path_regex: secrets/.*\.yaml$
    age: age1exampleexampleexampleexampleexampleexample
    encrypted_regex: '^(data|stringData)$'

===== Environment ===== * ''SOPS_AGE_RECIPIENTS'': 새 문서 암호화 시 기본 age recipient 목록. * ''SOPS_PGP_FP'': 기본 PGP fingerprint 목록. * ''SOPS_KMS_ARN'': 기본 AWS KMS ARN 목록. * ''SOPS_GCP_KMS_IDS'': 기본 GCP KMS resource ID 목록. * ''SOPS_AZURE_KEYVAULT_URLS'': 기본 Azure Key Vault key URL 목록. * ''SOPS_VAULT_URIS'': 기본 HashiCorp Vault Transit key URI 목록. * ''SOPS_CONFIG'': 사용할 ''.sops.yaml'' 경로를 명시적으로 고정. * ''SOPS_DECRYPTION_ORDER'': 복호화 시도 순서 지정. 예: ''age,pgp,kms''. * ''SOPS_ENABLE_LOCAL_KEYSERVICE'': 로컬 keyservice 사용 여부 제어. * ''SOPS_KEYSERVICE'': 추가 keyservice endpoint 지정. * ''SOPS_GPG_EXEC'': 기본 ''gpg'' 대신 다른 실행 파일 경로 지정. * ''SOPS_EDITOR'': ''sops edit''에서 사용할 editor 지정. * ''SOPS_DISABLE_VERSION_CHECK'': 버전 확인 비활성화.


export SOPS_AGE_RECIPIENTS="age1exampleexampleexampleexampleexampleexample"
export SOPS_CONFIG="$PWD/.sops.yaml"
export SOPS_DECRYPTION_ORDER="age,pgp"
export SOPS_EDITOR="nvim"

문서나 예제에는 실제 secret, 실제 recipient private key, production KMS 식별자를 넣지 않는다. ''--ignore-mac''는 위변조 감지 단계를 건너뛰므로, 파일이 손상되었는지 조사하거나 긴급 복구할 때만 제한적으로 쓴다. ===== Troubleshooting ===== * ''failed to get the data key'': 로컬에 복호화 가능한 ''age'' identity 또는 KMS/GPG credential이 없는 경우가 많다. * MAC 검증 오류가 나면 먼저 파일이 수동 편집으로 깨졌는지, recipient/key rotation 이후 metadata가 불일치하는지 본다. * stdin 기반 암호화가 설정 파일을 못 찾으면 ''**--filename-override**''를 함께 쓴다. * editor 실행 문제가 있으면 ''SOPS_EDITOR'' 또는 ''EDITOR'' 값을 확인한다. * ''updatekeys''가 기대와 다르게 동작하면 ''.sops.yaml''의 ''path_regex''와 recipient 목록을 다시 본다. ===== Compatibility ===== * 로컬 확인 버전: ''sops 3.13.0'' * 지원 형식: JSON, YAML, dotenv, binary * 지원 key provider: age, PGP, AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault Transit, HuaweiCloud KMS ===== Related ===== * ''sops encrypt''는 새 파일 생성 시 key provider를 명시하거나 ''.sops.yaml'' 규칙에 의존한다. * ''sops decrypt''는 결과를 stdout으로 내보내는 기본 동작이 안전한 편이다. * ''sops edit''는 평문 임시파일을 거치므로 작업 디렉터리, editor swap 파일 정책을 같이 고려해야 한다. * ''sops groups''와 ''sops updatekeys''는 팀 recipient 변경 시 유용하다. ===== Help ===== ++++ sops --help |


NAME:
   sops - sops - encrypted file editor with AWS KMS, GCP KMS, HuaweiCloud KMS, Azure Key Vault, age, and GPG support

USAGE:
   sops is an editor of encrypted files that supports AWS KMS, GCP KMS, AZKV,
  PGP, and Age

VERSION:
   3.13.0

COMMANDS:
   completion  Generate shell completion scripts
   exec-env    execute a command with decrypted values inserted into the environment
   exec-file   execute a command with the decrypted contents as a temporary file
   publish     Publish sops file or directory to a configured destination
   keyservice  start a SOPS key service server
   filestatus  check the status of the file, returning encryption status
   groups      modify the groups on a SOPS file
   updatekeys  update the keys of SOPS files using the config file
   decrypt     decrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.
   encrypt     encrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.
   rotate      generate a new data encryption key and reencrypt all values with the new key
   edit        edit an encrypted file
   set         set a specific key or branch in the input document.
   unset       unset a specific key or branch in the input document.

++++ ++++ sops encrypt --help |


NAME:
   sops encrypt - encrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.

USAGE:
   sops encrypt [command options] [file]

OPTIONS:
   --in-place, -i
   --output value
   --kms value, -k value
   --gcp-kms value
   --hckms value
   --azure-kv value
   --hc-vault-transit value
   --pgp value, -p value
   --age value, -a value
   --input-type value
   --output-type value
   --unencrypted-suffix value
   --encrypted-suffix value
   --unencrypted-regex value
   --encrypted-regex value
   --mac-only-encrypted
   --encryption-context value
   --shamir-secret-sharing-threshold value
   --filename-override value

++++ ++++ sops decrypt --help |


NAME:
   sops decrypt - decrypt a file, and output the results to stdout. If no filename is provided, stdin will be used.

USAGE:
   sops decrypt [command options] [file]

OPTIONS:
   --in-place, -i
   --extract value
   --output value
   --input-type value
   --output-type value
   --ignore-mac
   --filename-override value
   --decryption-order value

++++ ===== See Also ===== * [[age:ko]] * [[openssl:ko]] * [[git:ko]] ===== History ===== * codex:: 2026-06-17 Created SOPS reference page with age-centric workflow, config example, and help sections. * codex:: 2026-06-17 Added regex selection, MAC validation notes, and major SOPS environment variables.