Using keyrings - AWS Encryption SDK

Using keyrings

The AWS Encryption SDK for C, the AWS Encryption SDK for JavaScript, the AWS Encryption SDK for Java, and the AWS Encryption SDK for .NET use keyrings to perform envelope encryption. Keyrings generate, encrypt, and decrypt data keys. Keyrings determine the source of the unique data keys that protect each message, and the wrapping keys that encrypt that data key. You specify a keyring when encrypting and the same or a different keyring when decrypting. You can use the keyrings that the SDK provides or write your own compatible custom keyrings.

You can use each keyring individually or combine keyrings into a multi-keyring. Although most keyrings can generate, encrypt, and decrypt data keys, you might create a keyring that performs only one particular operation, such as a keyring that only generates data keys, and use that keyring in combination with others.

We recommend that you use a keyring that protects your wrapping keys and performs cryptographic operations within a secure boundary, such as the AWS KMS keyring, which uses AWS KMS keys that never leave AWS Key Management Service (AWS KMS) unencrypted. You can also write a keyring that uses wrapping keys that are stored in your hardware security modules (HSMs) or protected by other master key services. For details, see the Keyring Interface topic in the AWS Encryption SDK Specification.

Keyrings play the role of master keys and master key providers in the AWS Encryption SDK for Java, AWS Encryption SDK for Python, and the AWS Encryption CLI. If you use different language implementations of the AWS Encryption SDK to encrypt and decrypt your data, be sure to use compatible keyrings and master key providers. For details, see Keyring compatibility.

This topic explains how to use the keyring feature of the AWS Encryption SDK and how to choose a keyring. For examples of creating and using keyrings, see the C and JavaScript topics.