HushOsKeychain (hush_os_keychain v0.1.0)

Stores, fetches, and deletes generic passwords in macOS Keychain, Linux Secret Service, and Windows Credential Manager.

The service is the Hush key. The account comes from the :account option, then config :hush, Hush.Provider.OsKeychain, account: .... Writes default to the account "hush"; reads and deletes without an account search by service alone.

See the README for installation, Hush setup, OS tools, lookup rules, and platform and security limitations.

Summary

Types

error()

Functions

delete(service, opts \\ [])

Deletes the item stored under service, resolved the same way as fetch/2.

fetch(service, opts \\ [])

Fetches the secret stored under service.

format_error(error, service)

Formats an error returned by this module, naming the OS store and the service.

put(service, secret, opts \\ [])

Stores secret under service, replacing an existing item for the same account.

Types

error()

@type error() ::
  :not_found
  | {:unavailable, String.t()}
  | {:ambiguous, pos_integer()}
  | {:access_denied, String.t()}
  | {:invalid, String.t()}
  | {:platform, String.t()}
  | {:native_not_loaded, String.t()}

Functions

delete(service, opts \\ [])

@spec delete(String.t(), keyword()) :: :ok | {:error, error()}

Deletes the item stored under service, resolved the same way as fetch/2.

Options

:account - the account of the item

Examples

HushOsKeychain.delete("myapp.db_password")
#=> :ok

fetch(service, opts \\ [])

@spec fetch(String.t(), keyword()) :: {:ok, String.t()} | {:error, error()}

Fetches the secret stored under service.

Without an account, exactly one item with that service must exist.

Options

:account - the account of the item

Examples

HushOsKeychain.fetch("myapp.db_password")
#=> {:ok, "s3cret"}

HushOsKeychain.fetch("myapp.db_password", account: "ygor")
#=> {:error, :not_found}

format_error(error, service)

@spec format_error(error(), String.t()) :: String.t()

Formats an error returned by this module, naming the OS store and the service.

Examples

HushOsKeychain.format_error({:access_denied, "user canceled"}, "myapp.db_password")
#=> "macOS Keychain: access denied: user canceled (service \"myapp.db_password\")"

put(service, secret, opts \\ [])

@spec put(String.t(), String.t(), keyword()) :: :ok | {:error, error()}

Stores secret under service, replacing an existing item for the same account.

The account falls back to "hush" when none is configured.

Options

:account - the account of the item

Examples

HushOsKeychain.put("myapp.db_password", "s3cret")
#=> :ok