X509 class

class cryptosyspki.X509

Create and manage X.509 certificates.

class HashAlg

Digest algorithms for hashes.

MD5(as per RFC 1321) = 1

MD5 (as per RFC 1321)

SHA1 = 0

SHA-1 (default)

SHA224 = 6

SHA-224

SHA256 = 3

SHA-256

SHA384 = 4

SHA-384

SHA512 = 5

SHA-512

class KeyUsageFlags

Bitwise flags for key usage in certificate.

CRLSIGN = 64

Set the cRLSign bit

DATAENCIPHERMENT = 8

Set the dataEncipherment bit

DECIPHERONLY = 256

Set the decipherOnly bit

DIGITALSIGNATURE = 1

Set the digitalSignature bit

ENCIPHERONLY = 128

Set the encipherOnly bit

KEYAGREEMENT = 16

Set the keyAgreement bit

KEYCERTSIGN = 32

Set the keyCertSign bit

KEYENCIPHERMENT = 4

Set the keyEncipherment bit

NONE = 0

None

NONREPUDIATION = 2

Set the nonRepudiation (contentCommitment) bit

class Opts

Various option flags used by some methods of this class. Combine using 'bitwise or' operator |. Ignored if not applicable for the particular method. Check manual for details.

AUTHKEYID = 16777216

Add the issuer's KeyIdentifier, if present, as an AuthorityKeyIdentifer [default = do not add]

CA_TRUE = 67108864

Set the BasicConstraints subject type to be a CA [default = End Entity]

DECIMAL = 32768

Output serial number in decimal format [default = hex]

DETERMINISTIC = 8192

Use the deterministic signature generation procedure of [RFC6979] for an ECDSA signature.

FORMAT_BIN = 131072

Create in binary format (default for X.509 cert and CRL)

FORMAT_PEM = 65536

Create in PEM-encoded format (default for CSR)

LDAP = 4096

Output distinguished name in LDAP string representation

NO_BASIC = 33554432

Disable the BasicConstraints extension [default = include]

NO_TIMECHECK = 2097152

Avoid checking if the certificates are valid now (default = check validity dates against system clock)

REQ_KLUDGE = 1048576

Create a request with the "kludge" that omits the strictly mandatory attributes completely [default = include attributes with zero-length field]

SALTLEN_ZERO = 768

Use a zero-length salt in an RSA-PSS signature.

UTF8 = 8388608

Encode distinguished name as UTF8String [default = PrintableString]

VERSION1 = 134217728

Create a Version 1 certificate, i.e. no extensions [default = Version 3]

class SigAlg

Signature algorithm to use for signatures.

ECDSA_SHA1 = 16

Sign with ecdsaWithSHA1

ECDSA_SHA224 = 32

Sign with ecdsaWithSHA224

ECDSA_SHA256 = 48

Sign with ecdsaWithSHA256

ECDSA_SHA384 = 64

Sign with ecdsaWithSHA384

ECDSA_SHA512 = 80

Sign with ecdsaWithSHA512

ED25519 = 192

Sign with Ed25519

ED448 = 193

Sign with Ed448

RSA_MD5 = 1

Sign with md5WithRSAEncryption (rsa-md5) signature algorithm [legacy applications only]

RSA_PSS_SHA1 = 176

Sign with RSA-PSS using SHA-1

RSA_PSS_SHA224 = 182

Sign with RSA-PSS using SHA-224

RSA_PSS_SHA256 = 179

Sign with RSA-PSS using SHA-256

RSA_PSS_SHA384 = 180

Sign with RSA-PSS using SHA-384

RSA_PSS_SHA512 = 181

Sign with RSA-PSS using SHA-512

RSA_SHA1 = 0

Sign with sha1WithRSAEncryption (rsa-sha1) [default]

RSA_SHA224 = 6

Sign with sha224WithRSAEncryption (rsa-sha224)

RSA_SHA256 = 3

