keyring: a library for uniformly accessing secrets

8.12

keyring: a library for uniformly accessing secrets🔗ℹ

The keyring library is a library to access various password stores in a uniform way. It is based loosely on the Python keyring library.

The base library contains a basic environment variable based backend. Additionally there are other backends that interface with other secret stores which can be installed separately.

keyring-secret-service-lib - Freedesktop Secret Service, used on Linux desktop
keyring-keychain-lib - Mac OSX Keychain
keyring-credential-locker-lib - Windows Credential Locker backend (TBD)
keyring-get-pass-lib - backend that prompts the user on the console for a password using the get-pass library documentation.

1 Front End Interface🔗ℹ

(require keyring)

package: keyring-lib

procedure
(keyring? v) → boolean?
v : any/c

procedure
(get-password service-name
username
[ #:keyring keyring]) → (or/c #f bytes?)
  service-name : string?
  username : string?
  keyring : keyring? = (default-keyring)

procedure
(set-password! service-name
username
password
[ #:keyring keyring]) → void?
  service-name : string?
  username : string?
  password : bytes?
  keyring : keyring? = (default-keyring)

procedure
(remove-password! service-name
username
[ #:keyring keyring]) → void?
  service-name : string?
  username : string?
  keyring : keyring? = (default-keyring)

procedure
(make-keyring-from-string keyring-spec) → keyring?
keyring-spec : string?

Constructs a keyring using the backend specified by the url string keyring-spec. This procedure will raise an exception that passes keyring-backend-load-error? if keyring-spec is not a valid url or if the backend cannot be loaded.

parameter
(default-keyring) → (or/c #f keyring?)
(default-keyring keyring) → void?
keyring : (or/c #f keyring?)

The default keyring to use. When the keyring module is loaded it reads the KEYRING environment variable and applies make-keyring-from-string to the value and sets default-keyring to the result.

1.1 Exceptions🔗ℹ

procedure
(keyring-error? v) → boolean?
v : any/c

procedure
(keyring-backend-error? v) → boolean?
v : any/c

procedure
(keyring-backend-error-name e) → (or/c #f string?)
e : keyring-backend-error?

procedure
(keyring-backend-load-error? v) → boolean?
v : any/c

procedure
(keyring-backend-load-error-name e) → (or/c #f string?)
e : keyring-backend-load-error?

2 Back End Interface🔗ℹ

(require keyring/interface)

package: keyring-lib

2.1 Struct Type Property Keyring Interface🔗ℹ

value
prop:keyring : struct-type-property?

2.2 Struct Generic Keyring Interface🔗ℹ

syntax
gen:keyring

procedure
(get-password-proc keyring
service-name
username) → (or/c #f bytes?)
  keyring : keyring?
  service-name : string?
  username : string?

procedure
(set-password-proc! keyring
service-name
username
password) → void?
  keyring : keyring?
  service-name : string?
  username : string?
  password : bytes?

procedure
(remove-password-proc! keyring
service-name
username) → void?
  keyring : keyring?
  service-name : string?
  username : string?

2.3 Class Keyring Interface🔗ℹ

interface
keyring<%> : interface?

method
(send a-keyring get-password service-name
username) → (or/c #f bytes?)
  service-name : string?
  username : string?
method
(send a-keyring set-password! service-name
username
password) → void?
  service-name : string?
  username : string?
  password : bytes?
method
(send a-keyring remove-password! service-name
username) → void?
  service-name : string?
  username : string?

3 Changelog🔗ℹ

3.1 0.11🔗ℹ

Release date: 2023/10/31

Move tests into separate packages.
Reorganize the backends around prop:keyring
Clean up error message formatting.
Log errors from raise procedures.
Add null backend as default when the KEYRING environment variable is not set.

3.2 0.10.1🔗ℹ

Release date: 2022/11/09

Add license metadata to packages.
Regular Github Actions testing setup.
Logging changes.

3.3 0.10.0🔗ℹ

Release date: 2021/04/18

Code cleanups.
Logging improvements.

3.4 0.9.0🔗ℹ

Release date: 2021/02/26

A raco command for accessing the keyrings.
A backend system that works with classes, generics, or plain structs.
Implemented Backends
- Mac OSX Keychain backend
- Secret Service backend
- environment variable backend
- get-pass backend
Environment based configuration