# Bàn giao repo có secret mà không phải chờ Vault của khách

> SOPS chỉ mã hoá giá trị nên git diff vẫn đọc được, còn khoá age nằm trong tay khách.

Bản gốc: https://fdetimes.net/vi/cong-cu/sops-va-age-ma-hoa-secret-trong-repo-ban-giao-cho-khach/

Tuần cuối của một engagement, repo đã chạy, pipeline đã xanh, chỉ còn một câu hỏi chặn việc bàn giao: password database và API key để ở đâu? Khách nói sẽ dựng Vault "quý sau". Bạn thì không thể để file `.env` dạng rõ trong repo, cũng không thể gửi secret qua chat.

SOPS và age giải quyết gọn tình huống này. SOPS là một editor cho file đã mã hoá, hỗ trợ YAML, JSON, ENV, INI và binary.

Nó mã hoá được bằng AWS KMS, GCP KMS, Azure Key Vault, HuaweiCloud KMS, PGP, và cả age. Chọn age thì bạn bỏ qua được mọi dịch vụ quản lý khoá bên ngoài, kể cả cái Vault khách chưa có.

Với một FDE, đó là khác biệt giữa "bàn giao xong" và "bàn giao khi nào khách sẵn sàng". Secret đi cùng repo ở dạng mã hoá, và chỉ ai giữ khoá mới đọc được.

## Hai công cụ, ai làm phần nào?

Khi đội bảo mật của khách hỏi công cụ có đáng tin không, bạn có sẵn câu trả lời: SOPS ra đời ở Mozilla năm 2015, được tặng cho CNCF làm Sandbox project năm 2023, dùng giấy phép MPL-2.0.

age do Filippo Valsorda và benjojo thiết kế. Nó vừa là công cụ mã hoá file, vừa là một định dạng và một thư viện Go. Triết lý của nó là khoá nhỏ và tường minh, không có tuỳ chọn cấu hình, ghép nối theo kiểu UNIX. Với người bàn giao, "không có tuỳ chọn" là ưu điểm: khách không thể cấu hình sai thứ không tồn tại.

Phân vai rất rõ. age lo phần mật mã. SOPS lo phần hiểu cấu trúc file: đâu là khoá, đâu là giá trị, và giá trị nào cần giấu.

## Mã hoá giá trị, không mã hoá cả file

Điểm khác biệt của SOPS so với cách mã hoá nguyên file: nó chỉ mã hoá giá trị lá, tức giá trị không có con, còn tên khoá vẫn để dạng rõ. Thử hình dung file `config/prod.yaml` của bạn có bốn dòng:

```yaml
db_host: db.internal
db_port: 5432
db_password: s3cret-pass
openai_api_key: sk-xxxx
```

Trước khi mã hoá, bạn cần biết khoá public của người sẽ giải mã. SOPS nhận cả SSH public key làm age recipient, nên cách gọn nhất là xin khoá SSH public mà kỹ sư vận hành phía khách đang dùng.

Khoá riêng tương ứng không bao giờ rời máy họ và không bao giờ vào repo; họ cất nó ở đúng nơi đang cất khoá SSH, bạn chỉ cần phần public.

Có khoá rồi, mã hoá chỉ cần cờ `--age`, không cần server nào (nhiều recipient thì cách nhau bằng dấu phẩy, hoặc đặt trong biến `SOPS_AGE_RECIPIENTS`):

```bash
sops -e --age <khoá-public-của-khách>,<khoá-public-của-bạn> \
  --encrypted-regex '^(db_password|openai_api_key)$' \
  config/prod.yaml > config/prod.enc.yaml
```

Nhờ `encrypted_regex`, chỉ những khoá khớp regex mới bị mã hoá. File kết quả trông đại ý như sau, chuỗi `ENC[...]` là ciphertext rút gọn:

```yaml
db_host: db.internal
db_port: 5432
db_password: ENC[...]
openai_api_key: ENC[...]
```

Người giữ khoá riêng tương ứng chạy `sops -d config/prod.enc.yaml` để lấy lại bản rõ. Kỹ sư của khách vẫn đọc được host và port để debug mà không cần khoá. Mỗi lần đổi port, git diff chỉ ra đúng dòng `db_port`, thay vì một khối ký tự vô nghĩa như khi mã hoá cả file.