Sign with sha256WithRSAEncryption (rsa-sha256) [minimum recommended]

RSA_SHA384 = 4

Sign with sha384WithRSAEncryption (rsa-sha384)

RSA_SHA512 = 5

Sign with sha512WithRSAEncryption (rsa-sha512) signature algorithm

static cert_hashissuersn(certfilename, hashalg=0)

Return the hash of the issuer and serial number.

This should give a unique identifier for any certificate.

Parameters:

  • certfilename (str) -- Filename of certificate file (or its base64 representation).

  • hashalg (X509.HashAlg) -- Message digest algorithm to use.

Returns:

String containing the message digest in hexadecimal format.

Return type:

string

static cert_is_revoked(certfile, crlfile, crl_issuercert='', isodate='')

Check whether an X.509 certificate has been revoked in a given Certificate Revocation List (CRL).

Parameters:

  • certfile (str) -- name of X.509 certificate to be checked (or base64 representation).

  • crlfile (str) -- name of CRL file, or a string containing its PEM textual representation.

  • crl_issuercert (str) -- (optional) name of X.509 certificate file for the entity that issued the CRL (or its base64 representation). If given, the signature of the CRL will be checked against the key in the issuer's certificate and a SIGNATURE_ERROR will result if the signature is invalid. Leave empty to omit this check.

  • isodate (str) -- (optional) date in ISO format (yyyy-mm-dd[Thh[:nn:ss]][Z]) on or after you wish to check for revocation. Leave empty "" for any date. The time must be in GMT (UTC, Zulu time).

Returns:

True if the certificate has been revoked, False if not found in the revoked list.

Return type:

bool

static cert_is_valid_now(certfile)

Verify that an X.509 certificate is currently valid as per system clock.

Parameters:

certfile (str) -- Filename of certificate file (or its base64 representation).

Returns:

True if certificate is currently valid, False if certificate has expired or is not yet valid.

Return type:

bool

static cert_is_verified(certfile, issuercert)

Verify that an X.509 certificate has been signed by its issuer.

This can also be used to verify that an X.509 Certificate Revocation List (CRL) or PKCS#10 Certification Signing Request (CSR) has been signed by the owner of the issuer's certificate.

Parameters:

  • certfile (str) -- Filename of certificate (or CRL or CSR) to verify, or a string containing its PEM textual representation.

  • issuercert (str) -- Filename of purported issuer's certificate.

Returns:

True if the certificate's signature is verified, or False if the verification fails.

Return type:

bool

static cert_path_is_valid(certlist, trustedcert='', no_timecheck=False)

Validate a certificate path.

Parameters:

  • certlist (str) -- either a list of certificate names separated by a semicolon or the name of a PKCS-7 "certs-only" file containing the certificates to be validated.

  • trustedcert (str) -- name of the trusted certificate (or base64 representation).

  • no_timecheck (bool) -- Set True to avoid checking if the certificates are valid now, otherwise check each certificate's validity dates against system clock.

Returns:

True if the certification path is valid, or False if path is invalid.

Return type:

bool

static cert_request(newcsrfile, prikeyfile, password, distname, extns='', sigalg=0, opts=0)

Create a PKCS #10 certificate signing request (CSR).

Parameters:

  • newcsrfile (str) -- Name of file to be created.

  • prikeyfile (str) -- File containing issuer's private key data, or a string containing its PEM textual representation.

  • password (str) -- Password for issuer's private key.

  • distname (str) -- Distinguished name string. See Distinguished Names in the main manual.

  • extns (str) -- Extensions: a list of attribute-value pairs separated by a semicolon (;) to be included in an extensionRequest field. See X.509 Extensions Parameter in the main manual.

  • sigalg (X509.SigAlg) -- Signature algorithm to use when signing.

  • opts (X509.Opts) -- Option flags.

Returns:

Zero if successful.

Return type:

int

static cert_thumb(certfilename, hashalg=0)

