DEV Community: Sebastian

Turning the Raspberry Pi Zero into a Hacking Gadget

Sebastian — Thu, 16 Apr 2026 04:49:02 +0000

Single Board Computers with the ability to run a full-fledged Linux distribution can be used as portable devices for a wide variety of use cases. To my surprise, one of them is computer hacking. I was astonished about the creativity and ease-of-use how a Raspberry Pi, Raspberry Pi Zero or Pico can be used for potentially nefarious activities. And after a long deliberation, I decided to start writing blog posts about this subject.

The article completely covers the installation, setup, and configuration to convert a Raspberry Pi Zero into a portable hacking device. Once powered, the device will start a custom WiFi endpoint and can be connected to via SSH or HTTP. It offers a CLI and a full-fledged GUI to configure the device behavior when connected to USB. And it can run shell or a custom JavaScript compatible language to initiate keyboard stokes, move the mouse, and access files of the device it is connected too. You will also learn how to combine triggers, startup templates, and HID script for an entry level exploit: When connected via USB to a host system, a text editor will be opened and a message written into it.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The initial idea for this topic was sparked by an excellent article in the German computer magazine CT 2023/27 titled "Bad USB: Raspi Zero". The articles itself cannot be accessed, but only its link collection is available on the public internet.

This article originally appeared at my blog admantium.com.

Writing about Hacking?

For a long time, I have been thinking about the aspect of writing about hacking. My specific concern is about how knowledge in this area, the concrete concepts and processes, can be used for nefarious activities. On the other hand, knowledge gathered by first-hand experience, and transparent communication about it, can raise the awareness about essential dangers. Ultimately, this is tied to the question of knowledge itself: For which purpose do you use it?

Physical hacking is the process of connecting an external device to a target computer and starting an exploit. The goals of hacking are manifold, starting from recording interactions that happen at the computer, reading and copying computer files or the computer memory, running user interactions like keystrokes or mouse movements, executing scripts to modify the system or install new applications. An exploit is the concrete process to achieve a goal, and it can be a combination of intended computer behavior (e.g. registering a USB device) with known or new vulnerabilities in a computer system.

I'm no security consultant, but working in IT, I'm exposed to security topics on a daily basis. Bridging the gap from theoretical knowledge to hands-on experiences while further exploring the amazing Raspberry Pi use cases provided the final nudge to start this blog series. And with this realization, I also feel the need to formulate a disclaimer: This blog content is presented as-is for educational purposes. Only use them on computer systems that you own, and be aware that you can damage the systems.

Finally, bear in mind that explored concepts in this article are written from a beginner’s mind.

Hardware Requirements and Assembly

The required hardware for this article is as follows:

Raspberry Pi Zero W (specifically not a Pi Zero W)
USB Dongle (for example the EP-0097)

The USB dongle needs to be assembled to turn the Zero into a USB hacking device. The particular dongle that I acquired did not include a construction manual, but its components seemed manageable.

However, trying to assemble it manually surfaced an embarrassing knowledge gap. Specifically, I thought that the connection pins of the USB dongle need to be connected to the Zeros GPI pins. But no, right next to the Zeros USB ports, external circuit "touchpoints" are exposed - the dongle pins merely need to touch them too.

To assemble the USB dongle correctly, follow these steps:

Remove the protection layer from the acryl board
Put the thinner acryl board to the bottom
Put the dongle board on top so that the backside of the extruding pins aligns
Put the thicker acryl board on top, aligning with the pins outward facing direction
Put the RPI Zero with the bottom side down and align the connector pins with the touchpoints
Carefully tighten the screws

The resulting device should look like this:

Software Installation & First Boot

To turn the RPI Zero into a hacking device, the Linux Distribution P4wnP1 ALOA - called PPA from here - will be used. This is a custom Linux distribution, build on top of Kali Linux and specifically modified to run on the RPI Zero. As any other OS, the installation encompasses downloading the image, flashing it onto a SD Card, and booting the device.

The specific steps in detail:

