Secret engines

Secret engines are logical.Backend implementations mounted under arbitrary paths. They store, generate, encrypt, or transform data. Source: builtin/logical/ for built-ins, plugins/database/ for database plugins, and vault-plugin-secrets-* repos for external engines.

Purpose

Each secret engine owns a piece of the URL space and decides how to handle reads and writes there. They fall into a few patterns:

• Static stores: write a value once, read it back later. The canonical example is kv (versioned at v2). cubbyhole/ is a per-token version.
• Dynamic generators: every read mints a fresh credential with a lease (e.g. aws, database, consul, nomad).
• Crypto services: never store the data they operate on (e.g. transit encrypts/decrypts, pki issues certs, ssh signs SSH keys, totp generates codes).
• Identity-aware integrations: kubernetes, terraform, gcp, azure mint tokens or service accounts using Vault's identity.

Built-in engines (in this repo)

Mount type	Source	Pattern
aws	builtin/logical/aws/	Dynamic IAM credentials.
consul	builtin/logical/consul/	Consul ACL tokens.
database	builtin/logical/database/	Dispatcher to the database plugin protocol.
nomad	builtin/logical/nomad/	Nomad ACL tokens.
pki, pkiext	builtin/logical/pki/, builtin/logical/pkiext/	Certificate authority + ACME.
rabbitmq	builtin/logical/rabbitmq/	RabbitMQ users.
ssh	builtin/logical/ssh/	SSH OTP and CA-signed keys.
totp	builtin/logical/totp/	HOTP/TOTP token generation.
transit	builtin/logical/transit/	Crypto service: encrypt, decrypt, sign, verify, HMAC, datakey.

kv, the most-used engine, is not in this repo: it lives at hashicorp/vault-plugin-secrets-kv and is imported as a built-in.

External engines

helper/builtinplugins/registry_full.go imports and registers:

vault-plugin-secrets-ad (deprecated), vault-plugin-secrets-alicloud, vault-plugin-secrets-azure, vault-plugin-secrets-gcp, vault-plugin-secrets-gcpkms, vault-plugin-secrets-kubernetes, vault-plugin-secrets-mongodbatlas, vault-plugin-secrets-openldap (also aliased as ldap), vault-plugin-secrets-terraform.

Several legacy single-database engines (mssql, mysql, mongodb, postgresql, cassandra) are still listed but routed to removedFactory to fail mount with a friendly error.

Database plugins

Database secret engines have a shared dispatcher (builtin/logical/database/) and individual plugins under plugins/database/:

cassandra, hana, influxdb, mongodb, mssql, mysql, postgresql, redshift. Plus the third-party couchbase, elasticsearch, mongodbatlas, redis, redis-elasticache, snowflake. Each implements the database/v5 plugin protocol so the same database/ mount can manage many database types at once with a per-role config.

How a backend is built

Most backends follow the framework.Backend pattern from SDK:

func Backend(conf *logical.BackendConfig) *backend {
    var b backend
    b.Backend = &framework.Backend{
        Help:        backendHelp,
        Paths:       framework.PathAppend(b.paths(), b.rotatePaths(), ...),
        Secrets:     []*framework.Secret{b.cert(), b.key()},
        BackendType: logical.TypeLogical,
    }
    return &b
}

The framework auto-generates OpenAPI specs, help text, and capability checks from the *framework.Path definitions.

Lease management

When a backend's response includes a *logical.Secret, the expiration manager (vault/expiration.go) registers a lease, schedules its TTL, and calls back into the backend's revoke hook when the lease ends. See Expiration / leases.

How it works

graph LR
    Client --> HTTP[http/handler.go] --> Core --> Router
    Router -->|mount path lookup| SE[secret engine]
    SE -->|logical.Storage<br/>per-mount view| Barrier[AES-GCM barrier]
    Barrier --> Phys[physical backend]
    SE -->|logical.Response<br/>+ optional Secret| ExpMgr[expiration manager]

A backend never reads or writes outside its own storage view, so two engines mounted at different paths can't see each other's data even if they store the same key.

Integration points

• Mount lifecycle: see Router and mounts.
• Plugin catalog: external engines come from Plugin catalog.
• Identity: backends can call system.Identity* to introspect the caller's entity.
• Quotas: lease-count quotas in Quotas bound how many leases an engine can mint.

Entry points for modification

• Add a built-in engine: create builtin/logical/<name>/, register in helper/builtinplugins/registry.go (minimal) or registry_full.go (full).
• Add a database plugin: implement the v5 plugin protocol in plugins/database/<name>/ and register a name in helper/builtinplugins/registry_full.go.
• Add an external engine: build a separate binary using sdk/plugin/, register the import in helper/builtinplugins/registry_full.go.
• Add a feature to an existing engine: add a *framework.Path and matching handler.