README.md

AWS Encryption SDK Examples

This section features examples that show you how to use the AWS Encryption SDK. We demonstrate how to use the encryption and decryption APIs and how to set up some common configuration patterns.

APIs

The AWS Encryption SDK provides two high-level APIs: one-step APIs that process the entire operation in memory and streaming APIs.

You can find examples that demonstrate these APIs in the examples directory.

Configuration

To use the library APIs, you need to describe how you want the library to protect your data keys. You can do this using keyrings or cryptographic materials managers, or using master key providers. These examples will show you how to use the configuration tools that we include for you as well as how to create some of your own. We start with AWS KMS examples, then show how to use other wrapping keys.

• Using AWS Key Management Service (AWS KMS)
  • How to use a single AWS KMS CMK
    • with keyrings
  • How to use multiple AWS KMS CMKs in different regions
    • with keyrings
  • How to decrypt when you don't know the CMK
    • with keyrings
  • How to decrypt within a region
    • with keyrings
  • How to decrypt with a preferred region but failover to others
    • with keyrings
• Using raw wrapping keys
  • How to use a raw AES wrapping key
    • with keyrings
  • How to use a raw RSA wrapping key
    • with keyrings
  • How to encrypt with a raw RSA public key wrapping key without access to the private key
    • with keyrings
  • How to use a raw RSA wrapping key when the key is DER encoded
    • with keyrings
• Combining wrapping keys
  • How to combine AWS KMS with an offline escrow key
    • with keyrings

Keyrings

Keyrings are the most common way for you to configure the AWS Encryption SDK. They determine how the AWS Encryption SDK protects your data. You can find these examples in 'examples/keyring`.

Cryptographic Materials Managers

Keyrings define how your data keys are protected, but there is more going on here than just protecting data keys.

Cryptographic materials managers give you higher-level controls over how the AWS Encryption SDK protects your data. This can include things like enforcing the use of certain algorithm suites or encryption context settings, reusing data keys across messages, or changing how you interact with keyrings. You can find these examples in examples/crypto_materials_manager.

Master Key Providers

Before there were keyrings, there were master key providers. Master key providers were the original configuration structure that we provided for defining how you want to protect your data keys. Keyrings provide a simpler experience and often more powerful configuration options, but if you need to use master key providers, need help migrating from master key providers to keyrings, or simply want to see the difference between these configuration experiences, you can find these examples in examples/masterkeyprovider.

Legacy

This section includes older examples, including examples of using master keys and master key providers. You can use them as a reference, but we recommend looking at the newer examples, which explain the preferred ways of using this library. You can find these examples in examples/legacy.

Writing Examples

If you want to contribute a new example, that's awesome! To make sure that your example is tested in our CI, please make sure that it meets the following requirements:

1. The example MUST be a distinct class in the examples directory.
2. Each example file MUST contain exactly one example.
3. Each example file MUST contain a static method called run that runs the example.
4. If your run method needs any of the following inputs, the parameters MUST have the following types:
   • com.amazonaws.encryptionsdk.kms.AwsKmsCmkId : A single AWS KMS CMK ARN.
     • NOTE: You can assume that automatically discovered credentials have kms:GenerateDataKey, kms:Encrypt, and kms:Decrypt permissions on this CMK.
   • List<com.amazonaws.encryptionsdk.kms.AwsKmsCmkId> : A list of AWS KMS CMK ARNs to use for encrypting and decrypting data keys.
     • NOTE: You can assume that automatically discovered credentials have kms:Encrypt and kms:Decrypt permissions on these CMKs.
   • byte[] : Plaintext data to encrypt.
   • java.io.File : A path to a file containing plaintext to encrypt.
     • NOTE: You can assume that you have write access to the parent directory and that anything you do in that directory will be cleaned up by our test runners.
5. Any additional parameters MUST be optional and nullable and not of the same type as the above parameters.