Implementing Zero Knowledge

Managing Customer Fragments

Customer Fragments are stored in the customer_fragments.json file inside your stateless akeyless-gw container. Once you re-install the Gateway, all the data that was not saved externally (e.g., on a mounted volume) is lost.

This brings us to the most critical idea in this chapter: you need to back up your Customer Fragments regularly and outside the akeyless-gw container.

❗️

WARNING:

When working with Customer Fragments, it is the client's responsibility to back them up securely and in a safe place.

Encryption keys created with the Customer Fragment cannot be reconstructed without it. Therefore all information that is encrypted with those keys will not be recoverable if the Customer Fragment is lost.

You can create multiple Customer Fragments. Each Customer Fragment will be used to create a separate encryption key, for example, to force privacy segregation among different teams, departments, and organization units.

Generate a Customer Fragment

Working with the Web UI:

To generate a Customer Fragment,

  1. Open the Akeyless Gateway Configuration Manager at http://Your-Akeyless-Gateway-URL:8000.
  2. On the menu bar at the left, click Zero-Knowledge Encryption.
  3. On the Zero-Knowledge Encryption page, click Generate Customer Fragment.
  4. In the pop-up, provide a description of the new Customer Fragment and click Save. You can create as many Customer Fragments as you need.
  5. Click Download to download the file with all the generated Customer Fragments and save it in a safe and secured place.
Created Customer FragmentCreated Customer Fragment

Created Customer Fragment

Working with the CLI:

To generate a Customer Fragment, run the following command in the CLI of your akeyless-gw container:

akeyless gen-customer-fragment --description MyFirstCF

You'll get the following output:

$ akeyless gen-customer-fragment --description MyFirstCF

WARNING: It is the client's responsibility to back up the customer fragment.
Keys that were created with a customer fragment cannot be reconstructed without it and all information that is 
encrypted with them will not be recoverable if the customer fragment is lost.

In order to use the generated customer fragment, it must be saved in /root/.akeyless/customer_fragments.json

The following json contains the newly generated customer fragment:
{
    "customer_fragments": [
        {
            "id": "cf-xyzxyzxyzxyzxyzxyz",
            "value": "SomE/CUstOmer/FrAGMenTvALue==",
            "description": "MyFirstCF"
        }
    ]
}

Now that you have the Customer Fragment generated, you need to save it to the customer_fragments.json file. Open the file in the VI editor, paste there the code block with the customer fragment, save the changes, and exit.

vi /root/.akeyless/customer_fragments.json

Check if the content of the customer_fragments.json file looks good:

cat /root/.akeyless/customer_fragments.json
{
    "customer_fragments": [
        {
            "id": "cf-xyzxyzxyzxyzxyzxyz",
            "value": "SomE/CUstOmer/FrAGMenTvALue==",
            "description": "MyFirstCF"
        }
    ]
}

Don't forget to copy the updated file to the host for backup:

docker cp akeyless-gw:/root/.akeyless/customer_fragments.json /host/path/target/

To see the updated contents of the customer_fragments.json file in the Web UI of the Akeyless Gateway Configuration Manager and to start working with the CLI-generated Customer Fragments, you need to restart the Gateway.

docker restart akeyless-gw

🚧

IMPORTANT

Once you have your customer_fragments.json file saved externally, you'll need to provide a path to it in the Gateway installation command each time you want to re-install your Gateway instance.

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 5696:5696 -v /host/path/target/customer_fragments.json:/root/.akeyless/customer_fragments.json -e ADMIN_ACCESS_ID="identity-access-id" -e ADMIN_ACCESS_KEY="identity-access-key" --name akeyless-gw akeyless/base"

Create a DFC Encryption Key

With the Customer Fragment at hand, you can create DFC encryption keys.

Working with the Web UI:

To create a DFC Encryption Key,

  1. Open the Akeyless Gateway Console at http://Your-Akeyless-Gateway-URL:18888.
  2. On the menu bar at the left, click Secrets & Keys.
  3. On the Secrets & Keys page, click New -> Encryption Key -> DFC.
  4. In the pop-up, specify the parameters of the new key and select a Customer Fragment to be used with this key.
  5. Click Save.

Working with the CLI:

🚧

IMPORTANT

Before you start creating the keys from the CLI, you need to configure the Akeyless CLI Profile.

To generate a key using a Customer Fragment, run the following command in the CLI of your akeyless-gw container:

akeyless create-key -n MyKeyWithMyCF -a RSA2048 -f customer-fragment-id

You'll get the following output:

akeyless create-key -n MyKeyWithMyCF -a RSA2048 -f cf-xyzxyzxyzxyzxyzxyz 
=====================
Encryption Key Fragment #0 created successfully in 1.451µs milliseconds
Encryption Key Fragment #1 created successfully in 1.452µs milliseconds
=====================
A new RSA2048 key named MyKeyWithMyCF was successfully created

The key can be viewed in the Gateway Console.

DFC key in the ConsoleDFC key in the Console

DFC key in the Console

Set Up a Default Encryption Key

We recommend creating a Default Encryption Key based on your Customer Fragment to enforce Zero-Knowledge by default for all your secrets. This will ensure that any item created with Akeyless (via Web UI, CLI, or SDKs) will be encrypted using your encryption key.

🚧

IMPORTANT

Only AES-GCM encryption keys generated using a Customer Fragment can be used as Default Encryption Keys in the Akeyless solution.

To set up a Default Encryption Key,

  1. Open the Akeyless Gateway Configuration Manager at http://Your-Akeyless-Gateway-URL:8000.
  2. On the menu bar at the left, click Defaults.
  3. In the Default Encryption Key drop-down list, select one of the previously created AES-GCM encryption keys.
  4. Click Save Changes.
Default Encryption KeyDefault Encryption Key

Default Encryption Key


Did this page help you?