🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🗝️ धडा 07 — Secrets आणि KMS: keys तिजोरीत, code मध्ये नाही

📍 तुम्ही इथे आहात: 16 पैकी धडा 07 · मागे: lesson-06-authorization · पुढे: lesson-08-iam-network

📦 या ब्रँचमध्ये काय आहे

धडे 01–06, आणि इमारत खिडकीचा पहिला धडा. दोन कामे. पहिले, envelope encryption: एक ताजी data key data encrypt करते, आणि KMS कधीच न सोडणारी master key फक्त data key encrypt करते. दुसरे, गुपिते (secrets) — database passwords, API keys — files मध्ये नाही, तर secret manager मध्ये राहतात, आणि secret scanner code मध्ये निसटून आलेली गुपिते शोधतो. sec/demo.py मधले secrets() दोन्ही दाखवते.

⚠️ sec/cloud.py मधला cipher हा SHA-256 पासून बनवलेला शिकवण्यासाठीचा keystream आहे. तो फक्त envelope encryption चा आकार दाखवतो. त्यात integrity check नाही आणि त्याने कधीही खऱ्या data चे संरक्षण करू नये. खऱ्या systems AWS KMS आणि तपासलेली library (AES-256-GCM) वापरतात. स्वतःची cryptography कधीही लिहू नका.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

शाळा प्रगतीपुस्तके एका कपाटात ठेवते. प्रत्येक कपाटाची स्वतःची छोटी किल्ली असते (data key).

छोट्या किल्ल्या कपाटांच्या शेजारी खुंटीवर टांगल्या तर चोर त्या सगळ्या घेऊन जातो. म्हणून office प्रत्येक छोटी किल्ली एका छोट्या कुलूपबंद डबीत ठेवते, आणि त्या डब्या फक्त मुख्य office ची तिजोरी उघडू शकते (KMS मधली master key). मुख्य office ची तिजोरी कधीच मुख्य office सोडत नाही. ती उसनी घेता येत नाही. तुम्ही फक्त कुलूपबंद डबी घेऊन जाऊन विचारू शकता: "कृपया ही उघडा" — आणि मुख्य office कोणी विचारले, आणि कधी, ते लिहून ठेवते.

म्हणून प्रत्येक कपाटाशेजारी दोन गोष्टी असतात: कुलूपबंद प्रगतीपुस्तके, आणि तिच्या कुलूपबंद डबीतली छोटी किल्ली. दोन्ही चोरणाऱ्या चोराकडे उघडता येईल असे काहीच नसते.

आणि office एक metal detector घेऊन फिरते (secret scanner). कोणी noticeboard वर किल्ली चिकटवली असेल — file मधला password — तर तो वाजतो.

🗺️ आकृती

flowchart LR
    pt["📄 Katrina: A+ in maths"] --> enc["🔐 encrypt with data key"]
    dk["🔑 data key<br/>fresh per object"] --> enc
    enc --> ct["ciphertext"]
    dk --> wrap["📦 wrap with master key"]
    kms["🏦 KMS master key<br/>never leaves KMS"] --> wrap
    wrap --> wk["wrapped data key"]
    ct --> store["🗄️ stored together:<br/>ciphertext + wrapped key"]
    wk --> store
    scan["🔍 secret scanner<br/>AKIA… · PRIVATE KEY · password="] -.-> repo["📁 repo files"]

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/security/lesson-diagrams.html#l07

❓ काय

