Beacons - AWS Database Encryption SDK
Standard beaconsCompound beacons

Beacons

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

A beacon is a truncated Hash-Based Message Authentication Code (HMAC) tag that creates a map between the plaintext value written to a field and the encrypted value that is actually stored in your database. The beacon does not alter the encrypted state of the field. The beacon calculates an HMAC over the field's plaintext value and stores it alongside the encrypted value. This HMAC output is a one‐to‐one (1:1) match for the plaintext value of that field. The HMAC output is truncated so that multiple, distinct plaintext values map to the same truncated HMAC tag. These false positives limit an unauthorized user's ability to identify distinguishing information about the plaintext value.

Beacons can only be constructed from fields that are marked ENCRYPT_AND_SIGN, SIGN_ONLY, or SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT in your cryptographic actions. The beacon itself is not signed or encrypted. You cannot construct a beacon with fields that are marked DO_NOTHING.

The type of beacon you configure determines the type of queries you are able to perform. There are two types of beacons that support searchable encryption. Standard beacons perform equality searches. Compound beacons combine literal plaintext strings and standard beacons to perform complex database operations. After you configure your beacons, you must configure a secondary index for each beacon before you can search on the encrypted fields. For more information, see Configuring secondary indexes with beacons.

Standard beacons

Standard beacons are the simplest way to implement searchable encryption in your database. They can only perform equality searches for a single encrypted or virtual field. To learn how to configure standard beacons, see Configuring standard beacons.

The field that a standard beacon is constructed from is called the beacon source. It identifies the location of the data that the beacon needs to map. The beacon source can be either an encrypted field or a virtual field. The beacon source in each standard beacon must be unique. You cannot configure two beacons with the same beacon source.

Standard beacons can be used to perform equality searches for an encrypted or virtual field. Or, they can be used to construct compound beacons to perform more complex database operations. To help you organize and manage standard beacons, the AWS Database Encryption SDK provides the following optional beacon styles that define the intended use of a standard beacon. For more information see, Defining beacon styles.

You can create a standard beacon that performs equality searches for a single encrypted field, or you can create a standard beacon that performs equality searches on the concatenation of multiple ENCRYPT_AND_SIGN, SIGN_ONLY, and SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT fields by creating a virtual field.

Virtual fields

A virtual field is a conceptual field constructed from one or more source fields. Creating a virtual field does not write a new field to your record. The virtual field is not explicitly stored in your database. It is used in standard beacon configuration to give the beacon instructions on how to identify a specific segment of a field or concatenate multiple fields within a record to perform a specific query. A virtual field requires at least one encrypted field.

Note

The following example demonstrates the types of transformations and queries you can perform with a virtual field. In application, the example fields used in this example might not meet the distribution and correlation uniqueness recommendations for beacons.

For example, if you want to perform equality searches on the concatenation of FirstName and LastName fields, you might create one of the following virtual fields.

  • A virtual NameTag field, constructed from the first letter of the FirstName field, followed by the LastName field, all in lowercase. This virtual field enables you to query NameTag=mjones.

  • A virtual LastFirst field, which is constructed from the LastName field, followed by the FirstName field. This virtual field enables you to query LastFirst=JonesMary.

Or, if you want to perform equality searches on a specific segment of an encrypted field, create a virtual field that identifies the segment you want to query.

For example, if you want to query an encrypted IPAddress field using the first three segments of the IP address, create the following virtual field.

  • A virtual IPSegment field, constructed from Segments(‘.’, 0, 3). This virtual field enables you to query IPSegment=192.0.2. The query returns all records with an IPAddress value that starts with "192.0.2".

Virtual fields must be unique. Two virtual fields cannot be constructed from the exact same source fields.

For help configuring virtual fields and the beacons that use them, see Creating a virtual field.

Compound beacons

Compound beacons create indexes that improve query performance and enable you to perform more complex database operations. You can use compound beacons to combine literal plaintext strings and standard beacons to perform complex queries on encrypted records, such as querying two different record types from a single index or querying a combination of fields with a sort key. For more compound beacon solution examples, see Choose a beacon type.

Compound beacons can be constructed from standard beacons or a combination of standard beacons and signed fields. They are constructed from a list of parts. All compound beacons should include a list of encrypted parts that identifies the ENCRYPT_AND_SIGN fields included in the beacon. Every ENCRYPT_AND_SIGN field must be identified by a standard beacon. More complex compound beacons might also include a list of signed parts that identifies the plaintext SIGN_ONLY or SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT fields included in the beacon, and a list of constructor parts that identify all of the possible ways the compound beacon can assemble the fields.

Note

The AWS Database Encryption SDK also supports signed beacons that can be configured entirely from plaintext SIGN_ONLY and SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT fields. Signed beacons are a type of compound beacon that index and perform complex queries on signed, but not encrypted, fields. For more information, see Creating signed beacons.

For help configuring compound beacons, see Configuring compound beacons.

The way you configure your compound beacon determines the types of queries it can perform. For example, you can make some encrypted and signed parts optional to allow for more flexibility in your queries. For more information on the types of queries compound beacons can perform, see Querying beacons.