agentleFS
zalando-incubatorzalando-incubator/agentic-identity-broker/.agents/skills/aws-crypto-go/SKILL.md

aws-crypto-go

Skill79 starsChanged 14 days agoMITView on GitHub

Use for any Go code involving the AWS Encryption SDK or MPL: github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk, github.com/aws/aws-cryptographic-material-providers-library/releases/go/mpl. Triggers on: KMS hierarchical keyring (CreateAwsKmsHierarchicalKeyring, BranchKeyId, TtlSeconds), DynamoDB branch key storage, mpl client, esdk client, CommitmentPolicy, RequireEncryptRequireDecrypt, encryption context / AAD binding, context_mismatch or integrity_violation decrypt errors, envelope encryption in Go + KMS, reducing KMS API calls (hierarchical vs plain keyring), porting Caching CMM from Java or Python to Go (Go SDK has no Caching CMM — hierarchical keyring is the Go-native equivalent), import path questions for the Go encryption SDK, or encrypting secrets/tokens/ciphertext in a Go service with KMS. Do not answer AWS Encryption SDK + Go questions from training alone — always consult this skill.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when implementing encryption/decryption with the AWS Encryption SDK in Go applications.

    line 9
  2. Distinctive:

    Use the latest version of the official AWS Encryption SDK for Go:

    line 17
  3. Distinctive:

    Always use the latest SDK version.

    line 34
  4. Distinctive:

    Always specify wrapping keys: when encrypting AND decrypting:

    line 76
  5. Distinctive:

    Use AWS KMS with proper key policies

    line 95
  6. Distinctive:

    Never hardcode keys in source code

    line 98
  7. Distinctive:

    When decrypting untrusted messages, be aware that messages can contain up to 65,535 encrypted data keys.

    line 109
  8. Distinctive:

    Before completing any encryption implementation:

    line 162

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

AWS Encryption SDK for Go

Use this skill when implementing encryption/decryption with the AWS Encryption SDK in Go applications.

Supporting files (load when needed):

  • reference.md - Detailed API documentation, import paths, types
  • examples.md - Complete code examples for all patterns

Library

Use the latest version of the official AWS Encryption SDK for Go:

github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk
github.com/aws/aws-cryptographic-material-providers-library/releases/go/mpl

API Reference: https://pkg.go.dev/github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk


AWS Best Practices (MANDATORY)

These rules are derived from the AWS Encryption SDK Best Practices.

1. Use Latest Version

Always use the latest SDK version. Upgrade promptly when new versions are released. Replace deprecated APIs immediately.

2. Use Default Values

The SDK encodes best practices in its defaults. Use them unless you have a specific, security-reviewed reason not to.

3. Key Commitment (MANDATORY)

Always use RequireEncryptRequireDecrypt commitment policy:

encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{
    CommitmentPolicy: mpltypes.ESDKCommitmentPolicyRequireEncryptRequireDecrypt.Enum(),
})

Key commitment:

  • Verifies the unique data key identity
  • Prevents decryption to multiple plaintexts
  • Adds only ~30 bytes to ciphertext

Never use ForbidEncryptAllowDecrypt for new implementations.

4. Encryption Context (MANDATORY)

Always provide an encryptionContext for Additional Authenticated Data (AAD):

encryptionContext := map[string]string{
    "service_id": serviceID,
    "purpose":    "token_encryption",
}

Rules:

  • Do NOT include secrets — context is stored in plaintext in ciphertext header
  • Include identifying info — tenant ID, service ID, resource type
  • Verify on decrypt — check returned context matches expected values
  • Context is cryptographically bound via AAD

5. Specify Wrapping Keys Explicitly

Always specify wrapping keys when encrypting AND decrypting:

// Good: Explicit key specification
keyring, err := mplClient.CreateAwsKmsKeyring(mpltypes.CreateAwsKmsKeyringInput{
    KmsClient: kmsClient,
    KmsKeyId:  kmsKeyArn,  // Explicit ARN
})

Benefits:

  • Prevents using unintended keys
  • Avoids cross-account/cross-region issues
  • Improves performance (no key discovery)

Avoid discovery mode unless absolutely necessary. If required, use discovery filters.

6. Protect Wrapping Keys

  • Use AWS KMS with proper key policies
  • Apply least privilege via IAM policies
  • For raw keys, use HSM or AWS CloudHSM
  • Never hardcode keys in source code

7. Use Digital Signatures

The default algorithm suite includes ECDSA signatures. Keep this enabled unless:

  • Performance requirements are extreme
  • A security engineer has explicitly approved removal
  • The same entity encrypts and decrypts

8. Limit Encrypted Data Keys

When decrypting untrusted messages, be aware that messages can contain up to 65,535 encrypted data keys. Consider implementing limits for untrusted sources.


⚠️ Go SDK Caching Limitation

The Go SDK does NOT support the standard Caching CMM found in Java/Python SDKs.

For caching, cost reduction, or high-volume encryption: Use the AWS KMS Hierarchical Keyring.

Hierarchical Keyring Benefits

FeatureBenefit
Branch key cachingReduces KMS API calls by ~99%
DynamoDB storageDurable, scalable key storage
Multi-tenant isolationEncryption context routing
Automatic rotationBuilt-in key versioning

Key Hierarchy

  1. KEK (Key Encryption Key) — AWS KMS key protecting branch keys
  2. Branch Keys — Cached in DynamoDB, rotated periodically
  3. DEK (Data Encryption Key) — Generated per encrypt operation

See examples.md for complete Hierarchical Keyring setup code.


Quick Reference

Commitment Policies

PolicyUse Case
RequireEncryptRequireDecryptDefault — always use
RequireEncryptAllowDecryptMigration from old ciphertext only
ForbidEncryptAllowDecryptNever use for new code

Error Categories

Error KindDescription
encryption_failedKey unavailable, permissions error
decryption_failedWrong key, corrupted data
context_mismatchAAD verification failed
integrity_violationTampering detected
kek_unavailableKMS/branch key not accessible

Implementation Checklist

Before completing any encryption implementation:

  • Using latest SDK version
  • CommitmentPolicy is RequireEncryptRequireDecrypt
  • All encrypt/decrypt calls include meaningful encryptionContext
  • Encryption context does not contain secrets
  • Wrapping keys specified explicitly (no discovery mode)
  • Decryption verifies returned encryption context
  • Digital signatures enabled (default algorithm suite)
  • Branch keys created before first use (Hierarchical Keyring)
  • Error handling distinguishes encryption/decryption/context errors
  • Cache TTL balanced (security vs. KMS costs)
  • Key policies follow least privilege

External Resources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.