Secret (गुपित) — access देणारी कोणतीही गोष्ट: database password, API key, signing key, cloud access key, private TLS key.
Secret manager — गुपिते encrypted साठवणारी, प्रत्येक गुपित कोण वाचू शकतो ते नियंत्रित करणारी (IAM), प्रत्येक वाचनाचा log ठेवणारी, आणि त्यांना rotate करणारी service: AWS Secrets Manager, AWS Systems Manager Parameter Store (SecureString), HashiCorp Vault, Azure Key Vault, Google Secret Manager. App स्वतःच्या role ने गुपित runtime ला आणते — image किंवा repo मध्ये काहीच नसते.
Rotation — ठरलेल्या वेळापत्रकाने, आणि leak नंतर लगेच, गुपित बदलणे. त्याहूनही चांगले: आपोआप expire होणारी अल्पायुषी credentials (IAM roles, Vault dynamic database users).
KMS (key management service) — master keys (AWS त्यांना KMS keys म्हणते) hardware security modules मध्ये ठेवते. तुम्हाला key कधीच दिसत नाही; तुम्ही KMS ला ती वापरायला सांगता, आणि CloudTrail प्रत्येक request चा log ठेवतो. Key policies आणि IAM कोण हे करू शकतो ते ठरवतात.
Envelope encryption — KMS थेट जास्तीत जास्त 4 KB encrypt करते, आणि प्रत्येक call ही network request असते. म्हणून:
1. KMS कडून data key मागा (GenerateDataKey): ती तुम्हाला plain text मध्ये आणि wrapped (master key खाली encrypted) अशी दोन्ही रूपात मिळते,
2. plain data key ने data local पातळीवर encrypt करा (AES-GCM), मग plain key विसरून जा,
3. ciphertext wrapped key सोबत साठवा,
4. वाचण्यासाठी: wrapped key KMS ला पाठवा (Decrypt), plain data key परत मिळवा, local पातळीवर decrypt करा. KMS सह S3, EBS, RDS आणि DynamoDB encryption सगळे याच पद्धतीने काम करतात.
Secret scanning — code आणि history मध्ये patterns शोधणे: AWS access key ids (AKIA…), private key headers, URLs मधले passwords, password = "…". तो commit आधी चालवा (pre-commit hook), CI मध्ये, आणि host च्या push protection सह. OWASP Top 10 (2021) A02:2021 – Cryptographic Failures संरक्षित नसलेल्या keys आणि data ला लागू होते.

🤔 का

कारण code मधली गुपिते code जिथे जातो तिथे सगळीकडे जातात: प्रत्येक laptop, प्रत्येक fork, प्रत्येक CI log, प्रत्येक container image — आणि तुम्ही ओळ delete केल्यानंतरही git history ती ठेवते. कारण manager तुम्हाला files देऊ शकत नाहीत ते देतो: गुपित कोणी वाचले, release शिवाय ते बदलण्याचा मार्ग, आणि access काढून घेण्याचा मार्ग. आणि कारण envelope encryption महत्त्वाची एकमेव key KMS च्या आत ठेवते: data वाचण्यासाठी तुम्हाला साठवलेला blob आणि kms:Decrypt call करण्याची permission दोन्ही लागतात — जी तुम्ही audit करू शकता, आणि revoke करू शकता.

🔧 कसे (या repo मध्ये)

sec/cloud.py मध्ये: envelope_encrypt(plaintext, master_key, data_key) ciphertext (data key खालचा data) आणि wrapped_key (master key खालची data key) परत देते. envelope_decrypt(blob, master_key) आधी data key उघडते, मग decrypt करते — kms:Decrypt + local decryption सारख्याच दोन पायऱ्या. find_secrets(files) {filename: text} च्या dict वर चार regular expressions चालवते आणि (file, kind) जोड्या परत देते.

🧪 करून पाहा

python3 sec/demo.py secrets
python3 - <<'EOF'
import sys; sys.path.insert(0, "sec"); from cloud import envelope_encrypt, envelope_decrypt, find_secrets
blob = envelope_encrypt("Dipika: B+ in maths", master_key=b"kms-master-key", data_key=b"fresh-data-key-42")
print("stored next to the data:", sorted(blob))
print("right master key →", envelope_decrypt(blob, b"kms-master-key"))
try:
    print("wrong master key →", envelope_decrypt(blob, b"guess"))
except UnicodeDecodeError:
    print("wrong master key → unreadable bytes")
files = {"settings.py": 'DB_PASSWORD = os.environ["DB_PASSWORD"]',
         "docker-compose.yml": "DATABASE_URL: postgres://app:Winter2026@db:5432/school",
         "test_login.py": 'token = "abc"',
         "old.env": "API_TOKEN='sk_live_0123456789abcdef'"}
for name, kind in find_secrets(files): print(f"found: {name:<20} {kind}")
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

secrets हे print करते:

── envelope encryption: ciphertext fe1cf83a01159db61697… · wrapped data key 00d66fb446efd05f5b12…
   decrypt = unwrap the data key with the master key (KMS) → 'Katrina: A+ in maths'
── secret scan of 4 files → [('config.py', 'generic secret'), ('deploy.sh', 'AWS access key id'), ('notes.md', 'private key')]
   secrets live in a manager (Secrets Manager / Vault), are fetched at runtime, rotated, and never committed

तुमचा snippet हे print करतो:

stored next to the data: ['ciphertext', 'wrapped_key']
right master key → Dipika: B+ in maths
wrong master key → unreadable bytes
found: docker-compose.yml   password in a URL
found: old.env              generic secret

🏁 तुम्ही आत्ताच काय सिद्ध केले

