type Certificate

Parameters:

• data (SecItem or str or any buffer compatible object) - Data to initialize the certificate from, must be in DER format
• certdb (CertDB object or None) - CertDB certificate database object, if None then the default certdb will be supplied by calling nss.get\_default\_certdb().
• perm (bool) - True if certificate should be permantely stored in the certdb.
• nickname (string) - certificate nickname.

Overrides: object.__init__

Returns: a new object with type S, a subtype of T

Overrides: object.__new__

Overrides: object.__str__

check_ocsp_status(certdb, time, [user_data1, ...]) -> boolean

Checks the status of a certificate via OCSP. Will only check status for a certificate that has an AIA (Authority Information Access) extension for OCSP or when a "default responder" is specified and enabled. (If no AIA extension for OCSP and no default responder in place, the cert is considered to have a good status.

Returns True if an approved OCSP responder knows the cert and returns a non-revoked status for it. Otherwise a error.NSPRError is raised and it's error_code property may be one of the following:

• SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
• SEC_ERROR_OCSP_FUTURE_RESPONSE
• SEC_ERROR_OCSP_MALFORMED_REQUEST
• SEC_ERROR_OCSP_MALFORMED_RESPONSE
• SEC_ERROR_OCSP_OLD_RESPONSE
• SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
• SEC_ERROR_OCSP_SERVER_ERROR
• SEC_ERROR_OCSP_TRY_SERVER_LATER
• SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
• SEC_ERROR_OCSP_UNAUTHORIZED_RESPONSE
• SEC_ERROR_OCSP_UNKNOWN_CERT
• SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
• SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE
• SEC_ERROR_BAD_SIGNATURE
• SEC_ERROR_CERT_BAD_ACCESS_LOCATION
• SEC_ERROR_INVALID_TIME
• SEC_ERROR_REVOKED_CERTIFICATE
• SEC_ERROR_UNKNOWN_ISSUER
• SEC_ERROR_UNKNOWN_SIGNER

Other errors are possible failures in cert verification (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when verifying the signer's cert, or other low-level problems.

Parameters:

• certdb (CertDB object) - CertDB certificate database object.
• time (number or None) - Time for which status is to be determined. Time as number of microseconds since the NSPR epoch, midnight (00:00:00) 1 January 1970 UTC, either as an integer or a float. If time is None the current time is used.
• user_dataN (object) - zero or more caller supplied parameters which will be passed to the password callback function

check_valid_times(time=now, allow_override=False) --> validity

Checks whether a specified time is within a certificate's validity period.

Returns one of:

• secCertTimeValid
• secCertTimeExpired
• secCertTimeNotValidYet

Parameters:

• time (number or None) - an optional point in time as number of microseconds since the NSPR epoch, midnight (00:00:00) 1 January 1970 UTC, either as an integer or a float. If time is None the current time is used.
• allow_override (bool) - If True then check to see if the invalidity has been overridden by the user, defaults to False.

Returns key exchange type of the keys in an SSL server certificate.

May be one of the following:

• ssl_kea_null
• ssl_kea_rsa
• ssl_kea_dh
• ssl_kea_fortezza (deprecated)
• ssl_kea_ecdh

Returns: kea_type

Parameters:

• level (integer) - Initial indentation level, all subsequent indents are relative to this starting level.
• indent (string) - string replicated once for each indent level then prepended to output line

Returns: string)

Formats the object into a sequence of lines with indent level information. The return value is a list where each list item is a tuple. The first item in the tuple is an integer representing the indentation level for that line. Any remaining items in the tuple are strings to be output on that line.

The output of this function can be formatted into a single string by calling nss.nss.indented\_format(), e.g.:

print indented_format(obj.format_lines())

The reason this function returns a tuple as opposed to an single indented string is to support other text formatting systems such as GUI's with indentation controls. See nss.nss.indented\_format() for a complete explanation.

Parameters:

• level (integer) - Initial indentation level, all subsequent indents are relative to this starting level.

Returns: [(level, string),...]

Parameters:

• time (number or None) - an optional point in time as number of microseconds since the NSPR epoch, midnight (00:00:00) 1 January 1970 UTC, either as an integer or a float. If time is None the current time is used.
• usages (integer) - a certUsage* enumerated constant

Returns: (Certificate, ...)

Given an oid identifying the extension try to locate it in the certificate and return it as generic CertificateExtension object. If the extension is not present raise a KeyError.

The generic CertificateExtension object is not terribly useful on it's own, howerver it's value property can be used to intialize instances of a class representing the extension. Or it may be passed to functions that convert the value into some other usable format. Although one might believe this function should do these conversions for you automatically there are too many possible variations. Plus one might simple be interested to know if an extension is present or not. So why perform conversion work that might not be needed or might not be in the format needed? Therefore this function is just one simple element in a larger toolbox. Below are some suggestions on how to convert the generic CertificateExtension object (this list may not be complete).

SEC_OID_PKCS12_KEY_USAGE

x509\_key\_usage()

SEC_OID_X509_SUBJECT_KEY_ID

SecItem.der\_to\_hex()

SEC_OID_X509_CRL_DIST_POINTS

CRLDistributionPts()

case SEC_OID_X509_AUTH_KEY_ID

AuthKeyID()

SEC_OID_X509_EXT_KEY_USAGE

x509\_ext\_key\_usage()

SEC_OID_X509_BASIC_CONSTRAINTS

BasicConstraints()

SEC_OID_X509_SUBJECT_ALT_NAME

x509\_alt\_name()

SEC_OID_X509_ISSUER_ALT_NAME

x509\_alt\_name()

Parameters:

• oid (may be one of integer, string, SecItem) - The OID of the certification extension to retreive May be one of:

  • integer: A SEC OID enumeration constant (i.e. SEC_OID_*) for example SEC_OID_X509_BASIC_CONSTRAINTS.
  • string: A string either the OID name, with or without the SEC_OID_ prefix (e.g. "SEC_OID_X509_BASIC_CONSTRAINTS" or "X509_BASIC_CONSTRAINTS") or as the dotted decimal representation, for example 'OID.2 5 29 19'. Case is not significant for either form.
  • SecItem: A SecItem object encapsulating the OID in DER format.

Returns: CertificateExtension

generic CertificateExtension object

Parameters:

• ca_names ((SecItem, ...)) - Sequence of CA distinguished names. Each item in the sequence must be a SecItem object containing a distinguished name.

Returns: bool

is_ca_cert(True) -> boolean, cert_type

Returns True if the cert is a CA cert, False otherwise.

The function optionally can return a bitmask of NS_CERT_TYPE_* flags if return_cert_type is True. This is the updated cert type after applying logic in the context of deciding if the cert is a CA cert or not. Hint: the cert_type value can be converted to text with nss.cert\_type\_flags(). Hint: the unmodified cert type flags can be obtained with the Certificate.cert\_type property.

Parameters:

• return_cert_type (boolean) - If True returns both boolean result and certficate type bitmask. If False return only boolean result

Returns: boolean

Returns a nickname for the certificate guaranteed to be unique within the the current NSS database.

The nickname is composed thusly:

1. Establish a name by trying in order:
   1. subject's common name (i.e. CN)
   2. subject's organizational unit name (i.e. OU)
2. Establish a realm by trying in order:
   1. issuer's organization name (i.e. O)
   2. issuer's distinguished name (i.e. DN)
   3. set to "Unknown CA"
3. If name exists the nickname will be "name - realm", else the nickname will be "realm"
4. Then the nickname will be tested for existence in the database. If it does not exist it will be returned as the nickname. Else a loop is entered where the nickname will have " #%d" appended to it where %d is an integer beginning at 1. The generated nickname is tested for existence in the dabase until a unique name is found.

Returns: string

Parameters:

• string (trust) - NSS trust string
• certdb (CertDB object or None) - CertDB certificate database object, if None then the default certdb will be supplied by calling nss.get\_default\_certdb().
• slot (PK11Slot object) - The PK11 slot to use. If None defaults to internal slot, see nss.get\_internal\_key\_slot()
• user_dataN (object) - zero or more caller supplied parameters which will be passed to the password callback function

Given an integer with trust flags encoded as a bitmask return a sorted list of their values as specified in the repr_kind

This is a class method.

Parameters:

• flags (int) - certificate trust integer bitmask

• repr_kind (RepresentationKind constant) - Specifies what the contents of the returned list will be. May be one of:

  AsEnum

  The enumerated constant as an integer value.

  AsEnumName

  The name of the enumerated constant as a string.

  AsEnumDescription

  A friendly human readable description of the enumerated constant as a string.

Returns: ['flag_name', ...]

verify(certdb, check_sig, required_usages, time, [user_data1, ...]) -> valid_usages

Verify a certificate by checking if it's valid and that we trust the issuer.

Possible usage bitfield values are:

• certificateUsageCheckAllUsages
• certificateUsageSSLClient
• certificateUsageSSLServer
• certificateUsageSSLServerWithStepUp
• certificateUsageSSLCA
• certificateUsageEmailSigner
• certificateUsageEmailRecipient
• certificateUsageObjectSigner
• certificateUsageUserCertImport
• certificateUsageVerifyCA
• certificateUsageProtectedObjectSigner
• certificateUsageStatusResponder
• certificateUsageAnyCA

Returns valid_usages, a bitfield of certificate usages.

If required_usages is non-zero, the returned bitmap is only for those required usages, otherwise it is for all possible usages.

Hint: You can obtain a printable representation of the usage flags via cert\_usage\_flags.

Note: Anytime a NSPR or NSS function returns an error in python-nss it raises a NSPRError exception. When an exception is raised the normal return values are discarded because the flow of control continues at the first except block prepared to catch the exception. Normally this is what is desired because the return values would be invalid due to the error. However the certificate verification functions are an exception (no pun intended). An error might be returned indicating the cert failed verification but you may still need access to the returned usage bitmask and the log (if using the log variant). To handle this a special error exception CertVerifyError (derived from NSPRError) is defined which in addition to the normal NSPRError fields will also contain the returned usages and optionally the CertVerifyLog object. If no exception is raised these are returned as normal return values.

Parameters:

• certdb (CertDB object) - CertDB certificate database object
• check_sig (bool) - True if certificate signatures should be checked
• required_usages (integer) - A bitfield of all cert usages that are required for verification to succeed. If zero return all possible valid usages.
• time (number or None) - an optional point in time as number of microseconds since the NSPR epoch, midnight (00:00:00) 1 January 1970 UTC, either as an integer or a float. If time is None the current time is used.
• user_dataN (object) - zero or more caller supplied parameters which will be passed to the password callback function

A restricted regular expression syntax is used to test if the common name specified in the subject DN of the certificate is a match, returning True if so, False otherwise.

The regular expression systax is:

*

matches anything

?

matches one character

\ (backslash)

escapes a special character

$

matches the end of the string

[abc]

matches one occurrence of a, b, or c. The only character that needs to be escaped in this is ], all others are not special.

