zalando/go-keyring

The Linux/BSD implementation expects a default collection named login to exist. If it does not exist, you can create it using the seahorse frontend program:

1. Open seahorse.
2. Go to File > New > Password Keyring.
3. Click Continue.
4. When asked for a name, use: login.

The go-keyring library provides a simple, OS-agnostic API to manage secrets. You can use keyring.Set to store a secret, keyring.Get to retrieve it, and keyring.Delete to remove it. Secrets are identified by a combination of a service name and a user name.

package main

import (
    "log"

    "github.com/zalando/go-keyring"
)

func main() {
    service := "my-app"
    user := "anon"
    password := "secret"

    // set password
    err := keyring.Set(service, user, password)
    if err != nil {
        log.Fatal(err)
    }

    // get password
    secret, err := keyring.Get(service, user)
    if err != nil {
        log.Fatal(err)
    }

    log.Println(secret)
}

If you are running tests on a system without a keyring implementation (like a CI environment), you can use keyring.MockInit(). This replaces the OS-specific provider with an in-memory implementation, allowing you to test your logic without interacting with the actual system keychain.

package implementation

import (
    "testing"

    "github.com/zalando/go-keyring"
)

func TestMockedSetGet(t *testing.T) {
    keyring.MockInit()
    err := keyring.Set("service", "user", "password")
    if err != nil {
        t.Fatal(err)
    }

    p, err := keyring.Get("service", "user")
    if err != nil {
        t.Fatal(err)
    }

    if p != "password" {
        t.Error("password was not the expected string")
    }
}

On Linux and *BSD, the library uses the Secret Service API via D-Bus. You can use secret-tool (part of libsecret) to interact with it.

Installation:

• Debian/Ubuntu: sudo apt-get install libsecret-tools
• Fedora/RHEL: sudo dnf install libsecret
• Arch Linux: sudo pacman -S libsecret

Usage:

• Set a password: secret-tool store --label="<label>" service "<service>" username "<user>" (you will be prompted for the password, or you can pipe it in).
• Get a password: secret-tool lookup service "<service>" username "<user>"
• Delete a password: secret-tool clear service "<service>" username "<user>".

On macOS, you can use the security command to manage secrets. This is useful for debugging or scripting outside of Go.

• Set/Update a password: security add-generic-password -U -s "service" -a "user" -w "password" (the -U flag updates the password if it already exists).
• Get a password: security find-generic-password -s "service" -wa "user" (the -w flag ensures only the password value is output).
• Delete a password: security delete-generic-password -s "service" -a "user".

The keyring package provides a mock implementation to simulate keyring behavior in memory without interacting with the actual OS keychain. This is useful for unit testing or simulating environments where a real keyring is unavailable.

Use MockInit() to switch the global provider to an in-memory store. To revert to the platform's default keyring provider after your tests are complete, call MockRestore() (typically using defer).

func MockInit()
func MockRestore()
func MockInitWithError(err error)

Use Set(service, user, password string) to store a secret in the system's keyring. The service acts as a namespace for your application, and user identifies the specific account.

Note on data limits:

• macOS: The combined length of service, username, and password should not exceed ~3000 bytes.
• Windows: The service is limited to 32KiB and the password to 2560 bytes.
• Linux/Unix: No theoretical limit, but performance may degrade for values >100KiB.

If you need to test how your application handles keyring failures (e.g., permission denied or system errors), use MockInitWithError(err). This configures the mock provider to return the specified error for every operation (Set, Get, Delete, DeleteAll, and ListUsers).

func MockInitWithError(err error)