User:Mitr/NSS:DeveloperFriendliness

Documentation

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:

• https://developer.mozilla.org/en-US/docs/NSS top-level
• https://developer.mozilla.org/en-US/docs/NSS_reference contains structured documentation to a subset of functions
• https://developer.mozilla.org/en-US/docs/NSS_functions has a more complete list of functions, but mostly only links to MXR.
• Some header files contain (unformatted) documentation comments.
• https://developer.mozilla.org/en-US/docs/NSS/NSS_Tech_Notes contains various examples, notably https://developer.mozilla.org/en-US/docs/NSS/nss_tech_notes/nss_tech_note5 is the only(?) documentation of low-level cryptography facilities.

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: not filed yet

• • 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 https://bugzilla.redhat.com/show_bug.cgi?id=970727 )

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 https://bugzilla.mozilla.org/show_bug.cgi?id=842307 .

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).

References:

• https://wiki.mozilla.org/NSS_Library_Init
• https://wiki.mozilla.org/NSS_Shared_DB_And_LINUX

Performance

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