Introduction

To implement Zero-Knowledge Encryption, you must set up a Gateway.
Once you have a Gateway up and running, you will be able to Generate a component called the Customer Fragment. The customer fragment is a unique piece of any encryption key you will create using it that only you have access to, not even the Akeyless team can see it. These Customer Fragments will allow you to create our special type of key called the DFC key, which can only be used by an allowed user on the gateway that holds the corresponding Customer Fragment.

❗️

Warning:

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

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

Generate Customer Fragment from the Akeyless Console

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.

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 secure place.

Generate Customer Fragment from the Akeyless CLI

First, create the following environment variable to point your CLI to interact with the relevant Gateway:

export AKEYLESS_GATEWAY_URL=https://Your_GW_URL:8080

To generate a Customer Fragment, run the following Akeyless CLI command:

akeyless gen-customer-fragment --description MyFirstCF

You'll get the following output:

$ akeyless gen-customer-fragment --description MyFirstCF

WARNING: It is the clients 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"
        }
    ]
}

To download your customer fragments, use the following command:

akeyless gateway-download-customer-fragments -f <path to download to> -u <gateway URL>

🚧

Important

Once you have your customer_fragments.json file saved, you'll need to provide a path to the file containing your Fragment as part of the Gateway installation command each time you want to update 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.

🚧

Important

To use a Customer Fragment to create a DFC encryption key, the user must be on the list of allowed access IDs for the gateway.

Create Zero Knowledge Key from the Akeyless Console:

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.

Create Zero Knowledge Key from the Akeyless CLI:

To generate a key using a Customer Fragment, run the following command:

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

You'll get the following output:

A new RSA2048 key named MyKeyWithMyCF was successfully created

The key can be viewed in the Gateway Console at port 18888:

Set Up a Default Encryption Key

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

🚧

Note:

Only Symmetric encryption keys of AESGCM algorithm can be used as Default Encryption Keys.

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 available encryption keys.

4. Click Save Changes.