फक्त दोनच गोष्टी साठवल्या जातात — ciphertext आणि wrapped key; plain data key निघून गेली आहे. Master key शिवाय data वाचता येत नाही. Scanner ला database URL मधला password आणि जुन्या .env file मधला token सापडला. त्याने environment मधून password वाचणाऱ्या settings.py ला, किंवा 3 अक्षरांच्या test value ला flag केले नाही. Scanners patterns आणि लांबीचे नियम वापरतात — ते अनेक leaks पकडतात, सगळे नाही, म्हणून ते एक थर आहेत, संपूर्ण आराखडा नाही.

⚠️ नेहमीच्या चुका

"फक्त एका मिनिटासाठी" repo मध्ये गुपिते, किंवा docker-compose.yml मध्ये, किंवा image मध्ये भाजून टाकलेली
ओळ delete करून पुन्हा push करणे — गुपित अजूनही git history, forks आणि caches मध्ये आहे (धडा 15: आधी rotate करा)
प्रत्येक service आणि प्रत्येक developer साठी एकच shared database password
environment variables मधली गुपिते जी नंतर crash reports, logs किंवा ps output मध्ये दिसतात
तपासलेल्या library मधल्या KMS + AES-GCM ऐवजी स्वतःचे encryption लिहिणे
account मधल्या प्रत्येक role ला kms:Decrypt call करू देणारी KMS key policy

🏭 प्रत्यक्ष वापरात

खऱ्या account वर — database गुपित AWS Secrets Manager मध्ये, तुमच्या स्वतःच्या KMS key ने encrypted, साठवा आणि automatic rotation चालू करा:

aws kms create-key --description "school secrets"          # note the KeyId
aws kms create-alias --alias-name alias/school-secrets --target-key-id <KeyId>
aws kms enable-key-rotation --key-id <KeyId>
aws secretsmanager create-secret --name school/results-db \
    --kms-key-id alias/school-secrets --secret-string file://results-db.json
aws secretsmanager rotate-secret --secret-id school/results-db \
    --rotation-lambda-arn arn:aws:lambda:ap-south-1:111122223333:function:rotate-results-db \
    --rotation-rules AutomaticallyAfterDays=30

App च्या स्वतःच्या IAM role ने ते runtime ला वाचा (Python, boto3) — code किंवा image मध्ये काहीच नाही:

import boto3, json
sm = boto3.client("secretsmanager")
db = json.loads(sm.get_secret_value(SecretId="school/results-db")["SecretString"])

KMS data key आणि AES-256-GCM सह envelope encryption (cryptography library):

import boto3, os
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
kms = boto3.client("kms")
dk = kms.generate_data_key(KeyId="alias/school-data", KeySpec="AES_256")
nonce = os.urandom(12)
ciphertext = AESGCM(dk["Plaintext"]).encrypt(nonce, b"Katrina: A+ in maths", None)
record = {"ciphertext": ciphertext, "nonce": nonce, "wrapped_key": dk["CiphertextBlob"]}
del dk                                                     # never store the plain data key
# to read: key = kms.decrypt(CiphertextBlob=record["wrapped_key"])["Plaintext"]
#          AESGCM(key).decrypt(record["nonce"], record["ciphertext"], None)

(AWS Encryption SDK हे सगळे तुमच्यासाठी करते, key caching सह.)

गुपिते commit होण्याआधीच थांबवा — gitleaks सह pre-commit hook:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुमच्या code host चे secret scanning push protection सह चालू करा, CI मध्ये एकदा पूर्ण history वर scanner चालवा, आणि सापडलेले प्रत्येक गुपित manager मध्ये हलवा — जाता जाता ते rotate करत. Access keys ऐवजी IAM roles ला प्राधान्य द्या, म्हणजे leak होण्यासाठी दीर्घायुषी key मुळातच नसेल.

⏭️ पुढे

गुपित सुरक्षित आहे. पण ते वाचणाऱ्या role ला गरजेपेक्षा खूप जास्त करण्याची परवानगी असू शकते, आणि database कुठूनही पोहोचण्याजोगा असू शकतो. पुढे: किमान अधिकार आणि बंद दारे.

git checkout lesson-08-iam-network

🗝️ Lesson 07 — Secrets and KMS: keys in a vault, not in code

📍 You are here: Lesson 07 of 16 · Previous: lesson-06-authorization · Next: lesson-08-iam-network

📦 What's in this branch

Lessons 01–06, plus the first lesson of the building desk. Two jobs. First, envelope encryption: a fresh data key encrypts the data, and a master key that never leaves KMS encrypts only the data key. Second, secrets — database passwords, API keys — live in a secret manager, not in files, and a secret scanner finds the ones that slipped into code. secrets() in sec/demo.py shows both.