[a-z]

matches any character between a and z

[^az]

matches any character except a or z

~

followed by another shell expression removes any pattern matching the shell expression from the match list

(foo|bar)

matches either the substring foo or the substring bar. These can be shell expressions as well.

Returns: bool

verify_now(certdb, check_sig, required_usages, [user_data1, ...]) -> valid_usages

Verify a certificate by checking if it's valid and that we trust the issuer.

Possible usage bitfield values are:

• certificateUsageCheckAllUsages
• certificateUsageSSLClient
• certificateUsageSSLServer
• certificateUsageSSLServerWithStepUp
• certificateUsageSSLCA
• certificateUsageEmailSigner
• certificateUsageEmailRecipient
• certificateUsageObjectSigner
• certificateUsageUserCertImport
• certificateUsageVerifyCA
• certificateUsageProtectedObjectSigner
• certificateUsageStatusResponder
• certificateUsageAnyCA

Returns valid_usages, a bitfield of certificate usages. If required_usages is non-zero, the returned bitmap is only for those required usages, otherwise it is for all possible usages.

Hint: You can obtain a printable representation of the usage flags via cert\_usage\_flags.

Note: See the Certificate.verify documentation for details on how the Certificate verification functions handle errors.

Parameters:

• certdb (CertDB object) - CertDB certificate database object
• check_sig (bool) - True if certificate signatures should be checked
• required_usages (integer) - A bitfield of all cert usages that are required for verification to succeed. If zero return all possible valid usages.
• user_dataN (object) - zero or more caller supplied parameters which will be passed to the password callback function