Return the thumbprint (message digest hash) of an X.509 certificate.

Parameters:

  • certfilename (str) -- Filename of certificate file (or its base64 representation).

  • hashalg (X509.HashAlg) -- Message digest algorithm to use.

Returns:

String containing the message digest in hexadecimal format

Return type:

string

static get_cert_count_from_p7(p7file)

Return number of certificates in a PKCS-7 "certs-only" certificate chain file.

Parameters:

p7file (str) -- Name of the PKCS-7 "certs-only" file, or a string containing its PEM textual representation.

Returns:

Number of X.509 certificates found.

Return type:

int

static get_cert_from_p7(outfile, p7file, index=1)

Extract an X.509 certificate from a PKCS-7 "certs-only" certificate chain file, saving the output directly as a new file.

Parameters:

  • outfile (str) -- Name of output file to be created.

  • p7file (str) -- Name of the PKCS-7 "certs-only" file, or a string containing its PEM textual representation.

  • index (int) -- specifying which certificate (1,2,...) in the chain to extract.

Returns:

If successful, it returns the number of bytes written to the output file.

Return type:

int

static get_cert_from_pfx(outfile, pfxfile, password)

Extract an X.509 certificate from a PKCS-12 PFX/.p12 file, saving the output directly as a new file.

This will attempt to find a matching certificate for any private key, otherwise it will save the first pkcs-12-certBag found in the PFX file containing a x509Certificate. Only weak 40-bit RC2 encryption is supported for the certificate.

Parameters:

  • outfile (str) -- Name of output file to be created.

  • pfxfile (str) -- Name of the PKCS-12 file, or a string containing its PEM textual representation.

  • password (str) -- Password or "" if not encrypted.

Returns:

If successful, it returns the number of bytes written to the output file.

Return type:

int

static get_p7chain_from_pfx(outfile, pfxfile, password)

Extract all X.509 certificates from a PKCS-12 PFX/.p12 file, saving the output directly as a new PKCS-7 "certs-only" certificate chain file.

Parameters:

  • outfile (str) -- Name of output file to be created.

  • pfxfile (str) -- Name of the PKCS-12 file, or a string containing its PEM textual representation.

  • password (str) -- Password or "" if not encrypted. Only weak 40-bit RC2 encryption is supported for the certificate.

Returns:

If successful, it returns the number of bytes written to the output file.

Return type:

int

static key_usage_flags(certfile)

Return a bitfield containing the keyUsage flags for an X.509 certificate.

Parameters:

certfile (str) -- Filename of certificate file (or its base64 representation).

Returns:

A positive integer containing the keyUsage flags as a bitfield, or 0 if no keyUsage flags are set. See X509.KeyUsageFlags for values.

Return type:

int

static make_cert(newcertfile, issuercert, subject_pubkeyfile, issuer_prikeyfile, password, certnum=0, yearsvalid=0, distname='', extns='', keyusage=0, sigalg=0, opts=0)

Create an X.509 certificate using subject's public key and issuer's private key.

Parameters:

  • newcertfile (str) -- Name of file to be created.

  • issuercert (str) -- Name of issuer's certificate file.

  • subject_pubkeyfile (str) -- File containing subject's public key data, or a string containing its PEM textual representation.

  • issuer_prikeyfile (str) -- File containing issuer's private key data, or a string containing its PEM textual representation.

  • password (str) -- Password for issuer's private key.

  • certnum (int) -- Serial number for new certificate.

  • yearsvalid (int) -- Number of years to be valid.

  • distname (str) --

    Distinguished name string. See Distinguished Names in the main manual.

  • extns (str) --

    Extensions: a list of attribute-value pairs separated by semicolons (;). See X.509 Extensions Parameter in the main manual.

  • keyusage (X509.KeyUsageFlags) -- Key usage options.

  • sigalg (X509.SigAlg) -- Signature algorithm to use when signing.

  • opts (X509.Opts) -- Option flags.

