share/man/man1/derivepassphrase-vault.1 (46c906e) - derivepassphrase.git

derivepassphrase-vault.1

.Dd 2025-08-03
.Dt DERIVEPASSPHRASE-VAULT 1
.Os derivepassphrase 0.5.2
.
.Sh NAME
.
.Nm derivepassphrase-vault
.Nd derive a passphrase using the vault derivation scheme
.
.Sh SYNOPSIS
.
.Bd -ragged
.Nm derivepassphrase vault
.Op Fl \-phrase | Fl \-key
.Op Fl \-length Ar n
.Op Fl \-repeat Ar n
.Op Fl \-lower Ar n
.Op Fl \-upper Ar n
.Op Fl \-number Ar n
.Op Fl \-space Ar n
.Op Fl \-dash Ar n
.Op Fl \-symbol Ar n
.Op Fl \-print\-notes\-before | Fl \-print\-notes\-after
.Ar SERVICE
.
.Nm derivepassphrase vault
.Brq Fl \-phrase | \-key | No .\|.\|. | Fl \-symbol Ar n
.No .\|.\|.
.Fl \-config
.Op Fl \-unset Ar setting No .\|.\|.
.Op Fl \-overwrite\-existing | Fl \-merge\-existing
.Op Ar SERVICE
.
.Nm derivepassphrase vault
.Op Fl \-phrase | \-key | No .\|.\|. | Fl \-symbol Ar n
.No .\|.\|.
.Fl \-config \-notes
.Op Fl \-unset Ar setting No .\|.\|.
.Op Fl \-overwrite\-existing | Fl \-merge\-existing
.Op Fl \-modern\-editor\-interface | Fl \-vault-legacy-editor-interface
.Ar SERVICE
.
.Nm derivepassphrase vault
.Brq Fl \-delete Ar SERVICE | Fl \-delete\-globals | Fl \-clear
.
.Nm derivepassphrase vault
.Op Fl \-export\-as Brq Li json | sh
.Brq Fl \-import Ar PATH | Fl \-export Ar PATH
.Ed
.
.Sh DESCRIPTION
.
Using a master passphrase, derive a passphrase for
.Ar SERVICE ,
subject to length, character and character repetition constraints, in a
manner compatible with James Coglan's
.Xr vault 1 .
.Pp
.
The derivation is
.Em 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
.Em deterministic ,
given the same inputs, thus the resulting passphrase need not be stored
explicitly.
.Pp
.
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.
.Pp
.
In lieu of a master passphrase, a master
.Tn SSH
key can also be used if there is a reachable, running
.Tn SSH
agent currently holding this key and if the key type is supported.
(See
.Sx "SSH AGENT SOCKET PROVIDERS" ,
.Sx "SSH KEY SUITABILITY"
and
.Sx BUGS
below.)
This too is compatible with
.Xr vault 1 .
.
.Sh OPTIONS
.
.Ss Passphrase generation
.
The passphrase generation options can be divided into
.Dq passphrase source
options
.Fl ( \-phrase , \-key )
and
.Dq passphrase constraint
options (all others).
The passphrase source options are mutually exclusive \(em you may only
specify one of them \(em while the passphrase constraint options may be
combined in any way.
The
.Ar SERVICE
is mandatory (see synopsis\~#1 and #3), unless the
.Fl \-config
option is specified and the
.Fl \-notes
option is not (see synopsis\~#2).
All character constraints refer to ASCII printable characters only (space
.Pq Li U+0020
to tilde
.Pq Li U+007E ,
excluding the grave accent
.Pq Li U+0060 ) .
.
.Bl -tag -width ".Fl p , \-phrase"
.
.It Fl p , \-phrase
Prompt for a passphrase.
.Pp
.
See also
.Sx Configuration
for how this interacts with a stored passphrase or
.Tn SSH
key.
.
.It Fl k , \-key
Select an
.Tn SSH
key.
.Pp
.
An
.Tn SSH
agent such as
.Tn OpenSSH Ns No 's
.Xr ssh-agent 1
.Tn PuTTY Ns No 's
.Xr pageant 1
must be running and accessible, and have the desired key loaded.
The
.Tn SSH
key must also be
.Em suitable
for this purpose; see
.Sx SSH key suitability
for details.
.Pp
.
See also
.Sx Configuration
for how this interacts with a stored passphrase or
.Tn SSH
key.
.Pp
.Nm derivepassphrase
uses so-called
.Dq Tn SSH No agent socket providers
to configure how it connects to the
.Tn SSH
agent.
See
.Sx "SSH AGENT SOCKET PROVIDERS"
for details.
.
.It Fl l Ar n , Fl \-length Ar n
Force the passphrase to have the length
.Ar n .
Defaults to the length
.Sy 20
if not specified, or if explicitly specified as
.Li 0 .
.
.It Fl r Ar n , Fl \-repeat Ar n
Permit only runs of up to
.Ar n
consecutive occurrences of the same character.
Alternatively, forbid immediate additional repetitions of length
.Ar n
(or more) for any character in the derived passphrase.
Setting
.Ar n No = Li 0
disables repetition constraints, which is the default.
.
.It Fl \-lower Ar n
Include at least
.Ar n
lowercase characters in the derived passphrase.
Setting
.Ar n No = Li 0
forbids these characters entirely.
The default is to not constain the occurrences in any manner.
.
.It Fl \-upper Ar n
Include at least
.Ar n
uppercase characters in the derived passphrase.
Setting
.Ar n No = Li 0
forbids these characters entirely.
The default is to not constain the occurrences in any manner.
.
.It Fl \-number Ar n
Include at least
.Ar n
digits in the derived passphrase.
Setting
.Ar n No = Li 0
forbids these characters entirely.
The default is to not constain the occurrences in any manner.
.
.It Fl \-space Ar n
Include at least
.Ar n
spaces in the derived passphrase.
Setting
.Ar n No = Li 0
forbids these characters entirely.
The default is to not constain the occurrences in any manner.
.
.It Fl \-dash Ar n
Include at least
.Ar n
.Dq dashes
.Li ( \-
or
.Li _ )
in the derived passphrase.
Setting
.Ar n No = Li 0
forbids these characters entirely.
The default is to not constain the occurrences in any manner.
.
.It Fl \-symbol Ar n
Include at least
.Ar n
symbols (any of
.Li !\[dq]#$%&\[aq]()*+,./:;<=>?@[\e]\(ha{|}\(ti\-_ )
in the derived passphrase.
Setting
.Ar n No = Li 0
forbids these characters entirely, and effectively also implies
.Fl \-dash Li 0 .
The default is to not constain the occurrences in any manner.
.
.El
.
.Ss Configuration
.
The configuration options directly modify the stored settings: default
settings, known services, and service-specific settings.
The
.Fl \-notes
option requires the
.Fl \-config
option, and modifies its operation.
All others are mutually exclusive; you may only specify one of them.
The
.Ar SERVICE
is mandatory for
.Fl \-notes
and
.Fl \-delete ,
optional for
.Fl \-config ,
and forbidden for
.Fl \-delete\-globals
and
.Fl \-clear
(see synopses\~#2, #3 and #4).
.
.Bl -tag -width ".Fl p , \-phrase"
.
.It Fl n , \-notes
Spawn an editor to edit notes for
.Ar SERVICE .
Use the
.Ev VISUAL
or
.Ev EDITOR
environment variables to configure the spawned editor.
Must be used together with
.Fl \-config
to have any effect.
.
.It Fl c , \-config
Save the given settings for
.Ar SERVICE
(if given), or save the given settings as global default settings.
.Pp
.
The
.Fl \-notes
option is compatible with
.Fl \-config .
See the
.Sx Passphrase generation
and
.Sx Compatibility and extension options
sections for other compatible options.
.Pp
.
.Bf -symbolic
Do not use the
.Fl \-phrase
and
.Fl \-config
options together!
The configuration file is assumed to not contain sensitive contents, and is
not encrypted.
.Ef
.
.It Fl x , \-delete
Delete all stored settings for
.Ar SERVICE .
.
.It Fl \-delete\-globals
Delete all stored global default settings.
.
.It Fl X , \-clear
Delete all stored settings.
.
.El
.
.Ss 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
.Ar SERVICE
argument is forbidden.
.
.Pp
.
Using
.Li \-
as
.Ar PATH
for standard input/standard output is supported.
.
.Bl -tag -width ".Fl p , \-phrase"
.
.It Fl e Ar PATH , Fl \-export Ar PATH
Export all saved settings into file
.Ar PATH .
.
.It Fl i Ar PATH , Fl \-import Ar PATH
Import saved settings from file
.Ar PATH .
.
.El
.
.Ss Compatibility and extension options
.
By default,
.Nm derivepassphrase vault
behaves in a manner compatible with
.Xr vault 1 .
The compatibility and extension options modify the behavior to enable
additional functionality, or specifically to force compatibility.
.Pp
.
.Xr 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.
.
.Bl -tag -width ".Fl p , \-phrase"
.
.It Fl \-overwrite\-existing No "" / "" Fl \-merge\-existing
When importing a configuration via
.Fl \-import ,
or configuring the settings via
.Fl \-config ,
overwrite or merge
.Em ( default )
the existing configuration.
.Pp
.
If overwriting the configuration, then the whole configuration
.Pq for Fl \-import
or the respective section
.Pq service-specific or global, for Fl \-config ,
will be written from scratch.
If merging, then each section
.Pq service-specific or global, for Fl \-import
or each singular setting
.Pq for Fl \-config
will be overwritten, but other unaffected settings/sections will not.
.Pp
.
.Xr ( vault 1
behaves as if
.Fl \-merge\-existing
were always given.)
.
.It Fl \-unset Ar setting
When configuring via
.Fl \-config ,
also unset the specified
.Ar setting ,
where
.Ar setting
is one of the passphrase generation settings
.Pq Li phrase , key , lower , No .\|.\|. .
May be specified multiple times.
Must not overlap with any of the settings being set afterwards.
.Pp
.
.Xr ( vault 1
does not support this option.)
.
.It Fl \-export\-as Brq Li json | sh
When exporting the configuration via
.Fl \-export ,
export as
.Tn JSON
(default) or as a shell script in
.Xr sh 1
format.
.Pp
.
The
.Tn JSON
format is compatible with
.Xr vault 1 .
For the shell script format, see the
.Sx SHELL SCRIPT EXPORT FORMAT
section for details.
.Pp
.
.Xr ( vault 1
behaves as if
.Fl \-export\-as Li json
were always given.)
.
.It Fl \-modern\-editor\-interface | Fl \-vault\-legacy\-editor\-interface
When editing notes, use a modern editor interface similar to
.Xr git 1 ,
or use the
.Xr vault 1
legacy editing interface.
.Pp
.
The modern editor interface supports aborting the edit
.Pq 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
.Xr git 1 ,
.Xr hg 1
or
.Xr svn 1
use text editors for commit messages.
.Pp
.
The
.Xr 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.
.Pp
.
.Nm 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.
.Pp
.
.Xr ( vault 1
behaves as if
.Fl \-vault\-legacy\-editor\-interface
were always given.)
.
.It Fl \-print\-notes\-before No "" / "" Fl \-print\-notes\-after
When deriving a passphrase, if the service has any service notes,
print these notes before or after
.Em ( default )
the passphrase.
.Pp
.
.Xr ( vault 1
behaves as if
.Fl \-print\-notes\-after
were always given.)
.
.It Fl \-ssh\-agent\-socket\-provider Ar PROVIDER
When deriving a passphrase using an SSH key, use the named socket provider
to connect to the
.Tn SSH
agent.
If not given, use the provider given in the configuration file, if any,
else a platform-appropriate default provider.
.Pp
.
(See
.Sx "SSH AGENT SOCKET PROVIDERS"
for details.)
.Pp
.
.Xr ( vault 1
behaves as if the built-in
.Li ssh_auth_sock_on_unix
provider were always requested.)
.
.El
.
.Ss Other options
.
.Bl -tag -width ".Fl p , \-phrase"
.
.It Fl \-debug
Emit all diagnostic information to standard error, including progress,
warning and error messages.
.Pp
.
Cancels the effect of any previous
.Fl \-quiet
or
.Fl \-verbose
options.
Also applies to subcommands.
.
.It Fl v , \-verbose
Emit extra/progress information to standard error, on top of warning and
error messages.
.Pp
.
Cancels the effect of any previous
.Fl \-debug
or
.Fl \-quiet
options.
Also applies to subcommands.
.
.It Fl q , \-quiet
Suppress all other diagnostic output to standard error, except error
messages.
.Pp
.
Cancels the effect of any previous
.Fl \-debug
or
.Fl \-verbose
options.
Also applies to subcommands.
.
.It Fl \-version
Show version and feature information, then exit.
.Pp
This includes a list of known optional features, marked explicitly as either
supported or unavailable.
.
.It Fl h , \-help
Show a help message, then exit.
.
.El
.
.Sh SHELL SCRIPT EXPORT FORMAT
.
If the shell script export format is selected, the configuration will be
exported as a
.Tn POSIX
.Xr sh 1
script, containing calls to
.Nm derivepassphrase vault
to reconstruct the current configuration from scratch.
The script assumes a conforming
.Xr sh 1 ,
with support for
.Dq here
documents.
.Pp
.
.Bf -symbolic
Do not run these emitted shell scripts directly without double-checking
their output first!
.Ef
.
.Sh SSH AGENT SOCKET PROVIDERS
.
An
.Dq Tn SSH No agent socket provider
is a named configuration
.Pq and associated support code
that teaches
.Nm derivepassphrase
how to connect to a specific
.Tn 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.
.Pp
.Nm derivepassphrase
ships with the following built-in providers:
.Bl -ohang -offset indent
.It Li ssh_auth_sock_on_posix
connects to an
.Tn SSH
agent named by the
.Ev SSH_AUTH_SOCK
environment variable, using
.Tn UNIX
domain sockets
.It Li ssh_auth_sock_on_windows
connects to an
.Tn SSH
agent named by the
.Ev SSH_AUTH_SOCK
environment variable, using Windows named pipes
.It Li openssh_on_windows
connects to the
.Pf Powershell Pf / Dq Win32
port of
.Tn OpenSSH
at its standard address, using Windows named pipes
.It Li pageant_on_windows
connects to Pageant on Windows at its standard address, using Windows named pipes
.El
.Pp
and the following standard aliases:
.Bl -ohang -offset indent
.It Li unix_domain
alias for
.Li ssh_auth_sock_on_posix
.It Li windows_named_pipe
alias for
.Li ssh_auth_sock_on_windows
.It Li posix
alias for
.Li unix_domain
.It Li windows
alias for
.Li windows_named_pipe
.It Li native
alias for
.Li posix
or
.Li windows ,
depending on the operating system
.El
.Pp
(You are strongly advised to use a true provider name instead of an alias,
if feasible.)
.Pp
The list of currently available and otherwise known
.Tn SSH
agent socket providers is part of the feature information emitted by
.Fl \-version .
.
.Sh SSH KEY SUITABILITY
.
An
.Tn SSH
key is
.Sy suitable
for use with
.Nm derivepassphrase vault
if the
.Tn SSH
agent guarantees that signatures produced with this key will be
.Em deterministic ,
given the same message to be signed.
This is a property specific to the key
.Em type ,
and sometimes the agent used:
.
.Bl -bullet
.
.It
.Tn RSA ,
.Tn Ed25519
and
.Tn Ed448
keys are always suitable, by design of the key type.
.
.It
.Tn DSA
and
.Tn ECDSA
keys are suitable if the
.Tn SSH
agent supports deterministic
.Tn DSA
signatures, e.g. by implementing
.Tn RFC 6979 .
.
.It
As of version 10.2 (October 2025),
.Tn OpenSSH Ns No 's
.Xr ssh-agent 1
supports only some of the always-suitable key types:
.Tn RSA
and
.Tn Ed25519
keys.
.
.It
As of version 0.83 (February 2025),
.Tn PuTTY Ns No 's
.Xr pageant 1
supports all key types mentioned above, including
.Tn DSA
and
.Tn ECDSA
keys via deterministic signatures.
.
.El
.
.Sh ENVIRONMENT
.
.Bl -tag -width ".Fl p , \-phrase"
.
.It Ev VISUAL , EDITOR
.Nm derivepassphrase vault
uses this editor to edit service notes when called with
.Fl \-notes .
.Ev VISUAL
has higher precedence than
.Ev EDITOR .
.
.It Ev DERIVEPASSPHRASE_PATH
.Nm derivepassphrase
stores its configuration files and data in this directory.
Defaults to
.Pa \(ti/.derivepassphrase .
.
.El
.
.Sh FILES
.
.Bl -tag -width ".Fl p , \-phrase"
.
.It Ev $DERIVEPASSPHRASE_PATH Ns Pa /vault.json
The stored configuration for
.Nm derivepassphrase vault :
the default passphrase generation settings, the known service names, and the
service-specific settings.
This file is
.Em not
intended for the user to edit.
.
.It Ev $DERIVEPASSPHRASE_PATH Ns Pa /old-notes.txt
A backup copy of the old notes from the last successful notes editing
operation, using the
.Xr vault 1
legacy editor interface.
.
.El
.
.Sh SECURITY
.
.Bl -bullet
.
.It
There is
.Sy no way
to retrieve the generated passphrases if the master passphrase, the
.Tn SSH
key, or the exact passphrase settings are lost, short of trying out all
possible combinations.
You are
.Sy strongly
advised to keep independent backups of the settings and the
.Tn SSH
key, if any.
.
.It
The configuration is
.Sy not
encrypted, and you are
.Sy strongly
discouraged from using a stored passphrase.
.
.It
You are
.Sy strongly
advised to avoid the
.Pq shell script
configuration export format if possible, and use the JSON format instead.
If you
.Em must
use the shell script format, then
.Sy always
validate the export before attempting to interpret or run it.
.
.El
.
.Sh EXAMPLES
.
.Dl $ derivepassphrase vault \-\-phrase email
.Pp
Prompt for a master passphrase, then generate a standard passphrase
.Pq length 20, no character or repetition constraints
for the
.Dq email
service.
.Pp
.
.Dl $ derivepassphrase vault \-\-key \-\-upper 9 \-\-lower 9 example.com
.Pp
.
Select an
.Tn SSH
key from the available suitable
.Tn SSH
keys in the running
.Tn SSH
agent, then generate a passphrase for the
.Li example.com
service using the previously selected
.Tn 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.
.Pp
.
.Dl $ derivepassphrase vault \-\-key \-\-upper 9 \-\-lower 9 \-\-number 9 example.com
.Pp
.
Attempt to generate a passphrase as in the previous example.
.Em This
example will error out, because the passphrase constraints require at least
27 characters and the standard passphrase length 20 cannot accomodate this.
.Pp
.
.Dl $ derivepassphrase vault \-\-key \-\-upper 9 \-\-lower 9 \-\-space 2 \-\-config
.Pp
.
After selecting an
.Tn 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.)
.Pp
.
.Dl $ derivepassphrase vault example.com
.Pp
.
Because of the previous setting, the generated passphrase for the
.Li example.com
service will behave as if
.Fl \-key \-upper Li 9 Fl \-lower Li 9 Fl \-space Li 2
had been specified during invocation (with the
.Tn SSH
key already having been selected).
In particular, it is neither necessary to specify
.Fl \-phrase No or Fl \-key
nor is it necessary to actually select an
.Tn SSH
key or to type in a master passphrase.
.
.Sh DIAGNOSTICS
.
.Ex -std "derivepassphrase vault"
.Pp
.
.Ss Fatal error messages on standard error
.
.Pq Li %s Ns No " indicates a variable part of the message."
.
.Bl -diag
.
.\" Message-ID: ErrMsgTemplate.PARAMS_MUTUALLY_EXCLUSIVE
.It %s is mutually exclusive with %s.
The two indicated options must not be used at the same time.
.
.\" Message-ID: ErrMsgTemplate.PARAMS_NEEDS_SERVICE_OR_CONFIG
.It %s requires a SERVICE or \-\-config.
Using the indicated passphrase generation option requires the
.Ar SERVICE
argument or the
.Fl \-config
option.
.
.\" Message-ID: ErrMsgTemplate.PARAMS_NEEDS_SERVICE
.It %s requires a SERVICE.
Using the indicated option requires the
.Ar SERVICE
argument.
.
.\" Message-ID: ErrMsgTemplate.PARAMS_NO_SERVICE
.It %s does not take a SERVICE argument.
The indicated option must not be specified together with the
.Ar SERVICE
argument.
.
.\" Message-ID: ErrMsgTemplate.CANNOT_LOAD_VAULT_SETTINGS
.It 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.
.
.\" Message-ID: ErrMsgTemplate.CANNOT_STORE_VAULT_SETTINGS
.It 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.
.
.\" Message-ID: ErrMsgTemplate.CANNOT_DECODEIMPORT_VAULT_SETTINGS
.\" Message-ID: ErrMsgTemplate.CANNOT_IMPORT_VAULT_SETTINGS
.It 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.
.
.\" Message-ID: ErrMsgTemplate.CANNOT_EXPORT_VAULT_SETTINGS
.It 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.
.
.\" Message-ID: ErrMsgTemplate.CANNOT_LOAD_USER_CONFIG
.It 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.
.
.\" Message-ID: ErrMsgTemplate.INVALID_USER_CONFIG
.It The user configuration file is invalid.
(Exactly what it says.)
.
.\" Message-ID: ErrMsgTemplate.SSH_KEY_NOT_LOADED
.It The requested SSH key is not loaded into the agent.
The running
.Tn SSH
agent does not contain the necessary
.Tn SSH
key.
.
.\" Message-ID: ErrMsgTemplate.NO_SSH_AGENT_FOUND
.It Cannot find any running SSH agent because SSH_AUTH_SOCK is not set.
We require a running
.Tn SSH
agent, but cannot locate its communication channel, which is normally
indicated by the
.Ev SSH_AUTH_SOCK
environment variable.
.
.\" Message-ID: ErrMsgTemplate.NO_AGENT_SUPPORT
.It "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
.Tn SSH
agents.
.Bq "Since v0.6: May be preceded by several warning messages" "indicating which communication mechanisms were tried."
.
.\" Message-ID: ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT
.It Cannot connect to the SSH agent: %s.
We cannot connect to the
.Tn SSH
agent indicated by the respective address
.Pq e.g. a well-known address, or the Ev SSH_AUTH_SOCK No environment variable.
Further details are contained in the variable part of the message.
.
.\" Message-ID: ErrMsgTemplate.AGENT_REFUSED_LIST_KEYS
.It The SSH agent failed to or refused to supply a list of loaded keys.
The
.Tn SSH
agent \(em while responsive in principle \(em did not fulfill the request.
.
.\" Message-ID: ErrMsgTemplate.AGENT_REFUSED_SIGNATURE
.It "The SSH agent failed to or refused to" "issue a signature with the selected key," "necessary for deriving a service passphrase."
The
.Tn SSH
agent \(em while responsive in principle \(em failed to cooperate with
deriving a service passphrase from the selected master
.Tn SSH
key.
.
.\" Message-ID: ErrMsgTemplate.NO_SUITABLE_SSH_KEYS
.It The SSH agent contains no keys suitable for derivepassphrase.
.
None of the keys loaded into the
.Tn SSH
agent (if any) are suitable for use with
.Nm derivepassphrase vault .
See the
.Sx "SSH KEY SUITABILITY"
section for the requirements the
.Tn SSH
key and the
.Tn SSH
agent must fulfill to be suitable.
.
.\" Message-ID: ErrMsgTemplate.CANNOT_UNDERSTAND_AGENT
.It Cannot understand the SSH agent's response because it violates the communication protocol.
.
(Exactly what it says.)
.
.\" Message-ID: ErrMsgTemplate.UNKNOWN_SSH_AGENT_SOCKET_PROVIDER
.It The SSH agent socket provider %s is not in derivepassphrase's provider registry.
The requested
.Tn SSH
agent socket provider is unknown to
.Nm derivepassphrase .
The provider name may be misspelled, or it may be provided by an external
software package that is not installed on this system.
.Pp
The list of
.Tn SSH agent socket providers currently known to
.Nm derivepassphrase
may be queried via
.Li derivepassphrase vault Fl \-version .
.
.\" Message-ID: ErrMsgTemplate.USER_ABORTED_EDIT
.It Not saving any new notes: the user aborted the request.
(Exactly what it says.)
.
.\" Message-ID: ErrMsgTemplate.CANNOT_UPDATE_SETTINGS_NO_SETTINGS
.It Cannot update the %s settings without any given settings.
Using
.Fl \-config
requires at least one of the
.Fl \-phrase , \-key , \-length , No etc.\&
options.
.
.\" Message-ID: ErrMsgTemplate.SET_AND_UNSET_SAME_SETTING
.It Attempted to unset and set %s at the same time.
While handling
.Fl \-config ,
the same configuration setting was passed as an option and as an argument to
.Fl \-unset .
.
.\" Message-ID: ErrMsgTemplate.SERVICE_REQUIRED
.It Deriving a passphrase requires a SERVICE.
(Exactly what it says.)
.
.\" Message-ID: ErrMsgTemplate.NO_KEY_OR_PHRASE
.It No passphrase or key was given in the configuration.
.Nm derivepassphrase vault
does not know whether to use a master
.Tn SSH
key or a master passphrase.
.
.\" Message-ID: ErrMsgTemplate.USER_ABORTED_PASSPHRASE
.It No passphrase was given; the user aborted the request.
(Exactly what it says.)
.
.\" Message-ID: ErrMsgTemplate.USER_ABORTED_SSH_KEY_SELECTION
.It No SSH key was selected; the user aborted the request.
(Exactly what it says.)
.
.El
.Pp
.
.Ss Non-fatal warning and info messages on standard error
.
.Pq Li %s Ns No " indicates a variable part of the message."
.
.Bl -diag
.
.\" Message-ID: WarnMsgTemplate.PASSPHRASE_NOT_NORMALIZED
.It The %s passphrase is not %s-normalized.
The indicated passphrase \(em as a Unicode string \(em is not properly
normalized according to the preferred Unicode normalization form
.Pq as specified in the central configuration file .
It is therefore possible that the passphrase \(em as a byte string \(em is
not the same byte string as you expect it to be
.Pq even though it Em looks No correct ,
and that the derived passphrases thus do not match their expected values
either.
Please double-check.
.
.\" Message-ID: WarnMsgTemplate.EMPTY_SERVICE_NOT_SUPPORTED
.\" Message-ID: WarnMsgTemplate.EMPTY_SERVICE_SETTINGS_INACCESSIBLE
.It An empty SERVICE is not supported by vault(1).
.Xr vault 1
does not support the empty string as a value for
.Ar SERVICE ;
it will treat the
.Ar SERVICE
as missing.
For compatibility,
.Nm derivepassphrase vault
will do the same.
In particular, if the empty service is imported in a configuration via
.Fl \-import ,
then this service cannot be accessed via the
.Nm derivepassphrase vault
command-line.
.
.\" Message-ID: WarnMsgTemplate.STEP_REPLACE_INVALID_VALUE
.It 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.
.Pq The Do interpretation Dc of the configuration doesn't change .
.
.\" Message-ID: WarnMsgTemplate.STEP_REMOVE_INEFFECTIVE_VALUE
.It Removing ineffective setting %s = %s.
When importing a configuration, the indicated ineffective setting has been
removed.
.Pq The Do interpretation Dc of the configuration doesn't change .
.
.\" Message-ID: WarnMsgTemplate.SERVICE_NAME_INCOMPLETABLE
.It "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.
.Po
This
.Em only
affects tab completion, not other functionality.
.Pc
.
.\" Message-ID: WarnMsgTemplate.GLOBAL_PASSPHRASE_INEFFECTIVE
.\" Message-ID: WarnMsgTemplate.SERVICE_PASSPHRASE_INEFFECTIVE
.It 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
.Tn SSH
key.
The master passphrase will not take effect.
.
.\" Message-ID: WarnMsgTemplate.V10_SUBCOMMAND_REQUIRED
.It A subcommand will be required here in v1.0.
.Bo
Since v0.2.0, until v1.0.
.Bc
This command now requires a subcommand.
For compatibility, it currently defaults to
.Dq vault .
.
.\" Message-ID: WarnMsgTemplate.V01_STYLE_CONFIG
.\" Message-ID (mark only): WarnMsgTemplate.FAILED_TO_MIGRATE_CONFIG
.It Using deprecated v0.1-style config file %s, instead of v0.2-style %s.
.Bo
Since v0.2.0, until v1.0.
.Bc
A configuration file has been renamed.
.Nm derivepassphrase vault
will attempt to rename the file itself
.Pq Qq Li Successfully migrated to %s. ,
or complain if it cannot rename it
.Pq Qq Li Failed to migrate to %s: %s .
.
.\" Message-ID: WarnMsgTemplate.EDITING_NOTES_BUT_NOT_STORING_CONFIG
.It Specifying \-\-notes without \-\-config is ineffective.
(Exactly what it says.)
.
.\" Message-ID: WarnMsgTemplate.LEGACY_EDITOR_INTERFACE_NOTES_BACKUP
.It A backup copy of the old notes was saved to %s.
The
.Xr 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
.Nm derivepassphrase
configuration directory.
.
.\" Message-ID: WarnMsgTemplate.NO_UNIX_DOMAIN_SOCKETS
.\" Message-ID (mark only): WarnMsgTemplate.NO_AF_UNIX
.It Cannot connect to an SSH agent via UNIX domain sockets because this Python version does not support them.
We attempted to use
.Tn UNIX
domain sockets to communicate with an
.Tn SSH
agent, but this Python installation does not support them.
.Po
Only appears together with the error message
.Do
Cannot connect to an SSH agent because this Python version does not support communicating with it.
.Dc .
Other, similar messages about unsupported communication mechanisms may
precede the error message.
.Pc
.
.\" Message-ID: WarnMsgTemplate.NO_WINDOWS_NAMED_PIPES
.\" Message-ID (mark only): WarnMsgTemplate.NO_ANNOYING_OS_NAMED_PIPES
.It Cannot connect to an SSH agent via Windows named pipes because this Python version does not support them.
We attempted to use
.Tn Windows
named pipes to communicate with an
.Tn SSH
agent, but this Python installation does not support them.
.Po
Only appears together with the error message
.Do
Cannot connect to an SSH agent because this Python version does not support communicating with it.
.Dc .
Other, similar messages about unsupported communication mechanisms may
precede the error message.
.Pc
.
.El
.Pp
.
.Ss Discontinued error, warning and info messages on standard error
.
.Pq Li %s Ns No " indicates a variable part of the message."
.
.Bl -diag
.
.\" Message-ID (mark only): ErrMsgTemplate.NO_AF_UNIX
.It Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.
.Bo
Until v0.6.
.Bc
Superseded by both the more general error message
.Dq "Cannot connect to an SSH agent because this Python version" "does not support communicating with it."
and the warning message
.Dq "Cannot connect to an SSH agent using UNIX domain sockets" "because this Python version does not support them." .
.
.El
.
.Sh COMPATIBILITY
.
.Ss With other software
.
.Nm derivepassphrase vault
is
.Em almost
drop-in compatible with James Coglan's
.Xr vault 1 ,
version 0.3.0
.Pq including Do storeroom Dc support ,
meaning that each tool supports the same file formats and command-line
arguments/options as the other one.
.Pp
.
Exceptions:
.
.Bl -bullet
.
.It
.Xr vault 1
does not support the
.Sx "Compatibility and extension options"
listed above.
.
.It
.Nm derivepassphrase vault
can import and generate configuration exports in the same format as
.Xr vault 1 ,
but it cannot
.Em natively
read or write
.Xr vault 1
.Ns 's
configuration file
.Pq non-storeroom
or configuration directory
.Pq storeroom .
(The sister command
.Xr derivepassphrase-export 1
can read both these formats and export the contents.)
.
.El
.
.Ss Forward and backward compatibility
.
.Bl -bullet
.
.It
.Bo Since v0.2.0 . Bc
In v1.0, the configuration data file for the
.Ic vault
subcommand will be named
.Pa vault.json ,
instead of
.Pa config.json .
.
.It
.Bo Since v0.2.0, to be removed in v1.0 . Bc
An existing configuration data file
.Pa config.json
will be attempted to be renamed to
.Pa vault.json .
.El
.
.Sh SEE ALSO
.
.Xr derivepassphrase 1 ,
.Xr pageant 1 ,
.Xr ssh-agent 1 .
.Rs
.%A "James Coglan"
.%T "vault(1)"
.%U https://www.npmjs.com/package/vault
.Re
.Pp
.
Further online documentation for
.Xr derivepassphrase 1
.Pq tutorials, how-tos, reference and design documentation
is available at
.Lk https://the13thletter.info/derivepassphrase/ .
.
.Sh AUTHOR
.
.Lk mailto:software@the13thletter.info "Marco Ricci"
.
.Sh BUGS
.
.Bl -bullet
.
.It
The defaults are dictated by
.Xr vault 1 ,
necessitating the
.Sx Compatibility and extension options .
.Pq WONTFIX.
.
.El
.

derivepassphrase.git

Update the manpages with respect to SSH agents