alidkms-go-kms-wrapping

README

AliDKMS Auto-Unseal Plugin

This plugin is tested for Auto-Unseal using Alibaba Cloud DKMS Instance and Key, using AES_GCM method.

Prerequisites

Resources Needed

Before you install it into your OpenBao instance, you need these resources in your alicloud project:

1. AliCloud Dedicated KMS Instance

   To create or purchase your DKMS Instance, refer to this documentation.

2. Alicloud KMS Key, with Generic credential type

   You need to attach KMS Key to the instance. To create KMS Key, refer to this documentation.

3. Application Access Point (AAP) Network Rule and Policy

   Before you can create AAP Credential, you need to create Network Rule and Policy. For network rules, you need to insert your OpenBao IP. Then you need to attach the Network Rule into the Policy you create. For more info, refer to this documentation.

4. AAP Client

   You need to create client that attached to policy above, and write down the password you create. For more info, refer to this documentation

Files Needed

After you created all the resources, you need to save / downloads:

1. DKMS ca.cert

   You can download it in your DKMS page.

   Save it as file: ca.cert

2. AAP Client Secret Key

   You can download it in your AAP page.

   Save it as file: clientKey.json

3. Password you created in AAP Client

   Save it as file: clientPassword.txt

Testing Your Credentials

If you're unsure of your AAP Credentials and DKMS Instance, you can test your credential using our binary provided in this repository release page. You can refer the test configuration file using the sample-test.json file.

After you downloaded the binary, you can copy and change the sample-test.json file and test the credential by using command alidks-go-kms-wrapping -test-file <your-test-file.json>

For example:

alidks-go-kms-wrapping -test-file sample-test.json

How To Install

Kubernetes

If you're using Kubernetes, you can create Init Container that copy the binary from the docker we provided. It's recommended that you use OpenBao Helm for installing it inside Kubernetes. You can follow this documentation on how to install the OpenBao using Helm, and then use next section on how to install this plugin using OpenBao helm.

Helm

For installing using OpenBao Helm, you can follow these steps:

1. Create a secret files named alidkms-credentials inside the openbao namespace, that contains ca.cert, clientKey.json and clientPassword.txt

   For example:

   apiVersion: v1
   kind: Secret
   metadata:
     name: alidkms-credentials
     namespace: openbao
   type: Opaque
   stringData:
     ca.cert: |
         <copy your ca.cert file content into this path. mind the tabbing!>
       clientKey.json: |
         <copy your ca.cert file content into this path. mind the tabbing!>
       clientPassword.txt: "<copy your aap password here>"
   

2. Update your OpenBao helm values, add this line inside the server block:

   server:
     ...
     volumes:
       - name: plugins
         emptyDir: {}
       - name: alidkms-credentials
         secret:
           secretName: alidkms-credentials
     volumeMounts:
       - name: plugins
         mountPath: /opt/openbao/plugins
       - name: alidkms-credentials
         mountPath: /.alidkms
         readOnly: true
     extraInitContainers:
       - name: alidkms-plugin
         image: ghcr.io/durianpay/alidkms-go-kms-wrapping:latest
         command: ["sh", "-c"]
         args:
           - cp /plugins/alidkms-go-kms-wrapping /opt/openbao/plugins/
         volumeMounts:
           - name: plugins
             mountPath: /opt/openbao/plugins
   

3. Update your OpenBao configuration inside helm, please mind your server type block. This example uses ha for the type. Replace the needed configuration variable below.

   ha:
     ...
     config: |
       ...
       plugin_directory = "/opt/openbao/plugins"
   
       plugin "kms" "alidkms" {
         command   = "alidkms-go-kms-wrapping"
         sha256sum = "<refer to release page within the file name extension .sha256sum>"
       }
   
       seal "alidkms" {
         kms_key_id = "<your alicloud dkms key id. ex: key-xxx>"
         region     = "<region of your dkms instance. ex: ap-southeast-5>"
         endpoint   = "<endpoint of your dkms instance. ex: kst-xxxx.cryptoservice.kms.aliyuncs.com"
         ca         = "file:///.alidkms/ca.pem"
         client_key = "file:///.alidkms/clientKey.json"
         password   = "file:///.alidkms/password.txt"
       }
   

4. Install the helm and init your OpenBao instance

   Refer to this documentation for initializing your OpenBao instance.

Compute Instance

For installing using standard Compute Instance, you can follow these steps:

1. Download the binary in release page into OpenBao folder plugin, rename it to alidkms-go-kms-wrapping. If there's no plugins folder yet, you can simply create it. Note that you need to match the download for your instance OS and ARCH.

   For example: /opt/openbao/plugins/alidkms-go-kms-wrapping

2. Change filemod so it can be executed.

   For example: chmod +x /opt/openbao/plugins/alidkms-go-kms-wrapping

3. Copy your ca.cert into your preferred folder.

   For example: /etc/openbao-alidkms/ca.cert

4. Copy your clientKey.json into your preferred folder.

   For example: /etc/openbao-alidkms/clientKey.json

5. Create a txt file that contains your AAP client password.

   For example: /etc/openbao-alidkms/clientPassword.txt

6. Edit your OpenBao configuration file, include this config and replace the needed configuration variable below.

   plugin_directory = "/opt/openbao/plugins"
   
   plugin "kms" "alidkms" {
     command   = "alidkms-go-kms-wrapping"
     sha256sum = "<refer to release page within the file name extension .sha256sum>"
   }
   
   seal "alidkms" {
     kms_key_id = "<your alicloud dkms key id. ex: key-xxx>"
     region     = "<region of your dkms instance. ex: ap-southeast-5>"
     endpoint   = "<endpoint of your dkms instance. ex: kst-xxxx.cryptoservice.kms.aliyuncs.com"
     ca         = "file:///etc/openbao-alidkms/ca.cert"
     client_key = "file:///etc/openbao-alidkms/clientKey.json"
     password   = "file:///etc/openbao-alidkms/clientPassword.txt"
   }
   

7. Run and init your OpenBao instance

   Refer to this documentation for initializing your OpenBao instance.

Migrating to AliDKMS Auto Unseal

For OpenBao Auto-Unseal Migration, you can refer to this documentation.

FAQ

Is this production ready?

Since the code is based on alicloud official plugin in OpenBao repository, we think it's safe to use it in production, as we in DurianPay already used it for our credential sharing for Auto-Unseal. But we haven't test this plugin for seal-wrapping.

Can I use envars instead of file?

Absolutely, you can change the configuration from using file://your-file-path to env://YOUR_ENV_NAME since it's supported by OpenBao itself. But please mind that newline is not handled so well using envar, it is best to convert your ca and client key into one liner.

Why did you create this new repository instead of create a PR on https://github.com/openbao/go-kms-wrapping?

We're unable to create test file needed for this type of seal since it's needing ca.cert and clientKey.json file for testing. But if you think you can create a PR there, feel free to use this code and mention us!

This plugin is not working!

If you have any issues related to the plugin, you can create issue on our github page.