From Fedora Project Wiki


Full API documentation in a single place

Developers should have a single, definitive place to find all relevant reference documentation.

Probably it would be ideal to have documentation integrated in the source code, extracted at build time (and installed with the nss-devel RPM); this would make it easiest to update/reference during development (however, having all documentation in a single place is more important than having it in the source code).

We should have everything documented, priority items:

  • TLS (documentation mostly exists)
  • Basic crypto (encryption/hashing/signatures) (covered in tech note 5 only)
  • How to initialize NSS (no-DB, system-wide DB, other possibilities, when to use which one)
  • How to use the PEM token / interoperate with OpenSSL conventions (might want to improve the API first)

Known existing documentation:

NSS bug for docbook use: #912360

Smallish API improvements

(Can't break binary compatibility - will typically have to introduce new functions.)

Fix individual warts in the existing API

  • For ciphers with padding it is necessary to call PK11_DigestFinal() to get the last encrypted block.
NSS bug: #884178
python-nss bug: FIXME

Make it easier to integrate TLS user in UNIXy environments/applications

  • Make PR_ImportTCPSocket() a fully supported API (for UNIX at least, for applications that have no ambition to be portable to native Windows API).
NSS bug: #924376
python-nss bug: not filed yet
  • Add a "poll(2) flags" interface that would make it possible to integrate non-blocking NSS TLS sockets into an existing event loop infrastructure (currently it seems necessary to replace the existing event loop around one built on PR_Poll, which is too invasive for large applications)
NSS bug: #888581
python-nss bug: FIXME
    • Notes:
      • Bob: The big gotcha on non-blocking sockets is to handle on the fly prompts. We have to deal with the problem where the application throws up a dialog to, say, select a client auth cert, or decide to accept a failed cert. We could define the problem away (say that if you're application blocks in any SSL callback, you can't use non-blocking). Not an insurmountable problem, just one that perennially pops up.
      • Stef: gtls provides this for GLib based applications: In the GLib gtls backend we always handshake in another thread, even though we support doing all the bulk SSL reads/writes in the event loop in a 'pollable' fashion. We came to the realization that even with polling implemented that it's nearly impossible to do a TLS handshake in an event loop thread without big latency due to the following:
        • RSA operations on key sizes that are 'large' given the hardware introduce noticeable to unnacceptable latency.
        • PKCS#11 and other smart card operations are inherently blocking (there are a few exceptions).
      • Rich:
        • Some applications are not threaded and/or cannot use threads
        • SSL_ForceHandshake() is re-entrant (FIXME: ?)

Allow handling handshakes in non-blocking applications

Related to the above: allow setting a mode in which NSS will return an error instead of automatically doing a handshake, or add a callback when a handshake starts.

Contact: Dan Winship

NSS bug: #924381
python-nss bug: not filed yet

Minimize boilerplate

This is fairly general; e.g. avoid SECItem structures - they make it easy to pass data through layers, but at the top-level layer using them is more code than just passing a (void *, size_t) pair

NSS bug: #924390
python-nss bug: not filed yet

Make it easier to use NSS for basic cryptography

Add a set of "easy to use"/"lite" alternatives to pk11pub.h and related headers, to be at least as easy as PR_Connect()/PR_Read()/PR_Write() for TLS. At the very least, hide the existence of slots.

Together with avoiding SECItem, might involve primarily adding symmetric encryption to the cryptohi layer.

Would it make sense to make it also easy to import raw key material for an one-shot operation? Encourages handling raw key material directly, which is not too desirable.

NSS bug: #924396
python-nss bug: not filed yet

Make it really easy to initiate a TLS TCP connection

E.g. for clients, combine the DNS lookup with PR_Connect + SSL_SetURL etc to make the common case trivial.

NSS bug: #924401
python-nss bug: not filed yet

Minimize the amount of magic necessary for loading CA configuration (and other data) from files

E.g. hide the existence of the PEM token.

NSS bug: #924404
python-nss bug: not filed yet

Allow applications to enumerate cipher suites / mechanisms

(to avoid/minimize the need for )

NSS bug: #480174
python-nss bug: not filed yet

Defaults / System Policy Integration

Individual applications should not be forced or encouraged to individually enable/disable various mechanisms; this should primarily happen at an OS-wide policy level.

Setting the right developer/user expectations in the API is the primary challenge (when an algorithm is broken, do we keep the application running or do we keep the application secure by disabling the algorithm)?

Make it easy to use secure defaults

Already discussed as .

Make it really easy to initialize a client for using the system-wide CA database and policy

Allow loading the default CA trust without manually managing the database or loading magic modules, or at least document it well.

Multiple library contexts

This is currently fairly vague and expected to be difficult - however there is definite demand to allow several independent uses of NSS within an application (even within a single thread), with various modules independently setting their configuration and policy.

This involves at least CA trust configuration, not sure about individual mechanisms as set by e.g. NSS_SetDomesticPolicy (though recommending application writers to use an "OS policy" everywhere might be a way to avoid this).


Better smart-card login support

To get OpenSSL feature parity and allow using NSS in Fedora builds of Kerberos (and sssd?)

Support PKINIT certificate usage / trust

... when validating certificates, in addition to the existing TLS / email / code signing.

Fedora bug: #961113
NSS bug: #383601
python-nss bug: Not filed yet

Support validating certificates with other custom certificate usages

May be necessary for non-Kerberos smart card login mechanisms.

Get the NSS PEM module accepted upstream

Would help with NSS code acceptance in Kerberos.

Fedora bug: #804215
NSS bug: #402712

Alternative(?) DN<=>text mapping functions

As we implement smart card authentication in SSSD, we're going to want to be able to leverage printable versions of subject names which weren't generated by NSS, and which may include more attributes than NSS knows the names of, and which may refer to various attributes by different names (for example, "E" vs "emailAddress"), for example altSecurityIdentity attributes read from an Active Directory LDAP entry.

Being able to reliably derive the same string representation that the AD administrative tools did when populating that attribute (whether we accomplish that by being able to supply NSS with a custom NameToKind dictionary for CERT_AsciiToName (? or CERT_NameToAscii?), or by implementing an entire other DN-to-text conversion function) is going to be necessary for making that work.

PEM support enhancements

... for better OpenSSL compatibility:

Support reading CRLs

Fedora bug: #871670

Support PKCS#8 format for private keys

Support encryption/decryption using AES and Camellia

Fedora bug: [1]


Try to improve performance - [Milan Bartoš' bachelor thesis] measures a significant performance disadvantage, especially for small data sizes.

Notes on crypto use in OpenStack

(Only vaguely related - split?)

General notes

  • Universally stores keys, certificates, and the like, in files, or as text within configuration files.
  • TLS is used through several implementations/wrappers, including at least the built-in ssl module, httplib2 and python-requests
  • Most (all) TLS configurations include an option to run in "insecure" mode

(Uses of crypto within the test suite have been ignored)

OpenSSL library uses

Through PyOpenSSL:

  • glance/glance/common/ : OpenSSL.crypto.{load_private_key,load_certificate,sign,verify}, only to validate the key/certificate public/private is valid and they match
  • tempest/tempest/common/ : OpenSSL.SSL.Connection: does its own peer verification
  • python-glanceclient/glanceclient/common/ : OpenSSL.SSL.Connection: does its own peer verification
  • python-swiftclient/swiftclient/ : OpenSSL.SSL.Context

OpenSSL command-line uses

There are several instances of managing a CA (using the OpenSSL ca directory structure), and using openssl(1) as a data filter.

... and the used subcommands:

  • keystone/keystone/common/ : genrsa, req, ca
  • keystone/keystone/common/ : cms -verify, cms -sign
  • python-keystoneclient/keystoneclient/common/ : cms -verify, cms -sign
  • keystone/examples/pki/ ~= python-keystoneclient/examples/pki/ : req, ca, x509, cms -sign (used to generate test data only?)
  • trove/trove/guestagent/strategies/restore/ : enc -aes-256-cbc -salt -pass
  • trove/trove/guestagent/strategies/backup/ : enc -aes-256-cbc -salt -pass
  • python-novaclient/novaclient/ : rsautl -decrypt
  • nova/doc/source/devref/rc.local : openssl(1) enc -d, in a shell script
  • nova/nova/cloudpipe/bootscript.template : openssl(1) rand, dhparam, in a shell script
  • nova/nova/CA/ : openssl(1) req, ca -gencrl
  • nova/nova/CA/ : openssl(1) req, ca -gencrl
  • nova/nova/ : rsautl -{decrypt,encrypt}, ca -{revoke,gencrl}, genrsa, req, x509 -serial (also CA directory management)
  • nova/nova/image/ : enc -d -aes-128-cbc
  • nova/nova/virt/xenapi/ : aes-128-cbc


  • tempest/tools/ : installs openssl-devel on CentOS
  • nova/nova/CA/openssl.cnf.tmpl : OpenSSL configuration file


  • keystone/keystone/openstack/common/crypto/ ~= trove/trove/openstack/common/crypto/ ~= oslo-incubator/openstack/common/crypto/ Crypto.Hash.HMAC; CBC encryption; exposes Crypto.Hash.HMAC; with optional base64 en/decoding
  • python-keystoneclient/keystoneclient/middleware/ : Crypto.Cipher.AES in CBC mode
  • python-openstackclient/openstackclient/common/ : Crypto.Cipher.AES in CFB
  • glance/glance/common/ : Crypto.Cipher.AES, Crypto.Random: AES-CBC
  • heat/contrib/rackspace/heat/engine/plugins/ : Crypto.PublicKey.RSA: RSA.{importKey,generate}.{exportKey,publickey().exportKey()}
  • heat/heat/common/ : Crypto.Cipher.AES: CFB, base64


  • swift/swift/common/ :
  • heat/heat/common/ :
  • swift/swift/common/ :
  • glance/glance/common/ :
  • nova/nova/ : eventlet.wrap_ssl


... as a SSH client:

  • cinder/cinder/
  • cinder/cinder/volume/drivers/san/hp/
  • heat/contrib/rackspace/heat/engine/plugins/
  • ironic/ironic/common/
  • nova/nova/virt/powervm/
  • tempest/tempest/common/

Misc. other libraries

  • keystone/keystone/common/ : passlib.hash.sha512_crypt, passlib.hash.ldap_salted_sha1 (password hashing)
  • heat/heat/common/ : Uses os.urandom to generate an IV
  • openstack-chef/cookbooks/openssl/libraries/secure_password.rb : OpenSSL::Random::Random_bytes

Python standard library

(Ignoring very many hashlib uses, and many hmac uses.)

  • nova/nova/virt/disk/ : crypt.crypt (MD5 or DES)
  • cinder/cinder/volume/drivers/ : httplib.HTTPSConnection
  • keystone/keystone/middleware/ : httplib.HTTPSConnection
  • neutron/neutron/plugins/bigswitch/ : httplib.HTTPSConnection
  • neutron/neutron/plugins/nec/common/ : httplib.HTTPSConnection
  • neutron/neutron/services/loadbalancer/drivers/radware/ : httplib.HTTPSConnection
  • python-swiftclient/swiftclient/ : httplib.HTTPSConnection
  • glance/glance/common/ : httplib.HTTPSConnection, ssl.wrap_socket
  • ceilometer/ceilometer/openstack/common/ ~= heat/heat/openstack/common/ keystone/keystone/openstack/common/ ~= nova/nova/openstack/common/ ~= oslo-incubator/openstack/common/ ~= oslo.messaging/oslo/messaging/openstack/common/ ~= trove/trove/openstack/common/ : ssl.wrap_socket
  • cinder/cinder/ : ssl.wrap_socket
  • neutron/neutron/ : ssl.wrap_socket
  • nova/nova/scheduler/filters/ : ssl.wrap_socket
  • python-ceilometerclient/ceilometerclient/common/ : ssl.wrap_socket
  • python-heatclient/heatclient/common/ : ssl.wrap_socket

Custom crypto implementation

  • keystone/keystone/openstack/common/crypto/ ~= trove/trove/openstack/common/crypto/ ~= oslo-incubator/openstack/common/crypto/ : Implements HKDF (RFC 5869) based on Crypto.Hash.HMAC. Manually implements ANSI X.923 padding.
  • python-keystoneclient/keystoneclient/middleware/ : Derives a key using HMAC+SHA384. Implements PKCS#7 padding.
  • glance/glance/common/ : Implements a custom padding scheme.
  • nova/nova/ : Implements conversion from SSH key format to PKCS#8 (base64+ASN.1)
  • nova/nova/virt/xenapi/ : Implements D-H key exchange.
  • (nova/nova/virt/disk/ : Custom code editing /etc/shadow )