"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, csrname='csr-certbot.pem')

   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.make_csr(key_str, domains, must_staple=False)

   Generate a CSR.

   Parameters:
      * **key_str** (*str*) -- PEM-encoded RSA key.

      * **domains** (*list*) -- Domains included in the certificate.

   Todo: Detect duplicates in "domains"? Using a set doesn't preserve
   order...

   Returns:
      new CSR in PEM and DER form containing all domains

   Return type:
      tuple

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:
      ("OpenSSL.crypto.FILETYPE_PEM" or
      "OpenSSL.crypto.FILETYPE_ASN1", 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.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** -- "OpenSSL.crypto.FILETYPE_PEM" or
        "OpenSSL.crypto.FILETYPE_ASN1"

   Returns:
      A list of Subject Alternative Names.

   Return type:
      list

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

   Get a list of Subject Alternative Names from a CSR.

   Parameters:
      * **csr** (*str*) -- CSR (encoded).

      * **typ** -- "OpenSSL.crypto.FILETYPE_PEM" or
        "OpenSSL.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** -- "OpenSSL.crypto.FILETYPE_PEM" or
        "OpenSSL.crypto.FILETYPE_ASN1"

   Returns:
      A list of domain names.

   Return type:
      list

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

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

   Parameters:
      * **csr** (*str*) -- CSR (encoded).

      * **typ** -- "OpenSSL.crypto.FILETYPE_PEM" or
        "OpenSSL.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 "OpenSSL.crypto.X509" (or wrapped
      in "acme.jose.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
        "OpenSSL.crypto.X509.get_notBefore" or
        "OpenSSL.crypto.X509.get_notAfter"

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

   Return type:
      "datetime.datetime"
