Getting started

Defining a dataset and client

A dataset holds configuration for one or more database tables that contain data to be encrypted. A client allows an application to programmatically access a dataset. A dataset can have many clients (for example, different applications working with the same data), but a client belongs to exactly one dataset.

Ensure that you have completed the previous step before continuing as we assume you have all the prerequisites installed and configured.

Defining a dataset

We will use the CipherStash CLI to define a dataset that will be used to encrypt and decrypt data. The dataset will define which database columns should be encrypted and how the data should be indexed. Ensure you are logged in to the CipherStash CLI before continuing.

1stash login
2

Create a dataset

Next, we need to create a dataset for tracking what data needs to be encrypted. To create our first dataset run the following command:

1stash datasets create users --description "Data about our users"
2

The output will look like this:

1Dataset created:
2ID         : <a UUID style ID>
3Name       : users
4Description: Data about our users
5

Note down the dataset ID, as you'll need it in the next step. You can also set a local environment variable to make it easier to use the dataset ID in the next step:

1export CS_DATASET_ID=<your dataset ID>
2

Create a client

Clients are used to authenticate with the CipherStash API. We will use a client key to authenticate with the CipherStash API when we deploy Tandem. To create a client, use the dataset ID from Create a dataset to create a client (making sure you substitute your own dataset ID, if you didn't set the environment variable):

1stash clients create --dataset-id $CS_DATASET_ID "Tandem example application"
2

The output will look like this:

1Client created:
2Client ID  : <a UUID style ID>
3Name       : Tandem example application
4Description:
5Dataset ID : <your provided dataset ID>
6
7#################################################
8#                                               #
9#  Copy and store these credentials securely.   #
10#                                               #
11#  THIS IS THE LAST TIME YOU WILL SEE THE KEY.  #
12#                                               #
13#################################################
14
15Client ID          : <a UUID style ID>
16
17Client Key [hex]   : <a long hex string>
18

Note down the client key somewhere safe, like a password vault. You can also set local environment variables to make it easier to use the key info in the next steps:

1export CS_CLIENT_ID=<your client ID>
2export CS_CLIENT_KEY=<your client key>
3

Uploading the dataset configuration

A dataset is a collection of tables and fields that you want to encrypt. For the example application, we only have a single user table with three fields: id, name, and email. We want to encrypt the name and email fields. The example application has an existing dataset defined in the config directory. Open the config/dataset.yml file and you'll see the following:

1tables:
2  - path: users
3    fields:
4      - name: name
5        in_place: false
6        cast_type: utf8-str
7        mode: plaintext-duplicate
8        indexes:
9          - version: 1
10            kind: match
11            tokenizer:
12              kind: ngram
13              token_length: 3
14            token_filters:
15              - kind: downcase
16            k: 6
17            m: 2048
18            include_original: true
19          - version: 1
20            kind: ore
21          - version: 1
22            kind: unique
23      - name: email
24        in_place: false
25        cast_type: utf8-str
26        mode: plaintext
27        indexes:
28          - version: 1
29            kind: match
30            tokenizer:
31              kind: ngram
32              token_length: 3
33            token_filters:
34              - kind: downcase
35            k: 6
36            m: 2048
37            include_original: true
38          - version: 1
39            kind: ore
40          - version: 1
41            kind: unique
42

You can view the full list of configuration options and descriptions in the reference section.

If you want assistance defining a dataset for your application, please use our book a demo page to connect with one of our Solutions Engineers.

Uploading the dataset to CipherStash

Now that we have a dataset configuration, we need to upload it to CipherStash. We will use the CipherStash CLI to upload the dataset configuration. Run the following command to upload the dataset configuration and replace $CS_CLIENT_ID and $CS_CLIENT_KEY with the client ID and client key from Create a client if you didn't set the environment variables:

1stash datasets config upload --file config/dataset.yml --client-id $CS_CLIENT_ID --client-key $CS_CLIENT_KEY
2

Now that we have a dataset defined, we can deploy Tandem to our application.

Previous
Step 1 - Getting set up