secrets

go-secrets

A Go library that provides a unified interface for reading secrets from multiple backends. Switch between environment variables, Docker/Kubernetes mounted secrets, and credentials files without changing application code.

Installation

go get github.com/tommzn/go-secrets

Backends

All backends implement the same interface:

type SecretsManager interface {
    Obtain(key string) (*string, error)
}

Obtain returns a pointer to the secret value, or a *SecretNotFoundError when the key does not exist.

Usage

Environment variables

manager := secrets.NewSecretsManager()

value, err := manager.Obtain("DATABASE_URL")
if err != nil {
    // handle *secrets.SecretNotFoundError
}
fmt.Println(*value)

Key lookup is case-insensitive: Obtain("db_password") also matches DB_PASSWORD and Db_Password (the environment manager tries the original key, lowercase, and uppercase variants).

Docker / Kubernetes mounted secrets

// Use the default mount path /run/secrets
manager := secrets.NewDockerSecretsManager(secrets.DOCKER_SECRETS_PATH)

// Or a custom path
manager = secrets.NewDockerSecretsManager("/var/run/secrets/myapp")

value, err := manager.Obtain("db-password")

Each secret must be a separate file inside the secrets directory. The filename is the key. Key lookup is case-insensitive (the original key, lowercase, and uppercase variants are tried).

Credentials file

// ~ is expanded to the current user's home directory
manager := secrets.NewFileSecretsManager("~/.credentials")

value, err := manager.Obtain("db_password")

Credentials file format — one entry per line, key and base64-encoded value separated by ::

db_password:cGFzc3dvcmQxMjM=
api_key:c2VjcmV0a2V5eHl6

Encode a value:

echo -n "mysecretvalue" | base64

Security requirements for the credentials file:

• Permissions must be 0600 or stricter (no group or world read/write/execute; owner must have read access)
• The path must not be a symlink
• Key lookup in credentials files is case-sensitive — the key in the file must match exactly.

Static (for tests)

manager := secrets.NewStaticSecretsManager(map[string]string{
    "API_KEY": "test-key-123",
    "DB_URL":  "postgres://localhost/testdb",
})

value, err := manager.Obtain("API_KEY")

// Remove all secrets from memory when done
manager.(*secrets.StaticSecretsManager).Clear()

Export secrets to environment variables

ExportToEnvironment loads a list of secrets by key and sets each one as an environment variable. Keys that cannot be found are silently skipped.

manager := secrets.NewSecretsManager()
secrets.ExportToEnvironment([]string{"API_KEY", "DB_PASSWORD"}, manager)

Select backend from configuration

The library integrates with go-config. Set secrets.source in your config file to select a backend:

secrets:
  source: docker
  path: /run/secrets

conf, _ := config.NewFileConfigSource(&configFile).Load()
manager := secrets.NewSecretsManagerByConfig(conf)

Supported values for secrets.source:

Error handling

value, err := manager.Obtain("MISSING_KEY")
if err != nil {
    var notFound *secrets.SecretNotFoundError
    if errors.As(err, &notFound) {
        // key does not exist in this backend
    }
}

Security notes

• Credentials file: rejected if it has group or world permissions, or if the path resolves to a symlink.
• Docker backend: key names containing path separators (/, \) or traversal sequences (., ..) are rejected to prevent directory traversal attacks.
• Error messages: secret key names are never included in error messages to avoid leaking them into logs.
• Base64 in credentials files is encoding, not encryption. Protect the file with filesystem permissions and avoid committing it to version control.

License

MIT