Closed Bug 1603628 Opened 1 year ago Closed 1 year ago

Update NSS to handle PKCS #11 v3.0


(NSS :: Libraries, enhancement, P1)



(Not tracked)



(Reporter: rrelyea, Assigned: rrelyea)




(2 files)

The PKCS #11 v3.0 spec is finally 'out'. The final committee draft has been approved by the technical committee and Oasis is voting on it starting Dec 13, (2019).

There are a number of features in the spec that may be of interest to mozilla in general and NSS in particular:

  1. Better handling of AEAD algorithms (like CHACHA/POLY and AES/GCM). Currently PKCS #11 can't cache the key state between various AEAD blocks. PKCS #11 v3.0 includes new functions that can handle AEAD semantics.
  2. The ability to request fork safe semantics. Currently PKCS #11 requires a restart after a fork, and all calls to pkcs #11 fail until you do. In PKCS #11 v3.0 you can request a set of functions that operate as normal software across a fork.
  3. New method of getting the function list that lets you ask for a specific interface.
  4. Several new mechanism.

This bug is only about implementing 2 and 3. I envision this in 3 steps:

  1. integrate the new PKCS #11 v3.0 headers, but keep the same ABI and no new functions.
  2. implement the new PKCS #11 v3.0 function table interface.
  3. implement fork safe semantics (really just turning off the fork() check).
Assignee: nobody → rrelyea
Priority: -- → P1

This patch implements the first phase: updating the headers.


Were updated using the released OASIS PKCS #11 v3.0 header files.
lib/util/pkcs11n.h was updated to finally deprecate all uses of CK?NETSCAPE?.

A new define as added: NSS_PKCS11_2_0_COMPAT. If it's defined, the small
semantic changes (including the removal of deprecated defines) between the
NSS PKCS #11 v2 header file and the new PKCS #11 v3 are reverted in favor of
the PKCS #11 v2 definitions. This include the removal of CK?NETSCAPE? in
favor of CK?NSS?.

One notable change was caused by an inconsistancy between the spec and the
released headers in PKCS #11 v2.40. CK_GCM_PARAMS had an extra field in
the header that was not in the spec. OASIS considers the header file to be
normative, so PKCS #11 v3.0 resolved the issue in favor of the header file
definition. NSS had the spec definition, so now there are 2 defines for this

CK_NSS_GCM_PARAMS - the old nss define. Still used internally in freebl.
CK_GCM_PARAMS_V3 - the new define.
CK_GCM_PARAMS - no longer referenced in NSS itself. It's defined as
CK_GCM_PARAMS_V3 if NSS_PKCS11_2_0_COMPAT is not defined, and it's defined as

Softoken has been updated to accept either CK_NSS_GCM_PARAMS or
CK_GCM_PARAMS_V3. In a future patch NSS will be updated to use
CK_GCM_PARAMS_V3 and fall back to CK_NSS_GMC_PARAMS.

One other semantic difference between the 3.0 version of pkcs11f.h and the
version here: In the oasis version of the header, you must define
CK_PKCS11_2_0_ONLY to get just the PKCS #11 v2 defines. In our version you
must define CK_PKCS11_3 to get the PCKS #11 v3 defines.

Most of this patch is to handle changing the deprecated defines that have been
removed in PCKS #11 v3 from NSS.

Patch one has been checked in,
Patch 2 will be attached to phabricator as soon as the try build tests finish.

Update to PKCS #11 v3.0 part 2.

Create the functions and switch to the C_Interface() function to fetch the PKCS #11 function table. Also PKCS #11 v3.0 uses a new fork safe interface. NSS can already handle the case if the PKCS #11 module happens to be fork safe (when asked by the application to refresh the tokens in the child process, NSS can detect that such a refresh is not necessary and continue. Softoken could also be put in fork_safe mode with an environment variable. With this patch it's the default, and NSS asks for the fork safe API by default. Technically softoken should implement the old non-fork safe interface when PKCS #11 v2.0 is called, but NSS no longer needs it, and doing so would double the number of PKCS #11 interfaces are needed. You can still compile with fork unsafe semantics, and the PKCS #11 V3.0 module will do the right thing and not include the fork safe flag. Firefox does not fork(), so for firefox this is simply code that is no longer compilied.

We now use C_GetInterface, which allows us to specify what kind of interface we want (PKCS #11 v3.0, PKCS #11 v2.0, fork safe, etc.). Vendor specific functions can now be accessed through the C_GetInterface. If the C_GetInterface function does not exists, we fall bak to the old C_GetFunctionList.

There are 24 new functions in PKCS #11 v3.0:
C_GetInterfaceList - return a table of all the supported interfaces
C_GetInterface - return a specific interface. You can specify interface name, version and flags separately. You can leave off any of these and you will get what the token thinks is the best match of the interfaces that meet the criteria. We do this in softoken by the order of the interface list.
C_SessionCancel - Cancel one or more multipart operation
C_LoginUser - Supply a user name to C_Login(). This function has no meaning for softoken, so it just returns CKR_OPERATION_NOT_INITIALIZED under the theory that if we in the future want to support usernames, the NSS db would need special initialization to make that happen.
C_Message* and C_Message (20 functions in all) are the new AEAD interface (they are written generally so that it can be used for things other than AEAD). In this patch they are unimplemented (see the next patch).

This patch adds regular (NSC_) and FIPS (FC_) versions of these functions.
Also when creating the PKCS #11 v2.0 interface, we had to create a 2.0 specific version of C_GetInfo so that it can return a 2.40 in the CK_VERSION field rather than 3.00. We do this with #defines since all the function tables are generated automagically with pkcs11f.h.

Closed: 1 year ago
Resolution: --- → FIXED
See Also: → 1624128
Target Milestone: --- → 3.52
See Also: → 1637488
You need to log in before you can comment on or make changes to this bug.