Python binding for NSS (python-nss)

In this document

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:

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 seperated by underscores.
    • Constants are all upper case with words seperated 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. The current release's documentation can be found here.
  • 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 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:

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 CVS Information

The CVS tags for various python-nss releases can be found in the Release Information.

You may want to review the Getting Mozilla Source Code Using CVS documentation.

python-nss source code is in the mozilla/security/python/nss directories.

Release Information

Release 0.12.0

Release Date 2011-06-06
CVS Tag PYNSS_RELEASE_0_12_0
Source Download ftp://ftp.mozilla.org/pub/mozilla.org/security/python-nss/releases/PYNSS_RELEASE_0_12_0/src
Change Log
  • Major new enhancement is additon of PKCS12 support and AlgorithmID's.
  • setup.py build enhancements
    • Now searches for the NSS and NSPR header files rather than hardcoding their location. This makes building friendlier on other systems (i.e. debian)
    • Now takes optional command line arguments, -d or --debug will turn on debug options during the build.
  • Fix reference counting bug in PK11_password_callback() which contributed to NSS not being able to shutdown due to resources still in use.
  • Add UTF-8 support to ssl.config_server_session_id_cache()
  • Added unit tests for cipher, digest, client_server.
  • All unittests now run, added test/run_tests to invoke full test suite.
  • Fix bug in test/setup_certs.py, hardcoded full path to libnssckbi.so was causing failures on 64-bit systems, just use the libnssckbi.so basename, modutil will find it on the standard search path.
  • doc/examples/cert_dump.py uses new AlgorithmID class to dump Signature Algorithm
  • doc/examples/ssl_example.py now can cleanly shutdown NSS.
  • Exception error messages now include PR error text if available.
The following classes were replaced
  • SignatureAlgorithm replaced by new class AlgorithmID
The following classes were added
  • AlgorithmID
  • PKCS12DecodeItem
  • PKCS12Decoder
The following class methods were added
  • PK11Slot.authenticate()
  • PK11Slot.get_disabled_reason()
  • PK11Slot.has_protected_authentication_path()
  • PK11Slot.has_root_certs()
  • PK11Slot.is_disabled()
  • PK11Slot.is_friendly()
  • PK11Slot.is_internal()
  • PK11Slot.is_logged_in()
  • PK11Slot.is_removable()
  • PK11Slot.logout()
  • PK11Slot.need_login()
  • PK11Slot.need_user_init()
  • PK11Slot.user_disable()
  • PK11Slot.user_enable()
  • PKCS12DecodeItem.format()
  • PKCS12DecodeItem.format_lines()
  • PKCS12Decoder.database_import()
  • PKCS12Decoder.format()
  • PKCS12Decoder.format_lines()
The following class properties were added
  • AlgorithmID.id_oid
  • AlgorithmID.id_str
  • AlgorithmID.id_tag
  • AlgorithmID.parameters
  • PKCS12DecodeItem.certificate
  • PKCS12DecodeItem.friendly_name
  • PKCS12DecodeItem.has_key
  • PKCS12DecodeItem.shroud_algorithm_id
  • PKCS12DecodeItem.signed_cert_der
  • PKCS12DecodeItem.type
  • SignedData.data
  • SignedData.der
The following module functions were added
  • nss.nss.dump_certificate_cache_info()
  • nss.nss.find_slot_by_name()
  • nss.nss.fingerprint_format_lines()
  • nss.nss.get_internal_slot()
  • nss.nss.is_fips()
  • nss.nss.need_pw_init()
  • nss.nss.nss_init_read_write()
  • nss.nss.pk11_disabled_reason_name()
  • nss.nss.pk11_disabled_reason_str()
  • nss.nss.pk11_logout_all()
  • nss.nss.pkcs12_cipher_from_name()
  • nss.nss.pkcs12_cipher_name()
  • nss.nss.pkcs12_enable_all_ciphers()
  • nss.nss.pkcs12_enable_cipher()
  • nss.nss.pkcs12_export()
  • nss.nss.pkcs12_map_cipher()
  • nss.nss.pkcs12_set_nickname_collision_callback()
  • nss.nss.pkcs12_set_preferred_cipher()
  • nss.nss.token_exists()
  • nss.ssl.config_mp_server_sid_cache()
  • nss.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
  • nss.nss.int.PK11_DIS_COULD_NOT_INIT_TOKEN
  • nss.nss.int.PK11_DIS_NONE
  • nss.nss.int.PK11_DIS_TOKEN_NOT_PRESENT
  • nss.nss.int.PK11_DIS_TOKEN_VERIFY_FAILED
  • nss.nss.int.PK11_DIS_USER_SELECTED
  • nss.nss.int.PKCS12_DES_56
  • nss.nss.int.PKCS12_DES_EDE3_168
  • nss.nss.int.PKCS12_RC2_CBC_128
  • nss.nss.int.PKCS12_RC2_CBC_40
  • nss.nss.int.PKCS12_RC4_128
  • nss.nss.int.PKCS12_RC4_40
The following files were added
  • test/run_tests
  • test/test_cipher.py (replaces cipher_test.py)
  • test/test_client_server.py
  • test/test_digest.py (replaces digest_test.py)
  • test/test_pkcs12.py
Deprecated Functionality
  • SignatureAlgorithm

Release 0.11.0

Release Date 2011-02-21
CVS Tag PYNSS_RELEASE_0_11_0
Source Download ftp://ftp.mozilla.org/pub/mozilla.org/security/python-nss/releases/PYNSS_RELEASE_0_11_0/src
Change Log
External Changes
  • Add AddrInfo class to support IPv6 address resolution. Supports iteration over it's set of NetworkAddress objects and provides hostname, canonical_name object properties.
  • Add PR_AI_* constants.
  • NetworkAddress constructor and NetworkAddress.set_from_string() added optional family parameter. This is necessary for utilizing PR_GetAddrInfoByName().
  • NetworkAddress initialized via a string paramter are now initalized via PR_GetAddrInfoByName using family.
  • Add NetworkAddress.address property to return the address sans the port as a string. NetworkAddress.str() includes the port. For IPv6 the a hex string must be enclosed in brackets if a port is appended to it, the bracketed hex address with appended with a port is unappropriate in some circumstances, hence the new address property to permit either the address string with a port or without a port.
  • Fix the implementation of the NetworkAddress.family property, it was returning bogus data due to wrong native data size.
  • HostEntry objects now support iteration and indexing of their NetworkAddress members.
  • Add io.addr_family_name() function to return string representation of PR_AF_* constants.
  • Modify example and test code to utilize AddrInfo instead of deprecated NetworkAddress functionality. Add address family command argument to ssl_example.
  • Fix pty import statement in test/setup_certs.py
Deprecated Functionality
  • NetworkAddress initialized via a string paramter is now deprecated. AddrInfo should be used instead.
  • NetworkAddress.set_from_string is now deprecated. AddrInfo should be used instead.
  • NetworkAddress.hostentry is deprecated. It was a bad idea, NetworkAddress objects can support both IPv4 and IPv6, but a HostEntry object can only support IPv4. Plus the implementation depdended on being able to perform a reverse DNS lookup which is not always possible.
  • HostEntry.get_network_addresses() and HostEntry.get_network_address() are now deprecated. In addition their port parameter is now no longer respected. HostEntry objects now support iteration and indexing of their NetworkAddress and that should be used to access their NetworkAddress objects instead.
Internal Changes
  • Utilize PR_NetAddrFamily() access macro instead of explict access.
  • Add PRNetAddr_port() utility to hide host vs. network byte order requirements when accessing the port inside a PRNetAddr and simplify accessing the IPv4 vs. IPv6 port variants.
  • Replace the use of PR_InitializeNetAddr() with PR_SetNetAddr(), the later properly handles IPv6, the former did not.
  • Rename NetworkAddress.addr to NetworkAddress.pr_netaddr for naming consistency.
  • Update HostEntry documentation to indicate it's deprecated status.
  • Remove redundant implementation of NetworkAddress_new_from_PRNetAddr from py_ssl.c and properly import the implementation from py_nspr_io.c.
  • The following other non-IPv6 fixes were also made because they were discovered while doing the IPv6 work:
  • Move definition of TYPE_READY to py_nspr_common.h so it can be shared. Update all modules to utilize it.
  • Replace incorrect use of free() with PyMem_Free for string data returned by Python's utf-8 encoder.
  • Add header dependency information to setup.py so modules will be rebuilt when header files change.
  • Add utility tuple_str() to convert a tuple to a string representation by calling str() on each object in the tuple. Tuple.str() in CPython only calls repr() on each member.
  • HostEntry objects now store their aliases and NetworkAddress's in internal tuples.

Release 0.10.0

Release Date 2010-07-25
CVS Tag PYNSS_RELEASE_0_10_0
Source Download ftp://ftp.mozilla.org/pub/mozilla.org/security/python-nss/releases/PYNSS_RELEASE_0_10_0/src
Change Log
The following classes were added:
  • InitParameters
  • InitContext
The following module functions were added:
  • nss.nss.nss_initialize()
  • nss.nss.nss_init_context()
  • nss.nss.nss_shutdown_context()
  • nss.nss.nss_init_flags()
The following constants were added:
  • NSS_INIT_READONLY
  • NSS_INIT_NOCERTDB
  • NSS_INIT_NOMODDB
  • NSS_INIT_FORCEOPEN
  • NSS_INIT_NOROOTINIT
  • NSS_INIT_OPTIMIZESPACE
  • NSS_INIT_PK11THREADSAFE
  • NSS_INIT_PK11RELOAD
  • NSS_INIT_NOPK11FINALIZE
  • NSS_INIT_RESERVED
  • NSS_INIT_COOPERATE
The following file was added:
  • test/setup_certs.py

Release 0.9.0

Release Date 2010-05-28
CVS Tag PYNSS_RELEASE_0_9_0
Source Download
Change Log
General Modifications:
  • Correct definciencies in auth_certificate_callback found in several of the example files and documentation. If you've copied that code you should merge those changes in.
  • Unicode objects now accepted as well as str objects for interfaces expecting a string.
  • Sockets were enhanced thusly:
    • Threads will now yield during blocking IO.
    • Socket.makefile() reimplemented
      • file object methods that had been missing (readlines(), sendall(), and iteration) were implemented
      • makefile now just returns the same
      • Socket object but increments an "open" ref count. Thus a Socket object behaves like a file object and must be closed once for each makefile() call before it's actually closed.
    • Sockets now support the iter protocol
    • Added methods:
      • Socket.readlines()
      • Socket.sendall()
  • Apply patches from Miloslav Trmač for ref counting and threading support. Thanks Miloslav!
  • Review all ref counting, numerous ref counting fixes
  • Implement cyclic garbage collection support by adding object traversal and clear methods
  • Identify static variables, move to thread local storage
  • Remove python-nss specific httplib.py, no longer needed python-nss now compatible with standard library
  • Rewrite httplib_example.py to use standard library and illustrate ssl, non-ssl, connection class, http class usage
The following classes were added:
  • AuthKeyID
  • BasicConstraints
  • CRLDistributionPoint
  • CRLDistributionPts
  • CertificateExtension
  • GeneralName
  • SignedCRL
  • DN
  • RDN
  • AVA
  • CertificateRequest
The following module functions were added:
  • nss.nss.nss_is_initialized()
  • nss.nss.cert_crl_reason_from_name()
  • nss.nss.cert_crl_reason_name()
  • nss.nss.cert_general_name_type_from_name()
  • nss.nss.cert_general_name_type_name()
  • nss.nss.cert_usage_flags()
  • nss.nss.decode_der_crl()
  • nss.nss.der_universal_secitem_fmt_lines()
  • nss.nss.import_crl()
  • nss.nss.make_line_pairs()
  • nss.nss.oid_dotted_decimal()
  • nss.nss.oid_str()
  • nss.nss.oid_tag()
  • nss.nss.oid_tag_name()
  • nss.nss.read_der_from_file()
  • nss.nss.x509_alt_name()
  • nss.nss.x509_ext_key_usage()
  • nss.nss.x509_key_usage()
The following class methods and properties were added:
Note: it's a method if the name is suffixed with (), a propety otherwise
  • Socket.next()
  • Socket.readlines()
  • Socket.sendall()
  • SSLSocket.next()
  • SSLSocket.readlines()
  • SSLSocket.sendall()
  • AuthKeyID.key_id
  • AuthKeyID.serial_number
  • AuthKeyID.get_general_names()
  • CRLDistributionPoint.issuer
  • CRLDistributionPoint.get_general_names()
  • CRLDistributionPoint.get_reasons()
  • CertDB.find_crl_by_cert()
  • CertDB.find_crl_by_name()
  • Certificate.extensions
  • CertificateExtension.critical
  • CertificateExtension.name
  • CertificateExtension.oid
  • CertificateExtension.oid_tag
  • CertificateExtension.value
  • GeneralName.type_enum
  • GeneralName.type_name
  • GeneralName.type_string
  • SecItem.der_to_hex()
  • SecItem.get_oid_sequence()
  • SecItem.to_hex()
  • SignedCRL.delete_permanently()
  • AVA.oid
  • AVA.oid_tag
  • AVA.value
  • AVA.value_str
  • DN.cert_uid
  • DN.common_name
  • DN.country_name
  • DN.dc_name
  • DN.email_address
  • DN.locality_name
  • DN.org_name
  • DN.org_unit_name
  • DN.state_name
  • DN.add_rdn()
  • DN.has_key()
  • RDN.has_key()
