`vault_gpg`¶

Interface with the Vault GPG secret engine.

The API docs can be found here.

Added in version 1.8.0.

Important

This module requires the general Vault setup.

saltext.vault.modules.vault_gpg.create_key(name, real_name=None, email=None, comment=None, key_bits=None, exportable=False, mount='gpg')[source]¶

Create a GPG key.

CLI Example:

salt '*' vault_gpg.create_key mykey real_name='Foo Bar' email='foo@b.ar'

Required policy:

path "<mount>/keys/<name>" {
    capabilities = ["create"]
}

name: Name of the key.
real_name: Real name of the identity associated with the GPG key to create.
email: Email of the identity associated with the GPG key to create.
comment: Comment of the identity associated with the GPG key to create.
key_bits: Bitlength of the generated GPG key. Defaults to 2048.
exportable: If the raw private key is exportable. Defaults to false.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.import_key(name, text=None, path=None, fingerprint=None, exportable=False, user=None, gnupghome=None, keyring=None, use_passphrase=False, mount='gpg')[source]¶

Import a GPG key.

CLI Example:

salt '*' vault_gpg.import_key mykey text="lQHYBGOH8R0BBACb1xGmsPqP8..."
salt '*' vault_gpg.import_key mykey text="-----BEGIN PGP PRIVATE KEY BLOCK..."
salt-call vault_gpg.import_key mykey path=/root/test.key
salt-call vault_gpg.import_key mykey fingerprint=3abcf1...

Required policy:

path "<mount>/keys/<name>" {
    capabilities = ["create"]
}

name: Name of the key.
text: ASCII-armored GPG private key as a string (or Python bytes type) to import. Can also be passed as a raw base64 string without markers and newlines. Either this, path or fingerprint is required.
path: Path to a file local to the minion containing the ASCII-armored GPG private key. Either this, text or fingerprint is required.
fingerprint: Fingerprint of a secret key to export from a GnuPG keyring using gpg.export_key. Either this, text or path is required.

Note

This parameter requires the GPG modules from Salt >= 3007.
exportable: If the raw private key should be exportable. Defaults to false.
user: When fingerprint is specified, which user’s keychain to access. Defaults to user Salt is running as. Passing the user as salt sets the GnuPG home directory to /etc/salt/gpgkeys.
gnupghome: When fingerprint is specified, the location where the GPG keyring and related files are stored. Defaults to the user’s default.
keyring: When fingerprint is specified, limit the operation to this specific keyring, specified as a local filesystem path.
use_passphrase: When fingerprint is specified, whether to use a passphrase to export the secret key. The passphrase is retrieved from the Pillar key gpg_passphrase.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.list_keys(mount='gpg')[source]¶

List configured keys.

CLI Example:

salt '*' vault_gpg.list_keys

Required policy:

path "<mount>/keys" {
    capabilities = ["list"]
}

mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.read_key(name, mount='gpg')[source]¶

Read a configured key’s information. Returns a dictionary with keys exportable, fingerprint and public_key. Returns None if it does not exist.

CLI Example:

salt '*' vault_gpg.read_key mykey

Required policy:

path "<mount>/keys/<name>" {
    capabilities = ["read"]
}

name: Name of the key.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.delete_key(name, mount='gpg')[source]¶

Delete a GPG key.

CLI Example:

salt '*' vault_gpg.delete_key mykey

Required policy:

path "<mount>/keys/<name>" {
    capabilities = ["delete"]
}

name: Name of the key.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.export_private_key(name, path=None, gnupg=False, user=None, gnupghome=None, keyring=None, mount='gpg')[source]¶

Export a configured private key (ASCII-armored). Requires the key to be exportable.

CLI Example:

salt '*' vault_gpg.export_private_key mykey
salt '*' vault_gpg.export_private_key mykey path=/root/test.key
salt '*' vault_gpg.export_private_key mykey gnupg=true

Required policy:

path "<mount>/export/<name>" {
    capabilities = ["read"]
}