⚠️ The cipher in sec/cloud.py is a teaching keystream built from SHA-256. It only shows the shape of envelope encryption. It has no integrity check and must never protect real data. Real systems use AWS KMS and a vetted library (AES-256-GCM). Never write your own cryptography.

🧒 Explain like I'm 5

The school keeps report cards in a cupboard. Each cupboard has its own small key (the data key).

If the small keys hang on a hook next to the cupboards, a thief takes them all. So the office puts every small key into a tiny locked box, and only the head office safe can open those boxes (the master key in KMS). The head office safe never leaves the head office. You cannot borrow it. You can only bring a locked box and ask: "please open this" — and the head office writes down who asked, and when.

So next to each cupboard sit two things: the locked report cards, and the small key in its locked box. A thief who steals both has nothing he can open.

And the office walks around with a metal detector (the secret scanner). If someone has taped a key to a noticeboard — a password in a file — it beeps.

🗺️ Diagram

flowchart LR
    pt["📄 Katrina: A+ in maths"] --> enc["🔐 encrypt with data key"]
    dk["🔑 data key<br/>fresh per object"] --> enc
    enc --> ct["ciphertext"]
    dk --> wrap["📦 wrap with master key"]
    kms["🏦 KMS master key<br/>never leaves KMS"] --> wrap
    wrap --> wk["wrapped data key"]
    ct --> store["🗄️ stored together:<br/>ciphertext + wrapped key"]
    wk --> store
    scan["🔍 secret scanner<br/>AKIA… · PRIVATE KEY · password="] -.-> repo["📁 repo files"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/security/lesson-diagrams.html#l07

❓ What

Secret — anything that grants access: a database password, an API key, a signing key, a cloud access key, a private TLS key.
Secret manager — a service that stores secrets encrypted, controls who may read each one (IAM), logs every read, and rotates them: AWS Secrets Manager, AWS Systems Manager Parameter Store (SecureString), HashiCorp Vault, Azure Key Vault, Google Secret Manager. The app fetches the secret at runtime, with its own role — nothing is in the image or the repo.
Rotation — replace a secret on a schedule, and at once after a leak. Better still: short-lived credentials (IAM roles, Vault dynamic database users) that expire by themselves.
KMS (key management service) — holds master keys (AWS calls them KMS keys) in hardware security modules. You never see the key; you ask KMS to use it, and CloudTrail logs each request. Key policies and IAM decide who may.
Envelope encryption — KMS encrypts at most 4 KB directly, and every call is a network request. So:
1. ask KMS for a data key (GenerateDataKey): you get it in plain text and wrapped (encrypted under the master key),
2. encrypt the data locally with the plain data key (AES-GCM), then forget the plain key,
3. store the ciphertext with the wrapped key,
4. to read: send the wrapped key to KMS (Decrypt), get the plain data key back, decrypt locally. S3, EBS, RDS and DynamoDB encryption with KMS all work this way.
Secret scanning — search code and history for patterns: AWS access key ids (AKIA…), private key headers, passwords in URLs, password = "…". Run it before the commit (a pre-commit hook), in CI, and with the host's push protection. OWASP Top 10 (2021) A02:2021 – Cryptographic Failures covers keys and data that are not protected.

🤔 Why

Because secrets in code travel everywhere the code goes: every laptop, every fork, every CI log, every container image — and git history keeps them after you delete the line. Because a manager gives you what files cannot: who read the secret, a way to change it without a release, and a way to take access away. And because envelope encryption keeps the one key that matters inside KMS: to read data, you need both the stored blob and permission to call kms:Decrypt — which you can audit, and revoke.

🔧 How (in this repo)

In sec/cloud.py: envelope_encrypt(plaintext, master_key, data_key) returns ciphertext (the data under the data key) and wrapped_key (the data key under the master key). envelope_decrypt(blob, master_key) unwraps the data key, then decrypts — the same two steps as kms:Decrypt + local decryption. find_secrets(files) runs four regular expressions over a dict of {filename: text} and returns (file, kind) pairs.

🧪 Try it

python3 sec/demo.py secrets
python3 - <<'EOF'
import sys; sys.path.insert(0, "sec"); from cloud import envelope_encrypt, envelope_decrypt, find_secrets
blob = envelope_encrypt("Dipika: B+ in maths", master_key=b"kms-master-key", data_key=b"fresh-data-key-42")
print("stored next to the data:", sorted(blob))
print("right master key →", envelope_decrypt(blob, b"kms-master-key"))
try:
    print("wrong master key →", envelope_decrypt(blob, b"guess"))
except UnicodeDecodeError:
    print("wrong master key → unreadable bytes")
files = {"settings.py": 'DB_PASSWORD = os.environ["DB_PASSWORD"]',
         "docker-compose.yml": "DATABASE_URL: postgres://app:Winter2026@db:5432/school",
         "test_login.py": 'token = "abc"',
         "old.env": "API_TOKEN='sk_live_0123456789abcdef'"}
for name, kind in find_secrets(files): print(f"found: {name:<20} {kind}")
EOF

✅ Verify — what you should see

secrets prints:

── envelope encryption: ciphertext fe1cf83a01159db61697… · wrapped data key 00d66fb446efd05f5b12…
   decrypt = unwrap the data key with the master key (KMS) → 'Katrina: A+ in maths'
── secret scan of 4 files → [('config.py', 'generic secret'), ('deploy.sh', 'AWS access key id'), ('notes.md', 'private key')]
   secrets live in a manager (Secrets Manager / Vault), are fetched at runtime, rotated, and never committed

Your snippet prints:

stored next to the data: ['ciphertext', 'wrapped_key']
right master key → Dipika: B+ in maths
wrong master key → unreadable bytes
found: docker-compose.yml   password in a URL
found: old.env              generic secret

🏁 What you just proved

Only two things are stored — the ciphertext and the wrapped key; the plain data key is gone. Without the master key, the data stays unreadable. The scanner found the password inside a database URL and the token in an old .env file. It did not flag settings.py, which reads the password from the environment, or the 3-character test value. Scanners use patterns and length rules — they catch many leaks, not all, so they are one layer, not the plan.

⚠️ Common mistakes

secrets in the repo "only for a minute", or in docker-compose.yml, or baked into an image
deleting the line and pushing again — the secret is still in git history, forks and caches (lesson 15: rotate first)
one shared database password for every service and every developer
secrets in environment variables that then appear in crash reports, logs or ps output
writing your own encryption instead of KMS + AES-GCM from a vetted library
a KMS key policy that lets every role in the account call kms:Decrypt

🏭 In production

On a real account — store a database secret in AWS Secrets Manager, encrypted with your own KMS key, and turn on automatic rotation:

aws kms create-key --description "school secrets"          # note the KeyId
aws kms create-alias --alias-name alias/school-secrets --target-key-id <KeyId>
aws kms enable-key-rotation --key-id <KeyId>
aws secretsmanager create-secret --name school/results-db \
    --kms-key-id alias/school-secrets --secret-string file://results-db.json
aws secretsmanager rotate-secret --secret-id school/results-db \
    --rotation-lambda-arn arn:aws:lambda:ap-south-1:111122223333:function:rotate-results-db \
    --rotation-rules AutomaticallyAfterDays=30

Read it at runtime, with the app's own IAM role (Python, boto3) — nothing in code or image:

import boto3, json
sm = boto3.client("secretsmanager")
db = json.loads(sm.get_secret_value(SecretId="school/results-db")["SecretString"])

Envelope encryption with a KMS data key and AES-256-GCM (cryptography library):

import boto3, os
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
kms = boto3.client("kms")
dk = kms.generate_data_key(KeyId="alias/school-data", KeySpec="AES_256")
nonce = os.urandom(12)
ciphertext = AESGCM(dk["Plaintext"]).encrypt(nonce, b"Katrina: A+ in maths", None)
record = {"ciphertext": ciphertext, "nonce": nonce, "wrapped_key": dk["CiphertextBlob"]}
del dk                                                     # never store the plain data key
# to read: key = kms.decrypt(CiphertextBlob=record["wrapped_key"])["Plaintext"]
#          AESGCM(key).decrypt(record["nonce"], record["ciphertext"], None)

(The AWS Encryption SDK does all of this for you, including the key caching.)

Stop secrets before they are committed — a pre-commit hook with gitleaks:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks

🏭 Why this matters in production: turn on your code host's secret scanning with push protection, run a scanner in CI over the full history once, and move every secret you find into a manager — rotating it as you go. Prefer IAM roles over access keys, so there is no long-lived key to leak at all.

⏭️ Next

The secret is safe. But the role that reads it may be allowed to do far more than it needs, and the database may be reachable from anywhere. Next: least privilege and closed doors.

git checkout lesson-08-iam-network

← Previousauthorization Next →iam network

This page is the lesson's README from the lesson-07-secrets-kms branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.