"certbot.crypto_util"
*********************

Certbot client crypto utility functions.

Todo: Make the transition to use PSS rather than PKCS1_v1_5 when the
server is capable of handling the signatures.

certbot.crypto_util.init_save_key(key_size, key_dir, 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.

   Parameters:
      * **key_size** (*int*) – RSA key size in bits

      * **key_dir** (*str*) – Key save directory.

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

   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.

   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)

   Generate PEM encoded RSA key.

   Parameters:
      **bits** (*int*) – Number of bits, at least 1024.

   Returns:
      new RSA key in PEM form with specified number of bits

   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** (*storage.RenewableCert*) – cert to verify

   Raises:
      **errors.Error** – If verification fails.

certbot.crypto_util.verify_renewable_cert_sig(renewable_cert)

   Verifies the signature of a "storage.RenewableCert" object.

   Parameters:
      **renewable_cert** (*storage.RenewableCert*) – cert to verify

   Raises:
      **errors.Error** – If signature verification fails.

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** (*storage.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.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._notAfterBefore(cert_path, method)

   Internal helper function for finding notbefore/notafter.

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

      * **method** (*function*) – one of "crypto.X509.get_notBefore"
        or "crypto.X509.get_notAfter"

   Returns:
      the notBefore or notAfter value from the cert at cert_path

   Return type:
      "datetime.datetime"

certbot.crypto_util.sha256sum(filename)

   Compute a sha256sum of a file.

   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