Go to the P4wnP1 ALOA release page and download the latest version (Note: Don't be discouraged by the release date of February 2020 - the project works very well!)
Open an image software of your choice, then flash the image (my recommendation is Balena Etcher)

After this, put the SD Card into the device, and power it via the USB mini port.

Shortly after booting, PPA creates a custom WiFi with an awkward, UTF8 icon encoded named: "💥 🖥️ 💥". Connect to it with the password MaMe82-P4wnP1, and once the connection is established, you start exploring the many configuration options.

Tool Overview

PPA is a special Linux distribution with flexible and run-time configurable hardware features of the Raspberry Pi Zero. It provides access to this configuration both via the Web GUI and a CLI. After reading the projects extensive documentation and using the tool for some time, the Web GUI provides more features and will be used exclusively in the remainder of this article.

With an active connection to the hotspot, open http://172.24.0.1:8000 in a browser to access the configuration screen:

Each section in this GUI is a configurable building block of the complete functionality. By learning one section at a time, the overall number of available features becomes clearer.

Hardware Settings

Most sections in the tool menu directly modify the hardware features.

USB: In this section, you define the USB properties when the Zero is connected to the targets. Available options start with the ID, serial number and vendor name, and continue with which USB functions the device offers. It can serve as an ethernet adapter, an HID device (keyboard, mouse, custom HID like pointer), as a serial interface, and as USB storage.
WiFi: You can enable or disable the WiFi, change its SSID and PSK, and define its channel and visibility.
Bluetooth: The Bluetooth stack provides several configuration options. The basic ones: availability, discoverability, and connectivity. Furthermore, you can configure if other devices are pairable with/without a key. BLE and Blue Toot High Speed are also supported. Lastly, different Bluetooth network encapsulation protocol services are provided: Network Access Point, Portable Area Network, and Group Ad-hoc network.
Network: In this category, you can configure the concrete network interface settings for the bteth, usbeth and wlan0. For an DHCP server, the IPv4 gateway address, client addresses and netmask, and static hosts. Alternatively, you can also configure interfaces with just static addresses or as clients.

Behavior Programming

To create and manage scripts that are executed when the USB stick is connected to a host, you can use the following:

Trigger Actions: A combination of an event and a concrete action. For an event, several options exist: system checkpoints during startup (Wifi AP, core services), when an USB gadget connects or disconnects, when an external WiFi AP is joined, values on group channel, and even when a GPIO input is detection. The actions can be to write a log entry, send a value to a group channel, set an output to a GPIO, as well as starting a HID script or bash script. Each trigger action can be set to run only and exactly once, or continuously every time it occurs.
HID Script: The heart of exploitation scripting. PPA provides a JavaScript compatible language to program complex behavior that runs on the target machines. As provided in the documentation, special attention was given to robust and OS-agnostic keyboard interactions, including keyboard layout, timing of keystrokes, and waiting for keyboard input. Also, the mouse cursor can be controlled, and combining it with the concrete physical dimensions of the target screen, pixel perfect controls can be achieved. Finally, all JavaScript concepts can be used, giving access to functions, loops, complex conditions and much more.

Log and Settings

Two more sections complete the configurability of the PPA device.

Event Log: Shows all on-device stored log messages that PPA created during its usage. Messages are retained and persisted between boots, giving a complete picture how and when it was used.
Generic Settings: The very last menu item appears a bit misleadingly named - it does not control the overall GUI, but the concrete run- and boot time behavior of PPA. Essentially, the Master Template Editor allows you to select and combine any defined USB, WiFi, Bluetooth, and Network setting, as well as the Trigger actions. With this, you specify the concrete behavior of the PPA, essentially arming the device for its intend purpose. The other options are to restart or shutdown the system, and to create or restore a backup of all user-define settings and modifications.

Writing and activating an HID Exploit

The feature of PPA is extensive, and for a beginner exploring the device features, it might seem daunting to find a good start point. Following the project documentation closely, let’s start with a script that opens a text editor on the host and writes a message. The target OS is Linux Ubuntu.

In the GUI, open the HID Script tab. The editor features syntax highlighting and remote execution for testing purposes. Paste the following code into the editor:

layout('de');   // US keyboard layout
typingSpeed(100,150) // Wait 100ms between key strokes + an additional random value between 0ms and 150ms (natural)

//waitLED(ANY_OR_NONE);  // Wait till NUM LED of target changes frequently multiple times (doesn't work on OSX)

delay(5000);
press("CTRL ALT t");
delay(1000);
type("gedit\n")
delay(1000);
type("Hello from Raspberry Pi Zero");

As you see, the commands relate directly to executing keystrokes on the target machines, enriched by meta-arguments to influence the typing process. The function layout sets the target keyboard, and the delay function defines a random time range for each keystroke, making interactions more natural. With waitForLed, a specific trigger can be added, deferring the script execution until keyboard interaction is detected. This prevents executing the script when e.g. the screen is still locked by the user.

Now, to run this script, two options exist. If you connected the Raspberry Zero directly to a host system, you could click on "Run". The other option is to actually program this script to be executed when the Raspberry Zero is connected to a computer. For this:

Click on "Store" and define a suitable name for the script.
Select the tab "Trigger Action" and click on "Add one"
In the dialog, activate the "Enabled" slider, then fill out the trigger "USB gadget connected to host", and in the action field the option "start a HID script" as well as the given script name file (also see the next picture)

The final step is to store and activate this trigger definition:

Still on the "Trigger Action" tab, click on "Store" to save all active triggers as a configuration
Go to on "Generic Settings", and in the "Master Template Editor", select the Trigger Action template that you just stored

That’s it. Now you can connect the stick to a Linux host computer and see the script happening.

Where to Continue

Exploring the depth of HID script to write advanced exploits is not the focus of this article. However, I explored some ideas and give my summary here:

P4wnP1: The ancestor project. It includes links to videos and presentations showing particular exploits.
pwnhyve: Naming itself as a sibling project, it focuses on bad USB capabilities and the injection of shellcode into target computers.
pi_zero2w Another developer forked the project and created a version that runs on a Raspberry Pi Zero 2 W, but it with fewer Kali Linux tools and no Bluetooth support
Explore HID Script language: Unfortunately, there is no written document of the language, and digging into the project source code did not reveal an approachable form to me. Considering related rubber duck scripts, the general attack vector is to use HID commands to deploy a base64 decoded scripts for the shell language of the target system (PowerShell for Windows, Bash for Linux), which is then executed to install additional malware or a backdoor.
HID Script collection: This repository is the only other source of examples. It contains script that target Windows Systems to steal credentials and password and provides examples both in HID and in Rubber Duck script.

Conclusion

Small form-size single board computer can be used as hacking gadgets. This article showed how to turn a Raspberry Pi Zero into a bad USB device, a specific form of physical hacking in which an inserted USB stick executes command on the host. You only need a Raspberry Pi Zero, an USB dongle to expose the Zeros USB ports, and the PPA Linux Image. Once the initial setup is completed, the Zero turns into a WiFi and SSH accessible device with complex configuration options for all hardware features. To write a bad USB exploit, the HID language, based on JavaScript, can be used to instruct a sequence of keystrokes. This article showed only a simple exploit: Opening the systems text editor to write a message. Yet the potential for serious exploits becomes visible: By executing shell scripts on the targets, access to the system can be achieved, stealing credentials or installing malware and backdoors.

Hashicorp Vault CLI Part 9: Managing Encryption Keys

Sebastian — Mon, 06 Apr 2026 05:09:16 +0000

Hashicorp Vault provides many features, and the secure storage of encrypted data and secrets is at its heart. Secrets engines are dedicated plugins that govern this storage. They can be grouped into builtin, application and services, cloud, and encryption keys. While all secret engines provide a REST API for interaction, some Vault builtin engines also have dedicated CLI commands.

In this article, all CLI commands for managing or using keys are explored. These commands target the transform, transit, pki and ssh secrets engines. To further the understanding of applying these commands, examples in the context of a local, three server Vault cluster will be shown.

The technical context of this article is hashicorp_vault_v1.21.1, released 2025-11-18. All provided information and command examples should be valid with newer versions too, baring an update of the CLI commands' syntax.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups and commands marked with a checkmark were covered in an earlier article, and commands marked with an at sign are the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
✅ Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
✅ Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
Authentication
- ✅ auth: Interact with configured authentication options
- ✅ login: Authenticates access to a Vault server
Secrets Management
- ✅ secrets: General configuration of secret engines
- ✅ kv: Access to the essential key-value store
- 🌀 transform: Interact with the transform secrets engine
- 🌀 transit: Interact with the Vaults transit secrets engine
- 🌀 unwrap: One-time access to arbitrary encrypted data
- 🌀 pki: Access the private key infrastructure secrets engine
- 🌀 ssh: Initiates SSH sessions via the SSH secrets engine

General Purpose Encryption Key Commands

`transform`

The transform command allows to import a self-managed key for the purpose of defining a new generic or a special format preserving encryption tokenizer.

Alas, the transform secret engine is a Vault enterprise feature. A try to mount the secret engine merely results in an error.

> vault secrets enable transform

# Log messages
Error enabling: Error making API request.

URL: POST http://127.0.0.1:8210/v1/sys/mounts/transform
Code: 400. Errors:

* plugin not found in the catalog: transform

# Log messages
Retrieving wrapping key.
failed to fetch wrapping key: no mount found at transform: <nil>

`transit`

Normally, secret data is stored in Vault, but the transit engine instead encrypts or decrypts provided data without keeping a record of it. Therefore, it can be considered encryption-as-a-service.

The transit command allows to import external, self-managed keys with the import or import-version subcommands. Here is a full example, starting with the secret engines’ activation, key generation, and key import.

# Activate the transit secret engine
> vault secrets enable transit

# Generate the key in DER format, then encode in base64
> openssl genpkey -algorithm ed25519 -outform DER -out ed25519.key.der 
> cat ed25519.key.der| base64 > ed25519.key.b64

# Import the key
> vault transit import transit/keys/ed25519 @ed25519.key.b64 type="ed25519-2048" derived=true

# Log messages
Retrieving wrapping key.
Wrapping source key with ephemeral key.
Encrypting ephemeral key with wrapping key.
Submitting wrapped key.
Success!

# Check the key
> vault read transit/keys/rsa

# Log messages
Key                            Value
---                            -----
allow_plaintext_backup         false
auto_rotate_period             0s
convergent_encryption          false
deletion_allowed               false
derived                        true
exportable                     false
imported_key                   true
imported_key_allow_rotation    false
kdf                            hkdf_sha256
keys                           map[1:map[certificate_chain: creation_time:2025-12-23T08:18:13.700025+01:00 hybrid_public_key: name:ed25519 public_key:]]
latest_version                 1
min_available_version          0
min_decryption_version         1
min_encryption_version         0
name                           ed25519
supports_decryption            false
supports_derivation            true
supports_encryption            false
supports_signing               true
type                           ed25519

`unwrap`

The conventional workflow to access secrets in Hashicorp Vault is that a user or system authorizes, retrieves a token, and accesses end points to which the policies associated with the issued token provide sufficient access rights. However, in some situations, it might not be desirable to allow access for a prolonged period of time, or it is required to access a stored secret only once. For these situations, Vault provides a feature called response wrapping. The original returned data is encrypted and stored in a cubbyhole secret, and a token to decrypt this secret is returned instead. To retrieve this secret, the unwrap function can be used.

The following example shows how to create a secret in a KV store, then wrapping the secret access, and then to unwrap it.

> vault secrets enable --version=2

# Log messages
Success! Enabled the kv secrets engine at: kv/

> vault kv put kv/data/config-db admin=0ab84480a1efb802c1bd2 

# Log messages
===== Secret Path =====
kv/data/data/config-db

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-15T08:48:25.820085Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

> vault kv get -wrap-ttl=1m kv/data/config-db

# Log messages
Key                              Value
---                              -----
wrapping_token:                  hvs.CAESIKQIDe0zG0kMxKAMQVtk5n6dkt6FJ-1BOgkybvh1sddvGh4KHGh2cy43NTJGdG0xd1pqRkpMVnA2VExOS1ZWb00
wrapping_accessor:               B5rcG14qOl1y0SXUmpnr6J1n
wrapping_token_ttl:              1m
wrapping_token_creation_time:    2025-12-15 09:50:02.085264 +0100 CET
wrapping_token_creation_path:    kv/data/data/config-db

> vault unwrap hvs.CAESIKQIDe0zG0kMxKAMQVtk5n6dkt6FJ-1BOgkybvh1sddvGh4KHGh2cy43NTJGdG0xd1pqRkpMVnA2VExOS1ZWb00

# Log messages
Key         Value
---         -----
data        map[admin:0ab84480a1efb802c1bd2]
metadata    map[created_time:2025-12-15T08:48:25.820085Z custom_metadata:<nil> deletion_time: destroyed:false version:1]

Encryption Key Management

The pki secrets engine allows Vault to become an automated certificate issuer. Covering the complete lifecycle, from CSR to CER and revocation, external systems can get certificates as required.

With the vault pki command, several subcommands for certificate issuing and revocation are offered. Internally, they will perform a sequence of CRUD operations, reading from and writing to several endpoints. To operate the engine with its full functionality, the general CRUD methods need to be used, which were covered in my earlier article Plugin Management and General CRUD Operations.

To cover the certificate creation process from root to intermediate, the Vault documentation suggests to use multiple pki engines at different mount points. Following commands create the required example context:

> vault secrets enable pki

> vault write -field=certificate pki/root/generate/internal common_name=admantium.com exported=internal > root_ca.cer

> vault write pki/config/urls \
  issuing_certificates="$VAULT_ADDR/v1/pki/ca" \
  crl_distribution_points="$VAULT_ADDR/v1/pki/crl"

> vault secrets enable -path=pki_intermediate pki

`vault pki health-check`

With this command, a complete introspection to all endpoints of the PKI engine is provided. Its output checks aspects such as certificate validity, configuration for the external ACME issuer service, and more.

> vault pki health-check pki/

# Log messages
ca_validity_period
------------------
status      endpoint                                            message
------      --------                                            -------
critical    /pki/issuer/1cc848d5-b781-d4d3-2ab7-893d5e31f3ce    Issuer's validity is outside of the suggested rotation window: issuer is valid until 2026-01-25 but expires within 6mo (ending on 2026-06-22). It is suggested to start rotating this issuer to new key material to avoid future downtime caused by this current issuer expiring.


crl_validity_period
-------------------
status    endpoint                                                      message
------    --------                                                      -------
ok        /pki/issuer/1cc848d5-b781-d4d3-2ab7-893d5e31f3ce/crl          CRL's validity (2025-12-24 to 2025-12-27) is OK.
ok        /pki/issuer/1cc848d5-b781-d4d3-2ab7-893d5e31f3ce/crl/delta    Delta CRL's validity (2025-12-24 to 2025-12-27) is OK.


root_issued_leaves
------------------
status    endpoint      message
------    --------      -------
ok        /pki/certs    Root certificate(s) in this mount have not directly issued non-CA leaf certificates.


role_allows_localhost
---------------------
status    endpoint    message
------    --------    -------


role_allows_glob_wildcards
--------------------------
status    endpoint    message
------    --------    -------


role_no_store_false
-------------------
status    endpoint    message
------    --------    -------


audit_visibility
----------------
status           endpoint                message
------           --------                -------
informational    /sys/mounts/pki/tune    Mount currently HMACs csr because it is not in audit_non_hmac_request_keys; as this is not a sensitive security parameter, it is encouraged to disable HMACing to allow better auditing of the PKI engine.


allow_if_modified_since
-----------------------
status           endpoint                message
------           --------                -------
informational    /sys/mounts/pki/tune    Mount hasn't enabled If-Modified-Since Request or Last-Modified Response headers; consider enabling these headers to allow clients to fetch CAs and CRLs only when they've changed, reducing total bandwidth.


enable_auto_tidy
----------------
status           endpoint                 message
------           --------                 -------
informational    /pki/config/auto-tidy    Auto-tidy is currently disabled; consider enabling auto-tidy to execute tidy operations periodically. This helps the health and performance of a mount.


tidy_last_run
-------------
status      endpoint            message
------      --------            -------
critical    /pki/tidy-status    Tidy hasn't run since this mount was created; this can point to problems with the mount's auto-tidy configuration or an external tidy executor; this can impact PKI's and Vault's performance if not run regularly. It is suggested to enable auto-tidy on this mount.


too_many_certs
--------------
status    endpoint      message
------    --------      -------
ok        /pki/certs    This mount has an OK number of stored certificates.


enable_acme_issuance
--------------------
status            endpoint            message
------            --------            -------
not_applicable    /pki/config/acme    Mount contains only root issuers, ACME is not required.


allow_acme_headers
------------------
status            endpoint            message
------            --------            -------
not_applicable    /pki/config/acme    ACME is not enabled, no additional response headers required.

vault write -field=certificate pki/root/generate/internal \
     common_name="example.com" \
     issuer_name="Admantium_Root_CA" > root_2023_ca.crt

`vault pki issue`

To create an intermediate certificate, the issue subcommands requires the paths to the PKI engine that provides the root CA, the path to the PKI engine that creates the intermediate certificate, and flags for the issuer name and the common name of the new certificate.

> vault pki issue -issuer_name="Admantium_Root_CA" /pki/issuer/default /pki_intermediate/ common_name="blog.adamantium.com"

# Log messages
Key                               Value
---                               -----
ca_chain                          [-----BEGIN CERTIFICATE-----
MIIDRzCCAi+gAwIBAgIUX8qna7garPJWG7jWuW+Bp5MUPPAwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjUxMjI0MDk1NzMwWhcNMjYw
...
-----END CERTIFICATE-----

crl_distribution_points           []
delta_crl_distribution_points     []
enable_aia_url_templating         false
issuer_id                         9ea4aa8d-e69b-bb33-55cd-8a732dbe1d9d
issuer_name                       Admantium_Root_CA
issuing_certificates              []
key_id                            ce6a7bda-4a62-5f40-1d67-feff574e3629
leaf_not_after_behavior           err
manual_chain                      <nil>
ocsp_servers                      []
revocation_signature_algorithm    n/a
revoked                           false
usage                             crl-signing,issuing-certificates,ocsp-signing,read-only

`vault pki reissue`

A configured intermediate certificate issuer can be used as a template for another provider, where some attributes are modified. This is the goal of the reissue command, and it requires the three PKI engine endpoints for the root CA, the intermediate the serves as the template, and the new issuer endpoint.

> vault pki reissue -issuer_name="Admantium_Root_CA" /pki/issuer/default /pki_intermediate/issuer/Admantium_Root_CA /pki_intermediate_2/ common_name="blog2.admantium.com"

# Log messages
Key                               Value
---                               -----
ca_chain                          [-----BEGIN CERTIFICATE-----
MIIDXDCCAkSgAwIBAgIUEHX6GOJK+GirdUbIhxupfimJhCswDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjUxMjI0MTAxNzA2WhcNMjYw
...
-----END CERTIFICATE-----

crl_distribution_points           []
delta_crl_distribution_points     []
enable_aia_url_templating         false
issuer_id                         a4d92cfc-b71f-6492-47b2-5f0afb90bc8b
issuer_name                       Admantium_Root_CA
issuing_certificates              []
key_id                            9b629040-5903-cf8a-e0bd-9ade319b8099
leaf_not_after_behavior           err
manual_chain                      <nil>
ocsp_servers                      []
revocation_signature_algorithm    n/a
revoked                           false
usage                             crl-signing,issuing-certificates,ocsp-signing,read-only

`vault pki list-intermediate`

When the hierarchies of root to intermediate certificate becomes complex, this command can help to gain an overview. It requires the complete path to any certificate issuer, and lists all derived certificates.

As an example, when called on the root CA, it lists all so-far created certificates:

> vault pki list-intermediates /pki/issuer/default

# Log messages
intermediate                                                      match?
------------                                                      ------
pki_intermediate_2/issuer/b177e38f-8e3f-85c3-fed7-15e806d29010    true
pki_intermediate_2/issuer/d8873760-fe81-2062-8db8-9d03a0f16634    true
pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5                   true
pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c      true
pki_intermediate/issuer/9ea4aa8d-e69b-bb33-55cd-8a732dbe1d9d      true
pki_intermediate_2/issuer/a4d92cfc-b71f-6492-47b2-5f0afb90bc8b    true

intermediate                                                    match?
------------                                                    ------
pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c    true
pki_intermediate/issuer/9ea4aa8d-e69b-bb33-55cd-8a732dbe1d9d    true
pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5                 true

`vault pki verify-sign`

This command checks if the first given issuer was used to sign the second provided intermediate certificate.

> vault pki verify-sign pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5 pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c

# Log messages
issuer:pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5
issued:pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c

field              value
-----              -----
trust_match        true
key_id_match       true
signature_match    true
subject_match      true
path_match         true

Encryption Key Usage

The ssh secret engine allows connection to a remote machine based on signed SSH keys or one-time passwords. This allows users and systems to gain access to remote systems with ephemeral secrets, greatly improving security.

To create the context for this section's example, run the following commands:

> vault enable secret ssh

> vault write ssh/roles/otp \
    key_type=otp \
    default_user=admin \
    cidr_list=192.168.1.0/26

`vault ssh`

The vault ssh command establishes a connection to any remote host by one of these options. To establish a SSH connection to a remote host, the command needs to be called with a defined role, a mode, and a connection string:

> vault ssh -role otp -mode otp admin@192.168.1.42

# Log messages
Vault could not locate "sshpass". The OTP code for the session is displayed
below. Enter this code in the SSH password prompt. If you install sshpass,
Vault can automatically perform this step for you.
OTP for the session is: 99a09001-cfb6-2b4a-b422-fb9adb306125

Conclusion

The Vault CLI offers more than 30 subcommands. In a continuous blog article series, all commands were systematically explored and explained. In this final article, commands for handling encryption keys were covered. You learned how to a) import self-managed keys to the transit engine, b) use unwrap to decrypt data, c) utilize pki to issue root and intermediate certificates on demand, and d) establish ssh connections to remote hosts using ephemeral secrets.

Hashicorp Vault CLI Part 8: Secrets Management and Key-Value Engine

Sebastian — Thu, 26 Mar 2026 06:08:55 +0000

Hashicorp Vault is a tool for managing secrets and encrypted data. Upon successful authentication, a policy-based system authorizes access to Vault endpoints. All configuration aspects, as well as available functional featured, can be managed via its CLI.

In an ongoing series, all CLI commands are explored systematically. The focus of this article are commands from the secret’s management group. Specifically, the management if secret engines themselves, and commands for working with encrypted data.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups marked with a checkmark were covered in an earlier article, and the commands marked with an at sign are the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
✅ Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
✅ Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
✅ Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- 🌀 secrets: General configuration of secret engines
- 🌀 kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Secret Engine Management

Secrets engines manage different types of encrypted data. They can be grouped into native, applications and services, cloud provider, and encryption keys. For a detailed explanation, see my earlier article about Secret Management Engines

The secret command governs the complete life-cycle of an engine, from activation to re-configuration and dismantling. In the following sections, a kv-v2 engine will be regarded.

`kv secrets enable`

Every engine needs to be activated at first. A minimalist invocation of the enable command
with just the secret engine name applies its default configuration including the mount path. Alternatively, all exposed configuration options can be passed as flags to customize the engine right from the start.

To activate a kv-v2 engine with default properties:

> vault secrets enable kv-v2

# Log messages
2025-12-19T09:01:22.459+0100 [INFO]  core: successful mount: namespace="" path=kv-v2/ type=kv version="v0.25.0+builtin"

Custom configurations can be applied during setup. The list of options is long, and support varies by engine. Available are:

default-lease-ttl=<duration>: The TTL value for all leases issued by the engine
description=<string>: Additional documentation for this secret engine, intended for users
external-entropy-access=<bool>: Allow this engine to access external entropy sources
force-no-cache=<bool>: Configure the caching behavior of the engine
listing-visibility=<string>: Controls if the engine should be visible to authenticated unauthenticated users. Allowed values are hidden and unauth.
local=<bool>: Secret engines configuration and values are normally replicated in the context of running Vault as a cluster. This option can disable this behavior.
max-lease-ttl=<duration>: The maximum TTL of issues leases. If this time passes, the lease can not be renewed again.
options=<key=value>: Additional generic options passed to the engine.
path=<string>: The mount path of the engine. Needs to be unique.
plugin-name=<string>: Vaults plugin nature allows developers to implement custom engine. This configuration option sets the correct plugin to use.
plugin-version=<string>: Set the plugins version to use.
seal-wrap: All secrets are encrypted with Vault-internal keys. This option allows to use additional keys for storing and reading secret data.
version=<int>: The version of the secret engine.

Here is an example to create the kv-v2 engine with specific options.

> vault secrets enable \
  -description="datacenter secrets" \
  -external-entropy-access=true \
  -listing-visibility=hidden \
  -force-no-cache=true -path=kv2 \
  -default-lease-ttl=5m \
  -max-lease-ttl=1h \
  kv-v2

