Bug 1709817 - Import the NSS documentation from MDN in nss/doc. r=beurdouche

Differential Revision: https://phabricator.services.mozilla.com/D119912

3 files changed, 446 insertions, 0 deletions

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 <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Getting_Started_with_IRC>`__ in
+     channel `#nss <irc://irc.mozilla.org/#nss>`__ or you could ask your questions on the
+     `mozilla.dev.tech.crypto <https://lists.mozilla.org/listinfo/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 <https://developer.mozilla.org/en-US/docs/NSS>`__
+      from which we link to other documentation.
+   -  a `General Overview <https://developer.mozilla.org/en-US/docs/Overview_of_NSS>`__ 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 <https://www-archive.mozilla.org/projects/security/pki/nss/>`__ 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 <https://bugzilla.mozilla.org/show_bug.cgi?id=490238>`__.
+
+   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 <https://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 <https://bugzilla.mozilla.org/buglist.cgi?keywords=good-first-bug%2C%20&keywords_type=allwords&classification=Components&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Libraries&product=NSS>`__.
+
+.. _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/ <https://phabricator.services.mozilla.com>`__ is our
+   code review tool, which uses your Bugzilla account. Use our `Phabricator user instructions to
+   upload patches for
+   review <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`__.
+
+   Some items that will be evaluated during code review are `listed in checklist form on
+   Github. <https://github.com/mozilla/nss-tools/blob/master/nss-code-review-checklist.yaml>`__
+
+   After passing review, your patch can be landed by a member of the NSS team. You can find us on
+   `Mozilla IRC <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Getting_Started_with_IRC>`__ in
+   channel `#nss <irc://irc.mozilla.org/#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 <more_docs>
+
+`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 <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_Public-Key_Cryptography>`__
+      Explains the basic concepts of public-key cryptography that underlie NSS.
+   `Introduction to SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/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 <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code/Mercurial>`__
+      Information about with working with Mercurial.
+   `Get Mozilla Source Code Using CVS (deprecated) <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code/CVS>`__
+      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 <https://www-archive.mozilla.org/projects/security/pki/nss/testnss_32.html>`__
+      **Archived version.** Describes how to run the standard NSS tests.
+   `NSS Performance Reports <https://www-archive.mozilla.org/projects/security/pki/nss/performance_reports.html>`__
+      **Archived version.** Links to performance reports for NSS 3.2 and later releases.
+   `Encryption Technologies Available in NSS 3.11 <https://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11/nss-3.11-algorithms.html>`__
+      **Archived version.** Lists the cryptographic algorithms used by NSS 3.11.
+   `NSS 3.1 Loadable Root Certificates <https://www-archive.mozilla.org/projects/security/pki/nss/loadable_certs.html>`__
+      **Archived version.** Describes the scheme for loading root CA certificates.
+   `cert7.db <https://www-archive.mozilla.org/projects/security/pki/nss/db_formats.html>`__
+      **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 <https://developer.mozilla.org/en-US/docs/PKCS11_Jar_Install>`__
+   -  `PKCS #11 Conformance Testing - Archived
+      version <https://www-archive.mozilla.org/projects/security/pki/pkcs11/>`__
+
+   .. rubric:: CA certificates pre-loaded into NSS
+      :name: CA_certificates_pre-loaded_into_NSS
+
+   -  `Mozilla CA certificate policy <https://www.mozilla.org/projects/security/certs/policy/>`__
+   -  `List of pre-loaded CA certificates <https://wiki.mozilla.org/CA/Included_Certificates>`__
+
+      -  Consumers of this list must consider the trust bit setting for each included root
+         certificate. `More
+         Information <https://www.imperialviolet.org/2012/01/30/mozillaroots.html>`__, `Extracting
+         roots and their trust bits <https://github.com/agl/extract-nss-root-certs>`__
+
+   .. 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>`__
+      NSPR project page.
+   `NSPR Reference <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference>`__
+      NSPR API documentation.
+
+   .. rubric:: Additional Information
+      :name: Additional_Information
+
+   -  `Using the window.crypto object from
+      JavaScript <https://developer.mozilla.org/en-US/docs/JavaScript_crypto>`__
+   -  :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 <https://wiki.mozilla.org/NSS>`__,
+   including:
+
+   -  `FIPS Validation <https://wiki.mozilla.org/FIPS_Validation>`__
+   -  `NSS Roadmap page <https://wiki.mozilla.org/NSS:Roadmap>`__
+   -  `NSS Improvement
+      Project <https://fedoraproject.org/wiki/User:Mitr/NSS:DeveloperFriendliness>`__
+
+.. _Community:
+
+Community
+~~~~~~~~~
+
+-  View Mozilla Security forums...
+
+-  `Mailing list <https://lists.mozilla.org/listinfo/dev-security>`__
+-  `Newsgroup <http://groups.google.com/group/mozilla.dev.security>`__
+-  `RSS feed <http://groups.google.com/group/mozilla.dev.security/feeds>`__
+
+-  View Mozilla Cryptography forums...
+
+-  `Mailing list <https://lists.mozilla.org/listinfo/dev-tech-crypto>`__
+-  `Newsgroup <http://groups.google.com/group/mozilla.dev.tech.crypto>`__
+-  `RSS feed <http://groups.google.com/group/mozilla.dev.tech.crypto/feeds>`__
+
+.. _Related_Topics:
+
+Related Topics
+~~~~~~~~~~~~~~
+
+-  `Security <https://developer.mozilla.org/en-US/docs/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 <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 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 <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>`__.
\ No newline at end of file