keyring

package module
Version: v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 12, 2021 License: MIT Imports: 5 Imported by: 147

README

Go Keyring library

Build Status Build status Go Report Card GoDoc

go-keyring is an OS-agnostic library for setting, getting and deleting secrets from the system keyring. It supports OS X, Linux (dbus) and Windows.

go-keyring was created after its authors searched for, but couldn't find, a better alternative. It aims to simplify using statically linked binaries, which is cumbersome when relying on C bindings (as other keyring libraries do).

Potential Uses

If you're working with an application that needs to store user credentials locally on the user's machine, go-keyring might come in handy. For instance, if you are writing a CLI for an API that requires a username and password, you can store this information in the keyring instead of having the user type it on every invocation.

Dependencies

OS X

The OS X implementation depends on the /usr/bin/security binary for interfacing with the OS X keychain. It should be available by default.

Linux

The Linux implementation depends on the Secret Service dbus interface, which is provided by GNOME Keyring.

It's expected that the default collection login exists in the keyring, because it's the default in most distros. If it doesn't exist, you can create it through the keyring frontend program Seahorse:

  • Open seahorse
  • Go to File > New > Password Keyring
  • Click Continue
  • When asked for a name, use: login

Example Usage

How to set and get a secret from the keyring:

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)
}

Tests

Running tests

Running the tests is simple:

go test

Which OS you use does matter. If you're using Linux, it will test the implementation in keyring_linux.go. If running the tests on OS X, it will test the implementation in keyring_darwin.go.

Mocking

If you need to mock the keyring behavior for testing on systems without a keyring implementation you can call MockInit() which will replace the OS defined provider with an in-memory one.

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")
    }

}

Contributing/TODO

We welcome contributions from the community; please use CONTRIBUTING.md as your guidelines for getting started. Here are some items that we'd love help with:

  • The code base
  • Better test coverage

Please use GitHub issues as the starting point for contributions, new ideas and/or bug reports.

Contact

Contributors

Thanks to:

  • [your name here]

License

See LICENSE file.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound is the expected error if the secret isn't found in the
	// keyring.
	ErrNotFound = fmt.Errorf("secret not found in keyring")
)
View Source
var ErrUnsupportedPlatform = errors.New("Unsupported platform: " + runtime.GOOS)

All of the following methods error out on unsupported platforms

Functions

func Delete

func Delete(service, user string) error

Delete secret from keyring.

func Get

func Get(service, user string) (string, error)

Get password from keyring given service and user name.

func MockInit

func MockInit()

MockInit sets the provider to a mocked memory store

func Set

func Set(service, user, password string) error

Set password in keyring for user.

Types

type Keyring

type Keyring interface {
	// Set password in keyring for user.
	Set(service, user, password string) error
	// Get password from keyring given service and user name.
	Get(service, user string) (string, error)
	// Delete secret from keyring.
	Delete(service, user string) error
}

Keyring provides a simple set/get interface for a keyring service.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL