You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSS 3.2 Release Notes

2 March 2001

Newsgroup: mozilla.dev.tech.crypto
Engineering lead: Bob Relyea
Product manager: Roland Jones
Engineering manager: Wan-Teh Chang

Contents

Introduction

NSS 3.2 provides improved SSL performance, support for shared libraries, and improved tools support, among other goals listed in detail in the NSS 3.2 Plan. For a list of all the functions exported by the NSS 3.2 DLLs, see NSS 3.2 Public Functions. We guarantee that applications using these APIs will be remain compatible with future versions of the shared libraries. For information about migrating your code to use the NSS 3.2 DLLs, see Migration from NSS 3.1.1. For an overview of all the NSS 3.2 libraries, see Introduction to Network Security Services.

Network Security Services (NSS) is a set of libraries designed to support cross-platform development of security-enabled client and server applications. These libraries provide the security foundation for a variety of server products from iPlanet E-Commerce Solutions, including iPlanet Certificate Management System, iPlanet Web Server, iPlanet Directory Server, and iPlanet Messaging Server.

The NSS libraries also underlie Personal Security Manager (PSM), which performs cryptographic operations on behalf of Netscape Communicator, Netscape 6, and other client applications.

In early 2000, we contributed NSS to the open source community. All the code that we could publish was released as NSS 3.0 on mozilla.org. In October of 2000, we released NSS 3.1, a complete version of NSS that included support for the RSA algorithm. A major drawback of NSS 3.1 was that it did not perform as well as NSS 2.83 on some hardware platforms. In December of 2000, we released NSS 3.1.1, which fixed several bugs in NSS 3.1, including a bug related to prime number generation.

NSS 3.2 is dual-licensed under the MPL and the GPL.

Distribution Information

The CVS tag for the NSS 3.2 release is NSS_3_2_RTM.

NSS 3.2 source and binary distributions are also available on ftp.mozilla.org for anonymous ftp download:

You also need to download the NSPR 4.1 binary distributions to get the NSPR 4.1 header files and shared libraries, which NSS 3.2 requires. NSPR 4.1 binary distributions are in ftp://ftp.mozilla.org/pub/mozilla.org/nspr/r4.1/.

Bugs Fixed

For a list of all bugs that have been fixed in the NSS 3.2 release, click here.

Documentation

For a list of the primary NSS documentation pages on mozilla.org, see NSS Documentation. New and revised documents available since the release of NSS 3.1.1 include the following:

Source may be viewed with a browser (via the LXR tool) at http://lxr.mozilla.org/mozilla/source/security/nss/

The following tools are supported in this release:

    certutil
    cmsutil
    modutil
    pk12util
    signtool
    signver
    ssltap

For documentation and other information about these tools, see NSS Tools.

Changes Since NSS 3.1.1

NSS 3.2 supports shared libraries for the first time. For a list of the functions exported by the NSS shared libraries (and guaranteed to work with future NSS releases), see NSS 3.2 Public Functions. For information on migrating your code from NSS 3.1.1 to NSS 3.2, see Migration from NSS 3.1.1.

For a list of changes introduced in NSS 3.1.1, see NSS 3.1.1 Release Notes.

The sections that follow discuss specific changes in more detail.

New NSS initialization functions

NSS 3.2 introduces the mandatory use of the official NSS initialization functions.

For a long time, NSS had only one official initialization function, NSS_Init. Many products that used NSS found NSS_Init unsuitable for their purposes either because (a) it opened the security databases read-only or (b) it required applications to put all the security databases into a single directory (whose name is supplied by the application), and did not allow the application to control the names of the database files in that directory. Those applications often developed their own alternative functions for initializing NSS, functions that called NSS private internal functions to do their work.

NSS 3.1 included a new initialization function, NSS_InitReadWrite, that allowed the application to open the databases read-write, but did not give any more flexibility about database file and path names.

NSS 3.2 includes another new initialization function, NSS_Initialize. This function provides explicit control over the pathnames and file name prefixes for the security databases, as well as control over whether the files are opened read-only or read-write. This function is not recommended for use by most applications.

The private internal NSS functions that were previously called by applications that developed their own NSS initialization functions are not exposed in the new NSS DSOs and can no longer be called directly by application code.

So, beginning in NSS 3.2, applications MUST use one of the official NSS initialization functions.

New NSS functions for runtime checking of DSO version compatibility

With NSS packaged in DSOs (or DLLs) instead of being staticly linked into the applications, it is now possible for an application to be installed with an incompatible version of the NSS DSOs. Therefore, it's desirable for an application to be able to test at run time to ensure that the NSS DSOs it's using are indeed compatible. To that end, NSS 3.2 provides a new function, NSS_VersionCheck, that allows the application to tell the DSO what version of NSS it was built to use and receive a reply indicating whether the DSO is compatible with that version.

Additional SSL/TLS cipher suites supported

In NSS 3.2, the cipher suite known formally as SSL_RSA_WITH_RC4_128_SHA or TLS_RSA_WITH_RC4_128_SHA is now supported. To maximize compatibility with older programs, unlike all the TLS and SSL3 cipher suites that were implemented in older versions of NSS, this new cipher suite is NOT enabled by default.

