# sops와 age로 설정 파일의 비밀만 암호화하기: 저장소에 올려도 되는 비밀 관리

> 설정 파일에서 비밀번호와 토큰 값만 암호화해 파일 구조는 그대로 읽히게 하는 sops를 age 키와 함께 실행합니다. 복호화, 키가 없을 때와 틀릴 때, 파일 변조 감지, 값 수정 시 바뀌는 줄, 팀원 키 추가까지 확인합니다.

- 주소: https://copyandrun.com/blog/sops-age-encrypted-config/
- 분야: DevSecOps
- 발행일: 2026-10-29
- 태그: sops, age, 비밀 관리, 암호화, 설정 파일

설정 파일에는 데이터베이스 비밀번호와 API 토큰이 들어가는 일이 흔합니다. 이 파일을 저장소에 올리면 비밀이 새고, 올리지 않으면 팀원과 서버가 설정을 맞추기 어렵습니다. sops는 YAML, JSON 같은 파일에서 값만 암호화하고 키 이름과 구조는 그대로 두는 오픈소스 도구입니다. 그래서 암호화된 파일을 저장소에 올려도 되고, 코드 리뷰에서는 어느 항목이 바뀌었는지 볼 수 있습니다. age는 sops가 데이터 키를 감싸는 데 쓰는 작고 단순한 암호화 도구입니다. 이 글은 두 도구를 일회용 컨테이너에서 실행해 암호화부터 키 추가까지 해 보고, 무엇이 지켜지고 무엇이 지켜지지 않는지 확인합니다.

비밀값을 중앙에서 저장하고 정책으로 읽기 권한을 나누는 방법은 [Vault 개발 서버: KV 버전, 읽기 전용 정책](/blog/vault-dev-mode-kv-policy/) 글에서 다룹니다.

## 준비물

| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11) |
| 도구 | age v1.3.2, sops 3.12.2 (`alpine` 컨테이너에 `apk add age sops`로 설치) |

모든 작업은 일회용 컨테이너 안에서 하므로 내 PC에는 아무것도 설치되지 않고 파일도 남지 않습니다. 실제로 쓸 때는 두 도구를 PC나 CI 서버에 설치합니다.

## 1. 동작 원리

| 단계 | 일어나는 일 |
|---|---|
| 암호화 | sops가 무작위 데이터 키를 하나 만들어 값들을 암호화. 그 데이터 키를 받는 사람의 age 공개 키로 감싸 파일 끝(`sops:` 블록)에 저장 |
| 복호화 | 받는 사람이 자기 age 비밀 키로 데이터 키를 풀고, 그 키로 값을 복호화 |
| 무결성 | 파일 전체의 서명(MAC)을 함께 저장해, 암호화되지 않은 줄의 변경도 감지 |

공개 키는 받는 사람의 "주소"이고 공유해도 안전합니다. 비밀 키 파일(`key.txt`)이 진짜 열쇠이므로 저장소에 올리지 않고 각자 보관합니다.

## 2. 키와 평문 설정 파일

<!-- files: sops_demo.sh -->

`age-keygen -o key.txt`로 키 한 쌍을 만들면 공개 키(`age1...`로 시작)가 출력되고 비밀 키는 파일에 저장됩니다. 실습용 설정 파일은 이렇습니다.

```yaml
app:
  name: payroll
  debug: false
db:
  host: db.internal
  user: app
  password: S3cr3t-DB-Pass
api:
  token: tok_live_ABC123XYZ
```

비밀은 `password`와 `token` 두 값뿐이고 나머지는 숨길 필요가 없는 평범한 설정입니다.

## 3. 규칙 파일(.sops.yaml)과 암호화

어떤 값을 어떤 키로 암호화할지는 `.sops.yaml`에 적습니다.

```yaml
creation_rules:
  - path_regex: secrets(\.enc)?\.yaml$
    encrypted_regex: '^(password|token)$'
    age: age1...(공개 키)
```

| 항목 | 뜻 |
|---|---|
| `path_regex` | 이 규칙을 적용할 파일 이름. 이 글에서는 `secrets.yaml`과 `secrets.enc.yaml` |
| `encrypted_regex` | 키 이름이 이 식에 맞는 값만 암호화. 여기서는 `password`와 `token` |
| `age` | 받는 사람의 공개 키. 쉼표로 여러 개 적을 수 있음 |

