DERIVEPASSPHRASE-VAULT(1)

NAME
derivepassphrase-vault - derive a passphrase using the vault derivation scheme

SYNOPSIS

derivepassphrase vault [--phrase | --key] [--length n] [--repeat n] [--lower n] [--upper n] [--number n] [--space n] [--dash n] [--symbol n] [--print-notes-before | --print-notes-after] SERVICE
derivepassphrase vault {--phrase | --key | ... | --symbol n} ... --config [--unset setting ...] [--overwrite-existing | --merge-existing] [SERVICE]
derivepassphrase vault [--phrase | --key | ... | --symbol n] ... --config --notes [--unset setting ...] [--overwrite-existing | --merge-existing] [--modern-editor-interface | --vault-legacy-editor-interface] SERVICE
derivepassphrase vault {--delete SERVICE | --delete-globals | --clear}
derivepassphrase vault [--export-as {json | sh}] {--import PATH | --export PATH}

DESCRIPTION
Using a master passphrase, derive a passphrase for SERVICE, subject to length, character and character repetition constraints, in a manner compatible with James Coglan's vault(1).

The derivation is strong: derived passphrases have as much entropy as permitted by the master passphrase and the passphrase constraints (whichever is more restrictive), and even if multiple derived passphrases are compromised, the master passphrase remains cryptographically difficult to discern from theses compromised passphrases. The derivation is also deterministic, given the same inputs, thus the resulting passphrase need not be stored explicitly.

The service name and constraints themselves also need not be kept secret; the latter are usually stored in a world-readable file to ease repeated entry of passphrase constraints.

In lieu of a master passphrase, a master SSH key can also be used if there is a reachable, running SSH agent currently holding this key and if the key type is supported. (See SSH AGENT SOCKET PROVIDERS, SSH KEY SUITABILITY and BUGS below.) This too is compatible with vault(1).

OPTIONS

  Passphrase generation