# Log messages
2025-12-19T09:52:44.260+0100 [INFO]  core: successful mount: namespace="" path=kv2/ type=kv version="v0.25.0+builtin"

`kv secrets list`

This command shows all currently activated secret engines. The output can be formatted as table, JSON or YAML, and the -detailed flags

> vault secrets list -format=json

# Log messages
{
  "cubbyhole/": {
    "uuid": "2da6947a-8eb4-8bca-7405-8d056e87d997",
    "type": "cubbyhole",
    "description": "per-token private secret storage",
    "accessor": "cubbyhole_376f2732",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false
    },
    "options": null,
    "local": true,
    "seal_wrap": false,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
  "identity/": {
    "uuid": "985d0186-a541-5905-fabb-70352eaf55b9",
    "type": "identity",
    "description": "identity store",
    "accessor": "identity_6676eb9f",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false,
      "passthrough_request_headers": [
        "Authorization"
      ]
    },
    "options": null,
    "local": false,
    "seal_wrap": false,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
  "kv2/": {
    "uuid": "f7192663-902b-bc9f-da68-762c82c3738b",
    "type": "kv",
    "description": "datacenter secrets",
    "accessor": "kv_20ee0106",
    "config": {
      "default_lease_ttl": 300,
      "max_lease_ttl": 3600,
      "force_no_cache": true,
      "listing_visibility": "hidden"
    },
    "options": {
      "version": "2"
    },
    "local": false,
    "seal_wrap": false,
    "external_entropy_access": true,
    "plugin_version": "",
    "running_plugin_version": "v0.25.0+builtin",
    "running_sha256": "",
    "deprecation_status": "supported"
  },
  "postgres/": {
    "uuid": "50dae925-f07d-184c-a824-096e5719e213",
    "type": "database",
    "description": "",
    "accessor": "database_53cdbc55",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false
    },
    "options": null,
    "local": false,
    "seal_wrap": false,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
  "sys/": {
    "uuid": "9fc5f342-99e3-4d0a-b7c7-f3f015417a4e",
    "type": "system",
    "description": "system endpoints used for control, policy and debugging",
    "accessor": "system_5265b4ea",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false,
      "passthrough_request_headers": [
        "Accept"
      ]
    },
    "options": null,
    "local": false,
    "seal_wrap": true,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
}

`kv secrets move`

When a secrets engine mount path should be changed, this command can be used.

Here is an example to move the kv-v2 engine to a more descriptive mount path reflecting its intended use-case:

> vault secrets move kv2 datacenter-secrets/

# Log messages
2025-12-19T10:06:07.937+0100 [INFO]  core.mounts.migration: Starting to update the mount table and revoke leases: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/
2025-12-19T10:06:08.162+0100 [INFO]  core.mounts.migration: Removing the source mount from filtered paths on secondaries: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/
2025-12-19T10:06:08.162+0100 [INFO]  core.mounts.migration: Updating quotas associated with the source mount: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/
2025-12-19T10:06:08.162+0100 [INFO]  core.mounts.migration: Completed mount move operations: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/

`kv secrets tune`

Once a secret engine became operational, its configuration might need a modification. The tune command accepts most command from its activations, except those that govern the encryption itself, such as external-entropy-access

To modify the kv-v2 engine:

> vault secrets tune \
  -description="stores datacenter secrets" \
  -listing-visibility=unauth \
  -default-lease-ttl=10m datacenter-secrets

# Log messages
2025-12-19T10:23:13.086+0100 [INFO]  core: mount tuning of listing_visibility successful: path=datacenter-secrets/
2025-12-19T10:23:43.231+0100 [INFO]  core: mount tuning of leases successful: path=datacenter-secrets/
2025-12-19T10:23:43.351+0100 [INFO]  core: mount tuning of description successful: path=datacenter-secrets/ description="stores datacenter secrets"

`kv secrets disable`

When the secret engine is not required anymore, it can be turned off. All existing leases will be deleted, and all stored date is removed irreversible.

> vault secrets disable datacenter-secrets

# Log messages
2025-12-19T10:29:32.553+0100 [INFO]  core: successfully unmounted: path=datacenter-secrets/ namespace=""

Key-Value Secret Engine Data Commands

Vault comes with several built-in secrets engines, and the key-value store is the most generic one. Once configured, secrets in the form of key-value pairs can be stored at any nested path, allowing to reflect organizational or logical structure.

The key-value store is available in two different versions, a quick differentiation is this:

The kv-v1 store is more runtime efficient and requires fewer storage space. Secrets are stored unversioned. When a command overwrites data at an existing path, its data is lost. Furthermore, deletion is also non-recoverable.
The kv-v2 store adds versioning to all paths, with a default but tunable value of 10 versions. Storing data at an already defined path increments the version counter. Older versions can be read until the increments surpass the defined maximum value. Any version can be erased recoverable with the delete command, or non-recoverable with the destroy command. Finally, when using the vault CLI generic CRUD commands, the actual paths to access the secret need to differentiate between <mount_path>/data/<name> and <mount_path>/metadata/<name>.

Assuming a CRUD lifecycle, the kv subcommands can be seperated as follows:

Creation
- put: Adds a new secret or new version of the secret at a defined path
Reading
- list: Shows all secrets at a designated path, or at subsequent path parts
- get: Access a specific secret and expose all its metadata
Update
- patch: Modify existing data without incrementing the version
- rollback: Restores a previous version of a secret
- undelete: Restores a secret, or versions of a secrets, that were marked for deletion
- enable-versioning: Adds versioning capabilities to a secret if not present already
Delete
- delete: Removes a secret, or versions of a secret, but keeping an internal, recoverable record
- destroy: Non-recoverable erasing of a secret or versions of secrets

Only in an kv-v2 store are all CLI commands available, and will therfore be the context for this section. The store is created with the following command:

> vault secrets enable -path=kv2 kv-v2

`kv put`

In its simplest form, a single key-value pair can be stored at an arbitrary path. The command can include the secret data directly, which will be stored in the Shell history and therefore exposed, or read from file.

To pass secrets directly:

> vault kv put kv2/api-creds aws=75ae33a4b907bc87796

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T08:13:57.536865Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Another option is to store the secret data in a file, and pass multiple key-value pairs to the command, where the key is determined by the command, and its value by the content of the file.

> vault kv put kv2/api-creds value=@/tmp/aws.scr.txt

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T08:33:49.738235Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

Interestingly, the file content can even be binary, as the following example shows:

> dd if=/dev/urandom of=/tmp/binary.scr.txt bs=1 count=30

> vault kv put kv2/api-creds binary=@/tmp/binary.scr.txt

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                binary
---                -----
created_time       2025-12-20T08:42:50.150485Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            4

`kv list`

To get an overview about all secrets, the list command can be called with to secrets engines root-path.

> vault kv list kv2

# Log messages
Keys
----
api-creds
databases
kubernetes
kubernetes/

As the output shows, it lists the top-level paths only. When structured paths are defined, they will be shown with a trailing /. These paths need to be exposed additionally.

> vault kv list kv2/kubernetes/

# Log messages
Keys
----
datacenter1
datacenter2
datacenter3

`kv get`

This command retrieves all data stored at a specific path. Unless scoped, the most recent version will be returned.

Here is an example that returns the most-recent version, also showing that binary data was stored:

>  vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T09:27:46.102492Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            3

==== Data ====
Key      Value
---      -----
binary    7J\Z!kMTtcyM/T

To return a different version instead:

> vault kv get -version=2 kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T09:26:19.01058Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

==== Data ====
Key      Value
---      -----
value    aws=75ae33a4b907bc87796

`kv patch`

To amend additional data to an existing data record, two variants can be used. The put command requires the complete original data and the new, additional data to be specified. The patch command instead only requires to pass the additional data. In both cases, the version will be incremented.

Here is an example that adds a comment to the stored binary data:

> vault kv patch kv2/api-creds comment="Binary executable for retrieving secrets"

The new version has to following structure:

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            4

===== Data =====
Key        Value
---        -----
comment    Binary executable for retrieving secrets
binary     7J\Z!kMTtcyM/T

`kv undelete`

When a kv delete command for a specific version was issued, attempts to read the data will only return the metadata section with the additional attribute deletion_time.

Here is an example:

> vault kv delete -versions=4 kv2/api-creds
> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      2025-12-21T06:42:28.086713Z
destroyed          false
version            4

The data can be restored, and read attempts succeed once again.

> vault kv undelete -versions=4 kv2/api-creds

# Log messages
Success! Data written to: kv2/undelete/api-creds

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            4

===== Data =====
Key        Value
---        -----
comment    Binary executable for retrieving secrets
value      7J\Z!kMTtcyM/T

`kv rollback`

The rollback command accesses a previous version of a secret, and stores the secrets value at a new, incremented version.

Here is an example of a rollback to version 2:

> vault kv rollback -versions=2 kv2/api-creds

# Log messages
Key                Value
---                -----
created_time       2025-12-21T06:49:06.178864Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            5

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T06:49:06.178864Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            5

==== Data ====
Key      Value
---      -----
value    aws=75ae33a4b907bc87796

It is not possible to perform a rollback for a previously deleted version.

> vault kv delete -versions=4 kv2/api-creds

# Log messages
Success! Data deleted (if it existed) at: kv2/data/api-creds

# Log messages
> vault kv rollback -version=4 kv2/api-creds
Cannot roll back to a version that has been deleted

`kv enable-versioning`

As explained in the introductory paragraph, a kv-v1 store does not support versioned secrets. This command effectively turns the v1 to a v2 store.

Here is an example in which a kv-v1 store is created. First, the store is enabled at path kv, and two secrets stored.

> vault secrets enable -path=kv kv-v1

# Log messages
2025-12-21T08:41:57.535+0100 [INFO]  core: successful mount: namespace="" path=kv/ type=kv version="v0.25.0+builtin"
Success! Enabled the kv-v1 secrets engine at: kv/

> vault kv put kv/aws api_key=@/tmp/aws.scr.txt

# Log messages
Success! Data written to: kv/aws

> vault kv put kv/encryption_binary data==@/tmp/bin

# Log messages
Success! Data written to: kv/encryption_binary

> vault kv list kv

# Log messages
Keys
----
aws
encryption_binary

> vault kv get kv/aws

# Log messages
===== Data =====
Key        Value
---        -----
api_key    75ae33a4b907bc87796

Second, kv enable-versioning is applied, and a stored secret read. As shown, it now includes a metadata section, the sure sign that it is a kv-v2 secret.

> vault kv enable-versioning kv

# Log messages
2025-12-21T08:44:53.048+0100 [INFO]  core: mount tuning of options: path=kv/ options=map[version:2]
Success! Tuned the secrets engine at: kv/

2025-12-21T08:44:53.244+0100 [INFO]  secrets.kv.kv_845130a3: collecting keys to upgrade
2025-12-21T08:44:53.244+0100 [INFO]  secrets.kv.kv_845130a3: done collecting keys: num_keys=3
2025-12-21T08:44:54.174+0100 [INFO]  secrets.kv.kv_845130a3: upgrading keys finished

> vault kv list kv

# Log messages
Keys
----
aws
encryption_binary

> vault kv get kv/aws

# Log messages
== Secret Path ==
kv/data/aws

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T07:44:53.342531Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

===== Data =====
Key        Value
---        -----
api_key    75ae33a4b907bc87796

`kv delete`

In an kv-v2 store, the delete command modifies the data-record of a versioned secret. From that moment on, its metadata obtains a timestamp in the deletion_time attribute, and performing a kv get does not show the stored data anymore. This commands results are reversible - issuing a kv undelete restores the data, as shown above.

Here is an example:

> vault kv delete -versions=4 kv2/api-creds

# Log messages
Success! Data deleted (if it existed) at: kv2/data/api-creds

> vault kv get -version=4 kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      2025-12-21T06:52:17.001191Z
destroyed          false
version            4

`kv destroy`

Similar to kv delete, this command modifies the data record. Its metadata shows destroyed true, and read attempts do not return the data anymore. This change is non-reversible - the data is removed permanently.

> vault kv destroy -versions=5 kv2/api-creds

# Log messages
Success! Data written to: kv2/destroy/api-creds
midi :: work/development/vault » vault kv get kv2/api-creds
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T06:49:06.178864Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          true
version            5

Key-Value Secret Engine Metadata Commands

Each kv-v2 secret contains a data and a metadata section. The metadata section of a secret stored in a kv-v2 engine can be accessed and manipulated with the three subcommands get, put, and delete.

`kv metadata get`

Issuing a get returns the complete metadata history of a secret.

> vault kv metadata get kv2/api-creds

# Log messages
==== Metadata Path ====
kv2/metadata/api-creds

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2025-12-20T09:26:11.531797Z
current_version         5
custom_metadata         <nil>
delete_version_after    0s
last_updated_by         map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
max_versions            0
oldest_version          0
updated_time            2025-12-21T06:49:06.178864Z

====== Version 1 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:create]
created_time     2025-12-20T09:26:11.531797Z
deleted_by       <nil>
deletion_time    n/a
destroyed        false

====== Version 2 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
created_time     2025-12-20T09:26:19.01058Z
deleted_by       <nil>
deletion_time    n/a
destroyed        false

====== Version 3 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
created_time     2025-12-20T09:27:46.102492Z
deleted_by       <nil>
deletion_time    n/a
destroyed        false

====== Version 4 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:patch]
created_time     2025-12-20T10:09:59.494854Z
deleted_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
deletion_time    2025-12-21T06:52:17.001191Z
destroyed        false

====== Version 5 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
created_time     2025-12-21T06:49:06.178864Z
deleted_by       <nil>
deletion_time    n/a
destroyed        true

`kv metadata put`

Each secrets' metadata property inherits their configuration from the store itself. These properties can be changed on a per-record base, customizing especially sensitive secrets.

Following properties are configurable:

cas-required=<*bool>: CAS is an acronym for "check-and-set". When this property is enabled, all data-record updates need to include the cas attribute present, and its value needs to be that of the most recent version number. Therefore, this setting is an additional fail-safe to prevent accidental modifications of the secret
delete-version-after=<duration>: Secrets can be configured as self-destructing with this setting. When the duration passes, the most recent version of the secret will be deleted. If version increments happen before the duration expires, older records remain readable.
max-versions=<int>: Per default, each secret path can be updated for 10 iterations before older data is purged. This flag modifies this property.
custom-metadata=<key=value>: The metadata section of each secret can include arbitrary, custom fields to augment information for system or human user access.

Here is an example of extending the metadata record with custom fields:

> vault kv metadata put -custom-metadata="comment=API credentials for AWS" -custom-metadata="public-key=ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT" kv2/api-creds

