API Reference

PocketProtector’s Python API provides programmatic access to the same operations available through the CLI. All public symbols are importable from the top-level pocket_protector package.

from pocket_protector import KeyFile, Creds, PPError, KDF_SENSITIVE, KDF_INTERACTIVE

KeyFile

class pocket_protector.file_keys.KeyFile(path, domains=NOTHING, key_custodians=NOTHING, log=NOTHING)

Represents a key-file (containing many domains) Can be read from and written to disk

classmethod create(path)

classmethod from_file(path)

create a new KeyFile from path

classmethod from_contents_and_path(bytes, path)

create a new KeyFile from file contents

get_domain_names()

get_domain_secret_names(domain_name)

get_all_secret_names()

return a map of secret names to names of domains that contain that secret

get_contents()

get_audit_log()

write()

write contents to file

add_domain(domain_name, key_custodian_name)

return a copy with a new domain, empty but with one initial key custodian owner who can add other owners

rm_domain(domain_name)

return a copy with domain domain_name removed

set_secret(domain_name, name, value)

return a copy of the KeyFile with the given secret name and value added to a domain

add_secret(domain_name, name, value)

add a secret that doesnt exist yet

update_secret(domain_name, name, value)

update the value of a secret that already exists

rm_secret(domain_name, name)

return a copy with secret removed from domain

add_owner(domain_name, key_custodian_name, creds)

Register a new key custodian owner of domain_name based on the credentials of an existing owner

rm_owner(domain_name, key_custodian_name)

Remove an owner from domain. (NOTE: due to file history, the removed owner will still be able to get to values until you rotate the domain keypair, and secret values)

add_key_custodian(creds, opslimit=None, memlimit=None)

add_raw_key_custodian(creds)

add a key custodian using a raw-key (P<64hex>P) passphrase, no KDF

rm_key_custodian(key_custodian_name)

remove key custodian and all domain ownerships

decrypt_domain(domain_name, creds)

set_key_custodian_passphrase(creds, new_passphrase, opslimit=None, memlimit=None)

rekey_custodian(creds, new_creds, raw_key=False, opslimit=None, memlimit=None)

Replace a custodian’s key material entirely (new passphrase, new KDF type). The custodian name (email) must match between creds and new_creds.

check_creds(creds)

get_custodian_domains(key_custodian_name)

Return list of domain names where key_custodian_name is an owner.

migrate_owner(new_custodian_name, creds, domain_names=None)

Add new_custodian_name as owner to all (or specified) domains owned by creds user.

rotate_domain_key(domain_name, creds)

rotate the keypair used to secure a domain NIST recommends keys be rotated and not kept in use for more than ~1-3 years see http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r4.pdf Recommendation for Key Management, Part 1: General section 5.3.6 Cryptoperiod Recommendations for Specific Key Types

truncate_audit_log(max_keep)

Note

KeyFile is a frozen (immutable) attrs class. All mutating methods return a new KeyFile instance. You must call write() on the result to persist changes to disk.

Creds

class pocket_protector.file_keys.Creds(name, passphrase, name_source=None, passphrase_source=None)

Stores credentials used to open a KeyFile

classmethod from_env(prefix=None)

Create Creds from environment variables.

Parameters:

prefix – Env var prefix (e.g. ‘MYAPP’ reads MYAPP_USER / MYAPP_PASSPHRASE). If None, falls back to PPROTECT_ENV_PREFIX env var, then ‘PPROTECT’.

Returns:

Creds with name and passphrase from env vars, or empty strings if unset. name_source and passphrase_source record which env vars were consulted.

Creds is a frozen attrs class with four fields:

• name (str) – the custodian’s email address

• passphrase (str) – the custodian’s passphrase

• name_source (str or None) – how the name was obtained (e.g., "stdin", "env var: PPROTECT_USER")

• passphrase_source (str or None) – how the passphrase was obtained

classmethod Creds.from_env(prefix=None)

Create Creds from environment variables. If prefix is None, reads PPROTECT_ENV_PREFIX to determine the prefix, defaulting to PPROTECT. Returns Creds with name from {prefix}_USER and passphrase from {prefix}_PASSPHRASE (empty string if unset).

PPError

exception pocket_protector.file_keys.PPError

Bases: Exception

Base exception for PocketProtector errors. Inherits from Exception.

Constants

pocket_protector.KDF_SENSITIVE

KDF parameters for production use: (OPSLIMIT_SENSITIVE, MEMLIMIT_MODERATE). Approximately 0.8 seconds and 256 MB of memory. This is the default when creating custodians with --key-type hard.

pocket_protector.KDF_INTERACTIVE

KDF parameters for development and testing: (OPSLIMIT_INTERACTIVE, MEMLIMIT_INTERACTIVE). Approximately 0.1 seconds and 64 MB of memory. Used with --key-type fast.