Secrets Engine SDK

Quickstart

Secrets Engine and docker pass are bundled with Docker Desktop.

Let's store a secret using docker pass in the OS Keychain and then inject it into a running container using Secrets Engine.

# Store `Foo` in the OS Keychain
$ docker pass set Foo=bar
# Tell docker to use the Secrets Engine using the `se://` URI on an environment variable
$ docker run --rm -e Foo=se://Foo busybox /bin/sh -c "echo \${Foo}"
$ bar

Developer Guides

How to query secrets

Use the client module in your project:

go get github.com/docker/secrets-engine/client

Use the client to fetch a secret:

c, err := client.New()
if err != nil {
    log.Fatalf("failed to create secrets engine client: %v", err)
}

// Fetch a secret from the engine
resp, err := c.GetSecrets(t.Context(), client.MustParsePattern("my-secret"))
if err != nil {
    log.Fatalf("failed fetching secrets: %v", err)
}
fmt.Println(resp.Value)

How to create a plugin

1. Implement the plugin interface

Use the plugin module in your project:

go get github.com/docker/secrets-engine/plugin

A plugin needs to implement the Plugin interface:

var _ plugin.Plugin = &myPlugin{}

type myPlugin struct {
	m      sync.Mutex
	secrets map[secrets.ID]string
}

func (p *myPlugin) GetSecret(_ context.Context, request secrets.Request) ([]secrets.Envelope, error) {
	p.m.Lock()
	defer p.m.Unlock()

	var result []secrets.Envelope
	for id, value := range p.secrets {
		if request.Pattern.Match(id) {
			result = append(result, secrets.Envelope{
				ID:    id,
				Value: []byte(value),
				CreatedAt: time.Now(),
			})
		}
	}
	return result, nil
}

func (p *myPlugin) Config() plugin.Config {
	return plugin.Config{
		Version: "v0.0.1",
		Pattern: "*",
	}
}

2. Build a plugin binary

Create a Go binary that use your plugin interface implementation and runs it through the plugin SDK:

package main

import (
	"context"

	"github.com/docker/secrets-engine/plugin"
)

func main() {
    p, err := plugin.New(&myPlugin{secrets: map[secrets.ID]string{"foo": "bar"}})
    if err != nil {
        panic(err)
    }
	// Run your plugin
    if err := p.Run(context.Background()); err != nil {
        panic(err)
    }
}

3. Test and verify the plugin:

The secrets engine is integrated with Docker Desktop. To verify your plugin works, run the binary. Using the SDK it will automatically connect to the secrets engine in Docker Desktop. Then, you can query secrets, e.g. using curl:

$ curl --unix-socket ~/Library/Caches/docker-secrets-engine/engine.sock \
    -X POST http://localhost/resolver.v1.ResolverService/GetSecrets \
    -H "Content-Type: application/json" -d '{"pattern": "foo"}'
{"id":"foo","value":"bar","provider":"docker-pass","version":"","error":"","createdAt":"0001-01-01T00:00:00Z","resolvedAt":"2025-08-12T08:25:06.166714Z","expiresAt":"0001-01-01T00:00:00Z"}