# Beacons
<a name="beacons"></a>


****  

|  | 
| --- |
| Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). | 

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](concepts.md#crypt-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](configure-beacons.md), 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](ddb-searchable-encryption.md#ddb-beacon-indexes).

**Topics**
+ [Standard beacons](#standard-beacon-overview)
+ [Compound beacons](#compound-beacon-overview)

## Standard beacons
<a name="standard-beacon-overview"></a>

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](configure-beacons.md#config-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](configure-beacons.md#define-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.   
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](searchable-encryption.md#searchable-encryption-distribution) and [correlation](searchable-encryption.md#searchable-encryption-correlated-values) 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](configure-beacons.md#create-virtual-field).

## Compound beacons
<a name="compound-beacon-overview"></a>

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](choosing-beacon-type.md).

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](configure-beacons.md#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](configure-beacons.md#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](configure-beacons.md#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](configure.md#signed-beacons).

For help configuring compound beacons, see [Configuring compound beacons](configure-beacons.md#config-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](using-beacons.md#querying-beacons).