Submodule cli

derivepassphrase.cli

Command-line interface for derivepassphrase.

OptionGroupOption

OptionGroupOption(*args: Any, **kwargs: Any)

Bases: Option

A click.Option with an associated group name and group epilog.

Used by CommandWithHelpGroups to print help sections. Each subclass contains its own group name and epilog.

Attributes:

Name	Type	Description
option_group_name	str	The name of the option group. Used as a heading on the help text for options in this section.
epilog	str	An epilog to print after listing the options in this section.

option_group_name class-attribute instance-attribute

option_group_name: str = ''

epilog class-attribute instance-attribute

epilog: str = ''

CommandWithHelpGroups

Bases: Command

A click.Command with support for help/option groups.

Inspired by a comment on pallets/click#373, and further modified to support group epilogs.

format_options

format_options(
    ctx: Context, formatter: HelpFormatter
) -> None

Format options on the help listing, grouped into sections.

This is a callback for click.Command.get_help that implements the --help listing, by calling appropriate methods of the formatter. We list all options (like the base implementation), but grouped into sections according to the concrete click.Option subclass being used. If the option is an instance of some subclass of OptionGroupOption, then the section heading and the epilog are taken from the option_group_name and epilog attributes; otherwise, the section heading is “Options” (or “Other options” if there are other option groups) and the epilog is empty.

Parameters:

Name	Type	Description	Default
ctx	Context	The click context.	required
formatter	HelpFormatter	The formatter for the --help listing.	required

PasswordGenerationOption

PasswordGenerationOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Password generation options for the CLI.

ConfigurationOption

ConfigurationOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Configuration options for the CLI.

StorageManagementOption

StorageManagementOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Storage management options for the CLI.

derivepassphrase

derivepassphrase(*, subcommand_args: list[str]) -> None

Derive a strong passphrase, deterministically, from a master secret.

Using a master secret, derive a passphrase for a named service, subject to constraints e.g. on passphrase length, allowed characters, etc. The exact derivation depends on the selected derivation scheme. For each scheme, it is computationally infeasible to discern the master secret from the derived passphrase. The derivations are also deterministic, given the same inputs, thus the resulting passphrases need not be stored explicitly. The service name and constraints themselves also generally need not be kept secret, depending on the scheme.

The currently implemented subcommands are “vault” (for the scheme used by vault) and “export” (for exporting foreign configuration data). See the respective --help output for instructions. If no subcommand is given, we default to “vault”.

Deprecation notice: Defaulting to “vault” is deprecated. Starting in v1.0, the subcommand must be specified explicitly.

This is a click-powered command-line interface function, and not intended for programmatic use. Call with arguments ['--help'] to see full documentation of the interface. (See also click.testing.CliRunner for controlled, programmatic invocation.)

derivepassphrase_export

derivepassphrase_export(
    *, subcommand_args: list[str]
) -> None

Export a foreign configuration to standard output.

Read a foreign system configuration, extract all information from it, and export the resulting configuration to standard output.

The only available subcommand is “vault”, which implements the vault-native configuration scheme. If no subcommand is given, we default to “vault”.

Deprecation notice: Defaulting to “vault” is deprecated. Starting in v1.0, the subcommand must be specified explicitly.

This is a click-powered command-line interface function, and not intended for programmatic use. Call with arguments ['--help'] to see full documentation of the interface. (See also click.testing.CliRunner for controlled, programmatic invocation.)

derivepassphrase_export_vault

derivepassphrase_export_vault(
    ctx: Context,
    /,
    *,
    path: str | bytes | PathLike[str],
    formats: Sequence[
        Literal["v0.2", "v0.3", "storeroom"]
    ] = (),
    key: str | bytes | None = None,
) -> None

Export a vault-native configuration to standard output.

Read the vault-native configuration at PATH, extract all information from it, and export the resulting configuration to standard output. Depending on the configuration format, PATH may either be a file or a directory. Supports the vault “v0.2”, “v0.3” and “storeroom” formats.