# Log messages
Success! Data written to: kv2/metadata/api-creds

> vault kv get -format=JSON kv2/api-creds

# Log messages
{
  "request_id": "18da20a1-b67b-f781-ae10-a699675f3b80",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "data": {
      "api_key": "75ae33a4b907bc87796\n"
    },
    "metadata": {
      "created_time": "2025-12-21T09:36:44.286357Z",
      "custom_metadata": {
        "comment": "API credentials for AWS",
        "public-key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT"
      },
      "deletion_time": "",
      "destroyed": false,
      "version": 4
    }
  },
  "warnings": null,
  "mount_type": "kv"
}

The following experiment shows how the duration setting auto-deletes secrets. First, the duration is set to 1min. Second, a new version is created, and the return value shows a deletion timestamp in the future.

> vault kv metadata put -delete-version-after=1m kv2/api-creds

# Log messages
Success! Data written to: kv2/metadata/api-creds

> vault kv put kv2/api-creds api_key=@/tmp/aws.scr.txt

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T09:43:58.324523Z
custom_metadata    map[comment:API credentials for AWS public-key:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT]
deletion_time      2025-12-21T09:44:58.324523Z
destroyed          false
version            6

Once the time passed, the record is deleted. Executing a undelete command makes the secret available again.

vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T09:43:58.324523Z
custom_metadata    map[comment:API credentials for AWS public-key:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT]
deletion_time      2025-12-21T09:44:58.324523Z
destroyed          false
version            6

> vault kv undelete -versions=7 kv2/api-creds

# Log messages
Success! Data written to: kv2/undelete/api-creds

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T09:43:58.324523Z
custom_metadata    map[comment:API credentials for AWS public-key:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT]
deletion_time      2025-12-21T09:48:18.574148Z
destroyed          false
version            6

===== Data =====
Key        Value
---        -----
api_key    aws=75ae33a4b907bc87796

`kv metadata delete`

This command results in the immediate, non-recoverable destruction of all versions of a secret's data and metadata.

> vault kv metadata delete kv2/api-creds

# Log messages
Success! Data deleted (if it existed) at: kv2/metadata/api-creds

All following read attempts result in an error.

> vault kv metadata get kv2/api-creds

# Log messages
No value found at kv2/metadata/api-creds

Conclusion

The Hashicorp Vault CLI is a powerful tool for setup, configuration and maintenance of a Vault server or cluster. In an ongoing article series, all CLI commands are systematically explored. The focus for this article is two commands from the secret management group. With secrets, the available engines can be activated, their configuration read and modified, and finally disabled. Similarly, for the built-in key-value store engine, the kv subcommands cover all lifecycles. Here, you learned about the differences of kv-v1 and kv-v2 stores, and saw the intricacies of secret lifecycles with recoverable and non-recoverable deletion. Finally, you also saw how a secrets metadata can be accessed and manipulated, setting e.g. a property that automatically deletes secrets after a defined duration passed. Overall, this coverage should help you to use the key-value store with its full functionality.

Hashicorp Vault CLI Part 7: Authentication

Sebastian — Mon, 16 Mar 2026 05:58:06 +0000

Hashicorp Vault is a secrets management tool. For setup, configuration, and management, the Vault CLI can be used. It offers more than 30 subcommands, and in this blog series, they are explored systematically.

This article focuses on Authentication. It covers the setup and management of authentication engines, and it shows how to perform logins for the engines.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups marked with a checkmark were covered in an earlier article, and the section marked with an at sign is the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
✅ Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
✅ Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
🌀 Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- secrets: General configuration of secret engines
- kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Authentication Commands

`auth`

A new vault instance supports exactly one, not disableable authentication method: token. Using either the initially defined root token, or other created tokens with the required policies, access to the Vault server can be given.

The vault auth command provides several subcommands with which the available authentication methods can be managed.

enable: Activate a new authentication method
move: Change the mount path of an auth method
tune: Modify the configuration of an auth method
list: Show all configured auth methods
help: Show supporting information about how to use an authentication method
disable: Deactivate an authentication method

As explored in more detail in my article Authentication Provider Almanac, authentication methods can be divided into builtin, user, system, and cloud. While the subcommands structure stays the same for each method, parameters may vary.

To get an overview to all available authentication methods, one option is to access the Vault GUI at path /ui/vault/settings/auth/enable.

The other option is to access the plugin management and list authentication plugins.

> vault plugin list auth

Name          Version
----          -------
alicloud      v0.22.0+builtin
approle       v1.21.1+builtin.vault
aws           v1.21.1+builtin.vault
azure         v0.22.0+builtin
cert          v1.21.1+builtin.vault
cf            v0.22.0+builtin
gcp           v0.22.0+builtin
github        v1.21.1+builtin.vault
jwt           v0.25.0+builtin
kerberos      v0.16.0+builtin
kubernetes    v0.23.1+builtin
ldap          v1.21.1+builtin.vault
oci           v0.20.0+builtin
oidc          v1.21.1+builtin.vault
okta          v1.21.1+builtin.vault
pcf           v1.21.1+builtin.vault
radius        v1.21.1+builtin.vault
userpass      v1.21.1+builtin.vault

The following two sections contrast examples for builtin and user authentication methods.

Managing Builtin Authentication Method: Userpass

A new authentication method can be enabled by just passing its name. Several options can be passed already at initialization time, including the TTL of leases and plugin-specific options, or technical options like access to Vault-external entropy sources.

> vault auth enable userpass

# Log messages
Success! Enabled userpass auth method at: userpass/
core: enabled credential backend: path=userpass/ type=userpass version="v1.21.1+builtin.vault"

The default mount path can be changed, with the immediate effect that all existing tokens will be invalidated immediately. Internally, the authentication methods endpoints configuration will be copied, then unmounted, and mounted at the new path - a background operation that can take some time.

> vault auth move auth/userpass auth/login

# Log messages
Started moving auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6
Waiting for terminal status in migration of auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6
Success! Finished moving auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6

Once the authentication method is mounted, its configuration can be changed with the tune command. All options available during initialization can be accessed and modified. The following command shows how to change the default lease time.

> vault auth tune -default-lease-ttl=1h login/

# Log messages
2025-12-11T20:07:33.703+0100 [INFO]  core: mount tuning of leases successful: path=auth/login/
Success! Tuned the auth method at: login/

To get an overview to all defined authentication methods, run the following:

> vault auth list

# Log messages
Path      Type        Accessor                  Description                Version
----      ----        --------                  -----------                -------
login/    userpass    auth_userpass_208f6abe    n/a                        n/a
token/    token       auth_token_a5a09180       token based credentials    n/a

Each authentication methods can be used with the Vault CLI via vault login. A helpful shortcut to see when parameters an authentication method requires can be obtained as follows:

> vault auth help login/

# Log messages
Usage: vault login -method=userpass [CONFIG K=V...]

  The userpass auth method allows users to authenticate using Vault's
  internal user database.

  Authenticate as "sally":

      $ vault login -method=userpass username=sally
      Password (will be hidden):

  Authenticate as "bob":

      $ vault login -method=userpass username=bob password=password

Configuration:

  password=<string>
      Password to use for authentication. If not provided, the CLI will prompt
      for this on stdin.

  username=<string>
      Username to use for authentication.

Finally, a configured auth method can be disabled, immediately revoking all existing leases.

> vault auth disable login/

# Log messages
2025-12-11T20:14:25.462+0100 [INFO]  core: disabled credential backend: path=auth/login/
Success! Disabled the auth method (if it existed) at: login/

Managing User Authentication Method: OIDC

The OIDC method is activated and mounted at a predefined path.

> vault auth oidc

# Log messages
2025-12-13T11:20:44.946+0100 [INFO]  core: enabled credential backend: path=oidc/ type=oidc version="v1.21.1+builtin.vault"
Success! Enabled oidc auth method at: oidc/

However, it should be available at the path /openid-login. Let’s move it there.

> vault auth move auth/oidc auth/openid-login

# Log messages
2025-12-13T11:21:23.440+0100 [INFO]  core.mounts.migration: Starting to update the mount table and revoke leases: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
Started moving auth method auth/oidc/ to auth/openid-login/, with migration ID 64a573e0-b9f5-1a92-bf63-68578a90ee13
Waiting for terminal status in migration of auth method auth/oidc/ to auth/openid-login/, with migration ID 64a573e0-b9f5-1a92-bf63-68578a90ee13
2025-12-13T11:21:23.734+0100 [INFO]  core.mounts.migration: Removing the source mount from filtered paths on secondaries: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
2025-12-13T11:21:23.734+0100 [INFO]  core.mounts.migration: Updating quotas associated with the source mount: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
2025-12-13T11:21:23.735+0100 [INFO]  core.mounts.migration: Completed mount move operations: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/

The OIDC authentication can be used in conjunction with an external system. To see tunable properties, run the following command:

> vault read sys/auth/openid-login/tune

# Log messages
Key                  Value
---                  -----
default_lease_ttl    768h
description          n/a
force_no_cache       false
max_lease_ttl        768h
token_type           default-service

Let’s limit the TTL, and ensure unauthenticated users can access the method as well.

> vault auth tune -max-lease-ttl=1m -listing-visibility=unauth openid-login

2025-12-13T11:37:08.199+0100 [INFO]  core: mount tuning of leases successful: path=auth/openid-login/
2025-12-13T11:37:08.456+0100 [INFO]  core: mount tuning of listing_visibility successful: path=auth/openid-login/
Success! Tuned the auth method at: openid-login/

To see how to perform a login with this method, run the following command:

> vault auth help openid-login/

# Log messages
Usage: vault login -method=oidc [CONFIG K=V...]

  The OIDC auth method allows users to authenticate using an OIDC provider.
  The provider must be configured as part of a role by the operator.

  Authenticate using role "engineering":

      $ vault login -method=oidc role=engineering
      Complete the login via your OIDC provider. Launching browser to:

          https://accounts.google.com/o/oauth2/v2/...

  The default browser will be opened for the user to complete the login. Alternatively,
  the user may visit the provided URL directly.

Finally, the authentication method will be disabled again.

> vault auth disable openid-login

# Log messages
2025-12-13T11:44:33.916+0100 [INFO]  core: disabled credential backend: path=auth/openid-login/
Success! Disabled the auth method (if it existed) at: openid-login/

`login`

To login to a configured authentication method, both the GUI and the CLI can be used. An invocation via the CLI requires the following command flags to be present:

method: The authentication method type
path: In case of a non-default mount path, it needs to be configured specifically.
parameters: Additional parameters as required by the authentication method

Continuing with the examples from the last two sections, to perform the login for the userpass method, run the following commands:

> vault login -method=userpass -path=login username=user

# Log messages
Password (will be hidden):
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                    Value
---                    -----
token                  hvs.CAESICzlbzAXoGcIvdAgGQ1NToqs5jARRfP4oFJAS_37Mw-HGh4KHGh2cy5ORGMzYmYyQWlGbFk5em92cHVuNXFBbkU
token_accessor         EjZQYdMEMCAsN7VvVCR1ef1r
token_duration         768h
token_renewable        true
token_policies         ["default"]
identity_policies      []
policies               ["default"]
token_meta_username    user

To properly setup the OIDC authentication method, additional steps are required: Registration with an OIDC provider, configuring the discovery URL and secrets in vaults, and the setup of policies and roles. Assuming these steps were done, the login works as follows:

> vault login -method=oidc -path=openid-login role=user

#logMessages
Complete the login via your OIDC provider. Launching browser to:

...

Waiting for OIDC authentication to complete...

Conclusion

The Hashicorp Vault CLI offers more then 30 commands. In this article, you learned all about authentication. First, authentication methods are enabled at a specific mountpoints. Their properties can be modified, their mount path changed, and a list of all active methods obtained. Not required authentication methods can be disabled, immediately revoking all token leases. Second, users and systems alike can use the CLI also to login. Providing the authentication methods name, its mount path, and other required parameters. When successful, a new token is created, access policies attached, and the token owner can interact with the Vault server.

Hashicorp Vault CLI Part 6: Authorization

Sebastian — Thu, 05 Mar 2026 06:32:24 +0000

With Hashicorp Vault, the secure management of secrets and encrypted data becomes a manageable task. Thanks to its plugin architecture, functional extensions that target authentication, secrete creation, and short-lived access to system can be implemented and adapted to meet changing requirements.

In an ongoing blog series, all Vault CLI commands are explored systematically. This article explains three commands from the authorization group, showing how to define policies, and managing tokens and leases that embody the policies for providing access to a Vault server.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups marked with a checkmark were covered in an earlier article, and the section marked with an at sign is the focus for this article. From the authorization group, the commands policy and lease will be covered here. The token command is extensively covered in my earlier article about token management_.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
✅ Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
🌀 Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- secrets: General configuration of secret engines
- kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Policy Management Commands

Note: For a detailed guide to policies, see my earlier article Fine-Grained Access Control with Policies.

Policies are rules that detail which operations are available on which endpoints. Written in the Hashicorp Configuration Language, they are blocks of code consisting of a path declaration, which supports wildcard path segments, and a declaration of capabilities and other restrictions.

Here is an example that limits access to a kv-v2 secrets store.

path "kv2/*"
{
  capabilities = ["create", "update", "delete"]
}

The policy command provides high-level CRUD operations on policy definitions. All commands are explained in the following sections. To provide the example context for all commands, a kv-v2 secret store is assumed. It can be created with the following command:

vault secrets enable -max-lease-ttl=1h -path=kv2 kv-v2

# Log messages
2025-12-17T11:32:07.670+0100 [INFO]  core: successful mount: namespace="" path=kv2/ type=kv version="v0.25.0+builtin"

`policy fmt`

Documents written in Hashicorp Vault Configuration language should confirm with syntactic rules. This command processes a file and prints a formatted version of it.

Assuming a syntactic-valid, but ill-formatted document is created ...

> echo '
path "kv2/config-db/datacenter1" { capabilities = ["read"] }


path "kv2/config-db/datacenter1"{
  capabilities = ["create"]
  required_parameters = ["server_id"]}' > datacenter1.policy.hcl

... running fmt changes the file content:

> vault policy fmt datacenter1.policy.hcl

# Log messages
Success! Formatted policy: datacenter1.policy.hcl

> cat datacenter1.policy.hcl

# Log messages
path "kv2/config-db/datacenter1" {
  capabilities = ["read"]
}

path "kv2/config-db/datacenter1" {
  capabilities        = ["create"]
  required_parameters = ["server_id"]
}

`policy write`

