# 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

  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

    `certbot.util.Key`

  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')

  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

    `certbot.util.Key`

  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

  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) – 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.init_save_csr(privkey, names, path)

  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 CSR

    - names (set) – `str` names to include in the CSR

    - path (str) – Certificate save directory.

  Returns

    CSR

  Return type

    `certbot.util.CSR`

certbot.crypto_util.valid_csr(csr)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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.pyopenssl_load_certificate(data)

  Load PEM/DER certificate.

  Raises

    errors.Error –

certbot.crypto_util.get_sans_from_cert(cert, typ=1)

  Get a list of Subject Alternative Names from a certificate.

  Parameters

    - cert (str) – Certificate (encoded).

    - typ – `crypto.FILETYPE_PEM` or `crypto.FILETYPE_ASN1`

  Returns

    A list of Subject Alternative Names.

  Return type

    list

certbot.crypto_util.get_names_from_cert(csr, typ=1)

  Get a list of domains from a cert, including the CN if it is set.

  Parameters

    - cert (str) – Certificate (encoded).

    - typ – `crypto.FILETYPE_PEM` or `crypto.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]

  Get a list of domains from a CSR, including the CN if it is set.

  Parameters

    - cert (str) – CSR (encoded).

    - typ – `crypto.FILETYPE_PEM` or `crypto.FILETYPE_ASN1`

  Returns

    A list of domain names.

  Return type

    list

certbot.crypto_util.dump_pyopenssl_chain(chain, filetype=1)

  Dump certificate chain into a bundle.

  Parameters

    chain (list) – List of `crypto.X509` (or wrapped in `josepy.util.ComparableX509`).

certbot.crypto_util.notBefore(cert_path)

  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)

  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)

  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)

  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)

  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)

  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`