Python binding for NSS¶
Project Information¶
python-nss is a Python binding for NSS (Network Security Services) and NSPR (Netscape Portable Runtime). NSS provides cryptography services supporting SSL, TLS, PKI, PKIX, X509, PKCS*, etc. NSS is an alternative to OpenSSL and used extensively by major software projects. NSS is FIPS-140 certified.
NSS is built upon NSPR because NSPR provides an abstraction of common operating system services, particularly in the areas of networking and process management. Python also provides an abstraction of common operating system services but because NSS and NSPR are tightly bound python-nss exposes elements of NSPR.
For information on NSS and NSPR, see the following:
Legacy documentation. NSS project page.
Netscape Portable Runtime. NSPR project page.
NSPR Reference. NSPR API documentation.
Design Goals¶
NSS and NSPR are C language API’s which python-nss “wraps” and exposes to Python programs. The design of python-nss follows these basic guiding principles:
Be a thin layer with almost a one-to-one mapping of NSS/NSPR calls to python methods and functions. Programmers already familiar with NSS/NSPR will be quite comfortable with python-nss.
Be “Pythonic”. The term Pythonic means to follow accepted Python paradigms and idoms in the Python language and libraries. Thus when deciding if the NSS/NSPR API should be rigidly followed or a more Pythonic API provided the Pythonic implementation wins because Python programmers do not want to write C programs in Python, rather they want their Python code to feel like Python code with the richness of full Python.
Identifer names follow the preferred Python style instead of the style in the NSS/NSPR C header files.
Classes are camel-case. Class names always begin with a upper case letter and are then followed by a mix of lower and upper case letters, a upper case letter is used to separate words. Acronyms always appear as a contiguous string of upper case letters.
Method, function and property names are always lower case with words separated by underscores.
Constants are all upper case with words separated by underscores, they match the NSS/NSPR C API.
Every module, class, function, and method has associated documentation and is exposed via the standard Python methodology. This documentation is available via the numerous Python documentation extraction tools. Also see the generated HTML documentation provided with each release.
NSS/NSPR structs are exposed as Python objects.
NSS/NSPR functions which operate on a NSS/NSPR object (i.e. struct) become methods of that object.
NSS/NSPR objects which are collections support the Python iteration protocol. In other words they can be iterated over, indexed by position, or used as slices.
NSS/NSPR objects whose collection elements can be referenced by name support associative indexing.
NSS/NSPR objects which have “get” and “set” API function calls are exposed as Python properties.
All NSS/NSPR Python objects can print their current value by evaluting the Python object in a string context or by using the Python str() function.
Support threading. The Python Global Interpreter Lock (GIL) is released prior to calling NSS/NSPR C functions and reaquired after the NSS/NSPR C function returns. This allows other Python threads to execute during the time a NSS/NSPR function is progress in another thread. Also, any “global” values which are set in python-nss are actually thread-local. Examples of this are the various callbacks which can be set and their parameters. Thus each thread gets it own set of callbacks.
Many methods/functions provide sane default (keyword) parameters freeing the Python programmer from having to specify all parameters yet allowing them to be overriden when necessary.
Error codes are never returned from methods/functions. python-nss follows the existing Python exception mechanism. Any error reported by NSS/NSPR is converted into a Python exception and raised. The exact error code, error description, and often contextual error information will be present in the exception object.
Enumerated constants used in the NSS/NSPR API’s are available in the Python module under the exact same name as they appear in the C header files of NSS/NSPR.
Convenience functions are provided to translate between the numeric value of an enumerated constant and it’s string representation and visa versa.
python-nss internally supports UTF-8. Strings may be Python str objects or Python unicode objects. If a Python unicode object is passed to a NSS/NSPR function it will be encoded as UTF-8 first before being passed to NSS/NSPR.
python-nss tries to be flexible when generating a print representation of complex objects. For simplicity you can receive a block of formatted text but if you need more control, such as when building GUI elments you can access a list of “lines”, each line is paired with an indentation level value. The (indent, text) pairs allow you to insert the item into a GUI tree structure or simply change the indentation formatting.
Deprecated elements of the python-nss API are marked with Python deprecation warnings as well as being documented in the nss module documentation. As of Python 2.7 deprecation warnings are no longer reported by default. It is suggested Python developers using python-nss periodically run their code with deprecation warnings enabled. Depercated elements will persist for a least two releases before being removed from the API entirely.
Project History¶
Red Hat utilizes both NSS and Python in many of it’s projects, however it was not previously possible to call NSS directly from Python. To solve this problem Red Hat generously funded the initial development of python-nss as well as it’s continued maintenance. Red Hat following it’s open source philosophy has contributed the source to the Mozilla security project. Red Hat welcomes all interested contributors who would like to contribute the python-nss project as part of an open source community. The initial release of python-nss occurred in September 2008 with it’s inclusion in the Fedora distribution. The source code to python-nss was first imported into the Mozilla CVS repository on June 9th 2009. python-nss is currently available in:
Fedora
RHEL 6
The principal developer of python-nss is John Dennis jdennis@redhat.com. Additional contributors are:
Miloslav Trmač mitr@redhat.com
Bohuslav Kabrda slavek@redhat.com
The python-nss binding is still young despite having been utilized in several major software projects. Thus it’s major version number is still at zero. This is primarily so the developers can make changes to the API as experiece grows with it. For example it is already known there are some naming inconsistencies. Elments of the API are probably not ideally partitioned into proper namespaces via Python modules. Some functionality and interface have already been deprecated due to lessons learned. Thus at some point in the future when it is felt the API has solidified and been further proven in the field a 1.0 release will be made. At that point in time existing users of the python-nss API will need to some elements of their code. A migration script will be provided to assist them.
Licensing Information¶
python-nss is available under the Mozilla Public License, the GNU General Public License, and the GNU Lesser General Public License. For information on downloading python-nss releases as tar files, see Source Download.
Documentation¶
python-nss API documentation
The python-nss API documentation for the current release can be viewed at python-nss API documentation.
The API documentation is generated from the python-nss source code and compiled modules. You can
build it yourself via ./setup.py build_doc
. Most distributions include the python-nss API
documentation in the python-nss packaging. Consult your distribution for more information.
Example Code
The doc/examples directory contains numerous examples of python-nss programs and libraries you may wish to consult. They illustrate suggested usage and best practice.
Test Code
In addition the test directory contains unit tests that also illustrate python-nss usage, however unlike the examples the unit tests are geared towards testing rather than expository illustration.
Other Documentation
The doc directory contains other files you may wish to review.
How to Report a Bug¶
python-nss bugs are currently being tracked in the Red Hat bugzilla system for Fedora. You can enter a bug report here.
Source Download Area¶
Source downloads are maintained here. Links to download URL for a specific release can be found in the Release Information section.
Mozilla Source Code Management (SCM) Information¶
On March 21, 2013 the NSS project switched from using CVS as it’s source code manager (SCM) to
Mercurial, also known as hg
. All prior CVS information (including release tags) were imported
into the new Mercurial repositories, as such there is no need to utilize the deprecated CVS
repositories, use Mercurial instead.
To check out python-nss source code from Mercurial do this:
hg clone https://hg.mozilla.org/projects/python-nss
The SCM tags for various python-nss releases can be found in the Release Information.
You may want to review the Getting Mozilla Source Code Using Mercurial documentation for more information with working with Mercurial.
The old deprecated CVS documentation can be found here: Getting Mozilla Source Code Using CVS.
The old deprecated python-nss CVS source code location is mozilla/security/python/nss
.
Release Information¶
Release 1.0.1¶
Release Date |
2017-02-28 |
SCM Tag |
PYNSS_RELEASE_1_0_1 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securi ty/python-nss/releases/PYNSS_RELEASE_1_0_1/src/ |
Change Log |
|
Release 1.0.0¶
Release Date |
2016-09-01 |
SCM Tag |
PYNSS_RELEASE_1_0_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securi ty/python-nss/releases/PYNSS_RELEASE_1_0_0/src/ |
Change Log |
Official 1.0.0 release, only minor tweaks from the 1.0.0beta1 release.
|
Release 1.0.0beta1¶
Release Date |
2016-02-16 |
SCM Tag |
PYNSS_RELEASE_1_0_0beta1 |
Source Download |
http s://ftp.mozilla.org/pub/mozilla.org/security/py thon-nss/releases/PYNSS_RELEASE_1_0_0beta1/src/ |
Change Log |
The primary enhancement in this version is support for Python3. A single code base supports both Py2 (minimum version 2.7) and Py3
|
Release 0.17.0¶
Release Date |
2014-11-07 |
SCM Tag |
PYNSS_RELEASE_0_17_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_17_0/src/ |
Change Log |
The primary enhancement in this version is adding support for PBKDF2
|
Release 0.16.0¶
Release Date |
2014-10-29 |
SCM Tag |
PYNSS_RELEASE_0_16_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_16_0/src/ |
Change Log |
The primary enhancements in this version is adding support for the setting trust attributes on a Certificate, the SSL version range API, information on the SSL cipher suites and information on the SSL connection.
|
Release 0.15.0¶
Release Date |
2014-09-09 |
SCM Tag |
PYNSS_RELEASE_0_15_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_15_0/src/ |
Change Log |
The primary enhancements in this version was fixing access to extensions in a CertificateRequest and giving access to CertificateRequest attributes. There is a bug in NSS which hides the existence of extensions in a CSR if the extensions are not contained in the first CSR attribute. This was fixable in python-nss without requiring a patch to NSS. Formerly python-nss did not provide access to the attributes in a CSR only the extensions, with this release all components of a CSR can be accessed. See test/test_cert_request.py for examples.
|
Release 0.14.1¶
Release Date |
2013-10-28 |
SCM Tag |
PYNSS_RELEASE_0_14_1 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_14_1/src/ |
Change Log |
Release 0.14.1 contains only modifications to tests and examples, otherwise functionally it is the same as release 0.14.0
|
Release 0.14.0¶
Release Date
2013-05-10
SCM Tag
PYNSS_RELEASE_0_14_0
Source Download
https://ftp.mozilla.org/pub/mozilla.org/security/python-nss/releases/PYNSS_RELEASE_0_14_0/src/
Change Log
The primary enhancements in this version is support of certifcate validation, OCSP support, and support for the certificate “Authority Information Access” extension.
Enhanced certifcate validation including CA certs can be done via Certificate.verify() or Certificate.is_ca_cert(). When cert validation fails you can now obtain diagnostic information as to why the cert failed to validate. This is encapsulated in the CertVerifyLog class which is a iterable collection of CertVerifyLogNode objects. Most people will probablby just print the string representation of the returned CertVerifyLog object. Cert validation logging is handled by the Certificate.verify() method. Support has also been added for the various key usage and cert type entities which feature prominently during cert validation.
Certificate() constructor signature changed from
Certificate(data=None, der_is_signed=True)
to
Certificate(data, certdb=cert_get_default_certdb(), perm=False, nickname=None)
This change was necessary because all certs should be added to the NSS temporary database when they are loaded, but earlier code failed to do that. It’s is not likely that an previous code was failing to pass initialization data or the der_is_signed flag so this change should be backwards compatible.
Fix bug #922247, PKCS12Decoder.database_import() method. Importing into a NSS database would sometimes fail or segfault.
Error codes and descriptions were updated from upstream NSPR & NSS.
The password callback did not allow for breaking out of a password prompting loop, now if None is returned from the password callback the password prompting is terminated.
nss.nss_shutdown_context now called from InitContext destructor, this assures the context is shutdown even if the programmer forgot to. It’s still best to explicitly shut it down, this is just failsafe.
Support was added for shutdown callbacks.
cert_dump.py extended to print NS_CERT_TYPE_EXTENSION
cert_usage_flags, nss_init_flags now support optional repr_kind parameter
The following classes were added:
nss.CertVerifyLogNode
nss.CertVerifyLog
error.CertVerifyError (exception)
nss.AuthorityInfoAccess
nss.AuthorityInfoAccesses
The following class methods were added:
nss.Certificate.is_ca_cert
nss.Certificate.verify
nss.Certificate.verify_with_log
nss.Certificate.get_cert_chain
nss.Certificate.check_ocsp_status
nss.PK11Slot.list_certs
nss.CertVerifyLogNode.format_lines
nss.CertVerifyLog.format_lines
nss.CRLDistributionPts.format_lines
The following class properties were added:
nss.CertVerifyLogNode.certificate
nss.CertVerifyLogNode.error
nss.CertVerifyLogNode.depth
nss.CertVerifyLog.count
The following module functions were added:
nss.x509_cert_type
nss.key_usage_flags
nss.list_certs
nss.find_certs_from_email_addr
nss.find_certs_from_nickname
nss.nss_get_version
nss.nss_version_check
nss.set_shutdown_callback
nss.get_use_pkix_for_validation
nss.set_use_pkix_for_validation
nss.enable_ocsp_checking
nss.disable_ocsp_checking
nss.set_ocsp_cache_settings
nss.set_ocsp_failure_mode
nss.set_ocsp_timeout
nss.clear_ocsp_cache
nss.set_ocsp_default_responder
nss.enable_ocsp_default_responder
nss.disable_ocsp_default_responder
The following files were added:
src/py_traceback.h
doc/examples/verify_cert.py
test/test_misc.py
The following constants were added:
nss.KU_DIGITAL_SIGNATURE
nss.KU_NON_REPUDIATION
nss.KU_KEY_ENCIPHERMENT
nss.KU_DATA_ENCIPHERMENT
nss.KU_KEY_AGREEMENT
nss.KU_KEY_CERT_SIGN
nss.KU_CRL_SIGN
nss.KU_ENCIPHER_ONLY
nss.KU_ALL
nss.KU_DIGITAL_SIGNATURE_OR_NON_REPUDIATION
nss.KU_KEY_AGREEMENT_OR_ENCIPHERMENT
nss.KU_NS_GOVT_APPROVED
nss.PK11CertListUnique
nss.PK11CertListUser
nss.PK11CertListRootUnique
nss.PK11CertListCA
nss.PK11CertListCAUnique
nss.PK11CertListUserUnique
nss.PK11CertListAll
nss.certUsageSSLClient
nss.certUsageSSLServer
nss.certUsageSSLServerWithStepUp
nss.certUsageSSLCA
nss.certUsageEmailSigner
nss.certUsageEmailRecipient
nss.certUsageObjectSigner
nss.certUsageUserCertImport
nss.certUsageVerifyCA
nss.certUsageProtectedObjectSigner
nss.certUsageStatusResponder
nss.certUsageAnyCA
nss.ocspMode_FailureIsVerificationFailure
nss.ocspMode_FailureIsNotAVerificationFailure
Internal Changes
Reimplement exception handling
NSPRError is now derived from StandardException instead of EnvironmentError. It was never correct to derive from EnvironmentError but was difficult to implement a new subclassed exception with it’s own attributes, using EnvironmentError had been expedient.
NSPRError now derived from StandardException, provides:
errno (numeric error code)
strerror (error description associated with error code)
error_message (optional detailed message)
error_code (alias for errno)
error_desc (alias for strerror)
CertVerifyError derived from NSPRError, extends with:
usages (bitmask of returned usages)
log (CertVerifyLog object)
Expose error lookup to sibling modules
Use macros for bitmask_to_list functions to reduce code duplication and centralize logic.
Add repr_kind parameter to cert_trust_flags_str()
Add support for repr_kind AsEnumName to bitstring table lookup.
Add cert_type_bitstr_to_tuple() lookup function
Add PRTimeConvert(), used to convert Python time values to PRTime, centralizes conversion logic, reduces duplication
Add UTF8OrNoneConvert to better handle unicode parameters which are optional.
Add Certificate_summary_format_lines() utility to generate concise certificate identification info for output.
Certificate_new_from_CERTCertificate now takes add_reference parameter to properly reference count certs, should fix shutdown busy problems.
Add print_traceback(), print_cert() debugging support.
Release 0.13.0¶
Release Date |
2012-10-09 |
SCM Tag |
PYNSS_RELEASE_0_13_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_13_0/src/ |
Change Log |
The following classes were added
The following module functions were added : name: the_following_module_functions_were_added
The following internal utilities were added :na me: the_following_internal_utilities_were_added
The following class constructors were modified to accept intialization parameters ere_modified_to_accept_intialization_parameters
The following were deprecated
Deprecated Functionality make_line_pairs() has been replaced by make_line_fmt_tuples() because 2-valued tuples were not sufficently general. It is expected very few programs will have used this function, it’s mostly used internally but provided as a support utility. |
Release 0.12.0¶
Release Date |
2011-06-06 |
SCM Tag |
PYNSS_RELEASE_0_12_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_12_0/src/ |
Change Log |
The following classes were replaced
The following classes were added
The following class methods were added
The following class properties were added : name: the_following_class_properties_were_added
The following module functions were added :na me: the_following_module_functions_were_added_2
ss.nss.pkcs12_set_nickname_collision_callback() - nss.nss.pkcs12_set_preferred_cipher() - nss.nss.token_exists() - nss.ssl.config_mp_server_sid_cache() - ns s.ssl.config_server_session_id_cache_with_opt() - nss.ssl.get_max_server_cache_locks() - nss.ssl.set_max_server_cache_locks() - nss.ssl.shutdown_server_session_id_cache() The following constants were added
The following files were added
Deprecated Functionality
|
Release 0.11.0¶
Release Date |
2011-02-21 |
SCM Tag |
PYNSS_RELEASE_0_11_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_11_0/src/ |
Change Log |
External Changes
Deprecated Functionality
Internal Changes
|
Release 0.10.0¶
Release Date |
2010-07-25 |
SCM Tag |
PYNSS_RELEASE_0_10_0 |
Source Download |
https://ftp.mozilla.org/pub/mozilla.org/securit y/python-nss/releases/PYNSS_RELEASE_0_10_0/src/ |
Change Log |
The following classes were added:
The following module functions were added: :na me: the_following_module_functions_were_added_3
The following constants were added:
The following file was added:
|
Release 0.9.0¶
Release Date |
2010-05-28 |
SCM Tag |
PYNSS_RELEASE_0_9_0 |
Source Download |
|
Change Log |
General Modifications:
The following classes were added:
The following module functions were added: :na me: the_following_module_functions_were_added_4
The following class methods and properties were added: llowing_class_methods_and_properties_were_added Note: it’s a method if the name is suffixed with (), a propety otherwise
The following module functions were removed: :na me: the_following_module_functions_were_removed Note: use nss.nss.oid_tag() instead
The following files were added:
|
Release 0.8.0¶
Release Date |
2009-09-21 |
SCM Tag |
PYNSS_RELEASE_0_8_0 |
Source Download |
|
Change Log |
General Modifications:
The following were added:
|
Release 0.7.0¶
Release Date |
2009-09-18 |
SCM Tag |
|
Source Download |
|
Change Log |
General Modifications:
The following classes added:
The following methods and functions added: : name: the_following_methods_and_functions_added
The following files added:
|
Release 0.6.0¶
Release Date |
2009-07-08 |
SCM Tag |
|
Source Download |
|
Change Log |
General Modifications:
|
Release 0.5.0¶
Release Date |
2009-07-01 |
SCM Tag |
|
Source Download |
|
Change Log |
General Modifications:
|
Release 0.4.0¶
Release Date |
2009-06-30 |
SCM Tag |
|
Source Download |
|
Change Log |
General Modifications:
|
Release 0.3.0¶
Release Date |
2009-06-04 |
SCM Tag |
|
Source Download |
|
Change Log |
General Modifications:
|
Release 0.2.0¶
Release Date |
2009-05-21 |
SCM Tag |
|
Source Download |
|
Change Log |
General Modifications:
The following were added:
|
Release 0.1.0¶
Release Date |
2008-07-09 |
SCM Tag |
|
Source Download |
|
Change Log |
Initial release |