Policy declarations need to be saved in Vault to become effective. The command requires two parameters: The name of the policy object that is to be stored, and either a filename or the dash symbol so that the policy declaration is read from STDIN.

Here is the invocation that reads the content from the defined file:

> vault policy write datacenter1 ./datacenter1.policy.hcl

# Log messages
Success! Uploaded policy: datacenter1

And the invocation via STDIN:

> echo '
path "kv2/config-db/datacenter1" { capabilities = ["read"] }


path "kv2/config-db/datacenter1"{
  capabilities = ["create"]
  required_parameters = ["server_id"]}' | vault policy write datacenter1_v2 -
Success! Uploaded policy: datacenter1_v2

# Log messages
Success! Uploaded policy: datacenter1_v2

`policy list`

This command prints the name of all currently defined policies in a Vault server. The output can be formatted in a text table, as JSON or as YAML.

> vault policy list -format=table

#Log messages
datacenter1
datacenter1_v2
default
acl/kv-secrets
root

`policy read`

With the help of the read command, the full content of a policy can be shown. The command requires a concrete policy name, and the output can be formatted as a table, JSON or YAML.

> vault policy read "datacenter1"

# Log messages
path "kv2/config-db/datacenter1" {
  capabilities = ["read"]
}

path "kv2/config-db/datacenter1" {
  capabilities        = ["create"]
  required_parameters = ["server_id"]
}

Interestingly, when querying about the policy datacenter1_v2, the same ill-for mated input is returned.

> vault policy read -format=YAML "datacenter1_v2"

# Log messages
policy: |2

  path "kv2/config-db/datacenter1" { capabilities = ["read"] }

  path "kv2/config-db/datacenter1"{
    capabilities = ["create"]
    required_parameters = ["server_id"]}

`policy delete`

When the policy lifecycle ends, it should be removed with this command.

> vault policy delete datacenter1

# Log messages
Success! Deleted policy: datacenter1

Lease Management

Leases are special data structures in Vault, used to reference data in external systems. One type is the association of a token issued by an authentication provider with a data record at the providers system. Another type are dynamic secrets, ephemeral data that is stored at an external system, such as a database or a cloud provider.

Leases can be accessed and manipulated with the Vault CLI.

To provide a context for the following examples, a dynamic secret at a Postgres DB is assumed. Create a local Postgres DB, setup the user, then execute the following commands:

> vault secrets enable -path=postgres database

> vault write postgres/config/vault \
    plugin_name="postgresql-database-plugin" \
    connection_url="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/vault" \
    allowed_roles="vault"

> export ROLE_NAME=vault; \
  export ROLE_PASSWORD=SECRET; \
  vault write postgres/roles/vault \
    db_name="vault" \
    creation_statements="CREATE ROLE ${ROLE_NAME} WITH LOGIN PASSWORD '${ROLE_PASSWORD}'; \
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO ${ROLE_NAME};" \
    default_ttl="1h" \
    max_ttl="24h"

Finally, the dynamic secret is created:

> vault read postgres/creds/vault

# Log message
Key                Value
---                -----
lease_id           postgres/creds/vault/St5gVIx3wlUE7YQhj4yxESsl
lease_duration     1h
lease_renewable    true
password           -EEvuNgFotraoUpBxgY4
username           v-root-vault-tkTtmMfzNdnkVHwgJ4Pq-1766045698

`lease lookup`

This command introspects an existing lease.

> vault lease lookup postgres/creds/vault/St5gVIx3wlUE7YQhj4yxESsl

# Log messages
Key             Value
---             -----
expire_time     2025-12-18T10:14:58.165563+01:00
id              postgres/creds/vault/St5gVIx3wlUE7YQhj4yxESsl
issue_time      2025-12-18T09:14:58.165563+01:00
last_renewal    <nil>
renewable       true
ttl             52m18s

`lease renew`

Leases have a configured TTL. When the TTL expires, so does the data record at the external system. A renewal refreshes the lease TTL.

> vault lease renew postgres/creds/vault/St5gVIx3wlUE7YQhj4yxESsl

# Log messages
Key                Value
---                -----
lease_id           postgres/creds/vault/St5gVIx3wlUE7YQhj4yxESsl
lease_duration     1h
lease_renewable    true

`lease revoke`

An existing lease can be immediately revoked. The data record at the external system will be deleted as well.

> vault lease revoke postgres/creds/vault/St5gVIx3wlUE7YQhj4yxESsl

# Log messages
2025-12-18T09:40:07.289+0100 [INFO]  expiration: revoked lease: lease_id=postgres/creds/vault/St5gVIx3wlUE7YQhj4yxESsl

Conclusion

Hashicorp Vault uses policy definitions, tokens, and leases to provide authorization for accessing Vault API endpoints or interact with external systems. This article about the Vault CLI explored authorization commands. You learned that policy can be used to introspected, create, and delete any system-defined policies. And you learned the application of lease for introspecting, renewing and revoking data records at external systems.

Hashicorp Vault CLI Part 5: Vault Enterprise

Sebastian — Mon, 23 Feb 2026 06:02:43 +0000

The Hashicorp Vault CLI binary is a multi-purpose tool offering several commands for all configurational and operational aspects. This article investigates two commands available in Hashicorp Vault enterprise: Connecting with managed cloud platform instances, and using namespaces.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups marked with a checkmark were covered in an earlier article, and the section marked with an at sign is the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
🌀 Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- secrets: General configuration of secret engines
- kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Vault Enterprise Commands

`hcp`

Hashicorp offers cloud-based managed installations of Vault, called Hashicorp Cloud Plattform (HCP). With the same-named command, a connection between HCP and any computer that runs the same version of the Vault CLI can be established.

In the absence of a HCP installation, the connection establashing can only be hinted at:

> vault hcp connect

# Log messages
The default web browser has been opened at https://auth.idp.hashicorp.com/oauth2/auth?access_type=offline&audience=https%3A%2F%2Fapi.hashicorp.cloud&client_id=4edd6521-6eb9-4d78-9039-7ce8569d667c&redirect_uri=http%3A%2F%2Flocalhost%3A8443%2Foidc%2Fcallback&response_type=code&scope=openid+offline_access&state=A45XFyg3naoKuyc2LASrFV1RvzNQpFzlbn2rXFlFZMU. Please continue the login in the web browser.

`namespace`

In Vault, all interactions ultimately send data to a mount point. And when managing an extensive suite of multiple version of the same secrets or authentication methods, the route paths can become cobbled. Namespaces add a path-segment to the mount point, helping to structure Vault e.g. into company sections.

A full set of CRUD methods is available:

create: adds a new namespace
lookup: checks if the given namespace exists
list: reads all child namespaces
patch: update the parameters of a given namespace
delete: removes the namespaces
lock: prevents access to any endpoints mounted under a target namespace
unlock: removes the lock for a namespace

However, namespaces are a feature for enterprise hashicorp vault only. Calling any methods with the community edition results merely in an error:

> vault namespace create data-center-1

# log messages
Error creating namespace: Error making API request.

URL: PUT http://127.0.0.1:8210/v1/sys/namespaces/data-center-1
Code: 404. Errors:

* enterprise-only feature

Conclusion

The Vault CLI binary offers more than 30 subcommands. This blog post covered 2 miscellaneous commands. With hcp, a connection to a managed Hashicorp Vault Cloud Platform instance can be created. The namespace commands enables supplementing API endpoints with additional path segments to reflect organizational structure. Both commands require a Vault Enterprise server, they cannot be used in the Vault community version.

Hashicorp Vault CLI Part 4: Introspection

Sebastian — Thu, 12 Feb 2026 06:26:40 +0000

Hashicorp Vault is a secrets management tool. Its CLI is a powerful companion, supporting all tasks from setup to configuration and troubleshooting. Continuing the series about all CLI commands, this article focuses the introspection group. All available commands will be listed, explained, and applied in the context of a locally running cluster with three servers.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups marked with a checkmark were covered in an earlier article, and the section marked with an at sign is the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
🌀 Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- secrets: General configuration of secret engines
- kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Introspection Commands

`status`

This convenient method shows the current status of the vault server.

> vault status

# Log messages
Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            5
Threshold               2
Version                 1.21.1
Build Date              2025-11-18T13:04:32Z
Storage Type            raft
Cluster Name            vault
Cluster ID              dfbcadb4-8f92-3c29-2369-10a53a8a72b4
Removed From Cluster    false
HA Enabled              true
HA Cluster              https://127.0.0.1:8211
HA Mode                 active
Active Since            2025-12-03T20:09:40.417402+01:00
Raft Committed Index    60
Raft Applied Index      60

`version`

Prints the version of the vault server, complete with a verifiable hast value and timestamp.

> vault version

# Log messages
Vault v1.21.1 (2453aac2638a6ae243341b4e0657fd8aea1cbf18), built 2025-11-18T13:04:32Z

`version-history`

When upgrading the Vault binary, information about its installation date is gathered. This command lists all update information.

> vault version-history

# Log messages
Note:
Use of this command requires a server running Vault 1.10.0 or greater.
Version tracking was added in 1.9.0. Earlier versions have not been tracked.

Version  Installation Time     Build Date
-------  -----------------     ----------
1.20.0   2025-06-29T1142:02Z   2025-06-23T10:21:30Z
1.21.1   2025-12-02T18:57:15Z  2025-11-18T13:04:32Z

`print`

This command shows the currently used vault token. It either reflects the environment variable VAULT_TOKEN, or the content of the currents user ~/.vault-token file.

Here is an example of a successful invocation:

> vault print

# log messages
hvs.HTMdJOhLMnJ0l3mHYB242Swv

When no token is defined, the command merely prints an empty line and exits with status code 0.

`path-help`

This handy command prints compact information about any configured mount point of Vault. This helps to quickly find out which parameters can be used on which endpoint.

Here are some examples, showing the responses for endpoints accessible to the admin only, as well as generic endpoints for secrets.

> vault path-help sys

# log messages
## DESCRIPTION

The system backend is built-in to Vault and cannot be remounted or
unmounted. It contains the paths that are used to configure Vault itself
as well as perform core operations.

## PATHS

The following paths are supported by this backend. To view help for
any of the paths below, use the help command with any route matching
the path pattern. Note that depending on the policy of your auth token,
you may or may not be able to access certain paths.

    ^(leases/)?renew(/(?P<url_lease_id>.+))?$
        Renew a lease on a secret

    ^(leases/)?revoke(/(?P<url_lease_id>.+))?$
        Revoke a leased secret immediately

    ^(leases/)?revoke-force/(?P<prefix>.+)$
        Revoke all secrets generated in a given prefix, ignoring errors.

    ^(leases/)?revoke-prefix/(?P<prefix>.+)$
        Revoke all secrets generated in a given prefix
    ...

> vault path-help auth/token

# log messages
## DESCRIPTION

## PATHS

The following paths are supported by this backend. To view help for
any of the paths below, use the help command with any route matching
the path pattern. Note that depending on the policy of your auth token,
you may or may not be able to access certain paths.

    ^accessors/?$
        List token accessors, which can then be
        be used to iterate and discover their properties
        or revoke them. Because this can be used to
        cause a denial of service, this endpoint
        requires 'sudo' capability in addition to
        'list'.

    ^create$
        The token create path is used to create new tokens.

`events`

Vault usage logs data to an internal event system, and with the same named command, a live trail of events from a specific topic can be obtained. Alas, in the vault community edition, events are not implemented yet. Checking the official documentation about the /sys/experiments endpoint does not reveal information how to get events operational.

Calling the command returns an error only.

> vault events subscribe '*'

# Log messages
events endpoint not found; check `vault read sys/experiments` to see if an events experiment is available but disabled

`monitor`

This command continuously streams live log files. It gives an immediate insight into a Vault server.

> vault monitor

# Log messages
2025-12-07T10:20:26.602+0100 [INFO]  core: successful mount: namespace="" path=ldap/ type=ldap version="v1.21.1+builtin.vault"
2025-12-07T10:20:26.608+0100 [INFO]  secrets.ldap.ldap_e03497d2: initializing database rotation queue
2025-12-07T10:20:26.608+0100 [INFO]  secrets.ldap.ldap_e03497d2: populating role rotation queue
2025-12-07T10:20:26.617+0100 [INFO]  secrets.ldap.ldap_e03497d2: starting periodic ticker
2025-12-07T10:20:42.356+0100 [INFO]  core: successful mount: namespace="" path=totp/ type=totp version="v1.21.1+builtin.vault"
2025-12-07T10:21:00.354+0100 [INFO]  core: successfully unmounted: path=totp/ namespace=""

`debug`

While Vault's configuration can be determined statically, its runtime behavior needs to be actively observed and measured.

When executed, the debug command start a process that connects to the Vault server instance, captures data for a specific time, and creates an archive file with all individual results. The command uses the configured vault token and attached policies - to ensure complete coverage of all required endpoints, elevated access rights are required.

> vault debug

==> Starting debug capture...
         Vault Address: http://127.0.0.1:8210
        Client Version: 1.21.1
        Server Version: 1.21.1
              Duration: 2m0s
              Interval: 30s
      Metrics Interval: 10s
               Targets: config, host, requests, metrics, pprof, replication-status, server-status, log
                Output: vault-debug-2025-12-05T15-58-58Z.tar.gz

==> Capturing static information...
2025-12-05T17:58:58.830+0100 [INFO]  capturing configuration state