**Điểm mấu chốt:** Chỉ mã hoá giá trị, để tên khoá dạng rõ: diff vẫn đọc được mà secret vẫn kín.

SOPS còn tính một MAC trên toàn bộ giá trị để phát hiện giá trị bị thêm hay bớt trái phép. Vì thế người không có khoá khó lặng lẽ chèn hay xoá một giá trị trong file mã hoá; còn ai đã có khoá thì vẫn mã hoá lại được file, nên danh sách recipient mới là thứ cần giữ chặt.

## Một .sops.yaml đủ dùng cho bàn giao

Để không ai phải nhớ cờ, đặt quy tắc vào `.sops.yaml` ở gốc repo:

```yaml
creation_rules:
  - path_regex: config/prod/.*\.yaml$
    encrypted_regex: '^(db_password|openai_api_key)$'
    age: <khoá của trưởng nhóm vận hành phía khách>,<khoá của bạn>
  - path_regex: .*\.yaml$
    encrypted_regex: '^(db_password|openai_api_key)$'
    age: <khoá của cả đội dev>
```

Thứ tự ở đây là then chốt. Quy tắc được xét lần lượt và quy tắc khớp đầu tiên thắng. Nếu bạn đặt quy tắc chung `.*\.yaml$` lên trước, file prod cũng khớp nó, và secret production sẽ được mã hoá cho cả đội dev, đúng điều bạn muốn tránh. Quy tắc riêng luôn đứng trên.

## Giới hạn bạn phải nói thẳng với khách

Regex chỉ bảo vệ những tên nó biết. Nếu sáu tháng sau ai đó thêm khoá `db_pass` mà regex chỉ khớp `db_password`, giá trị ấy sẽ nằm trong repo dạng rõ. Trước khi bàn giao, nên đổi regex sang mẫu rộng hơn hoặc ghi rõ quy ước đặt tên trong README.

Giới hạn kế tiếp nằm ở lịch sử git. Một người từng là recipient vẫn giải mã được các commit cũ dù bạn xoá khoá của họ khỏi `.sops.yaml`. Gỡ quyền một người thực chất là đổi chính secret, chứ không chỉ mã hoá lại file. Ngày bàn giao, bước cuối nên là bỏ khoá của bạn khỏi danh sách và để khách xoay vòng secret.

Và vì không có server trung tâm, cũng không có nhật ký ai đã đọc secret nào. Khách cần điều đó thì Vault hay KMS vẫn là đích đến, còn SOPS là chiếc cầu sang đó.

## Học gì trước, ghi gì vào CV?

Bắt đầu bằng một bài khởi động: mã hoá một file YAML bằng SSH key của chính bạn, sửa một giá trị, xem diff. Sau đó mới viết `.sops.yaml` nhiều môi trường. Cả quá trình mất một buổi tối.

Trong CV, thay vì "secrets management" chung chung, hãy viết "bàn giao repo với secret mã hoá bằng SOPS và age, khách tự giữ khoá giải mã". Dòng đó cho thấy bạn nghĩ đến ngày khách tự vận hành, không chỉ ngày demo.

Engagement tốt kết thúc khi khách tự vận hành được mà không cần gọi bạn. Một file `.sops.yaml` xếp đúng thứ tự giúp được việc đó nhiều hơn bất kỳ tài liệu bàn giao dài nào.

**Thử ngay tuần này:**

- Lấy một file config có secret trong dự án phụ, mã hoá bằng SOPS với age recipient là SSH public key của bạn, rồi commit và xem git diff khi đổi một giá trị.
- Viết .sops.yaml có hai quy tắc (prod và mặc định), cố tình đảo thứ tự để thấy file prod bị mã hoá cho sai người.
- Thêm một khoá tên db_pass không khớp encrypted_regex và kiểm tra xem nó có bị để lộ dạng rõ không.

## Nguồn

- [getsops/sops (GitHub)](https://github.com/getsops/sops)

- [SOPS: Secrets OPerationS (getsops.io docs)](https://getsops.io/docs/)

- [sops | CNCF](https://www.cncf.io/projects/sops/)

- [FiloSottile/age (GitHub)](https://github.com/FiloSottile/age)

- [Age (SOPS docs)](https://getsops.io/docs/usage/identities/age/)

- [Config file (SOPS docs)](https://getsops.io/docs/usage/identities/config-file/)

- [Reference (SOPS docs)](https://getsops.io/docs/reference/)
