gpg module¶

GpgKey ¶

The GPG keys held in one key file on the target host.

Commands:

gpg --with-colons <src>

Returns:

list[GpgKeyInfo]

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_gpg_key.py.

GpgKeyDetails ¶

One key's full metadata from the executing user's keychain, or None.

Commands:

gpg --list-keys --with-colons -- <keyid> 2>/dev/null || true

Returns:

GpgKeyMetadata | None

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_gpg_key_details.py.

GpgKeyInfo ¶

Attributes:

Name	Type	Description
`id`		The key id (the last 16 hex digits of the fingerprint), the identity a colon-record listing names the key under.
`validity`		GPG's validity letter for the key (`-` unknown, `f` fully trusted, ...), exactly as the colon record prints it.
`length`		The key length in bits (e.g. 4096).
`fingerprint`		The full fingerprint, when a `fpr` record attached one.
`uid_hash`		The hash of the user id, when a `uid` record attached one.
`uid`		The user id string (name, comment and email), when a `uid` record attached one.
`subkeys`		The key's subkeys as further `GpgKeyInfo` entries (only the last `sub`/`ssb` record before the next primary key is kept); present on primary keys, absent on subkey entries.

GpgKeyMetadata ¶

Attributes:

Name	Type	Description
`id`		The primary key's id (the last 16 hex digits of the fingerprint).
`fingerprint`		The primary key's full fingerprint; `""` when the listing carried no `fpr` record.
`validity`		GPG's validity letter for the key (`u` ultimate, `f` full, `-` unknown, ...), exactly as the colon record prints it.
`length`		The primary key's length in bits (e.g. 4096).
`algo`		The public-key algorithm number as a string (`1` RSA, `22` EdDSA, ...), exactly as the colon record prints it.
`created`		The creation date as a raw epoch-seconds string (e.g. `"1794067588"`), kept raw so entries stay JSON-printable.
`capabilities`		The key's capability letters (e.g. `escarESCA`), exactly as the colon record prints them.
`expires`		The expiration date as a raw epoch-seconds string; absent when the key never expires (an empty colon field).
`uids`		Every user id string attached to the key, in listing order; `[]` when the listing carried no `uid` records.
`subkeys`		The key's subkeys as `GpgKeyInfo` entries (only the last `sub` record before the next primary key is kept, the shared parser's convention).

GpgKeyTrust ¶

Attributes:

Name	Type	Description
`fingerprint`		The full fingerprint of the key the ownertrust assignment names.
`ownertrust`		The raw numeric trust value exactly as the export line prints it (1-6; 5 and 6 both mean ultimate).
`level`		The trust level name for `ownertrust` (`unknown`, `never`, `marginal`, `full` or `ultimate`); an unrecognized number maps to `unknown` while keeping the raw value.

GpgKeyring ¶

Attributes:

Name	Type	Description
`path`		The keyring file's path, exactly as the `KEYRING:` marker line names it.
`format`		The file's extension lowercased (`gpg`, `kbx` or `asc`), the format label.
`keys`		The keys the file holds, as `GpgKeyInfo` entries in listing order; a keyring `gpg` could not read contributes no entry at all rather than an empty list.

GpgKeyrings ¶

The GPG keyring files found under given directories, with their keys.

Commands:

find "<directories>" -type f \( -name '*.gpg' -o -name '*.kbx' \) 2>/dev/null -exec sh -c 'echo "KEYRING:$1"; gpg --list-keys --with-colons --keyring "$1" --no-default-keyring 2>/dev/null || true' _ {} \; ; find "<directories>" -type f -name '*.asc' 2>/dev/null -exec sh -c 'echo "KEYRING:$1"; gpg --with-colons "$1" 2>/dev/null || true' _ {} \;

Returns:

list[GpgKeyring]

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_gpg_keyrings.py.

GpgKeys ¶

The public GPG keys in the executing user's keychain, or one keyring file.

Commands:

gpg --list-keys --with-colons

Returns:

list[GpgKeyInfo]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/gpg/gpg_gpg_keys.py.

GpgSecretKeys ¶

The secret GPG keys in the executing user's keychain, or one keyring file.

