sdk

github.com/hashicorp/vault/sdk is the framework for writing Vault plugins. It supplies the logical.Backend interface, the framework package that turns path declarations into a complete backend, the gRPC plumbing that connects an external plugin to Vault, and a large pile of helper packages for crypto, identity, parsing, testing, and more. Source: sdk/ (its own go.mod).

Purpose

• Define the contract every secret engine, auth method, and database plugin implements.
• Reduce boilerplate so a new plugin can be a few hundred lines of business logic and a Paths table.
• Provide reusable helpers for the operations every backend needs: cert parsing, key generation, password generation, LDAP, OCSP, idempotent storage, lease tracking.

Directory layout

sdk/
├── logical/                  # the core Backend, Request, Response types and protobufs
├── framework/                # The Framework backend: paths, fields, OpenAPI
├── plugin/                   # gRPC client/server, plugin v4/v5 Serve helpers
├── physical/                 # Backend interfaces + inmem backend
├── queue/                    # Priority queue used for rotating creds
├── rotation/                 # Helpers for credential rotation
├── database/                 # Database plugin interfaces (the "v5" protocol)
└── helper/                   # ~45 helper packages (see below)

The two big subtrees are logical/ and framework/. Everything else is supporting cast.

Key abstractions

Symbol	File	Description
logical.Backend	sdk/logical/logical.go	The core interface: Setup, HandleRequest, HandleExistenceCheck, Initialize, SpecialPaths, System, Cleanup.
logical.Request / Response	sdk/logical/request.go, response.go	The unit of work and result inside Vault.
logical.Storage	sdk/logical/storage.go	The barrier-prefixed view a backend sees.
logical.SystemView	sdk/logical/system_view.go	Limited handle to Core (mounts, namespace, license features, identity templating).
framework.Backend	sdk/framework/backend.go	A logical.Backend built from []*framework.Path.
framework.Path	sdk/framework/path.go	A regex pattern + fields + operations + help text.
framework.FieldData	sdk/framework/field_data.go	Typed access to request data.
framework.OpenAPI	sdk/framework/openapi.go	Auto-generates OpenAPI 3 from *framework.Paths.
framework.WALEntry, framework.PutWAL	sdk/framework/wal.go	Crash-resistant work logging for backends that mint external state.
plugin.Serve / Serve(s)	sdk/plugin/serve.go	What plugins call from main().

Plugin authoring

A minimal plugin's main.go:

package main

import (
    "github.com/hashicorp/vault/sdk/plugin"
    "github.com/example/vault-plugin-secrets-foo/foo"
)

func main() {
    err := plugin.ServeMultiplex(&plugin.ServeOpts{
        BackendFactoryFunc: foo.Factory,
    })
    if err != nil {
        panic(err)
    }
}

Inside foo:

func Factory(ctx context.Context, conf *logical.BackendConfig) (logical.Backend, error) {
    b := &backend{}
    b.Backend = &framework.Backend{
        Help:        "...",
        BackendType: logical.TypeLogical,
        Paths:       framework.PathAppend(b.paths()),
        Secrets:     []*framework.Secret{b.secret()},
    }
    if err := b.Setup(ctx, conf); err != nil {
        return nil, err
    }
    return b, nil
}

The plugin runs as a separate process and talks to Vault over gRPC. Everything else — capability checks, audit, leases, identity — is handled by Vault on the other side.

Database plugin protocol (v5)

sdk/database/ defines a typed protocol for database plugins that's distinct from the generic logical.Backend interface. It supports multiplexing — a single plugin process can serve many roles, which is what makes the unified database/ mount possible. sdk/plugin/plugin_v5.go is the multiplexing transport.

Helper packages

sdk/helper/ is a grab bag of ~45 packages that backends import. The most-used:

Package	Purpose
consts/	Shared string constants (plugin types, replication state, …).
certutil/	Certificate parsing, generation, marshalling — used by pki and others.
keysutil/	Symmetric/asymmetric key management used by transit.
ldaputil/	LDAP/AD client used by ldap auth method, openldap secrets, ad secrets.
ocsp/	OCSP client.
tokenutil/, roottoken/	Token format helpers.
policyutil/	Policy normalization and merge.
salt/	Salting for HMAC inputs.
pluginutil/, pluginidentityutil/, pluginruntimeutil/	Plugin lifecycle helpers.
template/	Username/credential templating.
testcluster/	Spin up multi-node test clusters (in-process and Docker).
testhelpers/	Generic test utilities.
useragent/	Standard Vault/<version> UA string.
password/	Random password generation per a policy.
wrapping/	Helpers around go-kms-wrapping wrappers.
mlock/	Memory locking on Linux.
parseutil/, cidrutil/, pointerutil/, strutil/	Small parsers and pointer helpers.
ldaputil/, kdf/, cryptoutil/, compressutil/	More crypto/compression helpers.
metricregistry/, logging/	Plumbing helpers for metrics and structured logging.
docker/	Helpers for spinning containers in tests.

If you're authoring a plugin, scan sdk/helper/ before writing your own version of anything.

Integration points

• vault.Core consumes plugins via helper/builtinplugins/ (in-process) or vault/plugincatalog/ (out-of-process via sdk/plugin).
• The HTTP layer constructs logical.Requests from incoming requests; sdk/logical/translate_response.go formats the response.
• framework.OpenAPI is consumed by vault openapi and the UI.
• Test clusters in sdk/helper/testcluster/ are used by core tests too, not just by plugin authors.

Entry points for modification

• Add a new field type for backends: extend sdk/framework/field_type.go and field_data.go.
• Add a new operation kind: extend sdk/logical/logical.go and framework.Path.Operations.
• Stabilize a helper currently in vault/: move it to sdk/helper/ if it makes sense for plugin authors.
• Bump the plugin protocol: see sdk/plugin/plugin_v5.go and the gRPC service definitions in sdk/plugin/pb/.