How the AWS Database Encryption SDK works - AWS Database Encryption SDK
Encrypt and signDecrypt and verify

How the AWS Database Encryption SDK works

Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the DynamoDB Encryption Client.

The AWS Database Encryption SDK provides client-side encryption libraries that are designed specifically to protect the data that you store in databases. The libraries include secure implementations that you can extend or use unchanged. For more information about defining and using custom components, see the GitHub repository for your database implementation.

The workflows in this section explain how the AWS Database Encryption SDK encrypts and signs and decrypts and verifies the data in your database. These workflows describe the basic process using abstract elements and the default features. For details about how the AWS Database Encryption SDK works with your database implementation, see the What is encrypted topic for your database.

The AWS Database Encryption SDK uses envelope encryption to protect your data. Each record is encrypted under a unique data key. The data key is used to derive a unique data encryption key for each field marked ENCRYPT_AND_SIGN in your cryptographic actions. Then, a copy of data key is encrypted by the wrapping keys you specify. To decrypt the encrypted record, the AWS Database Encryption SDK uses the wrapping keys you specify to decrypt at least one encrypted data key. Then it can decrypt the ciphertext and return a plaintext entry.

For more information about the terms used in the AWS Database Encryption SDK, see AWS Database Encryption SDK concepts.

Encrypt and sign

At its core, the AWS Database Encryption SDK is a record encryptor that encrypts, signs, verifies, and decrypts the records in your database. It takes in information about your records and instructions about which fields to encrypt and sign. It gets the encryption materials, and instructions on how to use them, from a cryptographic materials manager configured from the wrapping key you specify.

The following walkthrough describes how the AWS Database Encryption SDK encrypts and signs your data entries.

  1. The cryptographic materials manager provides the AWS Database Encryption SDK with unique data encryption keys: one plaintext data key, a copy of the data key encrypted by the specified wrapping key, and a MAC key.

    Note

    You can encrypt the data key under multiple wrapping keys. Each of the wrapping keys encrypt a separate copy of the data key. The AWS Database Encryption SDK stores all of the encrypted data keys in the material description. The AWS Database Encryption SDK adds a new field (aws_dbe_head) to the record that stores the material description.

    A MAC key is derived for each encrypted copy of the data key. The MAC keys are not stored in the material description. Instead, the decrypt method uses the wrapping keys to derive the MAC keys again.

  2. The encryption method encrypts each field marked as ENCRYPT_AND_SIGN in the cryptographic actions you specified.

  3. The encryption method derives a commitKey from the data key and uses it to generate a key commitment value, and then discards the data key.

  4. The encryption method adds a material description to the record. The material description contains the encrypted data keys and the other information about the encrypted record. For a complete list of the information included in the material description, see Material description format.

  5. The encryption method uses the MAC keys returned in Step 1 to calculate Hash-Based Message Authentication Code (HMAC) values over the canonicalization of the material description, encryption context, and each field marked ENCRYPT_AND_SIGN, SIGN_ONLY, or SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT in the cryptographic actions. The HMAC values are stored in a new field (aws_dbe_foot) that the encryption method adds to the record.

  6. The encryption method calculates an ECDSA signature over the canonicalization of the material description, encryption context, and each field marked ENCRYPT_AND_SIGN, SIGN_ONLY, or SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT and stores the ECDSA signatures in the aws_dbe_foot field.

    Note

    ECDSA signatures are enabled by default, but are not required.

  7. The encryption method stores the encrypted and signed record in your database

Decrypt and verify

  1. The cryptographic materials manager (CMM) provides the decryption method with the decryption materials stored in the material description, including the plaintext data key and the associated MAC key.

    1. The CMM decrypts the encrypted data key with the wrapping keys in the specified keyring and returns the plaintext data key.

  2. The decryption method compares and verifies the key commitment value in the material description.

  3. The decryption method verifies the signatures in the signature field.

    It identifies which fields are marked ENCRYPT_AND_SIGN, SIGN_ONLY, or SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT from the list of allowed unauthenticated fields that you defined. The decryption method uses the MAC key returned in Step 1 to recalculate and compare HMAC values for the fields marked ENCRYPT_AND_SIGN, SIGN_ONLY, or SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT. Then, it verifies the ECDSA signatures using the public key stored in the encryption context.

  4. The decryption method uses the plaintext data key to decrypt each value marked ENCRYPT_AND_SIGN. The AWS Database Encryption SDK then discards the plaintext data key.

  5. The decryption method returns the plaintext record.