The following module functions were removed:
Note: use nss.nss.oid_tag() instead
  • nss.nss.sec_oid_tag_from_name()
  • nss.nss.sec_oid_tag_name()
  • nss.nss.sec_oid_tag_str()
The following files were added:
  • doc/examples/cert_dump.py
  • test/test_cert_components.py

Release 0.8.0

Release Date 2009-09-21
CVS Tag PYNSS_RELEASE_0_8_0
Source Download
Change Log
General Modifications:
  • SecItem's now support indexing and slicing on their data
  • Clean up parsing and parameter validation of variable arg functions
The following were added:
  • SecItem.type SecItem.len
  • SecItem.data
  • PK11SymKey.key_data
  • PK11SymKey.key_length
  • PK11SymKey.slot
  • create_context_by_sym_key
  • param_from_iv
  • generate_new_param
  • get_iv_length
  • get_block_size
  • get_pad_mechanism

Release 0.7.0

Release Date 2009-09-18
CVS Tag
Source Download
Change Log
General Modifications:
  • add support for symmetric encryption/decryption
  • more support for digests (hashes)
The following classes added:
  • PK11SymKey
  • PK11Context
The following methods and functions added:
  • get_best_wrap_mechanism
  • get_best_key_length
  • key_gen
  • derive
  • get_key_length
  • digest_key
  • clone_context
  • digest_begin
  • digest_op
  • cipher_op
  • finalize
  • digest_final
  • read_hex
  • hash_buf
  • sec_oid_tag_str
  • sec_oid_tag_name
  • sec_oid_tag_from_name
  • key_mechanism_type_name
  • key_mechanism_type_from_name
  • pk11_attribute_type_name
  • pk11_attribute_type_from_name
  • get_best_slot
  • get_internal_key_slot
  • create_context_by_sym_key
  • import_sym_key
  • create_digest_context
  • param_from_iv
  • param_from_algid
  • generate_new_param
  • algtag_to_mechanism
  • mechanism_to_algtag
The following files added:
  • test/cipher_test.py
  • test/digest_test.py

Release 0.6.0

Release Date 2009-07-08
CVS Tag
Source Download
Change Log
General Modifications:
  • fix Red Hat bug #510343 client_auth_data_callback seg faults if False is returned from callback

Release 0.5.0

Release Date 2009-07-01
CVS Tag
Source Download
Change Log
General Modifications:
  • restore ssl.nss_init and ssl.nss_shutdown but make them deprecated
  • add __version__ string to nss module

Release 0.4.0

Release Date 2009-06-30
CVS Tag
Source Download
Change Log
General Modifications:
  • add binding for NSS_NoDB_Init(), Red Hat bug #509002
  • move nss_init and nss_shutdown from ssl module to nss module

Release 0.3.0

Release Date 2009-06-04
CVS Tag
Source Download
Change Log
General Modifications:
  • import to Mozilla CVS, tweak directory layout

Release 0.2.0

Release Date 2009-05-21
CVS Tag
Source Download
Change Log
General Modifications:
  • apply patch from Red Hat bug #472805, (Miloslav Trmač)
  • Don't allow closing a socket twice, that causes crashes.
  • Fix return value creation in SSLSocket.get_security_status
  • Convert licensing to MPL tri-license
The following were added:
  • nss.io.Socket.new_socket_pair()
  • nss.io.Socket.poll()
  • nss.io.Socket.import_tcp_socket()
  • nss.nss.Certificate.get_subject_common_name()
  • nss.nss.generate_random()
  • nss.ssl.SSLSocket.import_tcp_socket()

Release 0.1.0

Release Date 2008-07-09
CVS Tag
Source Download
Change Log Initial release