`sops -e secrets.yaml > secrets.enc.yaml`로 암호화했습니다. 결과 파일은 이런 모양입니다(값은 앞부분만 줄였습니다).

```yaml
app:
    name: payroll
    debug: false
db:
    host: db.internal
    user: app
    password: ENC[...4nkFb2...]
api:
    token: ENC[...lax0Wn...]
sops:
    age:
        - recipient: age1...
          enc: (age가 감싼 데이터 키)
    lastmodified: "2026-10-29T08:54:15Z"
    mac: ENC[...]
    encrypted_regex: ^(password|token)$
    version: 3.12.2
```

- `name`, `host`, `user` 같은 일반 설정은 그대로 읽힙니다. 무엇이 어디에 설정되어 있는지 알아볼 수 있습니다.
- `password`와 `token`만 `ENC[AES256_GCM,...]`으로 바뀌었습니다. 암호화된 파일에서 평문 비밀 문자열을 찾으니 두 값 모두 0건이었습니다.
- 아래쪽 `sops:` 블록에는 받는 사람, 감싼 데이터 키, 수정 시각, 파일 서명(`mac`)이 들어 있습니다.

일부만 암호화하는 방식의 장점은 코드 리뷰에서 드러납니다. 누가 `db.host`를 바꾸면 변경이 그대로 보이고, 비밀 값이 바뀌면 암호문이 바뀐 것만 보입니다. 모든 값을 암호화하는 기본 설정(`encrypted_regex`를 쓰지 않음)도 가능한데, 그러면 어떤 항목이 있는지도 알 수 없어서 리뷰가 어렵습니다. 이 글의 `host`와 `user`는 숨기지 않기로 정한 값입니다. 숨겨야 하는 정보(내부 주소, 사용자 이름 등)가 있다면 그 키 이름도 규칙에 넣습니다.

