Skip to content

derivepassphrase._types

Types used by derivepassphrase.

T_Buffer module-attribute

T_Buffer = TypeVar('T_Buffer', bound=Buffer)

A TypeVar for classes implementing the Buffer interface.

Warning

Non-public attribute, provided for didactical and educational purposes only. Subject to change without notice, including removal.

VaultConfigGlobalSettings

Bases: TypedDict

Configuration for vault: global settings.

Attributes:

Name Type Description
key NotRequired[str]

The base64-encoded ssh public key to use, overriding the master passphrase. Optional.

phrase NotRequired[str]

The master passphrase. Optional.

unicode_normalization_form NotRequired[Literal['NFC', 'NFD', 'NFKC', 'NFKD']]

The preferred Unicode normalization form; we warn the user if textual passphrases do not match their normalized forms. Optional, and a derivepassphrase extension.

length NotRequired[int]

Desired passphrase length.

repeat NotRequired[int]

The maximum number of immediate character repetitions allowed in the passphrase. Disabled if set to 0.

lower NotRequired[int]

Optional constraint on ASCII lowercase characters. If positive, include this many lowercase characters somewhere in the passphrase. If 0, avoid lowercase characters altogether.

upper NotRequired[int]

Same as lower, but for ASCII uppercase characters.

number NotRequired[int]

Same as lower, but for ASCII digits.

space NotRequired[int]

Same as lower, but for the space character.

dash NotRequired[int]

Same as lower, but for the hyphen-minus and underscore characters.

symbol NotRequired[int]

Same as lower, but for all other hitherto unlisted ASCII printable characters (except backquote).

key instance-attribute

phrase instance-attribute

phrase: NotRequired[str]

unicode_normalization_form instance-attribute

unicode_normalization_form: NotRequired[
    Literal["NFC", "NFD", "NFKC", "NFKD"]
]

length instance-attribute

length: NotRequired[int]

repeat instance-attribute

repeat: NotRequired[int]

lower instance-attribute

lower: NotRequired[int]

upper instance-attribute

upper: NotRequired[int]

number instance-attribute

number: NotRequired[int]

space instance-attribute

space: NotRequired[int]

dash instance-attribute

symbol instance-attribute

symbol: NotRequired[int]

VaultConfigServicesSettings

Bases: VaultConfigGlobalSettings

Configuration for vault: services settings.

Attributes:

Name Type Description
notes NotRequired[str]

Optional notes for this service, to display to the user when generating the passphrase.

key NotRequired[str]

As per the global settings.

phrase NotRequired[str]

As per the global settings.

unicode_normalization_form NotRequired[Literal['NFC', 'NFD', 'NFKC', 'NFKD']]

As per the global settings.

length NotRequired[int]

As per the global settings.

repeat NotRequired[int]

As per the global settings.

lower NotRequired[int]

As per the global settings.

upper NotRequired[int]

As per the global settings.

number NotRequired[int]

As per the global settings.

space NotRequired[int]

As per the global settings.

dash NotRequired[int]

As per the global settings.

symbol NotRequired[int]

As per the global settings.

notes instance-attribute

notes: NotRequired[str]

VaultConfig

Bases: TypedDict, _VaultConfig

Configuration for vault. For typing purposes.

Usually stored as JSON.

Attributes:

Name Type Description
global NotRequired[VaultConfigGlobalSettings]

Global settings.

services Required[dict[str, VaultConfigServicesSettings]]

Service-specific settings.

CleanupStep

Bases: NamedTuple

A single executed step during vault config cleanup.

Attributes:

Name Type Description
path Sequence[str | int]

A sequence of object keys or array indices to navigate to the JSON value that was cleaned up.

old_value Any

The old value.

action Literal['replace', 'remove']

Either 'replace' if old_value was replaced with new_value, or 'remove' if old_value was removed.

new_value Any

The new value.

path instance-attribute

path: Sequence[str | int]

old_value instance-attribute

old_value: Any

action instance-attribute

action: Literal['replace', 'remove']

new_value instance-attribute

new_value: Any

SSHKeyCommentPair

Bases: NamedTuple, Generic[T_Buffer]

SSH key plus comment pair. For typing purposes.

Attributes:

Name Type Description
key T_Buffer

SSH key.

comment T_Buffer

SSH key comment.

key instance-attribute

key: T_Buffer

comment instance-attribute

comment: T_Buffer

toreadonly

toreadonly() -> SSHKeyCommentPair[bytes]

Return a copy with read-only entries.

SSH_AGENTC

Bases: Enum

SSH agent protocol numbers: client requests.

Attributes:

Name Type Description
REQUEST_IDENTITIES int

List identities. Expecting SSH_AGENT.IDENTITIES_ANSWER.

SIGN_REQUEST int

Sign data. Expecting SSH_AGENT.SIGN_RESPONSE.

ADD_IDENTITY int

Add an (SSH2) identity.

REMOVE_IDENTITY int

Remove an (SSH2) identity.

ADD_ID_CONSTRAINED int

Add an (SSH2) identity, including key constraints.

