Azure KeyVault

Warning: this guide is not completed yet and under active development. Azure KeyVault is not officially, yet.

This guide shows how to setup a KES server that uses Azure KeyVault as a persistent key store:

1. Azure KeyVault Configuration
2. KES Server Setup

                         ╔══════════════════════════════════════════════╗
┌────────────┐           ║  ┌────────────┐          ┌────────────────┐  ║
│ KES Client ├───────────╫──┤ KES Server ├──────────┤ Azure KeyVault │  ║
└────────────┘           ║  └────────────┘          └────────────────┘  ║
                         ╚══════════════════════════════════════════════╝

---

Azure KeyVault

Azure KeyVault is a managed KMS that provides a secret store that can be used by KES.

An external application, i.e. KES, that wants to store and access secrets in Azure KeyVault, has to be registered in Azure Active Directory and needs client credentials.

1. Active Directory Service

First navigate to your Active Directory service:

2. App registration

Then go to App registrations and register a new application for KES:

Now, you can give the application a name - e.g. KES-Demo and register it. Once completed, Azure will show you some details about your newly registered application.

Some important fields are:

• The application or client ID
• The directory or tenant ID
• The client credentials

The application directory ID will be UUIDs - like c3b7badf-cd2b-4297-bece-4de5f2e575f6. However, there should be no client credentials, yet. So, we need to create a client secret for your KES server.

3. Create client secret

Here we select a client secret that we can give a name - e.g. KES-Demo - and select an expiry - e.g. 12 months:

Once completed, Azure will should a new secret with the chosen description and expiry. Make sure to copy the secret value. It may not be shown to you again. This secret value will be required later by KES to authenticate to Azure KeyVault.

After navigating back to the application overview, Azure will show that the application now has one secret.

At this point you should have the following information about your Azure application:

• The application / client ID
• The directory / tenant ID
• The value of the newly created secret.

---

Now, we have to configure Azure KeyVault to configure which KeyVault API operations our external application, i.e. KES, can perform.

4. Add a new KeyVault policy

First, navigate to the Access policies tab of your KeyVault instance and add a new access policy:

Here you specify which KeyVault API your application, i.e. KES, has access to. Select the following five Secret permissions:

Finally, you have to select a principal or a principal and an authorized application. The principal can either be the application itself - then no authorized application has to be selected. Alternatively, you can select a user or group as principal and select our newly registered KES Azure application as authorized application. Here, we just set the principal. Therefore, just search for the name you have chosen for your application before, e.g. KES-Demo, or insert the application UUID.

Once added, Azure should show you a new access policy associated to your registered KES application. Make sure you hit Save before navigating elsewhere..

Now, we are ready to setup a KES server and connect it to our Azure KeyVault instance.

---

KES Server setup

First, we need to generate a TLS private key and certificate for our KES server. A KES server can only be run with TLS - since secure-by-default. Here we use self-signed certificates for simplicity. For a production setup we highly recommend to use a certificate signed by CA (e.g. your internal CA or a public CA like Let's Encrypt)

1. Generate a TLS private key and certificate for the KES server.
   The following command will generate a new TLS private key server.key and a X.509 certificate server.cert that is self-signed and issued for the IP 127.0.0.1 and DNS name localhost (as SAN). You may want to customize the command to match your setup.

   kes tool identity new --server --key server.key --cert server.cert --ip "127.0.0.1" --dns localhost

   Any other tooling for X.509 certificate generation works as well. For example, you could use openssl:

   $ openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key
   
   $ openssl req -new -x509 -days 30 -key server.key -out server.cert \
      -subj "/C=/ST=/L=/O=/CN=localhost" -addext "subjectAltName = IP:127.0.0.1"
   

2. Then, create private key and certificate for your application:

   kes tool identity new --key=app.key --cert=app.cert app

   You can compute the app identity via:

   kes tool identity of app.cert

3. Now, we have defined all entities in our demo setup. Let's wire everything together by creating the config file server-config.yml:

   address: 0.0.0.0:7373
   root:    disabled  # We disable the root identity since we don't need it in this guide 
   
   tls:
     key : server.key
     cert: server.cert
   
   policy:
     my-app:
       allow:
       - /v1/key/create/my-app*
       - /v1/key/generate/my-app*
       - /v1/key/decrypt/my-app*
       identities:
       - ${APP_IDENTITY}
   
   keystore:
     azure:
       keyvault:
         endpoint: "https://kes-test-1.vault.azure.net"    # Use your KeyVault instance endpoint.
         credentials:
           tenant_id: "<your-tenant-ID>"          # The ID of the tenant the client belongs to - i.e. a UUID.
           client_id: "<your-client-ID>"          # The ID of the client - i.e. a UUID.
           client_secret: "<your-client-secret>"  # The value of the client secret.

   Please use your endpoint and access credentials

4. Finally we can start a KES server in a new window/tab:

   export APP_IDENTITY=$(kes tool identity of app.cert)
   
   kes server --config=server-config.yml --auth=off

   --auth=off is required since our root.cert and app.cert certificates are self-signed

5. In the previous window/tab we now can connect to the server by:

   export KES_CLIENT_CERT=app.cert
   export KES_CLIENT_KEY=app.key
   kes key create -k my-app-key

   -k is required because we use self-signed certificates

6. Finally, we can derive and decrypt data keys from the previously created my-app-key:

   kes key derive -k my-app-key
   {
     plaintext : ...
     ciphertext: ...
   }

   kes key decrypt -k my-app-key <base64-ciphertext>