verify_with_log(certdb, check_sig, required_usages, time, [user_data1, ...]) -> valid_usages, log

Verify a certificate by checking if it's valid and that we trust the issuer.

Possible usage bitfield values are:

• certificateUsageCheckAllUsages
• certificateUsageSSLClient
• certificateUsageSSLServer
• certificateUsageSSLServerWithStepUp
• certificateUsageSSLCA
• certificateUsageEmailSigner
• certificateUsageEmailRecipient
• certificateUsageObjectSigner
• certificateUsageUserCertImport
• certificateUsageVerifyCA
• certificateUsageProtectedObjectSigner
• certificateUsageStatusResponder
• certificateUsageAnyCA

Returns valid_usages, a bitfield of certificate usages and a nss.CertVerifyLog object with diagnostic information detailing the reasons for a validation failure.

If required_usages is non-zero, the returned bitmap is only for those required usages, otherwise it is for all possible usages.

Hint: You can obtain a printable representation of the usage flags via cert\_usage\_flags.

Note: See the Certificate.verify documentation for details on how the Certificate verification functions handle errors.

Parameters:

• certdb (CertDB object) - CertDB certificate database object
• check_sig (bool) - True if certificate signatures should be checked
• required_usages (integer) - A bitfield of all cert usages that are required for verification to succeed. If zero return all possible valid usages.
• time (number or None) - an optional point in time as number of microseconds since the NSPR epoch, midnight (00:00:00) 1 January 1970 UTC, either as an integer or a float. If time is None the current time is used.
• user_dataN (object) - zero or more caller supplied parameters which will be passed to the password callback function