Returns:

Zero if successful.

Return type:

int

static make_cert_self(newcertfile, prikeyfile, password, certnum, yearsvalid, distname, extns='', keyusage=0, sigalg=0, opts=0)

Create a self-signed X.509 certificate.

Parameters:

  • newcertfile (str) -- Name of file to be created.

  • prikeyfile (str) -- File containing issuer's private key data, or a string containing its PEM textual representation.

  • password (str) -- Password for issuer's private key.

  • certnum (int) -- Serial number for new certificate.

  • yearsvalid (int) -- Number of years to be valid.

  • distname (str) --

    Distinguished name string. See Distinguished Names in the main manual.

  • extns (str) --

    Extensions: a list of attribute-value pairs separated by semicolons (;). See X.509 Extensions Parameter in the main manual.

  • keyusage (X509.KeyUsageFlags) -- Key usage options.

  • sigalg (X509.SigAlg) -- Signature algorithm to use when signing.

  • opts (X509.Opts) -- Option flags.

Returns:

Zero if successful.

Return type:

int

static make_crl(newcrlfile, issuercert, prikeyfile, password, revokedcertlist='', extns='', sigalg=0, opts=0)

Create an X.509 Certificate Revocation List (CRL). Version 1 only.

Parameters:

  • newcrlfile (str) -- name of new CRL file to be created.

  • issuercert (str) -- name of issuer's X.509 certificate file (or its base64 representation).

  • prikeyfile (str) -- name of issuer's encrypted private key file, or a string containing its PEM textual representation.

  • password (str) -- password for Issuer's encrypted private key file.

  • revokedcertlist (str) -- list of revoked certificates in format. serialNumber,revocationDate; ... or the empty string "" for no revoked certificates. See the Remarks section below for more details

  • extns (str) --

    Extensions: a list of attribute-value pairs separated by a semicolon (;). Valid attribute-value pairs are:

    • lastUpdate=<iso-date-string>

    • nextUpdate=<iso-date-string>

  • sigalg (X509.SigAlg) -- Signature algorithm to use when signing.

  • opts (X509.Opts) -- Option flags.

Returns:

Zero if successful.

Return type:

int

Remarks:

This creates a version 1 CRL file with no extensions or cRLReason's. The parameter revokedCertList must be in the form serialNumber,revocationDate;serialNumber,revocationDate; .... The serialNumber must either be a positive decimal integer (e.g. 123) or the number in hex format preceded by #x (e.g. #x0102deadbeef). The revocation date must be in ISO date format (e.g. 2009-12-31T12:59:59Z). For example:

"1,2007-12-31; 2, 2009-12-31T12:59:59Z; 66000,2066-01-01; #x0102deadbeef,2010-02-28T01:01:59"

By default, the lastUpdate time in the CRL is set to the time given by the system clock, and nextUpdate time is left empty. You can specify your own times using the lastUpdate and nextUpdate attributes in the extensions parameter. Times, if specified, must be in ISO 8601 format and are always interpreted as GMT times whether or not you add a "Z".

static query_cert(filename, query, opts=0)

Query an X.509 certificate file for selected information. May return an integer or a string.

