keyring

README

go-keyring

go-keyring stores opaque secrets in the current user's native credential store without CGo and just purego as a single dependency.

This implementation supports macOS Keychain, Windows Credential Manager, and Linux Secret Service. Open returns ErrUnavailable on unsupported platforms; it never falls back to plaintext storage.

import "github.com/nfx/go-keyring"

// ...

store, err := keyring.Open("com.example.app")
if err != nil {
	return err
}
defer store.Close()

err = store.Set(ctx, "api-token", token)

Payloads are artificially limited to 1Mb and secret keys are limited to 255 bytes. store.Set does not mutate its input; store.Get returns a fresh caller-owned byte slice. keyring.Wipe overwrites a slice on a best-effort basis but cannot erase runtime, operating-system, or credential-provider copies. Native calls on macOS and Windows are synchronous, so cancellation prevents a call from starting but cannot reliably interrupt one already in progress. On Linux, running the backend requires the distribution's libsecret-1.so.0, GLib/GIO/GObject, a local D-Bus session, and a Secret Service provider such as GNOME Keyring, KeePassXC, or KWallet. These are runtime prerequisites, not bundled dependencies. When they are missing or unusable, Open returns ErrUnavailable; the package never writes a plaintext fallback. Linux operations pass context cancellation to libsecret cooperatively. A canceled Set or Delete can have an indeterminate postcondition if the provider committed just before observing cancellation.

Documentation

Index

• Constants
• Variables
• func Wipe(b []byte)
• type Store
  • func Open(service string) (Store, error)
• type Stub
  • func (s Stub) Close() error
  • func (s Stub) Delete(_ context.Context, account string) error
  • func (s Stub) Get(_ context.Context, account string) ([]byte, error)
  • func (s Stub) Set(_ context.Context, account string, secret []byte) error

Constants

const (
	// MaxSecretSize is the largest secret supported by every native backend. macOS Keychain and
	// Linux Secret Service accept 16MB+ items natively; Windows Credential Manager's per-entry
	// limit is far smaller, so the Windows backend transparently splits larger secrets across
	// multiple credentials.
	MaxSecretSize = 1024 * 1024
)

Variables

var (
	// ErrNotFound reports that a requested credential does not exist.
	ErrNotFound = errors.New("keyring: item not found")
	// ErrUnavailable reports that the platform credential store cannot be used.
	ErrUnavailable = errors.New("keyring: native store unavailable")
	// ErrDenied reports that the credential store denied access.
	ErrDenied = errors.New("keyring: access denied")
	// ErrCanceled reports that the user canceled a credential-store prompt.
	ErrCanceled = errors.New("keyring: user canceled")
	// ErrClosed reports use after Close has started.
	ErrClosed = errors.New("keyring: store closed")
	// ErrInvalid reports an invalid service or account identifier.
	ErrInvalid = errors.New("keyring: invalid input")
	// ErrTooLarge reports a secret larger than MaxSecretSize.
	ErrTooLarge = errors.New("keyring: secret too large")
)

Functions

func Wipe

func Wipe(b []byte)

Wipe overwrites b in place on a best-effort basis.

Types

type Store

type Store interface {
	Set(ctx context.Context, account string, secret []byte) error
	Get(ctx context.Context, account string) ([]byte, error)
	Delete(ctx context.Context, account string) error
	Close() error
}

Store provides access to credentials in a service namespace.

func Open

func Open(service string) (Store, error)

Open initializes the credential store for service using the native backend.

type Stub

type Stub map[string][]byte

Stub is an in-memory backend suitable for unit testing. It stores secrets as []byte values keyed by "service:account".

func (Stub) Close

func (s Stub) Close() error

Close implements the Store interface for in-memory testing.

func (Stub) Delete

func (s Stub) Delete(_ context.Context, account string) error

Delete implements the Store interface for in-memory testing.

func (Stub) Get

func (s Stub) Get(_ context.Context, account string) ([]byte, error)

Get implements the Store interface for in-memory testing.

func (Stub) Set

func (s Stub) Set(_ context.Context, account string, secret []byte) error

Set implements the Store interface for in-memory testing.