Types used by derivepassphrase.
module-attribute
¶
module-attribute
¶
SSHAgentSocketProvider: TypeAlias = (
"Callable[[], SSHAgentSocket]"
)
A callable that provides an SSH agent socket.
Bases: TypedDict
Common, optional arguments for the vault constructor.
(Also doubles as a base class for the vault configuration global settings.)
Attributes:
| Name | Type | Description |
|---|---|---|
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 |
number |
NotRequired[int]
|
Same as |
space |
NotRequired[int]
|
Same as |
dash |
NotRequired[int]
|
Same as |
symbol |
NotRequired[int]
|
Same as |
Bases: VaultConstructorArgs
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 |
instance-attribute
¶
unicode_normalization_form: NotRequired[
Literal["NFC", "NFD", "NFKC", "NFKD"]
]
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. |
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. |
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 |
new_value |
Any
|
The new value. |
Bases: Enum
SSH agent protocol numbers: client requests.
Attributes:
| Name | Type | Description |
|---|---|---|
REQUEST_IDENTITIES |
int
|
List identities. Expecting
|
SIGN_REQUEST |
int
|
Sign data. Expecting |
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 |
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 |
SIGN_RESPONSE |
int
|
Successful answer to |
EXTENSION_FAILURE |
int
|
Unsuccessful answer to |
EXTENSION_RESPONSE |
int
|
Successful answer to |
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. |
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. |
PEP 508 extras supported by derivepassphrase.
Attributes:
| Name | Type | Description |
|---|---|---|
EXPORT |
The necessary dependencies to allow the |
Optional features supported by derivepassphrase.
Attributes:
| Name | Type | Description |
|---|---|---|
SSH_KEY |
The This feature requires Python support for the SSH agent’s chosen communication channel technology. |
Derivation schemes provided by derivepassphrase.
Attributes:
| Name | Type | Description |
|---|---|---|
VAULT |
The derivation scheme used by James Coglan’s |
Configuration formats supported by derivepassphrase export.
Attributes:
| Name | Type | Description |
|---|---|---|
VAULT_STOREROOM |
The vault “storeroom” format for the |
|
VAULT_V02 |
The vault-native “v0.2” format for the |
|
VAULT_V03 |
The vault-native “v0.3” format for the |
SSH agent socket providers built into derivepassphrase.
Attributes:
| Name | Type | Description |
|---|---|---|
SSH_AUTH_SOCK_ON_POSIX |
A socket provider (on POSIX) that queries the
|
|
SSH_AUTH_SOCK_ON_WINDOWS |
A socket provider (on The Annoying OS, a.k.a. Microsoft
Windows) that queries the |
|
PAGEANT_ON_WINDOWS |
A socket provider (on The Annoying OS, a.k.a. Microsoft Windows) that connects to Pageant’s standard socket. The socket address is computed by the socket provider. |
|
OPENSSH_ON_WINDOWS |
A socket provider (on The Annoying OS, a.k.a. Microsoft Windows) that connects to OpenSSH on Windows’s standard socket. The socket address is hardcoded by the socket provider. |
|
STUB_AGENT |
A basic fake agent’s socket provider that only reacts to known test keys. Used by the test suite. |
|
STUB_AGENT_WITH_ADDRESS |
A more orchestratable fake agent’s socket provider, compared
to |
|
STUB_AGENT_WITH_ADDRESS_AND_DETERMINISTIC_DSA |
An elaborate fake agent’s socket provider that only reacts to known test keys. Used by the test suite. |
|
SSH_AUTH_SOCK |
A registry alias for |
|
UNIX_DOMAIN |
A registry alias for |
|
POSIX |
A registry alias for |
|
WINDOWS_NAMED_PIPE |
A registry alias for |
|
WINDOWS |
A registry alias for |
|
NATIVE |
class-attribute
instance-attribute
¶
SSH_AUTH_SOCK_ON_POSIX = 'ssh_auth_sock_on_posix'
class-attribute
instance-attribute
¶
SSH_AUTH_SOCK_ON_WINDOWS = 'ssh_auth_sock_on_windows'
class-attribute
instance-attribute
¶
STUB_AGENT_WITH_ADDRESS = 'stub_agent_with_address'
class-attribute
instance-attribute
¶
STUB_AGENT_WITH_ADDRESS_AND_DETERMINISTIC_DSA = (
"stub_agent_with_address_and_deterministic_dsa"
)
Return true if this SSH agent socket provider is available.
This works by actually attempting to connet to an agent via the socket provider.
Bases: Protocol
An abstract networking socket connected to an SSH agent.
The abstract socket supports the sendall
and a recv operation, with the same
signatures and semantics as for “real” sockets. The abstract socket
also supports use as a context manager, for automatically closing
the socket upon exiting the context.
Bases: NamedTuple
Registry information for the table of SSH agent socket providers.
Third-party developers can register new socket providers for
auto-discovery by setting up an entry point named
derivepassphrase.ssh_agent_socket_providers,
referencing an instance of this class. Upon startup of the vault
subsystem, derivepassphrase will then add appropriate entries to
the registry.
Attributes:
| Name | Type | Description |
|---|---|---|
provider |
SSHAgentSocketProvider
|
The callable that provides the socket. |
key |
str
|
The table key which this entry is registered as. |
aliases |
tuple[str, ...]
|
Other keys that shall point to this entry’s key. |
Note
The socket provider registry table uses the key as the key, and the provider as the value. It does not store this info object directly.
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(
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(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. |
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(
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 If cleanup was never attempted because of an obviously invalid
vault configuration, then |