EXTENSION int

Issue a named request that isn’t part of the core agent protocol. Expecting SSH_AGENT.EXTENSION_RESPONSE or SSH_AGENT.EXTENSION_FAILURE if the named request is supported, SSH_AGENT.FAILURE otherwise.

REQUEST_IDENTITIES class-attribute instance-attribute

REQUEST_IDENTITIES = 11

SIGN_REQUEST class-attribute instance-attribute

SIGN_REQUEST = 13

ADD_IDENTITY class-attribute instance-attribute

ADD_IDENTITY = 17

REMOVE_IDENTITY class-attribute instance-attribute

REMOVE_IDENTITY = 18

ADD_ID_CONSTRAINED class-attribute instance-attribute

ADD_ID_CONSTRAINED = 25

EXTENSION class-attribute instance-attribute

EXTENSION = 27

SSH_AGENT

Bases: Enum

SSH agent protocol numbers: server replies.

Attributes:

Name Type Description
FAILURE int

Generic failure code.

SUCCESS int

Generic success code.

IDENTITIES_ANSWER int

Successful answer to SSH_AGENTC.REQUEST_IDENTITIES.

SIGN_RESPONSE int

Successful answer to SSH_AGENTC.SIGN_REQUEST.

EXTENSION_FAILURE int

Unsuccessful answer to SSH_AGENTC.EXTENSION.

EXTENSION_RESPONSE int

Successful answer to SSH_AGENTC.EXTENSION.

FAILURE class-attribute instance-attribute

FAILURE = 5

SUCCESS class-attribute instance-attribute

SUCCESS = 6

IDENTITIES_ANSWER class-attribute instance-attribute

IDENTITIES_ANSWER = 12

SIGN_RESPONSE class-attribute instance-attribute

SIGN_RESPONSE = 14

EXTENSION_FAILURE class-attribute instance-attribute

EXTENSION_FAILURE = 28

EXTENSION_RESPONSE class-attribute instance-attribute

EXTENSION_RESPONSE = 29

StoreroomKeyPair

Bases: NamedTuple, Generic[T_Buffer]

A pair of AES256 keys, one for encryption and one for signing.

Attributes:

Name Type Description
encryption_key T_Buffer