If PATH is explicitly given as VAULT_PATH, then use the VAULT_PATH environment variable to determine the correct path. (Use ./VAULT_PATH or similar to indicate a file/directory actually named VAULT_PATH.)

derivepassphrase_vault

derivepassphrase_vault(
    ctx: Context,
    /,
    *,
    service: str | None = None,
    use_phrase: bool = False,
    use_key: bool = False,
    length: int | None = None,
    repeat: int | None = None,
    lower: int | None = None,
    upper: int | None = None,
    number: int | None = None,
    space: int | None = None,
    dash: int | None = None,
    symbol: int | None = None,
    edit_notes: bool = False,
    store_config_only: bool = False,
    delete_service_settings: bool = False,
    delete_globals: bool = False,
    clear_all_settings: bool = False,
    export_settings: (
        TextIO | Path | PathLike[str] | None
    ) = None,
    import_settings: (
        TextIO | Path | PathLike[str] | None
    ) = None,
) -> None

Derive a passphrase using the vault(1) derivation scheme.

Using a master passphrase or a master SSH key, derive a passphrase for SERVICE, subject to length, character and character repetition constraints. The derivation is cryptographically strong, meaning that even if a single passphrase is compromised, guessing the master passphrase or a different service’s passphrase is computationally infeasible. 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.

If operating on global settings, or importing/exporting settings, then SERVICE must be omitted. Otherwise it is required.

This is a click-powered command-line interface function, and not intended for programmatic use. Call with arguments ['--help'] to see full documentation of the interface. (See also click.testing.CliRunner for controlled, programmatic invocation.)

Parameters:

Name	Type	Description	Default
ctx	Context	The click context.	required

Other Parameters:

Name	Type	Description
service	str | None	A service name. Required, unless operating on global settings or importing/exporting settings.
use_phrase	bool	Command-line argument -p/--phrase. If given, query the user for a passphrase instead of an SSH key.
use_key	bool	Command-line argument -k/--key. If given, query the user for an SSH key instead of a passphrase.
length	int | None	Command-line argument -l/--length. Override the default length of the generated passphrase.
repeat	int | None	Command-line argument -r/--repeat. Override the default repetition limit if positive, or disable the repetition limit if 0.
lower	int | None	Command-line argument --lower. Require a given amount of ASCII lowercase characters if positive, else forbid ASCII lowercase characters if 0.
upper	int | None	Command-line argument --upper. Same as lower, but for ASCII uppercase characters.
number	int | None	Command-line argument --number. Same as lower, but for ASCII digits.
space	int | None	Command-line argument --space. Same as lower, but for the space character.
dash	int | None	Command-line argument --dash. Same as lower, but for the hyphen-minus and underscore characters.
symbol	int | None	Command-line argument --symbol. Same as lower, but for all other ASCII printable characters (except backquote).
edit_notes	bool	Command-line argument -n/--notes. If given, spawn an editor to edit notes for service.
store_config_only	bool	Command-line argument -c/--config. If given, saves the other given settings (--key, …, --symbol) to the configuration file, either specifically for service or as global settings.
delete_service_settings	bool	Command-line argument -x/--delete. If given, removes the settings for service from the configuration file.
delete_globals	bool	Command-line argument --delete-globals. If given, removes the global settings from the configuration file.
clear_all_settings	bool	Command-line argument -X/--clear. If given, removes all settings from the configuration file.
export_settings	TextIO | Path | PathLike[str] | None	Command-line argument -e/--export. If a file object, then it must be open for writing and accept str inputs. Otherwise, a filename to open for writing. Using - for standard output is supported.
import_settings	TextIO | Path | PathLike[str] | None	Command-line argument -i/--import. If a file object, it must be open for reading and yield str values. Otherwise, a filename to open for reading. Using - for standard input is supported.