diff options
Diffstat (limited to 'doc/rst/build_artifacts.rst')
| -rw-r--r-- | doc/rst/build_artifacts.rst | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/doc/rst/build_artifacts.rst b/doc/rst/build_artifacts.rst new file mode 100644 index 000000000..ba7a48bb5 --- /dev/null +++ b/doc/rst/build_artifacts.rst @@ -0,0 +1,177 @@ +.. _mozilla_projects_nss_build_artifacts: + +.. warning:: + This NSS documentation was just imported from our legacy MDN repository. It currently is very deprecated and likely incorrect or broken in many places. + +Build artifacts +=============== + +.. container:: + + **Network Security Services (NSS)** is a set of libraries designed to support cross-platform + development of communications applications that support TLS, S/MIME, and other Internet security + standards. For a general overview of NSS and the standards it supports, see + :ref:`mozilla_projects_nss_overview`. + +.. _shared_libraries: + +`Shared libraries <#shared_libraries>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services provides both static libraries and shared libraries. Applications that + use the shared libraries must use only the APIs that they export. Three shared libraries export + public functions: + + - The SSL/TLS library supports core TLS operations. + - The S/MIME library supports core S/MIME operations. + - The freebl library supports core crypto operations. + +.. note:: + + We guarantee that applications using the exported APIs will remain compatible with future + versions of those libraries until deprecated. + +.. container:: + + .. + For a complete list of public functions exported by these shared + libraries in NSS 3.2, see :ref:`mozilla_projects_nss_reference_nss_functions`. + + .. + For information on which static libraries in NSS 3.1.1 are replaced by each of the above shared + libraries in NSS 3.2 , see `Migration from NSS + 3.1.1 <https://www-archive.mozilla.org/projects/security/pki/nss/release_notes_32.html#migration>`__. + + .. + Figure 1, below, shows a simplified view of the relationships among the three shared libraries + listed above and NSPR, which provides low-level cross platform support for operations such as + threading and I/O. (Note that NSPR is a separate Mozilla project; see `Netscape Portable + Runtime <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR>`__ for details.) + + .. image:: /en-US/docs/Mozilla/Projects/NSS/Introduction_to_Network_Security_Services/nss.gif + :alt: Diagram showing the relationships among core NSS libraries and NSPR. + :width: 429px + :height: 196px + +.. _naming_conventions_and_special_libraries: + +`Naming conventions <#naming_conventions_and_special_libraries>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Windows and Unix use different naming conventions for static and dynamic libraries: + + ======= ======== =============================== + Windows Unix + static ``.lib`` ``.a`` + dynamic ``.dll`` ``.so`` or ``.dylib`` or ``.sl`` + ======= ======== =============================== + + In addition, Windows has "import" libraries that bind to dynamic libraries. So the NSS library + has the following forms: + + - ``libnss3.so`` - Linux shared library + - ``libnss3.dylib`` - MacOS shared library + - ``libnss3.sl`` - HP-UX shared library + - ``libnss.a`` - Unix static library + - ``nss3.dll`` - Windows shared library + - ``nss3.lib`` - Windows import library binding to ``nss3.dll`` + - ``nss.lib`` - Windows static library + + NSS, SSL, and S/MIME have all of the above forms. + + The following static libraries aren't included in any shared libraries + + - ``libcrmf.a``/``crmf.lib`` provides an API for CRMF operations. + - ``libjar.a``/``jar.lib`` provides an API for creating JAR files. + + The following static libraries are included only in external loadable PKCS #11 modules: + + - ``libnssckfw.a``/``nssckfw.lib`` provides an API for writing PKCS #11 modules. + - ``libswfci.a``/``swfci.lib`` provides support for software FORTEZZA. + + The following shared libraries are standalone loadable modules, not meant to be linked with + directly: + + - ``libfort.so``/``libfort.sl``/``fort32.dll`` provides support for hardware FORTEZZA. + - ``libswft.so``/``libswft.sl``/``swft32.dll`` provides support for software FORTEZZA. + - ``libnssckbi.so``/``libnssckbi.sl``/``nssckbi.dll`` defines the default set of trusted root + certificates. + +.. + .. _support_for_ilp32: + + `Support for ILP32 <#support_for_ilp32>`__ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. container:: + + In NSS 3.2 and later versions, there are two new shared libraries for the platforms HP-UX for + PARisc CPUs and Solaris for (Ultra)Sparc (not x86) CPUs. These HP and Solaris platforms allow + programs that use the ILP32 program model to run on both 32-bit CPUs and 64-bit CPUs. The two + libraries exist to provide optimal performance on each of the two types of CPUs. + + These two extra shared libraries are not supplied on any other platforms. The names of these + libraries are platform-dependent, as shown in the following table. + + ================================== ============================ ============================ + Platform for 32-bit CPUs for 64-bit CPUs + Solaris/Sparc ``libfreebl_pure32_3.so`` ``libfreebl_hybrid_3.so`` + HPUX/PARisc ``libfreebl_pure32_3.sl`` ``libfreebl_hybrid_3.sl`` + AIX (planned for a future release) ``libfreebl_pure32_3_shr.a`` ``libfreebl_hybrid_3_shr.a`` + ================================== ============================ ============================ + + An application should not link against these libraries, because they are dynamically loaded by + NSS at run time. Linking the application against one or the other of these libraries may produce + an application program that can only run on one type of CPU (e.g. only on 64-bit CPUs, not on + 32-bit CPUs) or that doesn't use the more efficient 64-bit code on 64-bit CPUs, which defeats the + purpose of having these shared libraries. + + On platforms for which these shared libraries exist, NSS 3.2 will fail if these shared libs are + not present. So, an application must include these files in its distribution of NSS shared + libraries. These shared libraries should be installed in the same directory where the other NSS + shared libraries (such as ``libnss3.so``) are installed. Both shared libs should always be + installed whether the target system has a 32-bit CPU or a 64-bit CPU. NSS will pick the right one + for the local system at run time. + + Note that NSS 3.x is also available in the LP64 model for these platforms, but the LP64 model of + NSS 3.x does not have these two extra shared libraries. + +.. + .. _what_you_should_already_know: + + `What you should already know <#what_you_should_already_know>`__ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. container:: + + Before using NSS, you should be familiar with the following topics: + + - Concepts and techniques of public-key cryptography + - The Secure Sockets Layer (SSL) protocol + - The PKCS #11 standard for cryptographic token interfaces + - Cross-platform development issues and techniques + + .. _where_to_find_more_information: + + `Where to find more information <#where_to_find_more_information>`__ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. container:: + + For information about PKI and SSL that you should understand before using NSS, see the following: + + - `Introduction to Public-Key + Cryptography <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_Public-Key_Cryptography>`__ + - `Introduction to + SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_SSL>`__ + + For links to API documentation, build instructions, and other useful information, see the + :ref:`mozilla_projects_nss`. + + As mentioned above, NSS is built on top of NSPR. The API documentation for NSPR is available at + `NSPR API + Reference <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference>`__. |