==> Capturing dynamic information...
2025-12-05T17:58:58.834+0100 [INFO]  capturing pprof data: count=0
2025-12-05T17:58:58.835+0100 [INFO]  capturing in-flight request status: count=0
2025-12-05T17:58:58.835+0100 [INFO]  capturing server status: count=0
2025-12-05T17:58:58.835+0100 [INFO]  capturing host information: count=0
2025-12-05T17:58:58.835+0100 [INFO]  capturing metrics: count=0
2025-12-05T17:58:58.835+0100 [INFO]  capturing replication status: count=0
2025-12-05T17:59:08.834+0100 [INFO]  capturing metrics: count=1
2025-12-05T17:59:18.834+0100 [INFO]  capturing metrics: count=2
2025-12-05T17:59:28.833+0100 [INFO]  capturing replication status: count=1
2025-12-05T17:59:28.833+0100 [INFO]  capturing server status: count=1
2025-12-05T17:59:28.833+0100 [INFO]  capturing in-flight request status: count=1
2025-12-05T17:59:28.833+0100 [INFO]  capturing metrics: count=3
2025-12-05T17:59:28.833+0100 [INFO]  capturing host information: count=1
2025-12-05T17:59:38.833+0100 [INFO]  capturing metrics: count=4
2025-12-05T17:59:48.832+0100 [INFO]  capturing metrics: count=5
2025-12-05T17:59:58.831+0100 [INFO]  capturing replication status: count=2
2025-12-05T17:59:58.831+0100 [INFO]  capturing metrics: count=6
2025-12-05T17:59:58.831+0100 [INFO]  capturing host information: count=2
2025-12-05T17:59:58.831+0100 [INFO]  capturing in-flight request status: count=2
2025-12-05T17:59:58.831+0100 [INFO]  capturing server status: count=2
2025-12-05T17:59:58.833+0100 [INFO]  capturing pprof data: count=1
2025-12-05T18:00:08.831+0100 [INFO]  capturing metrics: count=7
2025-12-05T18:00:18.830+0100 [INFO]  capturing metrics: count=8
2025-12-05T18:00:28.829+0100 [INFO]  capturing metrics: count=9
2025-12-05T18:00:28.830+0100 [INFO]  capturing in-flight request status: count=3
2025-12-05T18:00:28.830+0100 [INFO]  capturing host information: count=3
2025-12-05T18:00:28.830+0100 [INFO]  capturing replication status: count=3
2025-12-05T18:00:28.830+0100 [INFO]  capturing server status: count=3
2025-12-05T18:00:38.829+0100 [INFO]  capturing metrics: count=10
2025-12-05T18:00:48.828+0100 [INFO]  capturing metrics: count=11
2025-12-05T18:00:58.828+0100 [INFO]  capturing metrics: count=12
2025-12-05T18:00:58.828+0100 [INFO]  capturing host information: count=4
2025-12-05T18:00:58.828+0100 [INFO]  capturing in-flight request status: count=4
2025-12-05T18:00:58.828+0100 [INFO]  capturing replication status: count=4
2025-12-05T18:00:58.828+0100 [INFO]  capturing server status: count=4
2025-12-05T18:00:58.830+0100 [INFO]  capturing pprof data: count=2
Finished capturing information, bundling files...
Success! Bundle written to: vault-debug-2025-12-05T17-58-58Z.tar.gz

The created archive file contains the following:

config.json: Lists the derived, complete configuration of the Vault server, including TCP listeners, plugins, storage and listeners
host_info.json: Detailed hardware metrics of the host, including CPU, memory and storage
index.json: Meta information about the debug process, like timestamps and endpoint targets, and about the archive itself, listing all individual files
metrics.json: fine-grained measurements of the Vault process, such as read-write statistics of the storage and memory, health of replication, and other
replication_status.json: time-base probes about the status of replication
requests.json: A logfile detailing which Vault-internal endpoints were queried to obtain data
server_status.json: Reports the health and seal status monitored over the debug command duration
vault.log: An export of log statements printed by vault for the duration of the debug command

`audit`

Audit devices are files, syslog servers, or any sockets that can process a text stream. When configured, all API calls and responses to the Vault server are logged in these audit devices. In the logs, all string-encoded content is hashed in order to prevent the clear-text recording of sensitive data. If other value types are considered sensitive, they should be output as string values too.

Once configured, audit devices are strictly required: Vault logs first to an audit device, and then returns responses to the client. If all configured audit devices are non-responsive, the Vault server effectively stops functioning.

Finally, not all API endpoints are stored to an audit device - see the documentation about exempted API endpoints.

The audit command distinguishes three subcommands:

enable: Activate and configure an audit text file or stream
list: Shows all configured audit devices and their status
disable: Disables a device

The first step is to define an audit device. The following example activates a log file and the syslog stream.

> vault audit enable file \
    file_path=/var/log/vault/audit.log

# Log messages
Success! Enabled the file audit device at: file/
2025-12-08T20:34:08.865+0100 [INFO]  core: enabled audit backend: path=file/ type=file

> vault audit enable syslog

# Log messages
Success! Enabled the syslog audit device at: syslog/
2025-12-08T20:34:21.429+0100 [INFO]  core: enabled audit backend: path=syslog/ type=syslog

Now, any interactions with Vault are logged to the audit devices. Here is an example during interacting with Vault via the GUI. A read request to sys/internal/ui/mounts creates the following record:

{
  "auth": {
    "accessor": "hmac-sha256:8b11128ad2c588dfb8266c831fca6967ffb2248bb880c62ca7d5a997ea3df2f4",
    "client_token": "hmac-sha256:9b4208cf75a780083842745f54a4fa3827b2120af50c560aa74a03f83009d320",
    "display_name": "root",
    "policies": [
      "root"
    ],
    "policy_results": {
      "allowed": true
    },
    "token_policies": [
      "root"
    ],
    "token_issue_time": "2025-12-02T19:57:16+01:00",
    "token_type": "service"
  },
  "request": {
    "client_id": "0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8=",
    "client_token": "hmac-sha256:9b4208cf75a780083842745f54a4fa3827b2120af50c560aa74a03f83009d320",
    "client_token_accessor": "hmac-sha256:8b11128ad2c588dfb8266c831fca6967ffb2248bb880c62ca7d5a997ea3df2f4",
    "headers": {
      "user-agent": [
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_7_2) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15"
      ]
    },
    "id": "d0fff50b-0448-15cb-afd3-5dc9a394e717",
    "mount_class": "secret",
    "mount_point": "sys/",
    "mount_running_version": "v1.21.1+builtin.vault",
    "mount_type": "system",
    "namespace": {
      "id": "root"
    },
    "operation": "read",
    "path": "sys/internal/ui/mounts",
    "remote_address": "127.0.0.1",
    "remote_port": 61961
  },
  "time": "2025-12-09T19:26:00.392476Z",
  "type": "request"
}

All currently configured devices can be show by running the following:

> vault audit list

# Log messages
Path       Type      Description
----       ----      -----------
file/      file      n/a
syslog/    syslog    n/a

And to disable audit devices, following command can be used:

> vault audit disable file/
Success! Disabled audit device (if it was enabled) at: file/
2025-12-09T20:33:23.538+0100 [INFO]  core: disabled audit backend: path=file/

Conclusion

The Hashicorp vault CLI is the essential tool to setup, configure, maintain and troubleshoot a Vault server. This article explored commands from the introspection group. You learned how to a) see the status of the Vault server, b) access version information, c) get documentation about available endpoints, d) collect detailed metrics and access log message live stream, and e) configure and manage audit devices. Commands in this group should help you to diagnose and expediate the resolution of operational errors.

Hashicorp Vault CLI Part 3: Plugin Management and General CRUD Operations

Sebastian — Mon, 02 Feb 2026 06:31:41 +0000

The management of encrypted data and secrets in on-premise or cloud environments is a crucial task. Hashicorp Vault is a flexible tool, supporting a wide range of secret types and helping to provide short-lived access tokens to various systems.

All Vault operation and configuration tasks can be implemented with the Vault CLI tool. In an ongoing article series, all commands are explored systematically. This article continues commands from the configuration group. You will learn how to manage plugins, and how to perform general create-read-update-delete operations on any configuration or data.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups and commands marked with a checkmark were covered in an earlier article, and the commands marked with an at sign are the focus for this article. In particular, this article covers all commands from the configuration group, except vault operator.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
Configuration
- ✅ operator: Cluster management operations, including memberships, encryption and unseal keys
- 🌀 plugin: Manage and install additional plugins
- 🌀 read / list: Access stored configuration and secrets
- 🌀 write / patch: Modify or create any data
- 🌀 delete: Delete configuration data or secrets
Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- secrets: General configuration of secret engines
- kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Plugin Management Commands

Plugin is the technical name and architectural implementation of extended Vault functionality. They are separated into three groups: auth, database, and secrets. Each plugin exposes common functionality hooked with, and accessible by, the Vault CLI.

To manage plugins themselves, the same named command plugin can be used. Its subcommands either interact with the plugin catalog, a database that stores information about available plugins, or modify loaded plugins of a Vault instance.

`plugin list`

Show all available plugins that are configured in a Vaults instance plugin catalog. Naturally, on a fresh installation, these plugins reflect the complete list of built-in variants.

The following code blocks show which auth, database, and secret plugins are available in hashicorp_vault_v1.21.1.

> vault plugin list auth

# Log messages
Name          Version
----          -------
alicloud      v0.22.0+builtin
approle       v1.21.1+builtin.vault
aws           v1.21.1+builtin.vault
azure         v0.22.0+builtin
cert          v1.21.1+builtin.vault
cf            v0.22.0+builtin
gcp           v0.22.0+builtin
github        v1.21.1+builtin.vault
jwt           v0.25.0+builtin
kerberos      v0.16.0+builtin
kubernetes    v0.23.1+builtin
ldap          v1.21.1+builtin.vault
oci           v0.20.0+builtin
oidc          v1.21.1+builtin.vault
okta          v1.21.1+builtin.vault
pcf           v1.21.1+builtin.vault
radius        v1.21.1+builtin.vault
userpass      v1.21.1+builtin.vault

> vault plugin list database

# Log messages
Name                                 Version
----                                 -------
cassandra-database-plugin            v1.21.1+builtin.vault
couchbase-database-plugin            v0.15.0+builtin
elasticsearch-database-plugin        v0.19.0+builtin
hana-database-plugin                 v1.21.1+builtin.vault
influxdb-database-plugin             v1.21.1+builtin.vault
mongodb-database-plugin              v1.21.1+builtin.vault
mongodbatlas-database-plugin         v0.16.0+builtin
mssql-database-plugin                v1.21.1+builtin.vault
mysql-aurora-database-plugin         v1.21.1+builtin.vault
mysql-database-plugin                v1.21.1+builtin.vault
mysql-legacy-database-plugin         v1.21.1+builtin.vault
mysql-rds-database-plugin            v1.21.1+builtin.vault
postgresql-database-plugin           v1.21.1+builtin.vault
redis-database-plugin                v0.7.0+builtin
redis-elasticache-database-plugin    v0.8.0+builtin
redshift-database-plugin             v1.21.1+builtin.vault
snowflake-database-plugin            v0.15.0+builtin

> vault plugin list secret

# Log messages
Name            Version
----            -------
ad              v0.21.0+builtin
alicloud        v0.21.0+builtin
aws             v1.21.1+builtin.vault
azure           v0.23.0+builtin
consul          v1.21.1+builtin.vault
gcp             v0.23.0+builtin
gcpkms          v0.22.0+builtin
kubernetes      v0.12.0+builtin
kv              v0.25.0+builtin
ldap            v1.21.1+builtin.vault
mongodbatlas    v0.16.0+builtin
nomad           v1.21.1+builtin.vault
openldap        v0.17.0+builtin
pki             v1.21.1+builtin.vault
rabbitmq        v1.21.1+builtin.vault
ssh             v1.21.1+builtin.vault
terraform       v0.13.0+builtin
totp            v1.21.1+builtin.vault
transit         v1.21.1+builtin.vault

`plugin info`

Prints detailed information about a plugin.

For example, the built-in kv secret plugin is shown as this:

> vault plugin info secret kv

# Log messages
Key                   Value
---                   -----
args                  []
builtin               true
command               n/a
deprecation_status    supported
name                  kv
oci_image             n/a
runtime               n/a
sha256                n/a
version               v0.25.0+builtin

`plugin register`

In addition to the built-in plugins provided with the vault binary itself, several external and community plugins can be added too. This command assumes that the plugin is provided as a binary, executable file stored in the plugin directory path. Additional flags to this command control metainformations like the version, plugin parameters, and a sh256 sum of the binary file.

The documentation about Vault plugin ecosystem provides additional information and sources for different plugin types.

`plugin deregister`

Removes a manually added plugin from the local catalog, either completely, or a dedicated version by passing the same named flag to the command.

It is not possible to remove a built-in plugin - an attempt is shown in the following:

> vault plugin deregister secret aws

# Log messages
Plugin "aws" (type: "secret") is a built-in plugin and cannot be deregistered

`plugin reload`

Re-initializes a configured plugin with the default options. This method is helpful when a newer version of a plugin is installed, and should be loaded without a shutdown of the complete Vault instance. All type of plugins can be reloaded as shown by the following example.

> vault plugin reload -type=secret -plugin=kv

# Log messages
Success! Reloaded plugin: kv

`plugin reload-status`

Shows metainformation about a concrete reload action, requiring the reload ID.

However, I could not find information about where to obtain a reload ID. And when running the command with an example ID from its documentation, the following error message is returned.

> vault plugin reload-status d60a3e83-a598-4f3a-879d-0ddd95f11d4e

# Log messages
Error retrieving plugin reload status: Error making API request.

URL: GET http://127.0.0.1:8210/v1/sys/plugins/reload/backend/status?reload_id=d60a3e83-a598-4f3a-879d-0ddd95f11d4e
Code: 404. Errors:

* enterprise-only feature

`plugin runtime`

This subcommand interacts directly with the running Vault instance plugins, and supports the sub-subcommands info, list, register and deregister which work similarly as their plugin catalog counterparts.

At the time of writing, the runtime command only supports custom plugins of type container as the following explanation from the CLI itself exposes:

> vault plugin runtime --help

# Log messages
Usage: vault plugin runtime <subcommand> [options] [args]

  This command groups subcommands for interacting with Vaults plugin runtimes and the
  plugin runtime catalog. The plugin runtime catalog is divided into types. Currently,
  Vault only supports "container" plugin runtimes

CRUD Operations

Hashicorp Vault exposes its complete functionality via API endpoints. And these endpoints can be operated via CRUD operations directly via the CLI. Internally, the CLI will transform the commands to confirm with the REST-API design of its endpoint, issuing HTTP requests.

To see the CRUD operations in action, two different types of data are covered in the following examples: A kv-v2 secret engine, and their appropriate access policies.

The kv-v2 secret engine will be mounted at /kv-secrets with the following command.

> vault secrets enable -max-lease-ttl=1h -path=kv-secrets kv-v2

# Log messages
Success! Enabled the kv-v2 secrets engine at: kv-secrets/

`write`

The write operation creates a new dataset.

To add a new kv-v2 secret, the path structure <mount_path>/data/<secret_name> must be used. Furthermore, the data needs to be stored in a file, and provide via the @ sign.

First, create a file with the following content:

{
  "data": {
    "admin": "CjE3OjAwIEtvY2hlbiwg"
  },
  "options": {
    "cas": 0
  }
}

Second, write the secret config-db-credentials with the following command:

> vault write kv-secrets/data/config-db-credentials @secret.json

# Log messages
Key                Value
---                -----
created_time       2025-12-16T11:03:52.838769Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Next, create a read-only policy for non-admin users:

vault write sys/policy/kv-secrets policy='path "kv-secrets/*" {
  capabilities = ["read"]
}'

# Log messages
Success! Data written to: sys/policy/kv-secrets

`read`

The read operation prints stored data.

To access the secret, the path kv-secrets/metadata must be used in the request:

> vault read kv-secrets/metadata/config-db-credentials

# Log messages
Key                     Value
---                     -----
cas_required            false
created_time            2025-12-16T11:03:52.838769Z
current_version         1
custom_metadata         <nil>
delete_version_after    0s
last_updated_by         map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:create]
max_versions            0
oldest_version          0
updated_time            2025-12-16T11:03:52.838769Z
versions                map[1:map[created_by:map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:create] created_time:2025-12-16T11:03:52.838769Z deleted_by:<nil> deletion_time: destroyed:false]]

> vault read sys/policy/kv-secrets

# Log message
Key      Value
---      -----
name     kv-secrets
rules    path "kv-secrets/*" {
  capabilities = ["read"]
}

`list`

While the read operation returns a single entry with complete details, calling list shows all defined entries with their names.

Assuming additional secrets were added to the kv-v2 secret store:

> vault list kv-secrets/metadata

# Log messages
Keys
----
app-credentials
config-db-credentials
config-portal-credentials

The same operation applied to the policies returns the complete set of all system and user defined objects.

> vault list sys/policy/

# Log messages
Keys
----
default
kv-secrets
root

`patch`

To update configuration parts of an existing entry, the patch command can be used.

To update a kv-v2 entry, the payload file needs to be changed as follows:

// change cas value to the current version of the secret
{
  "data": {
    "admin": "CjE3OjAwIEtvY2hlbiwg"
  },
  "options": {
    "cas": 1
  }
}

Then perform the update:

> vault patch kv-secrets/data/config-db-credentials @secret.json

# Log messages
Key                Value
---                -----
created_time       2025-12-16T13:29:38.764223Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

And for the policy, the access rights shall be expanded.

However, executing the patch command returns an error - policies cannot be changed, merely redefined.

> vault patch sys/policy/kv-secrets policy='path "kv-secrets/*" {
  capabilities = ["read", "create"]
}'

# Log messages
Error writing data to sys/policy/kv-secrets: Error making API request.

URL: PATCH http://127.0.0.1:8210/v1/sys/policy/kv-secrets
Code: 405. Errors:

* 1 error occurred:
 * unsupported operation

The redefinition takes the form of another write command.

> vault write sys/policy/kv-secrets policy='path "kv-secrets/*" {
  capabilities = ["read", "create"]
}'

# Log messages
Success! Data written to: sys/policy/kv-secrets

`delete`

When data is not required anymore, a delete command safely erases it.

To delete a stored secret in the kv-v2 store:

> vault delete kv-secrets/metadata/config-db-credentials

# Log messages
Success! Data deleted (if it existed) at: kv-secrets/metadata/config-db-credentials

And to delete the policy:

> vault delete sys/policy/kv-secrets

# Log messages
Success! Data deleted (if it existed) at: sys/policy/kv-secrets

Conclusion

All operational and configurational Vault tasks can be implemented with the vault binary. In this article, CLI commands from the configuration group were explored. First, you learned about the plugin command, which gives either access to a static database, or reflects respectively modifies the runtime status of plugins. Second, you learned about the generic CRUD commands write, read, list, patch and delete, which can modify core Vault configuration data as well as data stored in its activated plugins.

Hashicorp Vault: TOTP Secrets Engine

Sebastian — Thu, 22 Jan 2026 05:57:30 +0000

In Hashicorp Vault, secrets are distinguished into static and dynamic. Static secrets are more long-term, stored encrypted in Vault, and given access to by tokens. Dynamic Secrets are created on demand at the target application when a token is issued, and removed when the token expires or is explicitly revoked. All secrets engines fall into one or the other category.

The TOTP secret engine is an exception. It creates one-time-password (OTP) tokens that are secrets themselves. In terms of password strength, they are rather weak with only 6-8 digits, but their lifetime is limited to typically 30 seconds. The primary use case is to show token ownership in this short lifespan, typically as a second factor when authenticating with a third party system.

This blog article is a complete coverage of the TOTP secrets engine. It shows the setup, groups and explains all API methods, and finally shows an application example.

The background material for this article stems from the official Hashicorp Vault documentation about TOTP secrets engine and TOTP secrets engine (API).

This blog article originally appeared at my blog admantium.com.

TOTP Secrets Engine

In Hashicorp Vault, secrets engines issue tokens that provide access to stored secrets. The default mechanism to implement this function is that a system or user authenticates with Vault, receives a token to which a policy is attached, and then uses this token to access other mount paths in the Vault instance. With the TOTP secrets engine, the secrets themselves are tokens - cryptographically rather weak with only 6-8 digits, but a very short time span and only one valid token at a time

The TOTP secrets engine can be used in two different roles. One role is the OTP generator. External applications that support second factor authentication expose a configuration URL. When this URL is registered as a Vault TOTP engine key, OTPs can be generated from it that are valid for the external application. The second role is as an OTP provider. Vault itself exposes API endpoints for generating short-lived OTPs, and provides an additional endpoint that validates these tokens.

In essence, the TOTP secrets engine issues one-time usable, short-lived secrets that are used as second factor when authenticating with external systems.

Setup

The TOTP engine must be enabled via GUI or CLI - the later will be used as it is in all other articles of this blog series.

> vault secrets enable -path /totp totp

# Log messages
[INFO]  core: successful mount: namespace="" path=totp/ type=totp version="v1.21.1+builtin.vault"

It offers a slim set of 6 API methods which are covered in the following sections.

Create Keys

Encryption keys are required for the TOTP engine to create its secrets. Either external keys are imported to Vault, or the keys are generated with Vault. Dependent on these, the API method features slightly different parameters.

To create a new key, the generate option must be passed. This option allows to configure the key size, the issuer and account name. To import a key, its remote URL and root key need to be defined.

Other options include to print the resulting URL for accessing the Vault key server, the hashing algorithm, the number of digits of the generated code (6 to 8), and the period time with which new TOTP codes will be generated.

POST /totp/keys/{name}

Manage Keys

To see the managed keys, a list can be created that contains only identification key.

GET /totp/keys/

All details of a specific key can be printed with a specific endpoint.

GET /totp/keys/{name}

Identified keys can be revoked. All currently issued TOTP tokens will also loose their viability immediately.

DELETE /totp/keys/{name}

Create or Validate Tokens

For a configured key, short-lived secrets can be created. Vault uses the key to generate a 6-8 digit value that is returned to the caller.

GET /totp/code/{name}

To validate a TOTP secret, it can be sent to the following endpoint, using the name of the key as an URL parameter, and a JSON structured request body containing the secret.

POST /totp/code/{name}

TOTP Secrets Engine Example: OTP Provider

In this example, Vault will be used as a provider for one-time passwords.

Once the OTP engine is mounted, a new key can be generated. Required parameters include the sub-path at the mount path, and meta data about the key issuer and his account name.

> vault write totp/keys/vault-otp \
    generate=true \
    issuer="Hashicorp Vault" \
    account_name=vault-otp@example.org

# Log messages
Key        Value
---        -----
barcode    iVBORw0KGgoA...
url        otpauth://totp/Hashicorp%20Vault:vault-otp@example.org?algorithm=SHA1&digits=6&issuer=Hashicorp+Vault&period=30&secret=E64DAQLJ35PEXAPFT4TYODI4KJZQGTZ4

For creating an OTP, two options exist.

One option is to use the Vault GUI. Navigating to the secrets engines section, selecting the key-name, and then the following dialog appears:

The second option is the use the HTTP API.

> curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request GET \
  http://127.0.0.1:8210/v1/totp/code/vault-otp

# Log messages
{
  "request_id": "a912546e-9454-3354-ad5d-52731f09225f",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "code": "306037"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "totp"
}

The generated code can be validated via the Vault CLI and the API. The API access can be used universally from other applications too, and is shown here.

Here is an example for the latter:

> curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"code" : "306037"}' \
  http://127.0.0.1:8210/v1/totp/code/vault-otp

# Log messages
{
  "request_id": "cfa70339-189c-bd4a-bda0-13feaf6ccf51",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "valid": true
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "totp"
}

Conclusion

Secrets engines govern access to and the creation of confidential data for various purposes. The TOTP secrets engine issues short-lived secrets, typically used as one-time-passwords. This compact blog article provided a complete coverage. It showed how to setup the engine at a defined path, explored the API methods to setup keys that create token, and the method for creating and validating secrets. An example showed how to uses these API methods. Overall, this engine fully complements Hashicorp Vault functionality as a tool for second-factor authentication.

Hashicorp Vault: Transit Secrets Engine

Sebastian — Mon, 12 Jan 2026 06:22:00 +0000

In Hashicorp Vault, secrets engines provide a uniform way to store and manage credentials, encryption keys, certificates and other sensitive information. To gain access to a secret, a typically time restricted token is generated. With this token, the secret can be read by any client application.

Secrets themselves can be static or dynamic. A static secret is stored as-is, and has a typical lifetime of several weeks or even months. Dynamic secrets are created on-demand with a limited lifetime of several hours or days, and are revoked at the end of their lifetime.

The transit secrets engine manages dynamic secrets to facilitate exchange between several applications. It stores generated or externally keys imported into Vault, and uses these keys to encrypt/decrypt data. This discusses the principal usage, covers all API endpoints, and shows a practical example.

The background material for this article stems from the official Hashicorp Vault documentation about Transit secrets engine and Transit secrets engine (API).

This article originally appeared at my blog admantium.com.

Transit Secrets Engine

In Hashicorp Vault, secrets engine can be accessed with a proper token, and provide different endpoints for their functionality. With the Transit Secrets engine, the stored secrets are key themselves, in different formats such as AES or RSA.

Based on these keys, different functions are offered. The main use-case is the encryption and decryption of plaintext data, where the data itself is not stored in Vault. Other functions are to sign and verify data, to create hash values for data as a means to validate data integrity, as well as to generate random bytes as entropy input to external encryption processes.

In essence, the transit secrets engine provides encryption-as-a-service. Applications do not need to implement encryption functions themselves, but can access a Hashicorp Vault server instance instead.

Setup

To initialize the transit secrets engine, it needs to be enabled via the CLI or the GUI. Continuing the focus in this blog series, CLI commands will be shown.

> vault secrets enable -path /transit transit

# Log messages
[INFO]  core: successful mount: namespace="" path=transit/ type=transit version="v1.21.1+builtin.vault"

No other configuration steps are necessary. The mounted transit secrets engine provides 39 different API methods for its core functionality, key management, and general operation. Following subsections explore them in detail.

Encryption Keys

The transit engine stores encryption keys with which data is decrypted and encrypted. It is possible to import keys and to generate new ones.

The key generation API method creates an RSA key with specified bit length and padding scheme. Additionally, key derivation context data and a nonce can be used. The endpoint either returns the key in plaintext or in cipher form.

POST  /transit/datakey/{plaintext}/{name}

A new key can also be generated with a CSR. The endpoint generates the key and stores it internally.

POST  /transit/keys/{name}/csr

It is also an option to import an external key, which can be variants of aes and rsa, as well as ed25519 and hmac.

First of all, the engines public key needs to be generated with the following endpoint.

GET /transit/wrapping_key

Second, following the instructions about bring your own key, a ciphertext needs to be created, which is an Vault-internal data format for the key. The ciphertext, key-type, and additional key-specific parameters are then passed to the following endpoints.

POST  /transit/keys/{name}/import
POST  /transit/keys/{name}/import_version

Encrypt and Decrypt Data

The data encryption endpoints require in its most essential form only the key name and the base64 encoded plaintext. When the used key is configured with key derivation, then also its context and associated data must be provided. For older versions of Vault, the nonce value could be provided - it is still an endpoint parameter, but not required. Finally, it is also possible to encrypt several plaintexts as well, requiring a structured JSON List with items that include the plaintext parameters, and others required for the targeted key.

POST  /transit/encrypt/{name}

The complementing decryption endpoint requires the key name and the ciphertext. Additional parameters are the same as of the encryption endpoint.

POST  /transit/decrypt/{name}

Sign and Verify Data

Encryption keys stored in the transit engine can be used to sign data. Several parameters can be provided to configure the signing process: key version, hash algorithm, signature and marshaling algorithm, and the used salt. Input data can be single, base64 encoded text, or a structured JSON format with a list of strings. The signing process returns a Vault-specific signature string.

POST  /transit/sign/{name}
POST  /transit/sign/{name}/{algorithm}

To verify data, the complementary endpoint can be used. It requires the original input (single text or structured JSON), and the signature string. Additional parameters used during signing, such as the key version and hash algorithm, can be provided too. Furthermore, this endpoint can also be used for verifying HMAC data.

POST  /transit/verify/{name}
POST  /transit/verify/{name}/{algorithm}

Creating HMAC Values

In cryptography, the message authentication code (MAC) is a unique signature for an arbitrary payload data and key. When two parties share the key, they can authenticate and check the integrity of exchanged messages.

Hashicorp Vault provides and endpoint to sign data using a hash function. The key name must be provided, optionally the hash algorithm, and mandatory the single or structured plaintext data.

POST  /transit/hmac/{name}
POST  /transit/hmac/{name}/{algorithm}

The returned HMAC data can be verified with the above explained /transit/verify endpoint.

Creating Hash Values

Hash values of data are unique identifiers that can be used to ensure data integrity. Hash values can be created for any base64 encoded input data, and returned as either base64 or hex value. Also, different sha2 and sha3 algorithms are supported.

POST  /transit/hash
POST  /transit/hash/{algorithm}

Creating Random Bytes

Random data can be used as a nonce for encrypting data. The available API endpoints return base64 or hex encoded values of defined byte length. Additionally, the entropy source from which the bytes are generated can be configured: either the virtual or physical server itself, or with the entropy augmentation feature from an enterprise vault.

POST  transit/random
POST  transit/random/{source}
POST  transit/random/{source}/{bytes}
POST  transit/random/{bytes}

Manage Encryption Keys

All configured keys can be read-accessed, returning type information and optionally the ciphertext, a Vault internal data form representing the key. For some keys, their internal configuration can be retrieved too.

GET /transit/keys/
GET /transit/keys/{name}
GET /transit/config/keys

Existing keys can be updated or deleted.

POST  /transit/keys/{name}
DELETE  /transit/keys/{name}

Some aspects of managed keys can be reconfigured without creating new keys.

