keyring: a library for uniformly accessing secrets

8.6

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 Back End Keyring Methods

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

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

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

2.2 Generic Keyring Interface

syntax
gen:keyring

value
prop:keyring : struct-type-property?

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?