Passphrase caching

The SecretHub CLI supports caching your passphrase so you don’t have to retype your passphrase every single time you execute a command in the CLI. It caches your passphrase by default for 5 minutes, but you can configure it to your liking or disable it altogether.

How passphrase caching works

Passphrase caching works as follows:

  • The first time you use the SecretHub CLI, you will be asked for your passphrase.
  • Then, for the following 5 minutes, you won’t be prompted for your password again.
  • After the timer runs out, the passphrase is automatically cleared and you will be asked to type it in next time you use the CLI.

The timer is reset each time the passphrase is used from the cache. So as long as you keep using the CLI, it will not run out.

To illustrate the behavior, an example of three commands executed at different intervals is shown below:

# 12:00 - First execution prompts for passphrase
$ secrethub ls
Please put in the passphrase to unlock your key:
accept/
dev/
prod/
test/

# 12:02 - Second execution within cache window reads from cache and resets the timer.
$ secrethub ls
accept/
dev/
prod/
test/

# 12:07 - Third execution after the timer has run out prompts for the passphrase once more.
$ secrethub ls alice/coolapp
Please put in the passphrase to unlock your key:
accept/
dev/
prod/
test/

Modifying passphrase caching

To configure the time window a passphrase is cached, you can use the --credential-passphrase-cache-ttl command-line flag. You set this command-line flag to your custom duration, e.g. 1h for 1 hour. This is set by default to 5m to cache for 5 minutes.

To persistently configure passphrase caching, you can configure the SECRETHUB_CREDENTIAL_PASSPHRASE_CACHE_TTL environment variable, e.g. in your terminal profile. See this page for a more extensive explanation on how to configure command-line flags using environment variables.

The following command shows how you can use the environment variable to configure the CLI to cache the passphrase for a custom duration:

export SECRETHUB_CREDENTIAL_PASSPHRASE_CACHE_TTL=1h

Disabling passphrase caching

You can disable the passphrase caching if you require this. To disable it, set the value of the --credential-passphrase-cache-ttl command-line flag to 0. You do not have to disable the passphrase caching if you provide your passphrase using the environment variable SECRETHUB_CREDENTIAL_PASSPHRASE.

To persistently disable passphrase caching, you can configure the SECRETHUB_CREDENTIAL_PASSPHRASE_CACHE_TTL environment variable, e.g. in your terminal profile. See this page for a more extensive explanation on how to configure command-line flags using environment variables.

The following command shows how to use the disable the CLI to cache the passphrase:

export SECRETHUB_CREDENTIAL_PASSPHRASE_CACHE_TTL=0

Supported platforms

The CLI stores your passphrase in the OS keyring and is supported for the following platforms:

  • The Windows implementation uses the Windows Credential Manager API to store your passphrase. It should be available by default.
  • The Linux implementation depends on the Secret Service dbus interface, which is part of GNOME Keyring.
  • The macOS implementation depends on the /usr/bin/security binary for interfacing with the macOS Keychain. It should be available by default.

Passphrase caching is automatically turned off for operating systems that do not support it.

Security considerations

There are security considerations to take into account when using the passphrase caching. As the passphrase protects your credential file, exposing the passphrase can be risky on certain systems. This should in generally not be a problem, but in some rare cases it might be applicable to you.

The passphrase is stored in the default OS keyring. That keyring is accessible to any process that runs under the same user. Consequently, any process running under the same user has access to a cached passphrase.

Also, when the system shuts down the cache clearing process makes a best effort to wipe the cache. However, because system shutdowns can be forced this clearing process is not guaranteed. So, a cached passphrase may still linger in the keyring the next time the machine boots.

We’re working on a redesign that is not dependent on the OS Keyring and is guaranteed to clear credentials on shutdown.

A better passphrase caching mechanism will be released in Q3 2018