AES256 key, used for encryption with AES256-CBC (with PKCS#7 padding).

signing_key T_Buffer

AES256 key, used for signing with HMAC-SHA256.

encryption_key instance-attribute

encryption_key: T_Buffer

signing_key instance-attribute

signing_key: T_Buffer

toreadonly

toreadonly() -> StoreroomKeyPair[bytes]

Return a copy with read-only entries.

StoreroomMasterKeys

Bases: NamedTuple, Generic[T_Buffer]

A triple of AES256 keys, for encryption, signing and hashing.

Attributes:

Name Type Description
hashing_key T_Buffer

AES256 key, used for hashing with HMAC-SHA256 to derive a hash table slot for an item.

encryption_key T_Buffer

AES256 key, used for encryption with AES256-CBC (with PKCS#7 padding).

signing_key T_Buffer

AES256 key, used for signing with HMAC-SHA256.

hashing_key instance-attribute

hashing_key: T_Buffer

encryption_key instance-attribute

encryption_key: T_Buffer

signing_key instance-attribute

signing_key: T_Buffer

toreadonly

toreadonly() -> StoreroomMasterKeys[bytes]

Return a copy with read-only entries.

PEP508Extra

Bases: str, Enum

PEP 508 extras supported by derivepassphrase.

Attributes:

Name Type Description
EXPORT

The necessary dependencies to allow the export subcommand to handle as many foreign configuration formats as possible.

EXPORT class-attribute instance-attribute

EXPORT = 'export'

Feature

Bases: str, Enum

Optional features supported by derivepassphrase.

Attributes:

Name Type Description
SSH_KEY

The vault subcommand supports using a master SSH key, instead of a master passphrase, if an SSH agent is running and the master SSH key is loaded into it.

This feature requires Python support for the SSH agent’s chosen communication channel technology.

SSH_KEY class-attribute instance-attribute

SSH_KEY = 'master SSH key'

DerivationScheme

Bases: str, Enum

Derivation schemes provided by derivepassphrase.

Attributes:

Name Type Description
VAULT

The derivation scheme used by James Coglan’s vault.

VAULT class-attribute instance-attribute

VAULT = 'vault'

ForeignConfigurationFormat

Bases: str, Enum

Configuration formats supported by derivepassphrase export.

Attributes:

Name Type Description
VAULT_STOREROOM

The vault “storeroom” format for the export vault subcommand.

VAULT_V02

The vault-native “v0.2” format for the export vault subcommand.

VAULT_V03

The vault-native “v0.3” format for the export vault subcommand.

VAULT_STOREROOM class-attribute instance-attribute

VAULT_STOREROOM = 'vault storeroom'

VAULT_V02 class-attribute instance-attribute

VAULT_V02 = 'vault v0.2'

VAULT_V03 class-attribute instance-attribute

VAULT_V03 = 'vault v0.3'

ExportSubcommand

Bases: str, Enum

Subcommands provided by derivepassphrase export.

Attributes:

Name Type Description
VAULT

The export vault subcommand.

VAULT class-attribute instance-attribute

VAULT = 'vault'

Subcommand

Bases: str, Enum

Subcommands provided by derivepassphrase.

Attributes:

Name Type Description
EXPORT

The export subcommand.

VAULT

The vault subcommand.

EXPORT class-attribute instance-attribute

EXPORT = 'export'

VAULT class-attribute instance-attribute

VAULT = 'vault'

json_path

json_path(path: Sequence[str | int]) -> str

Transform a series of keys and indices into a JSONPath selector.

The resulting JSONPath selector conforms to RFC 9535, is always rooted at the JSON root node (i.e., starts with $), and only contains name and index selectors (in shorthand dot notation, where possible).

Parameters:

Name Type Description Default
path Sequence[str | int]

A sequence of object keys or array indices to navigate to the desired JSON value, starting from the root node.

required

Returns:

Type Description
str

A valid JSONPath selector (a string) identifying the desired JSON value.

Examples:

>>> json_path(['global', 'phrase'])
'$.global.phrase'
>>> json_path(['services', 'service name with spaces', 'length'])
'$.services["service name with spaces"].length'
>>> json_path(['services', 'special\u000acharacters', 'notes'])
'$.services["special\\ncharacters"].notes'
>>> print(json_path(['services', 'special\u000acharacters', 'notes']))
$.services["special\ncharacters"].notes
>>> json_path(['custom_array', 2, 0])
'$.custom_array[2][0]'

validate_vault_config

validate_vault_config(
    obj: Any,
    /,
    *,
    allow_derivepassphrase_extensions: bool,
    allow_unknown_settings: bool = False,
) -> None
validate_vault_config(
    obj: Any, /, *, allow_unknown_settings: bool = False
) -> None
validate_vault_config(
    obj: Any,
    /,
    *,
    allow_unknown_settings: bool = False,
    allow_derivepassphrase_extensions: bool = _Omitted(),
) -> None

Check that obj is a valid vault config.

Parameters:

Name Type Description Default
obj Any

The object to test.

required
allow_unknown_settings bool

If false, abort on unknown settings.

False
allow_derivepassphrase_extensions bool

(Deprecated.) Ignored since v0.4.0.

_Omitted()

Raises:

Type Description
TypeError

An entry in the vault config, or the vault config itself, has the wrong type.

ValueError

An entry in the vault config is not allowed, or has a disallowed value.

Deprecated argument

v0.4.0: The allow_derivepassphrase_extensions keyword argument is deprecated, and will be removed in v1.0. There are no specified derivepassphrase extensions.

is_vault_config

is_vault_config(obj: Any) -> TypeIs[VaultConfig]

Check if obj is a valid vault config, according to typing.

Parameters:

Name Type Description Default
obj Any

The object to test.

required

Returns:

Type Description
TypeIs[VaultConfig]

True if this is a vault config, false otherwise.

js_truthiness

js_truthiness(value: Any) -> bool

Return the truthiness of the value, according to JavaScript/ECMAScript.

Like Python, ECMAScript considers certain values to be false in a boolean context, and every other value to be true. These considerations do not agree: ECMAScript considers math.nan to be false too, and empty arrays and objects/dicts to be true, contrary to Python. Because of these discrepancies, we cannot defer to bool for ECMAScript truthiness checking, and need a separate, explicit predicate.

(Some falsy values in ECMAScript aren’t defined in Python: undefined, and document.all. We do not implement support for those.)

Note

We cannot use a simple value not in falsy_values check, because math.nan behaves in annoying and obstructive ways. In general, float('NaN') == float('NaN') is false, and float('NaN') != math.nan and math.nan != math.nan are true. CPython says float('NaN') in [math.nan] is false, PyPy3 says it is true. Seemingly the only reliable and portable way to check for math.nan is to use math.isnan directly.

Parameters:

Name Type Description Default
value Any

The value to test.

required

clean_up_falsy_vault_config_values

clean_up_falsy_vault_config_values(
    obj: Any,
) -> Sequence[CleanupStep] | None

Convert falsy values in a vault config to correct types, in-place.

Needed for compatibility with vault(1), which sometimes uses only truthiness checks.

If vault(1) considered obj to be valid, then after clean up, obj will be valid as per validate_vault_config.

Parameters:

Name Type Description Default
obj Any

A presumed valid vault configuration save for using falsy values of the wrong type.

required

Returns:

Type Description
Sequence[CleanupStep] | None

A list of 4-tuples (key_tup, old_value, action, new_value), indicating the cleanup actions performed. key_tup is a sequence of object keys and/or array indices indicating the JSON path to the leaf value that was cleaned up, old_value is the old value, new_value is the new value, and action is either replace (old_value was replaced with new_value) or remove (old_value was removed, and new_value is meaningless).

If cleanup was never attempted because of an obviously invalid vault configuration, then None is returned, directly.