name: Name of the key.
path: Export the private key to this file path. Missing parent dirs are created. Optional. If set, gnupg is ignored.
gnupg: Import the exported private key into a GnuPG keyring via gpg.import_key. Optional. Ignored when path is set.

Note

This parameter requires the GPG modules from Salt >= 3008.
user: When gnupg is true, which user’s keychain to access. Defaults to user Salt is running as. Passing the user as salt sets the GnuPG home directory to /etc/salt/gpgkeys.
gnupghome: When gnupg is true, the location where the GPG keyring and related files are stored. Defaults to the user’s default.
keyring: When gnupg is true, limit the operation to this specific keyring, specified as a local filesystem path.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.export_public_key(name, path=None, gnupg=False, user=None, gnupghome=None, keyring=None, mount='gpg')[source]¶

Export the public key of a configured private key (ASCII-armored). This is a convenience wrapper around read_key.

CLI Example:

salt '*' vault_gpg.export_public_key mykey
salt '*' vault_gpg.export_public_key mykey path=/root/test.pub
salt '*' vault_gpg.export_public_key mykey gnupg=True

Required policy:

path "<mount>/keys/<name>" {
    capabilities = ["read"]
}

name: Name of the key.
path: Export the public key to this file path. Missing parent dirs are created. Optional.
gnupg: Import the exported public key into a GnuPG keyring via gpg.import_key. Optional.

Note

This parameter requires the GPG modules from Salt >= 3008.
user: When gnupg is true, which user’s keychain to access. Defaults to user Salt is running as. Passing the user as salt sets the GnuPG home directory to /etc/salt/gpgkeys.
gnupghome: When gnupg is true, the location where the GPG keyring and related files are stored. Defaults to the user’s default.
keyring: When gnupg is true, limit the operation to this specific keyring, specified as a local filesystem path.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.sign(name, message=None, message_encoded=None, path=None, algorithm=None, encoding=None, mount='gpg')[source]¶

Sign data with a configured GPG key. Returns the (detached) signature.

CLI Example:

salt '*' vault_gpg.sign mykey message="Hello there"
salt '*' vault_gpg.sign mykey path=/my/important/file

Required policy:

path "<mount>/sign/<name>" {
    capabilities = ["create", "update"]
}

# or algorithm-dependent
path "<mount>/sign/<name>/<algorithm>" {
    capabilities = ["create", "update"]
}

name: Name of the key.
message: Data to sign. Can be a string (or a Python bytes type). Either this, message_encoded or path is required.
message_encoded: Data to sign. Can be a string (or a Python bytes type). Decoded from Base64 before signing. Either this, message or path is required.
path: Path to a file local to the minion with data to sign. Mind that the data is read into memory, which might be relevant if you are signing a very large file. Either this, message or message_encoded is required.
algorithm: Hash algorithm to use. Valid: sha2-224, sha2-256, sha2-384, sha2-512. Defaults to sha2-256.
encoding: Encoding format for the returned signature. Valid: base64, ascii-armor. Defaults to base64.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.verify(name, message=None, sig=None, message_encoded=None, path=None, sig_path=None, mount='gpg')[source]¶

Verify signed data with a configured GPG key.

CLI Example:

salt '*' vault_gpg.verify mykey message="Hello there" sig="wsBcBAABCgAQBQJZme..."
salt '*' vault_gpg.verify mykey message="Hello there" sig="-----BEGIN PGP SIGNATURE..."
salt '*' vault_gpg.verify mykey path=/my/important/file sig_path=/my/important/file.asc

Required policy:

path "<mount>/verify/<name>" {
    capabilities = ["create", "update"]
}

name: Name of the key.
message: Signed data as a string (or a Python bytes type). Either this, message_encoded or path is required.
sig: Detached signature to verify as a string (or a Python bytes type). Can also be passed as a raw base64 string without markers and newlines. Either this or sig_path is required.
message_encoded: Data to verify, encoded as Base64. Can be a string (or a Python bytes type). Decoded before verifying. Either this, message or path is required.
path: Path to a file local to the minion containing the signed data. Mind that the data is read into memory, which might be relevant if you are signing a very large file. Either this, message or message_encoded is required.
sig_path: Path to a file local to the minion containing the detached signature to verify. Either this or sig is required.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.decrypt(name, message=None, signer_key=None, path=None, signer_key_path=None, signer_key_fingerprint=None, user=None, gnupghome=None, keyring=None, decode=True, decode_utf8=True, mount='gpg')[source]¶