The passphrase generation options can be divided into “passphrase source” options (--phrase, --key) and “passphrase constraint” options (all others). The passphrase source options are mutually exclusive — you may only specify one of them — while the passphrase constraint options may be combined in any way. The SERVICE is mandatory (see synopsis #1 and #3), unless the --config option is specified and the --notes option is not (see synopsis #2). All character constraints refer to ASCII printable characters only (space (U+0020) to tilde (U+007E), excluding the grave accent (U+0060)).

-p, --phrase
    Prompt for a passphrase.

    See also Configuration for how this interacts with a stored passphrase or SSH key.

-k, --key
    Select an SSH key.

    An SSH agent such as OpenSSH's ssh-agent(1) PuTTY's pageant(1) must be running and accessible, and have the desired key loaded. The SSH key must also be suitable for this purpose; see SSH key suitability for details.

    See also Configuration for how this interacts with a stored passphrase or SSH key.

    derivepassphrase uses so-called “SSH agent socket providers” to configure how it connects to the SSH agent. See SSH AGENT SOCKET PROVIDERS for details.

-l n, --length n
    Force the passphrase to have the length n. Defaults to the length 20 if not specified, or if explicitly specified as 0.

-r n, --repeat n
    Permit only runs of up to n consecutive occurrences of the same character. Alternatively, forbid immediate additional repetitions of length n (or more) for any character in the derived passphrase. Setting n = 0 disables repetition constraints, which is the default.

--lower n
    Include at least n lowercase characters in the derived passphrase. Setting n = 0 forbids these characters entirely. The default is to not constain the occurrences in any manner.

--upper n
    Include at least n uppercase characters in the derived passphrase. Setting n = 0 forbids these characters entirely. The default is to not constain the occurrences in any manner.

--number n
    Include at least n digits in the derived passphrase. Setting n = 0 forbids these characters entirely. The default is to not constain the occurrences in any manner.

--space n
    Include at least n spaces in the derived passphrase. Setting n = 0 forbids these characters entirely. The default is to not constain the occurrences in any manner.

--dash n
    Include at least n “dashes” (- or _) in the derived passphrase. Setting n = 0 forbids these characters entirely. The default is to not constain the occurrences in any manner.

--symbol n
    Include at least n symbols (any of !"#$%&'()*+,./:;<=>?@[\]^{|}~-_) in the derived passphrase. Setting n = 0 forbids these characters entirely, and effectively also implies --dash 0. The default is to not constain the occurrences in any manner.

  Configuration
The configuration options directly modify the stored settings: default settings, known services, and service-specific settings. The --notes option requires the --config option, and modifies its operation. All others are mutually exclusive; you may only specify one of them. The SERVICE is mandatory for --notes and --delete, optional for --config, and forbidden for --delete-globals and --clear (see synopses #2, #3 and #4).

-n, --notes
    Spawn an editor to edit notes for SERVICE. Use the VISUAL or EDITOR environment variables to configure the spawned editor. Must be used together with --config to have any effect.

-c, --config
    Save the given settings for SERVICE (if given), or save the given settings as global default settings.

    The --notes option is compatible with --config. See the Passphrase generation and Compatibility and extension options sections for other compatible options.

    Do not use the --phrase and --config options together! The configuration file is assumed to not contain sensitive contents, and is not encrypted.

-x, --delete
    Delete all stored settings for SERVICE.

--delete-globals
    Delete all stored global default settings.

-X, --clear
    Delete all stored settings.

  Storage management
The storage management options deal with importing and exporting the stored settings. They are mutually exclusive; you may only specify one of them. The SERVICE argument is forbidden.

Using - as PATH for standard input/standard output is supported.

-e PATH, --export PATH
    Export all saved settings into file PATH.

-i PATH, --import PATH
    Import saved settings from file PATH.

  Compatibility and extension options
By default, derivepassphrase vault behaves in a manner compatible with vault(1). The compatibility and extension options modify the behavior to enable additional functionality, or specifically to force compatibility.

vault(1) supports none of these options, and behaves as if the option had not been given or had been left in its default state.

--overwrite-existing / --merge-existing
    When importing a configuration via --import, or configuring the settings via --config, overwrite or merge (default) the existing configuration.

    If overwriting the configuration, then the whole configuration (for --import) or the respective section (service-specific or global, for --config), will be written from scratch. If merging, then each section (service-specific or global, for --import) or each singular setting (for --config) will be overwritten, but other unaffected settings/sections will not.

    ((vault) 1 behaves as if --merge-existing were always given.)

--unset setting
    When configuring via --config, also unset the specified setting, where setting is one of the passphrase generation settings (phrase, key, lower, ...). May be specified multiple times. Must not overlap with any of the settings being set afterwards.

    ((vault) 1 does not support this option.)

--export-as {json | sh}
    When exporting the configuration via --export, export as JSON (default) or as a shell script in sh(1) format.

    The JSON format is compatible with vault(1). For the shell script format, see the SHELL SCRIPT EXPORT FORMAT section for details.

    ((vault) 1 behaves as if --export-as json were always given.)

--modern-editor-interface | --vault-legacy-editor-interface
    When editing notes, use a modern editor interface similar to git(1), or use the vault(1) legacy editing interface.

    The modern editor interface supports aborting the edit (i.e., leaving the stored notes (if any) unchanged) by leaving the edited file empty, and automatically removes the editing instructions text (which it inserts into the file prior to editing). This is similar to how version-control systems/source code management systems such as git(1), hg(1) or svn(1) use text editors for commit messages.

    The vault(1) legacy edititng interface uses the file contents directly, including any leftover editing instructions, and does not support aborting the edit. Its use is not recommended, unless required for compatibility.

    derivepassphrase vault will use different editing instructions texts to reflect the editing interface in use. Additionally, for the legacy editing interface, a backup of the old notes contents will be stored in the configuration directory if the new notes differ from the old notes, to mitigate the risk of data loss because the edit cannot be aborted.

    ((vault) 1 behaves as if --vault-legacy-editor-interface were always given.)

--print-notes-before / --print-notes-after
    When deriving a passphrase, if the service has any service notes, print these notes before or after (default) the passphrase.

    ((vault) 1 behaves as if --print-notes-after were always given.)

--ssh-agent-socket-provider PROVIDER
    When deriving a passphrase using an SSH key, use the named socket provider to connect to the SSH agent. If not given, use the provider given in the configuration file, if any, else a platform-appropriate default provider.

    (See SSH AGENT SOCKET PROVIDERS for details.)

    ((vault) 1 behaves as if the built-in ssh_auth_sock_on_unix provider were always requested.)

  Other options

--debug
    Emit all diagnostic information to standard error, including progress, warning and error messages.

    Cancels the effect of any previous --quiet or --verbose options. Also applies to subcommands.

-v, --verbose
    Emit extra/progress information to standard error, on top of warning and error messages.

    Cancels the effect of any previous --debug or --quiet options. Also applies to subcommands.

-q, --quiet
    Suppress all other diagnostic output to standard error, except error messages.

    Cancels the effect of any previous --debug or --verbose options. Also applies to subcommands.

--version
    Show version and feature information, then exit.

    This includes a list of known optional features, marked explicitly as either supported or unavailable.

-h, --help
    Show a help message, then exit.

SHELL SCRIPT EXPORT FORMAT
If the shell script export format is selected, the configuration will be exported as a POSIX sh(1) script, containing calls to derivepassphrase vault to reconstruct the current configuration from scratch. The script assumes a conforming sh(1), with support for “here” documents.

Do not run these emitted shell scripts directly without double-checking their output first!

SSH AGENT SOCKET PROVIDERS
An “SSH agent socket provider” is a named configuration (and associated support code) that teaches derivepassphrase how to connect to a specific SSH agent. Such providers can either be built-in, or contributed by third-party software, and may be dependent on a specific operating system and/or further third-party software.

derivepassphrase ships with the following built-in providers:

ssh_auth_sock_on_posix
connects to an SSH agent named by the SSH_AUTH_SOCK environment variable, using UNIX domain sockets

ssh_auth_sock_on_windows
connects to an SSH agent named by the SSH_AUTH_SOCK environment variable, using Windows named pipes

openssh_on_windows
connects to the Powershell/“Win32” port of OpenSSH at its standard address, using Windows named pipes

pageant_on_windows
connects to Pageant on Windows at its standard address, using Windows named pipes

and the following standard aliases:

unix_domain
alias for ssh_auth_sock_on_posix

windows_named_pipe
alias for ssh_auth_sock_on_windows

posix
alias for unix_domain

windows
alias for windows_named_pipe

native
alias for posix or windows, depending on the operating system

(You are strongly advised to use a true provider name instead of an alias, if feasible.)

The list of currently available and otherwise known SSH agent socket providers is part of the feature information emitted by --version.

SSH KEY SUITABILITY
An SSH key is suitable for use with derivepassphrase vault if the SSH agent guarantees that signatures produced with this key will be deterministic, given the same message to be signed. This is a property specific to the key type, and sometimes the agent used:

•   RSA, Ed25519 and Ed448 keys are always suitable, by design of the key type.

•   DSA and ECDSA keys are suitable if the SSH agent supports deterministic DSA signatures, e.g. by implementing RFC 6979.

•   As of version 10.2 (October 2025), OpenSSH's ssh-agent(1) supports only some of the always-suitable key types: RSA and Ed25519 keys.

•   As of version 0.83 (February 2025), PuTTY's pageant(1) supports all key types mentioned above, including DSA and ECDSA keys via deterministic signatures.

ENVIRONMENT

VISUAL, EDITOR
    derivepassphrase vault uses this editor to edit service notes when called with --notes. VISUAL has higher precedence than EDITOR.

DERIVEPASSPHRASE_PATH
    derivepassphrase stores its configuration files and data in this directory. Defaults to ~/.derivepassphrase.

FILES

$DERIVEPASSPHRASE_PATH/vault.json
    The stored configuration for derivepassphrase vault: the default passphrase generation settings, the known service names, and the service-specific settings. This file is not intended for the user to edit.

$DERIVEPASSPHRASE_PATH/old-notes.txt
    A backup copy of the old notes from the last successful notes editing operation, using the vault(1) legacy editor interface.

SECURITY

•   There is no way to retrieve the generated passphrases if the master passphrase, the SSH key, or the exact passphrase settings are lost, short of trying out all possible combinations. You are strongly advised to keep independent backups of the settings and the SSH key, if any.

•   The configuration is not encrypted, and you are strongly discouraged from using a stored passphrase.

•   You are strongly advised to avoid the (shell script) configuration export format if possible, and use the JSON format instead. If you must use the shell script format, then always validate the export before attempting to interpret or run it.

EXAMPLES
    $ derivepassphrase vault --phrase email

Prompt for a master passphrase, then generate a standard passphrase (length 20, no character or repetition constraints) for the “email” service.

    $ derivepassphrase vault --key --upper 9 --lower 9 example.com

Select an SSH key from the available suitable SSH keys in the running SSH agent, then generate a passphrase for the example.com service using the previously selected SSH key. The passphrase will have (standard) length 20, and at least nine characters will be uppercase characters and at least another nine characters will be lowercase characters.

    $ derivepassphrase vault --key --upper 9 --lower 9 --number 9 example.com

Attempt to generate a passphrase as in the previous example. This example will error out, because the passphrase constraints require at least 27 characters and the standard passphrase length 20 cannot accomodate this.

    $ derivepassphrase vault --key --upper 9 --lower 9 --space 2 --config

After selecting an SSH key, configure the default settings to use exactly nine uppercase characters, nine lowercase characters, and two spaces for each generated passphrase. (The specific service settings, or the command-line invocation, can still override these settings.)

    $ derivepassphrase vault example.com

Because of the previous setting, the generated passphrase for the example.com service will behave as if --key --upper 9 --lower 9 --space 2 had been specified during invocation (with the SSH key already having been selected). In particular, it is neither necessary to specify --phrase or --key nor is it necessary to actually select an SSH key or to type in a master passphrase.

DIAGNOSTICS

  Fatal error messages on standard error
(%s indicates a variable part of the message.)

%s is mutually exclusive with %s. The two indicated options must not be used at the same time.

%s requires a SERVICE or --config. Using the indicated passphrase generation option requires the SERVICE argument or the --config option.

%s requires a SERVICE. Using the indicated option requires the SERVICE argument.

%s does not take a SERVICE argument. The indicated option must not be specified together with the SERVICE argument.

Cannot load vault settings: %s. There was a fatal problem loading the stored vault configuration data. Further details are contained in the variable part of the message.

Cannot store vault settings: %s. There was a fatal problem saving the vault configuration data. Further details are contained in the variable part of the message.

Cannot import vault settings: %s. There was a fatal problem loading the imported vault configuration data. Further details are contained in the variable part of the message.

Cannot export vault settings: %s. There was a fatal problem saving the exported vault configuration data. Further details are contained in the variable part of the message.

Cannot load user config: %s. There was a fatal problem loading the central user configuration file. Further details are contained in the variable part of the message.

The user configuration file is invalid. (Exactly what it says.)

The requested SSH key is not loaded into the agent. The running SSH agent does not contain the necessary SSH key.

Cannot find any running SSH agent because SSH_AUTH_SOCK is not set. We require a running SSH agent, but cannot locate its communication channel, which is normally indicated by the SSH_AUTH_SOCK environment variable.

Cannot connect to an SSH agent because this Python version does not support communicating with it. This Python installation does not support the communication mechanism necessary to talk to SSH agents. [Since v0.6: May be preceded by several warning messages indicating which communication mechanisms were tried.]

Cannot connect to the SSH agent: %s. We cannot connect to the SSH agent indicated by the respective address (e.g. a well-known address, or the SSH_AUTH_SOCK environment variable.) Further details are contained in the variable part of the message.

The SSH agent failed to or refused to supply a list of loaded keys. The SSH agent — while responsive in principle — did not fulfill the request.

The SSH agent failed to or refused to issue a signature with the selected key, necessary for deriving a service passphrase. The SSH agent — while responsive in principle — failed to cooperate with deriving a service passphrase from the selected master SSH key.

The SSH agent contains no keys suitable for derivepassphrase. None of the keys loaded into the SSH agent (if any) are suitable for use with derivepassphrase vault. See the SSH KEY SUITABILITY section for the requirements the SSH key and the SSH agent must fulfill to be suitable.

Cannot understand the SSH agent's response because it violates the communication protocol. (Exactly what it says.)

The SSH agent socket provider %s is not in derivepassphrase's provider registry. The requested SSH agent socket provider is unknown to derivepassphrase. The provider name may be misspelled, or it may be provided by an external software package that is not installed on this system.

The list of SSH agent socket providers currently known to derivepassphrase may be queried via derivepassphrase vault --version.

Not saving any new notes: the user aborted the request. (Exactly what it says.)

Cannot update the %s settings without any given settings. Using --config requires at least one of the --phrase, --key, --length, etc. options.

Attempted to unset and set %s at the same time. While handling --config, the same configuration setting was passed as an option and as an argument to --unset.

Deriving a passphrase requires a SERVICE. (Exactly what it says.)

passphrase or key was given in the configuration. derivepassphrase vault does not know whether to use a master SSH key or a master passphrase.

passphrase was given; the user aborted the request. (Exactly what it says.)

SSH key was selected; the user aborted the request. (Exactly what it says.)

  Non-fatal warning and info messages on standard error
(%s indicates a variable part of the message.)

The %s passphrase is not %s-normalized. The indicated passphrase — as a Unicode string — is not properly normalized according to the preferred Unicode normalization form (as specified in the central configuration file). It is therefore possible that the passphrase — as a byte string — is not the same byte string as you expect it to be (even though it looks correct), and that the derived passphrases thus do not match their expected values either. Please double-check.

empty SERVICE is not supported by vault(1). vault(1) does not support the empty string as a value for SERVICE; it will treat the SERVICE as missing. For compatibility, derivepassphrase vault will do the same. In particular, if the empty service is imported in a configuration via --import, then this service cannot be accessed via the derivepassphrase vault command-line.

Replacing invalid value %s for key %s with %s. When importing a configuration, the indicated invalid value has been replaced with the indicated replacement value. (The “interpretation” of the configuration doesn't change).

Removing ineffective setting %s = %s. When importing a configuration, the indicated ineffective setting has been removed. (The “interpretation” of the configuration doesn't change).

The service name %s contains an ASCII control character, which is not supported by our shell completion code. Because of limitations in the shell completion code, this specific service name will not be available as a suggestion in tab completion. ( This only affects tab completion, not other functionality.)

Setting a %s passphrase is ineffective because a key is also set The configuration (global or key-specific) contains both a stored master passphrase and an SSH key. The master passphrase will not take effect.

A subcommand will be required here in v1.0. [ Since v0.2.0, until v1.0.] This command now requires a subcommand. For compatibility, it currently defaults to “vault”.

Using deprecated v0.1-style config file %s, instead of v0.2-style %s. [ Since v0.2.0, until v1.0.] A configuration file has been renamed. derivepassphrase vault will attempt to rename the file itself ("Successfully migrated to %s."), or complain if it cannot rename it ("Failed to migrate to %s: %s").

Specifying --notes without --config is ineffective. (Exactly what it says.)

A backup copy of the old notes was saved to %s. The vault(1) legacy editor interface is in use, which carries a high risk of accidentally losing or corrupting the old notes because a notes editing session cannot be aborted mid-editing. To guard against such accidental data loss, a backup copy of the old notes was saved to the derivepassphrase configuration directory.

Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them. We attempted to use UNIX domain sockets to communicate with an SSH agent, but this Python installation does not support them. ( Only appears together with the error message “ Cannot connect to an SSH agent because this Python version does not support communicating with it. ”. Other, similar messages about unsupported communication mechanisms may precede the error message.)

Cannot connect to an SSH agent via Windows named pipes because this Python version does not support them. We attempted to use Windows named pipes to communicate with an SSH agent, but this Python installation does not support them. ( Only appears together with the error message “ Cannot connect to an SSH agent because this Python version does not support communicating with it. ”. Other, similar messages about unsupported communication mechanisms may precede the error message.)

  Discontinued error, warning and info messages on standard error
(%s indicates a variable part of the message.)

Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets. [ Until v0.6.] Superseded by both the more general error message “Cannot connect to an SSH agent because this Python version does not support communicating with it.” and the warning message “Cannot connect to an SSH agent using UNIX domain sockets because this Python version does not support them.”.

COMPATIBILITY

  With other software
derivepassphrase vault is almost drop-in compatible with James Coglan's vault(1), version 0.3.0 (including “storeroom” support), meaning that each tool supports the same file formats and command-line arguments/options as the other one.

Exceptions:

•   vault(1) does not support the Compatibility and extension options listed above.

•   derivepassphrase vault can import and generate configuration exports in the same format as vault(1), but it cannot natively read or write vault(1) 's configuration file (non-storeroom) or configuration directory (storeroom). (The sister command derivepassphrase-export(1) can read both these formats and export the contents.)

  Forward and backward compatibility

•   [Since v0.2.0.] In v1.0, the configuration data file for the vault subcommand will be named vault.json, instead of config.json.

•   [Since v0.2.0, to be removed in v1.0.] An existing configuration data file config.json will be attempted to be renamed to vault.json.

SEE ALSO
derivepassphrase(1), pageant(1), ssh-agent(1). James Coglan, vault(1), https://www.npmjs.com/package/vault.

Further online documentation for derivepassphrase(1) (tutorials, how-tos, reference and design documentation) is available at https://the13thletter.info/derivepassphrase/.

AUTHOR
Marco Ricci: mailto:software@the13thletter.info

BUGS

•   The defaults are dictated by vault(1), necessitating the Compatibility and extension options. (WONTFIX.)