Parameters:

  • filename (str) -- Name of file to be queried (or its base64 representation).

  • query (str) --

    Query string (case-insensitive). Valid queries are:

    • "version" -- X.509 version number, e.g. 3.

    • "serialNumber" -- Serial number in hex-encoded format.

    • "signatureAlgorithm" -- Signature algorithm used, e.g. "sha1WithRSAEncryption".

    • "sigAlgId" -- ID of signature algorithm used. See X509.SigAlg.

    • "signatureValue" -- Signature value in hex-encoded format.

    • "notBefore" -- Date on which the certificate validity period begins in ISO format yyyy-mm-ddThh:nn:ssZ

    • "notAfter" -- Date on which the certificate validity period ends in ISO format yyyy-mm-ddThh:nn:ssZ

    • "issuerName" -- Distinguished name (DN) of entity who has signed and issued the certificate.

    • "subjectName" -- Distinguished name (DN) of the subject.

    • "subjectPublicKeyAlgorithm" -- Algorithm used in subject's public key, e.g. "dsa".

    • "subjectKeyIdentifier" -- The subject key identifier extension, if present, in hex-encoded format.

    • "authorityKeyIdentifier" -- The authority key identifier extension, if present, in hex-encoded format.

    • "rfc822Name" -- Internet mail address contained in a subjectAltName extension, if present.

    • "isCA" -- Returns 1 -- if the subject type is a CA, otherwise returns 0.

    • "keyUsageString" -- keyUsage flags in text format, e.g. "digitalSignature,nonRepudiation".

    • "extKeyUsageString" -- extKeyUsage purposes in text format, e.g. "codeSigning,timeStamping".

    • "cRLDistributionPointsURI" -- First URI found in cRLDistributionPoints, if any.

    • "authorityInfoAccessURI" -- First URI found in authorityInfoAccess, if any.

    • "subjectAltName" -- Subject alternative name extension, if present.

    • "hashAlgorithm" -- Hash algorithm used in signature, e.g. "sha256".

    • "pssParams" -- Parameters used for RSA-PSS (if applicable).

  • opts (X509.Opts) -- Option flags for output formatting, e.g. X509.Opts.Ldap.

Returns:

Result of query or an empty string if query not found.

static read_cert_string_from_p7chain(inputfile, index)

Reads an X.509 certificate into a base64 string from PKCS-7 "certs-only" data.

Parameters:

  • inputfile (str) -- Name of PKCS-7 "certs-only" file, or a string containing its PEM textual representation.

  • index (int) -- Specifying which certificate (1,2,...) in the chain to extract.

Returns:

String in continuous base64 format, or an empty string on error.

Return type:

str

Remarks:

To find the number of certificates in the P7 chain, use X509.get_cert_count_from_p7.

static read_cert_string_from_pfx(inputfile, password)

Read an X.509 certificate into a base64 string from PKCS-12 PFX/.p12 data.

Parameters:

  • inputfile (str) -- Name of PKCS-12 file, or a string containing its PEM textual representation.

  • password (str) -- Password for PFX or "" if certificate is not encrypted.

Returns:

String in continuous base64 format, or an empty string on error.

Return type:

str

static read_string_from_file(certfilename)

Create a base64 string representation of an X.509 certificate.

Parameters:

certfilename (str) -- Filename of certificate file (or its base64 representation).

Returns:

String in continuous base64 format.

Return type:

str

static save_file_from_string(newcertfile, certstring, in_pem_format=False)

Create an X.509 certificate file from its base64 string representation.

Parameters:

  • newcertfile (str) -- Name of new certificate file to be created.

  • certstring (str) -- String containing certificate data in base64 format.

  • in_pem_format (bool) -- True to save in base64 PEM format, or False to save in binary DER format. A PEM format file starts with -----BEGIN CERTIFICATE-----.

Returns:

Zero if successful.

Return type:

int

static text_dump(outputfile, certfile, opts=0)

Dump details of X.509 certificate (or CRL or CSR) to a text file.

Parameters:

  • outputfile (str) -- Filename of text file to be created.

  • certfile (str) -- Filename of certificate file (or its base64 representation).

  • opts (X509.Opts) -- Option flags for output formatting, e.g. X509.Opts.Ldap.

Returns:

Zero if successful.

Return type:

int

static text_dump_tostring(certfile, opts=0)

Dump details of X.509 certificate (or CRL or CSR) to a string.

Parameters:

  • certfile (str) -- Filename of certificate file (or its base64 representation).

  • opts (X509.Opts) -- Option flags for output formatting, e.g. X509.Opts.Ldap.

Returns:

Result of text dump.

Return type:

str