certbot.crypto_util module¶
Certbot client crypto utility functions.
-
certbot.crypto_util.
generate_key
(key_size: int, key_dir: str, key_type: str = 'rsa', elliptic_curve: str = 'secp256r1', keyname: str = 'key-certbot.pem', strict_permissions: bool = True) → certbot.util.Key[source]¶ Initializes and saves a privkey.
Inits key and saves it in PEM format on the filesystem.
Note
keyname is the attempted filename, it may be different if a file already exists at the path.
- Parameters
key_size (int) – key size in bits if key size is rsa.
key_dir (str) – 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
- Raises
ValueError – If unable to generate the key given key_size.
-
certbot.crypto_util.
init_save_key
(key_size, key_dir, key_type='rsa', elliptic_curve='secp256r1', keyname='key-certbot.pem')[source]¶ Initializes and saves a privkey.
Inits key and saves it in PEM format on the filesystem.
Note
keyname is the attempted filename, it may be different if a file already exists at the path.
Deprecated since version 1.16.0: Use
generate_key()
instead.- Parameters
key_size (int) – key size in bits if key size is rsa.
key_dir (str) – 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
- Returns
Key
- Return type
- Raises
ValueError – If unable to generate the key given key_size.
-
certbot.crypto_util.
generate_csr
(privkey: certbot.util.Key, names: Set[str], path: str, must_staple: bool = False, strict_permissions: bool = True) → certbot.util.CSR[source]¶ Initialize a CSR with the given private key.
- Parameters
privkey (
certbot.util.Key
) – Key to include in the CSRnames (set) –
str
names to include in the CSRpath (str) – 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.crypto_util.
init_save_csr
(privkey, names, path)[source]¶ Initialize a CSR with the given private key.
Deprecated since version 1.16.0: Use
generate_csr()
instead.- Parameters
privkey (
certbot.util.Key
) – Key to include in the CSRnames (set) –
str
names to include in the CSRpath (str) – Certificate save directory.
- Returns
CSR
- Return type
-
certbot.crypto_util.
valid_csr
(csr)[source]¶ Validate CSR.
Check if
csr
is a valid CSR for the given domains.- Parameters
csr (str) – CSR in PEM.
- Returns
Validity of CSR.
- Return type
bool
-
certbot.crypto_util.
csr_matches_pubkey
(csr, privkey)[source]¶ Does private key correspond to the subject public key in the CSR?
- Parameters
csr (str) – CSR in PEM.
privkey (str) – Private key file contents (PEM)
- Returns
Correspondence of private key to CSR subject public key.
- Return type
bool
-
certbot.crypto_util.
import_csr_file
(csrfile, data)[source]¶ Import a CSR file, which can be either PEM or DER.
- Parameters
csrfile (str) – CSR filename
data (str) – contents of the CSR file
- Returns
(
crypto.FILETYPE_PEM
, util.CSR object representing the CSR, list of domains requested in the CSR)- Return type
tuple
-
certbot.crypto_util.
make_key
(bits=1024, key_type='rsa', elliptic_curve=None)[source]¶ Generate PEM encoded RSA|EC key.
- Parameters
bits (int) – Number of bits if key_type=rsa. At least 1024 for RSA.
ec_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
str
-
certbot.crypto_util.
valid_privkey
(privkey)[source]¶ Is valid RSA private key?
- Parameters
privkey (str) – Private key file contents in PEM
- Returns
Validity of private key.
- Return type
bool
-
certbot.crypto_util.
verify_renewable_cert
(renewable_cert)[source]¶ For checking that your certs were not corrupted on disk.
- Several things are checked:
Signature verification for the cert.
That fullchain matches cert and chain when concatenated.
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)[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, signature, payload, signature_hash_algorithm)[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 (cryptography.hazmat.primitives.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, key_path)[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)[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, typ=1)[source]¶ Get a list of Subject Alternative Names from a certificate.
- Parameters
cert (str) – Certificate (encoded).
typ –
crypto.FILETYPE_PEM
orcrypto.FILETYPE_ASN1
- Returns
A list of Subject Alternative Names.
- Return type
list
-
certbot.crypto_util.
get_names_from_cert
(csr, typ=1)[source]¶ Get a list of domains from a cert, including the CN if it is set.
- Parameters
cert (str) – Certificate (encoded).
typ –
crypto.FILETYPE_PEM
orcrypto.FILETYPE_ASN1
- Returns
A list of domain names.
- Return type
list
-
certbot.crypto_util.
get_names_from_req
(csr: str, typ: int = 1) → List[str][source]¶ Get a list of domains from a CSR, including the CN if it is set.
- Parameters
cert (str) – CSR (encoded).
typ –
crypto.FILETYPE_PEM
orcrypto.FILETYPE_ASN1
- Returns
A list of domain names.
- Return type
list
-
certbot.crypto_util.
dump_pyopenssl_chain
(chain, filetype=1)[source]¶ Dump certificate chain into a bundle.
- Parameters
chain (list) – List of
crypto.X509
(or wrapped injosepy.util.ComparableX509
).
-
certbot.crypto_util.
notBefore
(cert_path)[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)[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)[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)[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)[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, issuer_cn, warn_on_no_match=False)[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
ofstr
) – 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