POST  /transit/config/keys`
POST  /transit/keys/{name}/config

Key rotation is a security best practice, and implemented in Vault by a dedicated API method. Stored key versions are kept indefinitely, but limits can be set via key configuration, or explicitly trimmed.

POST  /transit/keys/{name}/rotate
POST  /transit/keys/{name}/trim

When keys are versioned, older ciphertexts are not valid anymore. They can be rewrapped to the newest version of a key.

POST  /transit/rewrap/{name}

For stored keys, the corresponding certificate chain can be configured. Please note: The documentation does not detail if this method is only applicable to keys created with the CSR endpoint, data keys, or imported keys.

POST  /transit/keys/{name}/set-certificate

When the keys need to be migrated to an external system, they can be explicitly exported. The API methods are differentiated into keys created with the transit engine itself or externally created keys. The export itself targets either the most recent version of a key, or a very specific version identified by a time string.

GET /transit/export/{type}/{name}
GET /transit/export/{type}/{name}/{version}
GET /transit/byok-export/{destination}/{source}
GET /transit/byok-export/{destination}/{source}/{version}

Backup and Restore

For any managed key, a complete plaintext backup can be generated. This contains the keys ciphertext, its HMAC, and its version information. A corresponding endpoint can be used to restore keys from their backup data.

GET transit/backup/{name}
POST  transit/restore
POST  transit/restore/{name}

Cache Management

The transit secrets engine internally caches its responses. The current number of items in the cache can be read, and the maximum allowed number of cached items can be seat (but requires a reload of the plugin to become effective).

GET transit/cache-config
POST  transit/cache-config

Transit Secrets Engine Example: Date Encryption and Decryption

In this example, a transit secrets engine with an internally managed key will be setup.

First of all, the engine itself needs to be created.

> vault secrets enable -path /transit transit

# Log messages
[INFO]  core: successful mount: namespace="" path=transit/ type=transit version="v1.20.0+builtin.vault"

Next, a key will be generated.

> vault write transit/keys/cha type=chacha20-poly1305

# Log messages
Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        0s
deletion_allowed          false
derived                   false
exportable                false
imported_key              false
keys                      map[1:1760175423]
latest_version            1
min_available_version     0
min_decryption_version    1
min_encryption_version    0
name                      cha
supports_decryption       true
supports_derivation       true
supports_encryption       true
supports_signing          false
type                      chacha20-poly1305

With the key in place, let’s explore the decryption and encryption of data.

First, the plaintext data needs to be base64 encoded:

> echo "Lorem ipsum dolor sit amet"|base64

# Log messages
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQK

This encoded text needs to be sent to the key endpoint.

> vault write transit/encrypt/cha plaintext="TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQK"

# Log messages
Key            Value
---            -----
ciphertext     vault:v1:KihZ/vP/a/4Jk7N0533I1bj+TGWE526HrMyr1V6+RJYCPNsGv1XQxDGxQoUBRDuYE8qyNRk7bQ==
key_version    1

The ciphertext starts with the metainformation vault:v1:, followed by the decrypted text. Decryption is straightforward:

> vault write transit/decrypt/cha ciphertext="vault:v1:KihZ/vP/a/4Jk7N0533I1bj+TGWE526HrMyr1V6+RJYCPNsGv1XQxDGxQoUBRDuYE8qyNRk7bQ=="

# Log messages
Key          Value
---          -----
plaintext    TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQK

Vault supports key rotation, and therefore decryption requires to specify the key version too. Once a newer key is in use, old ciphertext versions need to be rewrapped.

Let’s rotate the key twice.

> vault write -force transit/keys/cha/rotate
> vault write -force transit/keys/cha/rotate

# Log messages
Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        0s
deletion_allowed          false
derived                   false
exportable                false
imported_key              false
keys                      map[1:1760175423 2:1760177345 3:1760177350]
latest_version            3
min_available_version     0
min_decryption_version    1
min_encryption_version    0
name                      cha
supports_decryption       true
supports_derivation       true
supports_encryption       true
supports_signing          false
type                      chacha20-poly1305

Then, try to decrypt the ciphertext, but alter its metainformation.

> vault write transit/decrypt/cha ciphertext="vault:v2:KihZ/vP/a/4Jk7N0533I1bj+TGWE526HrMyr1V6+RJYCPNsGv1XQxDGxQoUBRDuYE8qyNRk7bQ=="

# Log messages
Error writing data to transit/decrypt/cha: Error making API request.

URL: PUT http://127.0.0.1:8210/v1/transit/decrypt/cha
Code: 400. Errors:

* chacha20poly1305: message authentication failed

Let’s rewrap the ciphertext ...

> vault write transit/rewrap/cha ciphertext="vault:v1:KihZ/vP/a/4Jk7N0533I1bj+TGWE526HrMyr1V6+RJYCPNsGv1XQxDGxQoUBRDuYE8qyNRk7bQ=="

# Log messages
Key            Value
---            -----
ciphertext     vault:v3:W1lRpdvej7N5IEWuxqOqLSiYCibD0/cu9lLNXt1fhInGxTrLkvuXUyf3I4AqdQj8VbCALvjZrA==
key_version    3

.. and then decrypt it:

> vault write transit/decrypt/cha ciphertext="vault:v3:W1lRpdvej7N5IEWuxqOqLSiYCibD0/cu9lLNXt1fhInGxTrLkvuXUyf3I4AqdQj8VbCALvjZrA=="

# Log messages
Key          Value
---          -----
plaintext    TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQK

Old versions of a key can be removed intentionally, but any non-rewrapped ciphertext is then irrevocably lost. To remove old versions, the values min_decryption_version and min_encryption_version should be set to the desired version, and a background job in the Vault instance deletes non-required versions eventually.

> vault write transit/keys/cha/config min_decryption_version=3 min_encryption_version=3

# Log messages
Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        0s
deletion_allowed          false
derived                   false
exportable                false
imported_key              false
keys                      map[3:1760177350]
latest_version            3
min_available_version     0
min_decryption_version    3
min_encryption_version    3
name                      cha
supports_decryption       true
supports_derivation       true
supports_encryption       true
supports_signing          false
type                      chacha20-poly1305

Conclusion

In Hashicorp Vault, secrets engines manage setup and access to confidential data. The transit secrets engine provides a special use case: Encryption and decryption of plaintext data without actually storing it. This blog post introduced and showed how to setup and use this engine. The first step is the generation or import of a key, supporting different variants of AES, RSA, and ED25519. Once stored, several endpoints for various use cases become available. The encryption endpoint accepts base64 encoded plaintext, and returns a ciphertext. Likewise, the decryption endpoint expects to be passed the full ciphertext, and will return the base64 decoded base text. These texts are not stored at all in Vault - client applications are expected to handle them. Additional endpoints support signing and verifying data, creating HMAC values or hash values, and random bytes. Overall, the transit secrets' engine features complement the Vault functionality with a secrets-as-a-service component.

Hashicorp Vault: Fine-Grained Access Control with Policies

Sebastian — Thu, 01 Jan 2026 06:39:46 +0000

Hashicorp Vault is a flexible secret management engine. It provides several authentication and authorization mechanisms, and stores secrets that represent credentials, ciphers, or certificates. To access Vaults functionality, successful authentication is required, resulting in an access token and associated policies. These policies determine which actions on which mount paths are allowed.

This blog article details Hashicorp Vault policies. It shows how to write policies in HCL, explains the action words and paths patterns, and shows several practical examples.

The background material for this article stems from the official Hashicorp Vault documentation about Policies and the tutorial Access controls with Vault policies.

This article originally appeared on my blog admantium.com.

Access Control Essential

Policies encode which actions, such as writing, reading or deleting, are allowed at specific mount paths of a Vault instance. Essentially, in a Vault instance, all functionality is accessible by mount paths. Both CLI commands and explicit HTTP API requests targets these paths. Policies underlie every interaction: For example, in order to create a token, the write action to path /auth/token/create is required. Any path and any action that is not part of a policy is denied.

Two built-in policies exist. The root policy provides complete access to all paths, and allows all actions. It is attached to the root token so that an administrator can setup a Vault instance initially. A complementing policy is named default. It is attached to all tokens (unless explicitly removed), and governs essential self-referential lookup and data access for the token itself.

Policies consists of a path declaration, which can be a fixed absolute path or include wildcard segments, and a list of actions. Should a token have multiple policies with overlapping path declarations, all applicable policies are resolved following the priority matching ruleset. Then, path access and targeted actions are checked, so that the access is either granted or denied.

Finally, some paths are only accessible by the root policy itself, or when the sudo action is allowed for a specific path - see the documentation about root protected API endpoints.

Hashicorp Vault Policies

Hashicorp Vault policies are written in the Hashicorp Configuration Language.

Policy Declaration

In its most simple form, they consist of only two mandatory declarations: path and capabilities. Here is an example:

path "PATH" {
  capabilities = ["cap"]
}

Additionally, parameters passed to the HTTP API endpoints can be set to be explicitly allowed, denied, or required.

path "PATH" {
  capabilities = ["cap"]
  allowed_parameters = {
    "key" = ["values"]
  }
  denied_parameters = {
    "key" = ["values"]
  }
  required_parameters = {
    "key" = ["values"]
  }
}

Finally, some HTTP API endpoints can be used for response wrapping to e.g. protect a sensible secret. When the endpoint is accessed, the data will not be returned as is, but a one-time access token to a cubbyhole secret is returned. For this API endpoint, the response wrapping validity TTLs can be specified as shown:

path "PATH" {
  capabilities = ["cap"]

  min_wrapping_ttl = "time"

  max_wrapping_ttl = "time"
}

Path Declaration

The path declaration can be a fixed, absolute path with multiple segments, or encompass two different wildcard symbols that match segments.

With the symbol +, one segment is covered. For example, the declaration path /auth/token/+ would allow access to /auth/token/create but not to /auth/token/create/{role_name}.

With the * symbol, any number of path segments are matched. The declaration path /auth/token/* includes any paths that have a prefix of /auth/token, and therefore access to /auth/token/create/{role_name} and auth/token/roles/{role_name} is covered.

Policy Actions

The capabilities property is a list of action verbs. Following values can be used:

create: Add a new entity definition.
read: Provide read access to an entity definition.
update and patch: Rewrite an existing entity definition (there is no clear distinction about their scope in the official documentation, but the CLI command vault patch maps to the same named action)
delete: Remove an entity definition
list: Enumerate all entity definitions by their name or ID (to obtain the full details of an individual resource, the read access right is required)
sudo: Provide full access to the entity, as well access to the mentioned root protected API endpoints
deny: Bar any access to the resource.

Except sudo and deny, all other actions directly translate to HTTP verbs or CLI commands when performing an operation at the desired path.

Policy Examples

This section shows three policies for managing authentication methods, managing a secrets engine, and creating orphaned tokens.

CRUD access to a custom kv v2 engine

path "kv2/*"
{
  capabilities = ["create", "read", "update", "delete"]
}

Complete management access to AUTH methods

path "sys/auth"
{
  capabilities = ["create", "read", "update", "delete", "sudo"]
}

path "sys/auth/+/tune"
{
  capabilities = ["create", "read", "update", "delete", "sudo"]
}

Create Orphaned Tokens

path "auth/token/create"
{
  capabilities = ["create", "sudo"]
}

Conclusion

The secrets management tool Hashicorp Vault implements fine-grained access control with the help of policies. This blog article showed how to declare policies in the compact Hashicorp Configuration Language syntax. Essentially, they consist of two parts. First, a path declaration, which can be fixed and absolute, or flexible by including wildcard segments. Second, actions in the form of verbs such as create, delete, list, deny and sudo. Declared policies are attached to tokens, and when using a token to access a path, applicable policies are resolved and processed in priority order. Finally, this article showed three example policies for managing auth methods, configuring a defined kv v2 secrets engine, and for issuing orphaned tokens.

Hashicorp Vault: Fine-Grained Access Control with Policies

Sebastian — Wed, 31 Dec 2025 13:54:21 +0000

This blog article details Hashicorp Vault policies. It shows how to write policies in HCL, explains the action words and paths patterns, and shows several practical examples.

The background material for this article stems from the official Hashicorp Vault documentation about Policies and the tutorial Access controls with Vault policies.

This article originally appeared on my blog admantium.com.

Access Control Essential

Finally, some paths are only accessible by the root policy itself, or when the sudo action is allowed for a specific path - see the documentation about root protected API endpoints.

Hashicorp Vault Policies

Hashicorp Vault policies are written in the Hashicorp Configuration Language.

Policy Declaration

In its most simple form, they consist of only two mandatory declarations: path and capabilities. Here is an example:

path "PATH" {
  capabilities = ["cap"]
}

Additionally, parameters passed to the HTTP API endpoints can be set to be explicitly allowed, denied, or required.

path "PATH" {
  capabilities = ["cap"]
  allowed_parameters = {
    "key" = ["values"]
  }
  denied_parameters = {
    "key" = ["values"]
  }
  required_parameters = {
    "key" = ["values"]
  }
}

path "PATH" {
  capabilities = ["cap"]

  min_wrapping_ttl = "time"

  max_wrapping_ttl = "time"
}

Path Declaration

The path declaration can be a fixed, absolute path with multiple segments, or encompass two different wildcard symbols that match segments.

With the symbol +, one segment is covered. For example, the declaration path /auth/token/+ would allow access to /auth/token/create but not to /auth/token/create/{role_name}.

Policy Actions

The capabilities property is a list of action verbs. Following values can be used:

create: Add a new entity definition.
read: Provide read access to an entity definition.
update and patch: Rewrite an existing entity definition (there is no clear distinction about their scope in the official documentation, but the CLI command vault patch maps to the same named action)
delete: Remove an entity definition
list: Enumerate all entity definitions by their name or ID (to obtain the full details of an individual resource, the read access right is required)
sudo: Provide full access to the entity, as well access to the mentioned root protected API endpoints
deny: Bar any access to the resource.

Except sudo and deny, all other actions directly translate to HTTP verbs or CLI commands when performing an operation at the desired path.

Policy Examples

This section shows three policies for managing authentication methods, managing a secrets engine, and creating orphaned tokens.

CRUD access to a custom kv v2 engine

path "kv2/*"
{
  capabilities = ["create", "read", "update", "delete"]
}

Complete management access to AUTH methods

path "sys/auth"
{
  capabilities = ["create", "read", "update", "delete", "sudo"]
}

path "sys/auth/+/tune"
{
  capabilities = ["create", "read", "update", "delete", "sudo"]
}

Create Orphaned Tokens

path "auth/token/create"
{
  capabilities = ["create", "sudo"]
}