![sops_demo.sh 실행 결과 앞부분에서 age와 sops 버전, 평문 설정 파일, .sops.yaml 규칙, 암호화된 파일에서 password와 token만 ENC로 바뀌고 일반 설정은 그대로이며, 파일에 평문 비밀이 0건 남은 것을 확인합니다.](https://copyandrun.com/img/sops-age-encrypted-config/01-암호화-결과.png)

## 4. 복호화

<!-- files: sops_demo.sh -->

비밀 키 파일의 위치를 환경 변수 `SOPS_AGE_KEY_FILE`로 알려 주고 `sops -d`를 실행하면 원래 값이 나옵니다.

| 명령 | 결과 |
|---|---|
| `sops -d secrets.enc.yaml` | 전체를 복호화. `password: S3cr3t-DB-Pass`, `token: tok_live_ABC123XYZ` |
| `sops -d --extract '["db"]["password"]' secrets.enc.yaml` | 값 하나만 출력: `S3cr3t-DB-Pass` |

`--extract`는 배포 스크립트에서 비밀 하나만 환경 변수나 다른 프로그램의 입력으로 넘길 때 씁니다. 복호화한 평문을 파일로 저장하면 비밀이 디스크에 남으므로, 가능하면 파이프로 바로 넘기고 파일로 만들지 않습니다.

## 5. 키가 없거나 틀리면

<!-- files: sops_demo.sh -->

| 상황 | 결과 |
|---|---|
| 비밀 키 지정 없음 | `Failed to get the data key required to decrypt the SOPS file.` |
| 다른 사람의 비밀 키 | 같은 오류. 자세한 설명에 `identity did not match any of the recipients`(키가 받는 사람과 맞지 않음)가 들어 있음 |

받는 사람 목록에 없는 키로는 열 수 없습니다. 비밀 키를 잃으면 이 파일의 비밀을 복구할 방법이 없으므로, 받는 사람을 둘 이상으로 하고 비밀 키는 안전한 곳에 따로 보관합니다.

## 6. 변조 감지

<!-- files: sops_demo.sh -->

암호화되지 않은 줄과 암호화된 값을 각각 바꿔 보았습니다.

| 변조 | 결과 |
|---|---|
| 평문 줄 `host: db.internal`을 `host: evil.example`로 바꿈 | `MAC mismatch.` 복호화 거부 |
| 암호화된 `token` 값의 암호문 일부를 바꿈 | `Could not decrypt with AES_GCM: cipher: message authentication failed` |

두 번째는 예상된 결과입니다. 중요한 것은 첫 번째입니다. 암호화하지 않은 줄을 바꿨는데도 복호화가 거부되었습니다. 파일 서명(MAC)이 암호화하지 않은 값까지 포함하기 때문입니다. 누군가 `host`를 공격자의 서버로 몰래 바꿔 저장소에 올려도, 비밀을 풀기 전에 알아챌 수 있습니다. 평문으로 둔 값도 변조에서 보호된다는 뜻입니다.

## 7. 값 수정과 바뀌는 줄

<!-- files: sops_demo.sh -->

`sops set secrets.enc.yaml '["db"]["password"]' '"N3w-DB-Pass"'`로 비밀번호 하나를 바꿨습니다. 파일에서 바뀐 줄은 이렇습니다.

```text
-    password: ENC[AES256_GCM,data:4nkFb...
+    password: ENC[AES256_GCM,data:ZMB/4...
-    lastmodified: "2026-10-29T08:54:15Z
-    mac: ENC[AES256_GCM,data:G7ifEBuMtZ...
+    lastmodified: "2026-10-29T08:54:16Z
+    mac: ENC[AES256_GCM,data:GlUngR9//y...
```

바뀐 것은 `password` 한 줄과 수정 시각, 서명 줄뿐이었습니다. `token`과 일반 설정은 그대로입니다. 그래서 저장소의 변경 내용이 작고, 다른 항목을 건드렸는지 리뷰에서 확인할 수 있습니다.

## 8. 받는 사람 추가

팀원이 늘면 받는 사람(공개 키)을 추가하고 `sops updatekeys`로 파일을 다시 맞춥니다. `.sops.yaml`의 `age:` 값에 쉼표로 새 공개 키를 덧붙이고 실행했습니다.

| 확인 | 결과 |
|---|---|
| `updatekeys` 실행 | `File ... synced with new keys` |
| 파일 안의 받는 사람 수 | 2 |
| 새 키(팀원)로 `token` 복호화 | `tok_live_ABC123XYZ` |

값 자체는 다시 암호화되지 않고 데이터 키를 감싸는 부분만 갱신되는 것으로 추정합니다. 이 글에서 암호문이 바뀌었는지는 비교하지 않았습니다. 팀원이 나갈 때는 받는 사람에서 빼고 `updatekeys`를 하면 되지만, 그 사람이 이미 복호화해 본 비밀은 알고 있으므로 비밀 값 자체를 바꿔야 합니다. 이 점은 sops의 한계가 아니라 비밀 관리 전반의 원칙입니다.

![sops_demo.sh 실행 결과 뒷부분에서 복호화와 값 하나 꺼내기가 되고, 키가 없거나 틀리면 오류가 나며, 평문 줄을 바꾸면 MAC mismatch, 암호문을 바꾸면 인증 실패가 나고, 값 수정 시 password와 수정 시각과 서명 줄만 바뀌며, 받는 사람이 2명이 되어 새 키로도 복호화되는 것을 확인합니다.](https://copyandrun.com/img/sops-age-encrypted-config/02-복호화-변조-키추가.png)

## 9. 쓸 때 정할 것

| 항목 | 내용 |
|---|---|
| 비밀 키 보관 | 개인별로 따로 두고 저장소에 올리지 않음. 비밀번호 관리자나 하드웨어 키에 보관 |
| 받는 사람 | 사람과 서버(배포용 키)를 구분. 둘 이상으로 두어 한 사람이 키를 잃어도 열 수 있게 함 |
| 어떤 값을 암호화하나 | `encrypted_regex`에 비밀이 되는 키 이름을 빠짐없이 기재. 새 비밀 항목을 추가하면 규칙도 맞는지 확인 |
| 평문 노출 | 복호화한 값을 파일, 로그, 명령 기록에 남기지 않기 |
| 배포 | CI나 서버에는 복호화용 비밀 키를 환경 변수나 비밀 저장소로 주입. 이 글에서는 시험하지 않음 |
| 이력 | 이미 평문으로 저장소에 올라간 비밀은 지워도 이력에 남음. 그 비밀은 이미 새어 나갔다고 보고 값을 교체 |

## 전체 코드

위 1~8절을 한 번에 실행하는 파일입니다. `sops_demo.sh`로 저장하고 `bash sops_demo.sh`로 실행합니다. 일회용 `alpine` 컨테이너 안에서 `age`와 `sops`를 설치해 쓰므로 내 PC에는 아무것도 남지 않습니다. 이 PC에서는 약 1분이 걸렸습니다. 키, 비밀번호, 토큰은 모두 실습용입니다.

```bash
#!/usr/bin/env bash
# sops 와 age 로 설정 파일의 비밀 값만 암호화하고, 복호화, 키 없음/틀린 키, 변조 감지, 값 수정, 받는 사람 추가까지 확인한다.
# 준비: Docker. 모든 작업은 일회용 alpine 컨테이너 안에서 하고(age, sops 를 설치), 파일은 컨테이너와 함께 사라진다.
# 주의: 이 파일의 키와 비밀 값은 모두 실습용이다. 실제 비밀을 넣지 않는다.
# 실행(Git Bash): bash sops_demo.sh   (약 1분)
export MSYS_NO_PATHCONV=1
docker run --rm -i alpine sh -s <<'INNER'
apk add --no-cache age sops >/dev/null 2>&1
export SOPS_DISABLE_VERSION_CHECK=1 2>/dev/null
cd /tmp && mkdir w && cd w

echo "## 1. 도구 버전과 키 만들기"
echo "age $(age --version), $(sops --version 2>&1 | head -1)"
age-keygen -o key.txt 2>&1 | sed 's/^Public key: /공개 키(받는 사람 주소): /'
PUB=$(grep -o 'age1[a-z0-9]*' key.txt | head -1)

echo "## 2. 평문 설정 파일(secrets.yaml)"
cat > secrets.yaml <<Y
app:
  name: payroll
  debug: false
db:
  host: db.internal
  user: app
  password: S3cr3t-DB-Pass
api:
  token: tok_live_ABC123XYZ
Y
cat secrets.yaml

echo "## 3. .sops.yaml 규칙: password 와 token 값만 암호화"
cat > .sops.yaml <<Y
creation_rules:
  - path_regex: secrets(\.enc)?\.yaml\$
    encrypted_regex: '^(password|token)\$'
    age: $PUB
Y
cat .sops.yaml | sed "s/age1[a-z0-9]*/age1.../"
sops -e secrets.yaml > secrets.enc.yaml
echo "-- 암호화된 파일(secrets.enc.yaml)"
sed 's/ENC\[AES256_GCM,data:\([^,]\{6\}\)[^]]*\]/ENC[...\1...]/; s/age1[a-z0-9]*/age1.../; s/mac: .*/mac: ENC[...]/; s/enc: .*/enc: (age 가 감싼 데이터 키)/' secrets.enc.yaml | grep -v -E '^\s+(-----|[A-Za-z0-9+/=]{20,}$)'
echo "평문 비밀이 파일에 남았나: password=$(grep -c 'S3cr3t' secrets.enc.yaml) token=$(grep -c 'ABC123' secrets.enc.yaml)  (0 이면 남지 않음)"

echo "## 4. 복호화"
SOPS_AGE_KEY_FILE=key.txt sops -d secrets.enc.yaml | grep -E 'password|token'
echo "-- 값 하나만 꺼내기(--extract)"
SOPS_AGE_KEY_FILE=key.txt sops -d --extract '["db"]["password"]' secrets.enc.yaml; echo

echo "## 5. 키가 없거나 틀리면"
echo "-- 키 없음"
sops -d secrets.enc.yaml 2>&1 | head -2 | cut -c1-110
age-keygen -o other.txt >/dev/null 2>&1
echo "-- 다른 사람의 키"
SOPS_AGE_KEY_FILE=other.txt sops -d secrets.enc.yaml 2>&1 | grep -m2 -E 'Failed|did not match' | cut -c1-110

echo "## 6. 변조 감지: 암호화되지 않은 줄(host)과 암호화된 값(token)을 각각 바꿔 본다"
sed 's/host: db.internal/host: evil.example/' secrets.enc.yaml > t1.yaml
SOPS_AGE_KEY_FILE=key.txt sops -d t1.yaml 2>&1 | head -1 | cut -c1-110
awk '/token: ENC/ { sub(/data:./, "data:Z"); } { print }' secrets.enc.yaml > t2.yaml
SOPS_AGE_KEY_FILE=key.txt sops -d t2.yaml 2>&1 | head -1 | cut -c1-110

echo "## 7. 값 수정(sops set)과 변경된 줄 수"
cp secrets.enc.yaml before.yaml
SOPS_AGE_KEY_FILE=key.txt sops set secrets.enc.yaml '["db"]["password"]' '"N3w-DB-Pass"'
echo "-- 바뀐 줄(diff -u 의 - 와 + 줄, 앞 40글자만)"
diff -u before.yaml secrets.enc.yaml | grep '^[-+] ' | cut -c1-40
SOPS_AGE_KEY_FILE=key.txt sops -d --extract '["db"]["password"]' secrets.enc.yaml; echo

echo "## 8. 받는 사람 추가(updatekeys): 팀원의 키로도 열 수 있게"
PUB2=$(grep -o 'age1[a-z0-9]*' other.txt | head -1)
sed "s/age: \(age1[a-z0-9]*\)/age: \1,$PUB2/" .sops.yaml > .sops.yaml.new && mv .sops.yaml.new .sops.yaml
SOPS_AGE_KEY_FILE=key.txt sops updatekeys -y secrets.enc.yaml 2>&1 | tail -1
echo "받는 사람 수: $(grep -c 'recipient: age1' secrets.enc.yaml)"
echo "-- 새 키(other.txt)로 복호화"
SOPS_AGE_KEY_FILE=other.txt sops -d --extract '["api"]["token"]' secrets.enc.yaml; echo
INNER
```

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| `no matching creation rules found` | `.sops.yaml`의 `path_regex`가 파일 이름과 맞지 않음. 처음에 `secrets\.yaml$`만 적었더니 `secrets.enc.yaml`에는 규칙이 없어 이 오류가 났고, `(\.enc)?`를 넣어 해결 |
| `Failed to get the data key` | 비밀 키를 못 찾았거나 받는 사람이 아님. `SOPS_AGE_KEY_FILE` 경로와 공개 키 확인 |
| `MAC mismatch` | 파일의 평문 줄이나 암호문을 누군가 바꿈. 의도한 수정이라면 `sops set`이나 `sops 파일`로 수정. 편집기로 직접 고치면 서명이 맞지 않음 |
| 평문이 파일에 남아 있음 | `encrypted_regex`에 그 키 이름이 없음. 규칙을 고치고 평문 파일에서 다시 암호화 |
| 새 버전 안내 메시지 출력 | 도구가 새 버전을 알리는 정보 메시지. 동작에는 영향 없음 |

## 확인 범위

- **해 본 것:** 2026-10-29, Windows 11 · Docker 29.5.3 · age v1.3.2 · sops 3.12.2(일회용 컨테이너)에서 키 생성, 일부 값 암호화, 복호화와 값 하나 꺼내기, 키 없음과 틀린 키, 평문 줄과 암호문 변조, `sops set`, 받는 사람 추가(`updatekeys`)를 실행했습니다. 같은 스크립트를 여러 번 실행했고 결과가 같았습니다.
- **해 보지 않은 것:** 클라우드 키 관리 서비스(AWS KMS 등)와의 연동, git 훅과 CI 연동, `sops 파일`로 편집기 열기, JSON과 .env 형식, 받는 사람 제거, 키 교체(rotation) 절차, 큰 파일의 속도, Linux 서버 설치, Windows 설치 버전.
- **읽을 때 주의:** 이 글의 비밀과 키는 실습용으로 만든 값입니다. 평문 줄을 바꿔도 복호화가 거부되는 동작은 이 버전(3.12.2)에서 본 결과입니다.
