certbot.crypto_util module

Certbot client crypto utility functions.

certbot.crypto_util.generate_key(key_size: int, key_dir: str | None, key_type: str = 'rsa', elliptic_curve: str = 'secp256r1', keyname: str = 'key-certbot.pem', strict_permissions: bool = True) → Key[source]
Initializes and saves a privkey.

Inits key and saves it in PEM format on the filesystem.

Parameters:

• key_size (int) – key size in bits if key size is rsa.

• key_dir (str) – Optional key save directory.

• key_type (str) – Key Type [rsa, ecdsa]

• elliptic_curve (str) – Name of the elliptic curve if key type is ecdsa.

• keyname (str) – Filename of key

• strict_permissions (bool) – If true and key_dir exists, an exception is raised if the directory doesn’t have 0700 permissions or isn’t owned by the current user.

Returns:
Key

Return type:
certbot.util.Key

Raises:
ValueError – If unable to generate the key given key_size.

certbot.crypto_util.generate_csr(privkey: Key, names: list[str] | set[str], path: str | None, must_staple: bool = False, strict_permissions: bool = True, ipaddrs: list[IPv4Address | IPv6Address] | None = None) → CSR[source]
Initialize a CSR with the given private key.

Parameters:

• privkey (certbot.util.Key) – Key to include in the CSR

• names (set) – str names to include in the CSR

• path (str) – Optional certificate save directory.

• must_staple (bool) – If true, include the TLS Feature extension “OCSP Must-Staple”

• strict_permissions (bool) – If true and path exists, an exception is raised if the directory doesn’t have 0755 permissions or isn’t owned by the current user.

Returns:
CSR

Return type:
certbot.util.CSR

certbot.crypto_util.valid_csr(csr: bytes) → bool[source]
Validate CSR.

Check if csr is a valid CSR with a correct self-signed signature.

Parameters:
csr (bytes) – CSR in PEM.

Returns:
Validity of CSR.

Return type:
bool

certbot.crypto_util.csr_matches_pubkey(csr: bytes, privkey: bytes) → bool[source]
Does private key correspond to the subject public key in the CSR?

Parameters:

• csr (bytes) – CSR in PEM.

• privkey (bytes) – Private key file contents (PEM)

Returns:
Correspondence of private key to CSR subject public key.

Return type:
bool

certbot.crypto_util.read_csr_file(csrfile: str, data: bytes) → CSR[source]
Reads a CSR file, which can be either PEM or DER, and returns a certbot.util.CSR object.

Parameters:

• csrfile (str) – CSR filename

• data (bytes) – contents of the CSR file

Returns:
object representing the CSR

Return type:
util.CSR

certbot.crypto_util.import_csr_file(csrfile: str, data: bytes) → tuple[Format, CSR, list[str]][source]
Import a CSR file, which can be either PEM or DER.

Parameters:

• csrfile (str) – CSR filename

• data (bytes) – contents of the CSR file

Returns:
(acme_crypto_util.Format.PEM, util.CSR object representing the CSR, list of domains requested in the CSR)

Return type:
tuple

certbot.crypto_util.make_key(bits: int = 2048, key_type: str = 'rsa', elliptic_curve: str | None = None) → bytes[source]
Generate PEM encoded RSA|EC key.

Parameters:

• bits (int) – Number of bits if key_type=rsa. At least 2048 for RSA.

• key_type (str) – The type of key to generate, but be rsa or ecdsa

• elliptic_curve (str) – The elliptic curve to use.

Returns:
new RSA or ECDSA key in PEM form with specified number of bits or of type ec_curve when key_type ecdsa is used.

Return type:
bytes

certbot.crypto_util.valid_privkey(privkey: str | bytes) → bool[source]
Is valid RSA private key?

Parameters:
privkey – Private key file contents in PEM

Returns:
Validity of private key.

Return type:
bool

certbot.crypto_util.verify_renewable_cert(renewable_cert: RenewableCert) → None[source]
For checking that your certs were not corrupted on disk.

Several things are checked:

1. Signature verification for the cert.

2. That fullchain matches cert and chain when concatenated.

3. Check that the private key matches the certificate.

Parameters:
renewable_cert (certbot.interfaces.RenewableCert) – cert to verify

Raises:
errors.Error – If verification fails.

certbot.crypto_util.verify_renewable_cert_sig(renewable_cert: RenewableCert) → None[source]
Verifies the signature of a RenewableCert object.

Parameters:
renewable_cert (certbot.interfaces.RenewableCert) – cert to verify

Raises:
errors.Error – If signature verification fails.