Commands:

gpg --list-secret-keys --with-colons

Returns:

list[GpgKeyInfo]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/gpg/gpg_gpg_secret_keys.py.

GpgTrust ¶

The ownertrust assignments in the executing user's trust database.

Commands:

gpg --batch --export-ownertrust 2>/dev/null || true

Returns:

list[GpgKeyTrust]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/gpg/gpg_gpg_trust.py.

GpgVerification ¶

Attributes:

Name	Type	Description
`valid`		True only when gpg reported a good signature (`GOODSIG`).
`status`		The deciding status line lowercased (`goodsig`, `badsig`, `no_pubkey` or `errsig`), or `error` when no recognized status line was printed at all.
`keyid`		The signing key's id as the status line names it; absent when `status` is `error`.
`signer`		The signing key's user id string; present only for `goodsig` and `badsig` (the statuses that carry one).

GpgVerify ¶

The outcome of verifying a signature on the target host, read-only.

Commands:

gpg --batch --status-fd 1 --verify <signature> [<file>] 2>/dev/null || true

Returns:

GpgVerification

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_gpg_verify.py.

dearmor `async` ¶

dearmor(
    ctx: OpContext, src: str, dest: str, **kwargs: Any
) -> AsyncGenerator[Command]

Convert an ASCII-armored GPG key file to binary format on the target host.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`str`	Path of the ASCII-armored key file on the target host.	required
`dest`	`str`	Path of the binary key file to write on the target host; its parent directory is created when missing.	required
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The dearmor command, always (the operation is stateless).

Raises:

ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_dearmor.py.

delete_key `async` ¶

