From 1c126b14820154bb8b262263f8c3e05507b6d19f Mon Sep 17 00:00:00 2001 From: Benjamin Beurdouche Date: Wed, 14 Jul 2021 19:34:14 +0000 Subject: Bug 1709817 - Import the NSS documentation from MDN in nss/doc. r=beurdouche Differential Revision: https://phabricator.services.mozilla.com/D119912 --- doc/rst/getting_started_with_nss/index.rst | 106 ++++++++++++ doc/rst/index.rst | 178 +++++++++++++++++++++ .../index.rst | 162 +++++++++++++++++++ 3 files changed, 446 insertions(+) create mode 100644 doc/rst/getting_started_with_nss/index.rst create mode 100644 doc/rst/index.rst create mode 100644 doc/rst/introduction_to_network_security_services/index.rst diff --git a/doc/rst/getting_started_with_nss/index.rst b/doc/rst/getting_started_with_nss/index.rst new file mode 100644 index 000000000..4f9ae3540 --- /dev/null +++ b/doc/rst/getting_started_with_nss/index.rst @@ -0,0 +1,106 @@ +.. _mozilla_projects_nss_getting_started_with_nss: + +Getting Started With NSS +======================== + +.. _how_to_get_involved_with_nss: + +`How to get involved with NSS <#how_to_get_involved_with_nss>`__ +---------------------------------------------------------------- + +.. container:: + + | Network Security Services (NSS) is a base library for cryptographic algorithms and secure + network protocols used by Mozilla software. + | Would you like to get involved and help us to improve the core security of Mozilla Firefox and + other applications that make use of NSS? We are looking forward to your contributions! + | We have a large list of tasks waiting for attention, and we are happy to assist you in + identifying areas that match your interest or skills. You can find us on `Mozilla + IRC `__ in + channel `#nss `__ or you could ask your questions on the + `mozilla.dev.tech.crypto `__ newsgroup. + + The NSS library and its supporting command line tools are written in the C programming language. + Its build system and the automated tests are based on makefiles and bash scripts. + + Over time, many documents have been produced that describe various aspects of NSS. You can start + with: + + - the current `primary NSS documentation page `__ + from which we link to other documentation. + - a `General Overview `__ of the + applications that use NSS and the features it provides. + - a high level :ref:`mozilla_projects_nss_an_overview_of_nss_internals`. + - learn about getting the :ref:`mozilla_projects_nss_nss_sources_building_testing` + - `Old documentation `__ that is on + the archived mozilla.org website. + + (Unfortunately the NSS project doesn't have a technical writer at this time, so our documentation + is not as organized as we would like it to be. You could contribute by organizing it in a better + way.) + +.. _nss_sample_code: + +`NSS Sample Code <#nss_sample_code>`__ +-------------------------------------- + +.. container:: + + A good place to start learning how to write NSS applications are the command line tools that are + maintained by the NSS developers. You can find them in subdirectory mozilla/security/nss/cmd + + Or have a look at some basic :ref:`mozilla_projects_nss_nss_sample_code`. + + A new set of samples is currently under development and review, see `Create new NSS + samples `__. + + You are welcome to download the samples via: hg clone https://hg.mozilla.org/projects/nss; cd + nss; hg update SAMPLES_BRANCH + +.. _how_to_contribute: + +`How to Contribute <#how_to_contribute>`__ +------------------------------------------ + +.. container:: + + ... (this section is still under construction, but there are many contribution opportunities) + + Start by opening a bugzilla account at `bugzilla.mozilla.org `__ + if you don't have one. + + NSS :: Libraries component for issues you'd like to work on. We maintain a list of `NSS bugs + marked with a keyword "good-first-bug" that you can + view `__. + +.. _creating_your_patch: + +`Creating your Patch <#creating_your_patch>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Seee our section on :ref:`mozilla_projects_nss_nss_sources_building_testing` to get started + making your patch. When you're satisfied with it, you'll need code review. + +.. _code_review: + +`Code Review <#code_review>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + `http://phabricator.services.mozilla.com/ `__ is our + code review tool, which uses your Bugzilla account. Use our `Phabricator user instructions to + upload patches for + review `__. + + Some items that will be evaluated during code review are `listed in checklist form on + Github. `__ + + After passing review, your patch can be landed by a member of the NSS team. You can find us on + `Mozilla IRC `__ in + channel `#nss `__. + + Note that we don't land code that isn't both reviewed and tested. Code only works when it has + tests, and tests only work when they're part of the automation. \ No newline at end of file diff --git a/doc/rst/index.rst b/doc/rst/index.rst new file mode 100644 index 000000000..486a99446 --- /dev/null +++ b/doc/rst/index.rst @@ -0,0 +1,178 @@ +.. _mozilla_projects_nss: + +Network Security Services +========================= + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + getting_started_with_nss/index.rst + introduction_to_network_security_services/index.rst + More documentation + +`Documentation <#documentation>`__ +---------------------------------- + +.. container:: + + **Network Security Services** (**NSS**) is a set of libraries designed to support cross-platform + development of security-enabled client and server applications. Applications built with NSS can + support SSL v3, TLS, PKCS #5, PKCS #7, PKCS #11, PKCS #12, S/MIME, X.509 v3 certificates, and + other security standards. + + For detailed information on standards supported, see :ref:`mozilla_projects_nss_overview`. For a + list of frequently asked questions, see the :ref:`mozilla_projects_nss_faq`. + + NSS is available under the Mozilla Public License. For information on downloading NSS releases as + tar files, see :ref:`mozilla_projects_nss_nss_sources_building_testing`. + + If you're a developer and would like to contribute to NSS, you might want to read the documents + :ref:`mozilla_projects_nss_an_overview_of_nss_internals` and + :ref:`mozilla_projects_nss_getting_started_with_nss`. + + .. rubric:: Background Information + :name: Background_Information + + :ref:`mozilla_projects_nss_overview` + Provides a brief summary of NSS and its capabilities. + :ref:`mozilla_projects_nss_faq` + Answers basic questions about NSS. + `Introduction to Public-Key Cryptography `__ + Explains the basic concepts of public-key cryptography that underlie NSS. + `Introduction to SSL `__ + Introduces the SSL protocol, including information about cryptographic ciphers supported by + SSL and the steps involved in the SSL handshake. + + .. rubric:: Getting Started + :name: Getting_Started + + :ref:`mozilla_projects_nss_nss_releases` + This page contains information about the current and past releases of NSS. + :ref:`mozilla_projects_nss_nss_sources_building_testing` + Instructions on how to build NSS on the different supported platforms. + `Get Mozilla Source Code Using Mercurial `__ + Information about with working with Mercurial. + `Get Mozilla Source Code Using CVS (deprecated) `__ + Old deprecated CVS documentation. + + .. rubric:: NSS APIs + :name: NSS_APIs + + :ref:`mozilla_projects_nss_introduction_to_network_security_services` + Provides an overview of the NSS libraries and what you need to know to use them. + :ref:`mozilla_projects_nss_ssl_functions` + Summarizes the SSL APIs exported by the NSS shared libraries. + :ref:`mozilla_projects_nss_reference` + API used to invoke SSL operations. + :ref:`mozilla_projects_nss_nss_api_guidelines` + Explains how the libraries and code are organized, and guidelines for developing code (naming + conventions, error handling, thread safety, etc.) + :ref:`mozilla_projects_nss_nss_tech_notes` + Links to NSS technical notes, which provide latest information about new NSS features and + supplementary documentation for advanced topics in programming with NSS. + + .. rubric:: Tools, testing, and other technical details + :name: Tools_testing_and_other_technical_details + + :ref:`mozilla_projects_nss_building` + Describe how to check out and build NSS releases. + + :ref:`mozilla_projects_nss_nss_developer_tutorial` + How to make changes in NSS. Coding style, maintaining ABI compatibility. + + :ref:`mozilla_projects_nss_tools` + Tools for developing, debugging, and managing applications that use NSS. + :ref:`mozilla_projects_nss_nss_sample_code` + Demonstrates how NSS can be used for cryptographic operations, certificate handling, SSL, etc. + :ref:`mozilla_projects_nss_nss_third-party_code` + A list of third-party code included in the NSS library. + `NSS 3.2 Test Suite `__ + **Archived version.** Describes how to run the standard NSS tests. + `NSS Performance Reports `__ + **Archived version.** Links to performance reports for NSS 3.2 and later releases. + `Encryption Technologies Available in NSS 3.11 `__ + **Archived version.** Lists the cryptographic algorithms used by NSS 3.11. + `NSS 3.1 Loadable Root Certificates `__ + **Archived version.** Describes the scheme for loading root CA certificates. + `cert7.db `__ + **Archived version.** General format of the cert7.db database. + + .. rubric:: PKCS #11 information + :name: PKCS_11_information + + - :ref:`mozilla_projects_nss_pkcs11` + - :ref:`mozilla_projects_nss_pkcs11_implement` + - :ref:`mozilla_projects_nss_pkcs11_module_specs` + - :ref:`mozilla_projects_nss_pkcs11_faq` + - `Using the JAR Installation Manager to Install a PKCS #11 Cryptographic + Module `__ + - `PKCS #11 Conformance Testing - Archived + version `__ + + .. rubric:: CA certificates pre-loaded into NSS + :name: CA_certificates_pre-loaded_into_NSS + + - `Mozilla CA certificate policy `__ + - `List of pre-loaded CA certificates `__ + + - Consumers of this list must consider the trust bit setting for each included root + certificate. `More + Information `__, `Extracting + roots and their trust bits `__ + + .. rubric:: NSS is built on top of Netscape Portable Runtime (NSPR) + :name: NSS_is_built_on_top_of_Netscape_Portable_Runtime_NSPR + + `Netscape Portable Runtime `__ + NSPR project page. + `NSPR Reference `__ + NSPR API documentation. + + .. rubric:: Additional Information + :name: Additional_Information + + - `Using the window.crypto object from + JavaScript `__ + - :ref:`mozilla_projects_nss_http_delegation` + - :ref:`mozilla_projects_nss_tls_cipher_suite_discovery` + - :ref:`mozilla_projects_nss_certificate_download_specification` + - :ref:`mozilla_projects_nss_fips_mode_-_an_explanation` + - :ref:`mozilla_projects_nss_key_log_format` + + .. rubric:: Planning + :name: Planning + + Information on NSS planning can be found at `wiki.mozilla.org `__, + including: + + - `FIPS Validation `__ + - `NSS Roadmap page `__ + - `NSS Improvement + Project `__ + +.. _Community: + +Community +~~~~~~~~~ + +- View Mozilla Security forums... + +- `Mailing list `__ +- `Newsgroup `__ +- `RSS feed `__ + +- View Mozilla Cryptography forums... + +- `Mailing list `__ +- `Newsgroup `__ +- `RSS feed `__ + +.. _Related_Topics: + +Related Topics +~~~~~~~~~~~~~~ + +- `Security `__ + diff --git a/doc/rst/introduction_to_network_security_services/index.rst b/doc/rst/introduction_to_network_security_services/index.rst new file mode 100644 index 000000000..031f4ab64 --- /dev/null +++ b/doc/rst/introduction_to_network_security_services/index.rst @@ -0,0 +1,162 @@ +.. _mozilla_projects_nss_introduction_to_network_security_services: + +Introduction to Network Security Services +========================================= + +.. container:: + + **Network Security Services (NSS)** is a set of libraries designed to support cross-platform + development of communications applications that support SSL, 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 library supports core SSL operations. + - The S/MIME library supports core S/MIME operations. + - The NSS library supports core crypto operations. + + We guarantee that applications using the exported APIs will remain compatible with future + versions of those libraries. 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 `__. + + 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 `__ 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 and special libraries <#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 ``.sl`` + ======= ======== ================== + + In addition, Windows has "import" libraries that bind to dynamic libraries. So the NSS library + has the following forms: + + - ``libnss3.so`` - Unix 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 `__ + - `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 `__. \ No newline at end of file -- cgit v1.2.1