certbot.crypto_util.verify_signed_payload(public_key: DSAPublicKey | Ed25519PublicKey | Ed448PublicKey | EllipticCurvePublicKey | MLDSA44PublicKey | MLDSA65PublicKey | MLDSA87PublicKey | MLKEM768PublicKey | MLKEM1024PublicKey | RSAPublicKey | X25519PublicKey | X448PublicKey, signature: bytes, payload: bytes, signature_hash_algorithm: HashAlgorithm) → None[source]
Check the signature of a payload.

Parameters:

• public_key (RSAPublicKey/EllipticCurvePublicKey) – the public_key to check signature

• signature (bytes) – the signature bytes

• payload (bytes) – the payload bytes

• signature_hash_algorithm (hashes.HashAlgorithm) – algorithm used to hash the payload

Raises:

• InvalidSignature – If signature verification fails.

• errors.Error – If public key type is not supported

certbot.crypto_util.verify_cert_matches_priv_key(cert_path: str, key_path: str) → None[source]
Verifies that the private key and cert match.

Parameters:

• cert_path (str) – path to a cert in PEM format

• key_path (str) – path to a private key file

Raises:
errors.Error – If they don’t match.

certbot.crypto_util.verify_fullchain(renewable_cert: RenewableCert) → None[source]
Verifies that fullchain is indeed cert concatenated with chain.

Parameters:
renewable_cert (certbot.interfaces.RenewableCert) – cert to verify

Raises:
errors.Error – If cert and chain do not combine to fullchain.

certbot.crypto_util.get_sans_from_cert(cert: bytes, typ: Format | int | None = None) → list[str][source]
Get a list of Subject Alternative Names from a certificate.

Parameters:

• cert (str) – Certificate (encoded).

• typ (Format) – Which format the cert bytes are in.

Returns:
A list of Subject Alternative Names.

Return type:
list

certbot.crypto_util.get_names_from_cert(cert: bytes, typ: Format | int | None = None) → list[str][source]
Get a list of domains from a cert, including the CN if it is set.

Parameters:

• cert (str) – Certificate (encoded).

• typ (Format) – Which format the cert bytes are in.

Returns:
A list of domain names.

Return type:
list

certbot.crypto_util.get_names_from_req(csr: bytes, typ: Format | int | None = None) → list[str][source]
Get a list of domains from a CSR, including the CN if it is set.

Parameters:

• csr (str) – CSR (encoded).

• typ (acme_crypto_util.Format) – Which format the csr bytes are in.

Returns:
A list of domain names.

Return type:
list

certbot.crypto_util.notBefore(cert_path: str) → datetime[source]
When does the cert at cert_path start being valid?

Parameters:
cert_path (str) – path to a cert in PEM format

Returns:
the notBefore value from the cert at cert_path

Return type:
datetime.datetime

certbot.crypto_util.notAfter(cert_path: str) → datetime[source]
When does the cert at cert_path stop being valid?

Parameters:
cert_path (str) – path to a cert in PEM format

Returns:
the notAfter value from the cert at cert_path

Return type:
datetime.datetime

certbot.crypto_util.sha256sum(filename: str) → str[source]
Compute a sha256sum of a file.

NB: In given file, platform specific newlines characters will be converted into their equivalent unicode counterparts before calculating the hash.

Parameters:
filename (str) – path to the file whose hash will be computed

Returns:
sha256 digest of the file in hexadecimal

Return type:
str

certbot.crypto_util.cert_and_chain_from_fullchain(fullchain_pem: str) → tuple[str, str][source]
Split fullchain_pem into cert_pem and chain_pem

Parameters:
fullchain_pem (str) – concatenated cert + chain

Returns:
tuple of string cert_pem and chain_pem

Return type:
tuple

Raises:
errors.Error – If there are less than 2 certificates in the chain.

certbot.crypto_util.get_serial_from_cert(cert_path: str) → int[source]
Retrieve the serial number of a certificate from certificate path

Parameters:
cert_path (str) – path to a cert in PEM format

Returns:
serial number of the certificate

Return type:
int

certbot.crypto_util.find_chain_with_issuer(fullchains: list[str], issuer_cn: str, warn_on_no_match: bool = False) → str[source]
Chooses the first certificate chain from fullchains whose topmost intermediate has an Issuer Common Name matching issuer_cn (in other words the first chain which chains to a root whose name matches issuer_cn).

Parameters:

• fullchains (list of str) – The list of fullchains in PEM chain format.

• issuer_cn (str) – The exact Subject Common Name to match against any issuer in the certificate chain.

Returns:
The best-matching fullchain, PEM-encoded, or the first if none match.

Return type:
str