delete_key(
    ctx: OpContext,
    keyid: str,
    secret: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Delete a GPG key from the executing user's keychain.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`keyid`	`str`	The key id, long id or fingerprint to delete (`0x` prefixes accepted); resolved to the full fingerprint from the keychain listing before deleting.	required
`secret`	`bool`	Whether to delete the secret and public key (`--delete-secret-and-public-keys`, looked up in `GpgSecretKeys`) instead of only the public key (`--delete-keys`, looked up in `GpgKeys`). Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated gpg key-deletion commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_delete_key.py.

export_key `async` ¶

export_key(
    ctx: OpContext,
    keyid: str,
    dest: str,
    armor: bool = False,
    secret: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Export a GPG key from the executing user's keychain to a file.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`keyid`	`str`	The key id, long id or fingerprint to export (`0x` prefixes accepted by gpg).	required
`dest`	`str`	Path of the export file to write on the target host; its parent directory is created when missing.	required
`armor`	`bool`	Whether to write ASCII-armored output (`--armor`) instead of binary. Defaults to False.	`False`
`secret`	`bool`	Whether to export the secret key (`--export-secret-keys`) instead of the public key. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The export command, always (the operation is stateless).

Raises:

ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_export_key.py.

gen_key `async` ¶

gen_key(
    ctx: OpContext,
    real_name: str,
    email: str,
    algo: str = "rsa",
    length: int = 4096,
    expire: str = "never",
    **kwargs: Any,
) -> AsyncGenerator[Command]

Generate a GPG key in the executing user's keychain.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`real_name`	`str`	The key user id's real name (the `Name-Real` batch parameter).	required
`email`	`str`	The key user id's email address (the `Name-Email` batch parameter).	required
`algo`	`str`	The key algorithm (the `Key-Type` batch parameter, e.g. `rsa`, `eddsa`). Defaults to "rsa".	`'rsa'`
`length`	`int`	The key length in bits (the `Key-Length` batch parameter). Defaults to 4096.	`4096`
`expire`	`str`	The key's expiry (the `Expire-Date` batch parameter: `never`, a date, or a `2y`-style interval). Defaults to "never".	`'never'`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated gpg key-generation commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_gen_key.py.

import_key `async` ¶

import_key(
    ctx: OpContext,
    src: IO[Any],
    keyid: str | None = None,
    secret: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Import a GPG key stream into the executing user's keychain.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`IO[Any]`	The key content as a seekable IO-like object on the control machine (an `io.BytesIO`/`io.StringIO`, a file opened with `open()`, ...), rewound to position 0 before it is read; public and secret key material are both accepted.	required
`keyid`	`str \| None`	The key id or fingerprint (`0x` prefix accepted) that makes the import idempotent: when the keychain already holds a matching key, nothing is imported. Without it the import always runs. Defaults to None.	`None`
`secret`	`bool`	Whether `keyid` is checked against the secret keys (`GpgSecretKeys`) instead of the public keys (`GpgKeys`). Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated gpg import commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_import_key.py.

key `async` ¶

key(
    ctx: OpContext,
    src: IO[Any] | None = None,
    dest: str | None = None,
    keyid: str | list[str] | tuple[str, ...] | None = None,
    present: bool = True,
    working_dirs: list[str] | tuple[str, ...] | None = None,
    dearmor: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Install or remove GPG keyring files on the target host.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`IO[Any] \| None`	The key content as a seekable IO-like object on the control machine (an `io.BytesIO`/`io.StringIO`, a file opened with `open()`, ...), rewound to position 0 before it is read; ASCII-armored and binary key content are both accepted. Required for installation, unused for removal. Defaults to None.	`None`
`dest`	`str \| None`	The keyring file path on the target host. Required for installation; for removal it names the one keyring to act on (the whole file without `keyid`, selective keys with it). Defaults to None.	`None`
`keyid`	`str \| list[str] \| tuple[str, ...] \| None`	Key id(s) or fingerprint(s) (`0x` prefixes accepted). Prefer tuples when building requests via `op()`, since `OperationRequest` kwargs must stay hashable. With `present=True` they make the install idempotent per key via `GpgKeyrings`; with `present=False` they select the keys to delete from `dest` or from every keyring under `working_dirs`. Defaults to None.	`None`
`present`	`bool`	Whether the key/keyring should be present (True) or absent (False). Defaults to True.	`True`
`working_dirs`	`list[str] \| tuple[str, ...] \| None`	Directories to scan for keyrings when removing by `keyid` without `dest` (prefer tuples via `op()`). Unused for installation. Defaults to None.	`None`
`dearmor`	`bool`	Whether to convert ASCII-armored key content to binary form on install (the content is sniffed, not the file extension); False copies the stream verbatim. Defaults to True.	`True`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated gpg keyring commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_key.py.

refresh_keys `async` ¶

refresh_keys(
    ctx: OpContext,
    keyids: str | list[str] | tuple[str, ...] | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Refresh GPG keys from the keyservers.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`keyids`	`str \| list[str] \| tuple[str, ...] \| None`	The key id(s) or fingerprint(s) to refresh (`0x` prefixes accepted). Prefer tuples when building requests via `op()`, since `OperationRequest` kwargs must stay hashable. None refreshes every key in the keychain. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The refresh command, always (the operation is stateless).

Raises:

None

Examples:

Examples can be found in examples/modules/gpg/gpg_refresh_keys.py.

trust `async` ¶

trust(
    ctx: OpContext,
    fingerprint: str,
    level: str,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Set one key's ownertrust in the executing user's trust database.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`fingerprint`	`str`	The full fingerprint of the key whose ownertrust is set.	required
`level`	`str`	The trust level: `unknown`, `never`, `marginal`, `full` or `ultimate`.	required
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated gpg ownertrust commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/gpg/gpg_trust.py.

gpg module¶

GpgKey ¶

GpgKeyDetails ¶

GpgKeyInfo ¶

GpgKeyMetadata ¶

GpgKeyTrust ¶

GpgKeyring ¶

GpgKeyrings ¶

GpgKeys ¶

GpgSecretKeys ¶

GpgTrust ¶

GpgVerification ¶

GpgVerify ¶

dearmor async ¶

delete_key async ¶

export_key async ¶

gen_key async ¶

import_key async ¶

key async ¶

refresh_keys async ¶

trust async ¶

dearmor `async` ¶

delete_key `async` ¶

export_key `async` ¶

gen_key `async` ¶

import_key `async` ¶

key `async` ¶

refresh_keys `async` ¶

trust `async` ¶