Registering a buckypaper plugin

Learn how to register a buckypaper plugin in a vHSM server.

The Buckypaper plugin is a secrets engine that provides a secure and efficient way to manage cryptographic keys within vHSM .

Prerequisites

• Install Docker

• Set the environment variable for ENCLAIVE_LICENCE

• Download the vHSM docker image

• Download the vHSM CLl

To register a buckypaper plugin in a Docker container running vHSM:

1. Get the SHA of the plugin using: docker run --rm -it --entrypoint sha256sum harbor.enclaive.cloud/vhsm/vhsm:latest /vault/plugins/vault-plugin-secrets-buckypaper

2. Create a config.json file that provides the path for the plugins directory.

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

api_addr = "http://0.0.0.0:8200"
plugin_directory = "/vault/plugins"
disable_mlock = true

storage "file" {
  path = "/vault/data"
}

1. Start the vHSM server with the configuration parameters that you defined in the config.json file.

docker run --rm -it \
  -v ./config.json:/config.json \
  -p 8200:8200 \
  -e ENCLAIVE_LICENCE=$ENCLAIVE_LICENCE \
  harbor.enclaive.cloud/vhsm/vhsm:latest \
  server -config=/config.json

The output is similar to:

No usage registration configured for this binary.
==> vHSM server configuration:

Administrative Namespace: 
             Api Address: http://0.0.0.0:8200
                     Cgo: enabled
         Cluster Address: https://0.0.0.0:8201
   Environment Variables: ENCLAIVE_LICENCE, GODEBUG, HOME, HOSTNAME, NAME, PATH, PWD, SHLVL, TERM
              Go Version: go1.23.7
              Listener 1: tcp (addr: "0.0.0.0:8200", cluster address: "0.0.0.0:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled")
               Log Level: 
                   Mlock: supported: true, enabled: false
           Recovery Mode: false
                 Storage: file
                 Version: Vhsm v1.4.2-1 heads/feature/update-0-g251e70f 2025-04-01T12:51:26+00:00, built 2025-04-01T14:49:46Z
             Version Sha: 251e70fd90b75d4c66b89584a1cc8a61db79182e+CHANGES

==> vHSM server started! Log data will stream in below:

2025-04-02T06:08:14.213Z [INFO]  proxy environment: http_proxy="" https_proxy="" no_proxy=""
2025-04-02T06:08:14.214Z [INFO]  core: Initializing version history cache for core
Attempting auto-setup with enclaive tooling
Processed all sealed shards
2025-04-02T06:09:54.051Z [INFO]  core: security barrier not initialized
2025-04-02T06:09:54.051Z [INFO]  core: seal configuration missing, not initialized
2025-04-02T06:10:26.061Z [INFO]  core: security barrier not initialized

Note: Verify the status of the vhsm server and initialize it or unseal if necessary.

1. In a different terminal, set the environment variable as export VAULT_ADDR='http://127.0.0.1:8200' and login using the root token for the vHSM server.

2. In the following command ensure that you replace the SHA digest with the one that you made note after downloading the plugin binary to register the plugin.

vhsm plugin register -sha256=<sha-digest> secret vault-plugin-secrets-buckypaper

The output is:

Success! Registered plugin: vault-plugin-secrets-buckypaper

1. Verify that the plugin is listed in the vHSM server using the command: vhsm plugin list .

2. Enable the buckypaper secret engine using the command: vhsm secrets enable buckypaper

3. Verify that it is listed under secrets, using the command: vhsm secrets list

The output is:

Path           Type                               Accessor                                    Description
----           ----                               --------                                    -----------
buckypaper/    vault-plugin-secrets-buckypaper    vault-plugin-secrets-buckypaper_7e973220    n/a
cubbyhole/     cubbyhole                          cubbyhole_5769dce0                          per-token private secret storage
identity/      identity                           identity_6eafac39                           identity store
sys/           system                             system_1b5a77e2                             system endpoints used for control, policy and debugging

The Buckypaper plugin is a secrets engine that provides a secure and efficient way to manage cryptographic keys within vHSM . By default, this plugin is enabled in vault.enclaive.cloud, allowing you to generate, store, and manage cryptographic keys seamlessly. For more information about using this secrets engine to pass root admin password, see Provisioning MariaDB Password on Azure DCXas_v5 VM.