Decrypt a message with a configured GPG key.

CLI Example:

salt '*' vault_gpg.decrypt mykey message="wsBcBAABCgAQBQJZme..."
salt '*' vault_gpg.decrypt mykey message="-----BEGIN PGP MESSAGE..."
salt '*' vault_gpg.decrypt mykey path=/my/important/file

Required policy:

path "<mount>/decrypt/<name>" {
    capabilities = ["create", "update"]
}

name: Name of the key.
message: Ciphertext as a string (or a Python bytes type). Can also be passed as a raw base64 string. Either this or path is required.
signer_key: (ASCII-armored) GPG key of the signer as a string. Can also be passed as a raw base64 string without markers and newlines. Optional. If present, the ciphertext must be signed and the signature valid, otherwise the decryption fails.
path: Path to a file local to the minion containing the encrypted data. Mind that the data is read into memory, which might be relevant if you are decrypting a very large file. Either this or message is required.
signer_key_path: Path to a file local to the minion containing the (ASCII-armored) GPG key of the signer. Optional. If present, the ciphertext must be signed and the signature valid, otherwise the decryption fails.
signer_key_fingerprint: Fingerprint of the signer key. Used to fetch key via gpg.export_key. Optional. If present, the ciphertext must be signed and the signature valid, otherwise the decryption fails.

Note

This parameter requires the GPG modules from Salt >= 3007.
user: When signer_key_fingerprint is specified, which user’s keychain to access. Defaults to user Salt is running as. Passing the user as salt sets the GnuPG home directory to /etc/salt/gpgkeys.
gnupghome: When signer_key_fingerprint is specified, the location where the GPG keyring and related files are stored. Defaults to the user’s default.
keyring: When signer_key_fingerprint is specified, limit the operation to this specific keyring, specified as a local filesystem path.
decode: The API endpoint responds with the plaintext encoded in base64. Decode the return value using base64. Defaults to true.
decode_utf8: When decode is true, also decode the bytes returned by decoding base64 into a string (using UTF-8). Defaults to true.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

saltext.vault.modules.vault_gpg.show_session_key(name, message=None, signer_key=None, path=None, signer_key_path=None, mount='gpg')[source]¶

Decrypt and return the session key of the provided ciphertext using the configured GPG key.

CLI Example:

salt '*' vault_gpg.show_session_key mykey message="wsBcBAABCgAQBQJZme..."
salt '*' vault_gpg.show_session_key mykey message="-----BEGIN PGP MESSAGE..."
salt '*' vault_gpg.show_session_key mykey path=/my/important/file

Required policy:

path "<mount>/show-session-key/<name>" {
    capabilities = ["create", "update"]
}

name: Name of the key.
message: Ciphertext as a string (or a Python bytes type). Can also be passed as a raw base64 string. Either this or path is required.
signer_key: (ASCII-armored) GPG key of the signer as a string. Can also be passed as a raw base64 string without markers and newlines. Optional. If present, the ciphertext must be signed and the signature valid, otherwise the decryption fails.

Important

This is how it’s documented, but an invalid signature was ignored when this module was written.
path: Path to a file local to the minion containing the encrypted data. Mind that the data is read into memory, which might be relevant if you are decrypting a very large file. Either this or message is required.
signer_key_path: Path to a file local to the minion containing the (ASCII-armored) GPG key of the signer. Optional. If present, the ciphertext must be signed and the signature valid, otherwise the decryption fails.

Important

This is how it’s documented, but an invalid signature was ignored when this module was written.
mount: Mount path the GPG backend is mounted to. Defaults to gpg.

vault_gpg¶

`vault_gpg`¶