To use this new cipher suite, an application must enable it explicitly by a call to SSL_CipherPrefSetDefault or SSL_CipherPrefSet. The new cipher suite is properly handled by the functions NSS_SetDomesticPolicy, NSS_SetExportPolicy, and NSS_SetFrancePolicy. Applications that call SSL_CipherPolicySet instead of one of the three aforementioned policy functions must also call SSL_CipherPolicySet for this new policy if they wish to use it.

Use of SEC_ASN1 templates

NSS 3.2 provides new macros (#defines) used to access SEC_ASN1 templates that are inside a DLL/DSO from outside of that DSO/DLL. If you use these macros, your code will work on both NT and UNIX.

There are two parts to the changes.

  1. In any C code (except in initialization data for structures), you simply replace the reference to the template with SEC_ASN1_GET(the template).

    For example,

    theTemplate = SEC_IA5StringTemplate;
    theTemplate = SEC_ASN1_GET(SEC_IA5StringTemplate);

  2. If you have a template of your own that is initialized and whose initialization data contains a reference to a DSO/DLLs template, then you must make two changes to your template. You must OR the value SEC_ASN1_XTRN into the "kind" member of your template, and you must place the reference to the external template inside the SEC_ASN1_SUB() macro.

    For example:

    { SEC_ASN1_SET_OF,
    offsetof(NSSCMSSignedData,digestAlgorithms),
    SECOID_AlgorithmIDTemplate
    },

    { SEC_ASN1_SET_OF | SEC_ASN1_XTRN,
    offsetof(NSSCMSSignedData,digestAlgorithms),
    SEC_ASN1_SUB(SECOID_AlgorithmIDTemplate)
    },

    You can see examples of such changes here:

Deprecated SSL functions no longer available

As explained in NSS 3.2 Public Functions, five old SSL functions are deprecated and no longer available in NSS 3.2. The same document lists a new replacement function for each deprecated function.

One caveat: In NSS 2.7, certain old proprietary Netscape SSL cipher suite numbers were replaced with new ciphersuite numbers. For backward binary compatibility, the now-deprecated functions SSL_SetPolicy and SSL_EnableCipher automatically substituted the new cipher suite numbers for the old ones. So, if an application called SSL_EnableCipher with the old value for SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA or SSL_RSA_FIPS_WITH_DES_CBC_SHA, the function SSL_EnableCipher would substitute the new cipher suite number for the old one transparently to the application. The new replacement functions, SSL_CipherPolicySet and SSL_CipherPrefSetDefault do not perform this automatic substitution. However, applications compiled with the NSS 3.2 header files will get the new numbers from the header files and will not require the automatic substitution. So this will not be a problem for applications that are compiled with the NSS 3.2 headers.

Use of Netscape's proprietary FIPS cipher suites is now discouraged. Applications that want FIPS compliance should now use TLS instead of SSL3.

New dependence on LD_LIBRARY_PATH for 32-bit Solaris applications, and on SHLIB_PATH for 32-bit HP-UX applications

For applications on Solaris and HP-UX that use each platform's 32-bit ABI, NSS 3.2 now dynamically loads one or more DLLs at run time. NSS 3.2 relies on those DLLs being in the path specified by the LD_LIBRARY_PATH environment variable on Solaris, or by the SHLIB_PATH environment variable on HPUX. If you are developing 32-bit applications on Solaris and HPUX, make sure that all NSS and NSPR DSOs are installed in the same directory and that the name of that directory is in the appropriate environment variable.

Migration from NSS 3.1.1

NSS 3.2 has three shared libraries: NSS base (nss), S/MIME (smime), and SSL (ssl). These shared libraries replace the static NSS libraries as follows:
  • NSS base:
    • On Unix, libnss3.so replaces libnss.a, libcerthi.a, libpk11wrap.a, libcryptohi.a, libsoftoken.a, libcertdb.a, libcrypto.a, libfreebl.a, libsecutil.a, and libdbm.a.
    • On Windows, nss3.lib (the import library) replaces nss.lib, certhi.lib, cryptohi.lib, pk11wrap.lib, certdb.lib, softoken.lib, crypto.lib, freebl.lib, secutil.lib, and dbm.lib (the static libraries).
  • S/MIME:
    • On Unix, libsmime3.so replaces libsmime.a, libpkcs12.a, and libpkcs7.a.
    • On Windows, smime3.lib (the import library) replaces smime.lib, pkcs12.lib, and pkcs7.lib (the static libraries).
  • SSL:
    • On Unix, libssl3.so replaces libssl.a.
    • On Windows, ssl3.lib (the import library) replaces ssl.lib (the static library).
Note the following:
  • The shared libraries export fewer functions than the corresponding static libraries. However, all the functions exported by the shared libraries will be supported by future NSS 3.x releases.
  • PSM won't be able to use the shared libraries in NSS 3.2 because some of the NSS internal functions used by PSM won't be exported by the shared libraries. We plan to address this issue soon (in NSS 3.3 or 3.4).
  • Similarly, JSS won't be able to use the shared libraries in NSS 3.2. We will address this issue in NSS 3.3.
  • Shared library linking order: Both the S/MIME and SSL shared libraries depend on the NSS base shared library. When we build the S/MIME and SSL shared libraries, we already link them with the NSS base shared library to resolve symbols. Therefore, linking order of the shared libraries is not important. For example, on Unix, if your code calls both the SSL functions and NSS base functions, you can link with either -lssl3 -lnss3 or -lnss3 -lssl3, but we recommend the -lssl3 -lnss3 order as a matter of style.
  • On Solaris and HP-UX, we also include two shared objects (libfreebl_pure32_3.so and libfreebl_hybrid_3.so) that applications do not link with directly but are dynamically loaded at run time when NSS is initialized. These two shared objects need to be placed in a directory on the shared library search path for the applications (e.g., as specified by LD_LIBRARY_PATH or HP-UX's SHLIB_PATH). They contain code specific to the processor architecture that improves performance.

Platform Information

NSS is maintained on the platforms listed below. "Certified" means the iPlanet NSS team has built and run QA tests for NSS on a machine with the specified OS.

Platform Build Certify Compiler(s)
AIX 4.3.3 (32 bit) 4.3.3 (32 bit)
4.3.3 (64 bit)		 xlC/C++ 3.6.4
4.3.3 (64 bit) 4.3.3 (64 bit) xlC/C++ 3.6.4
Compaq Tru64 4.0D 4.0D 
5.0A		 (cc) Digital C v5.6-071
HP-UX 11.0 (32 bit) 11.0 (32 bit)
11.0 (64 bit)		 C compiler: A.11.01.00
11.0 (64 bit) 11.0 (64 bit) C compiler A.11.01.00
Linux RedHat 6.0 RedHat 6.0
RedHat 6.1		 egcs-1.1.2
NT NT 4.0 w/ SP 6a NT 4.0 w/ SP 6a
Win2000		 VC++ 6.0 Service Pack 3
Windows NT 4.0 w/ SP 6a
NT 4.0 w/ SP 6a
Win2000		 VC++ 6.0 Service Pack 3
Solaris 2.6 2.6
8 (32 bit)
8 (64 bit)		 WorkShop Compilers 
C/C++ version 4.2 
8 (64-bit) 8 (64-bit) WorkShop Compilers 
C/C++ version 5.0

NSS has not yet been formally tested or certified on any other platforms. If you have successfully run NSS on other platforms, or if you are interested in taking responsibility for testing and maintaining NSS on a particular platform that's not listed above, post a message to mozilla.dev.tech.crypto.

Note re NT builds: The build listed in the left column above as the "NT" build runs on NT (including Windows 2000) only and hence can potentially take advantage of some Win32 functions that are only implemented on NT, such as fibers and I/O completion ports. The build listed above as the "Windows" build runs on all Windows flavors -- 95, 98, Me, NT, and 2000.

Only NSPR makes use of this NT vs. Windows distinction and provides different NT and Windows builds. Many Netscape products, including NSS, have NT and Windows builds that are essentially the same except one difference: one is linked with the NT version of NSPR and the other is linked with the Windows version of NSPR.

Note to Macintosh Developers: Due to a lack of resources, our team was unable to develop NSS for the Macintosh platform. We are looking for help from any interested parties to modify the Macintosh project file for NSS 3.2. For contact information, please see the Feedback section.

Known Bugs and Issues

  • NSS 3.2 uses mozilla/dbm, which is based on Berkeley DB 1.85. Berkeley DB 1.85 is released under the original BSD license, whose "advertising clause" is incompatible with the GNU GPL.

    In a letter dated July 22, 1999, UC Berkeley announced that the advertising clause is deleted from all the BSD Unix files (of any version of BSD) containing it. (The announcement is available at ftp.cs.berkeley.edu/ucb/4bsd/README.Impt.License.Change.) The final (AT&T proprietary) 4.4BSD release contained version 1.6 of Berkeley DB. The 4.4BSD-Lite2 release contained version 1.74 of Berkeley DB. Since Berkeley DB 1.85 is not technically in any version of BSD (although it is derived from the Berkeley DB files in 4.4BSD and 4.4BSD-Lite2), it is not clear whether the Berkeley announcement deletes the advertising clause from Berkeley DB 1.85.

  • For a list of reported bugs that have not been fixed in NSS 3.2, click here. (Note that not all of these bugs have been confirmed. Even some bugs in the "new" state are unconfirmed.)

Compatibility

NSS 3.2 is backward compatible with NSS 3.1.1, NSS 3.1, and NSS 3.0.x. Applications that restrict their use of NSS APIs to the functions listed in NSS 3.2 Public Functions will remain compatible with future versions of the NSS shared libraries.

Feedback

Bugs discovered should be reported by filing a bug report with bugzilla (product NSS).

You can also give feedback directly to the developers on the IRC channel #mozcrypto on the server irc.mozilla.org.