diff options
Diffstat (limited to 'security/nss/doc/rst')
434 files changed, 82031 insertions, 0 deletions
diff --git a/security/nss/doc/rst/build.rst b/security/nss/doc/rst/build.rst new file mode 100644 index 0000000000..e07f6971e9 --- /dev/null +++ b/security/nss/doc/rst/build.rst @@ -0,0 +1,230 @@ +.. _mozilla_projects_nss_building: + +Building NSS +============ + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + This page has detailed information on how to build NSS. Because NSS is a + cross-platform library that builds on many different platforms and has many + options, it may be complex to build._ Two build systems are maintained + concurrently: a ``Make`` based and a ``gyp`` based system. + +.. _build_environment: + +`Prerequisites <#build_environment>`__ +------------------------------------------ + +.. container:: + + NSS needs a C and C++ compiler. It has minimal dependencies, including only + standard C and C++ libraries, plus `zlib <https://www.zlib.net/>`__. + For building, you also need `make <https://www.gnu.org/software/make/>`__. + Ideally, also install `gyp-next <https://github.com/nodejs/gyp-next>`__ and `ninja + <https://ninja-build.org/>`__ and put them on your path. This is + recommended, as the build is faster and more reliable. + Please, note that we ``gyp`` is currently unmaintained and that our support for + ``gyp-next`` is experimental and might be unstable. + + To install prerequisites on different platforms, one can run the following + commands: + + **On Linux:** + + .. code:: + + sudo apt install mercurial git ninja-build python3-pip + python3 -m pip install gyp-next + + **On MacOS:** + + .. code:: + + brew install mercurial git ninja python3-pip + python3 -m pip install gyp-next + + It is also necessary to make sure that a `python` (not just `python3`) + executable is in the path. + The Homebrew Python installation has the necessary symlink but may require + explicit adding to the PATH variable, for example like this: + + .. code:: + + export PATH="/opt/homebrew/opt/python/libexec/bin:$PATH" + + **On Windows:** + + .. code:: + + <TODO> + +.. note:: + To retrieve the source code from the project repositories, users will need to + download a release or pull the source code with their favourite Version + Control System (git or Mercurial). Installing a VCS is not necessary to build + an NSS release when downloaded as a compressed archive. + + By default Mozilla uses a Mercurial repository for NSS. If you whish to + contribute to NSS and use ``git`` instead of Mercurial, we encourage you to + install `git-cinnabar <https://github.com/glandium/git-cinnabar>`__. + +.. + `Windows <#windows>`__ + ~~~~~~~~~~~~~~~~~~~~~~ + + .. container:: + + NSS compilation on Windows uses the same shared build system as Mozilla + Firefox. You must first install the `Windows Prerequisites + <https://firefox-source-docs.mozilla.org/setup/windows_build.html>`__, + including **MozillaBuild**. + + You can also build NSS on the Windows Subsystem for Linux, but the resulting binaries aren't + usable by other Windows applications. + +.. _get_the_source: + +`Source code <#get_the_source>`__ +--------------------------------- + +.. container:: + + NSS and NSPR use Mercurial for source control like other Mozilla projects. To + check out the latest sources for NSS and NSPR--which may not be part of a + stable release--use the following commands: + + .. code:: + + hg clone https://hg.mozilla.org/projects/nspr + hg clone https://hg.mozilla.org/projects/nss + + + **To get the source of a specific release, see:** + ref:`mozilla_projects_nss_releases` **.** + + To download the source using ``git-cinnabar`` instead: + + .. code:: + + git clone hg::https://hg.mozilla.org/projects/nspr + git clone hg::https://hg.mozilla.org/projects/nss + + +`Build with gyp and ninja <#build>`__ +------------------------------------- + +.. container:: + + Build NSS and NSPR using our build script from the ``nss`` directory: + + .. code:: + + cd nss + ./build.sh + + This builds both NSPR and NSS in a parent directory called ``dist``. + + Build options are available for this script: ``-o`` will build in **Release** + mode instead of the **Debug** mode and ``-c`` will **clean** the ``dist`` + directory before the build. + + Other build options can be displayed by running ``./build.sh --help`` + +.. _build_with_make: + +`Build with make <#build_with_make>`__ +-------------------------------------- + +.. container:: + + Alternatively, there is a ``make`` target, which produces a similar + result. This supports some alternative options, but can be a lot slower. + + .. code:: + + USE_64=1 make -j + + The make-based build system for NSS uses a variety of variables to control + the build. Below are some of the variables, along with possible values they + may be set to. + +.. csv-table:: + :header: "BUILD_OPT", "" + :widths: 10,50 + + "0", "Build a debug (non-optimized) version of NSS. **This is the default.**" + "1", "Build an optimized (non-debug) version of NSS." + +.. csv-table:: + :header: "USE_64", "" + :widths: 10,50 + + "0", "Build for a 32-bit environment/ABI. **This is the default.**" + "1", "Build for a 64-bit environment/ABI. *This is recommended.*" + +.. csv-table:: + :header: "USE_ASAN", "" + :widths: 10,50 + + "0", "Do not create an `AddressSanitizer + <http://clang.llvm.org/docs/AddressSanitizer.html>`__ build. **This is the default.**" + "1", "Create an AddressSanitizer build." + + +.. _unit_testing: + +`Unit testing <#unit_testing>`__ +-------------------------------- + +.. container:: + + NSS contains extensive unit tests. Scripts to run these are found in the ``tests`` directory. + Run the standard suite by: + + .. code:: + + HOST=localhost DOMSUF=localdomain USE_64=1 ./tests/all.sh + +.. _unit_test_configuration: + +`Unit test configuration <#unit_test_configuration>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS tests are configured using environment variables. + The scripts will attempt to infer values for ``HOST`` and ``DOMSUF``, but + can fail. Replace ``localhost`` and ``localdomain`` with the hostname and + domain suffix for your host. You need to be able to connect to + ``$HOST.$DOMSUF``. + + If you don't have a domain suffix you can add an entry to ``/etc/hosts`` (on + Windows,\ ``c:\Windows\System32\drivers\etc\hosts``) as follows: + + .. code:: + + 127.0.0.1 localhost.localdomain + + Validate this opening a command shell and typing: ``ping localhost.localdomain``. + + Remove the ``USE_64=1`` override if using a 32-bit build. + +.. _test_results: + +`Test results <#test_results>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Running all tests can take a considerable amount of time. + + Test output is stored in ``tests_results/security/$HOST.$NUMBER/``. The file + ``results.html`` summarizes the results, ``output.log`` captures all the test + output. + + Other subdirectories of ``nss/tests`` contain scripts that run a subset of + the full suite. Those can be run directly instead of ``all.sh``, which might + save some time at the cost of coverage. diff --git a/security/nss/doc/rst/build_artifacts.rst b/security/nss/doc/rst/build_artifacts.rst new file mode 100644 index 0000000000..b55252512e --- /dev/null +++ b/security/nss/doc/rst/build_artifacts.rst @@ -0,0 +1,176 @@ +.. _mozilla_projects_nss_build_artifacts: + +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>`__. diff --git a/security/nss/doc/rst/community.rst b/security/nss/doc/rst/community.rst new file mode 100644 index 0000000000..02dad97509 --- /dev/null +++ b/security/nss/doc/rst/community.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_community: + +Community +--------- + +Network Security Services (NSS) is maintained by a group of engineers and researchers, +mainly RedHat and Mozilla. + +.. warning:: + + While the NSS team focuses mainly on supporting platforms and features needded by + Firefox and RHEL, we are happy to take contributions. + +Contributors can reach out the the core team and follow NSS related news through the +following mailing list, Google group and Element/Matrix channel: + +.. note:: + + Mailing list: `https://groups.google.com/a/mozilla.org/g/dev-tech-crypto <https://groups.google.com/a/mozilla.org/g/dev-tech-crypto>`__ + + Matrix/Element: `https://app.element.io/#/room/#nss:mozilla.org <https://app.element.io/#/room/#nss:mozilla.org>`__ + +.. + - 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>`__ + +.. _how_to_contribute: + +`How to Contribute <#how_to_contribute>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Start by opening a **Bugzilla** account at `bugzilla.mozilla.org <https://bugzilla.mozilla.org/>`__ if you don't have one. + + ``NSS :: Libraries`` is the component for issues you'd like to work on. + We maintain a list of `NSS bugs marked with a keyword "good-first-bug" <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:: + + See 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 <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`__ to upload patches for review. + 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. Note that we don't land code that isn't both reviewed and tested. + +.. warning:: + + Please reach out to the team before engaging in a lot of work to make ensure we are willing to accept your contributions. diff --git a/security/nss/doc/rst/getting_started.rst b/security/nss/doc/rst/getting_started.rst new file mode 100644 index 0000000000..4505f4a60b --- /dev/null +++ b/security/nss/doc/rst/getting_started.rst @@ -0,0 +1,60 @@ +.. _mozilla_projects_nss_getting_started: + +.. 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. + +Getting Started +=============== + +.. _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! + + .. note:: + + 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 `chat.mozilla.org` + in channel `#nss <https://chat.mozilla.org/#/room/#nss:mozilla.org>`__ or you could ask your + questions on the `mozilla.dev.tech.crypto <https://groups.google.com/a/mozilla.org/g/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. + + .. _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 diff --git a/security/nss/doc/rst/index.rst b/security/nss/doc/rst/index.rst new file mode 100644 index 0000000000..bfbb1fab9e --- /dev/null +++ b/security/nss/doc/rst/index.rst @@ -0,0 +1,142 @@ +.. _mozilla_projects_nss: + +Network Security Services (NSS) +=============================== + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + build.rst + build_artifacts.rst + releases/index.rst + community.rst + +.. 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. + +.. 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. + + NSS is available under the Mozilla Public License v2 (MPLv2). + + If you're a developer and would like to contribute to NSS, you might want to + read the documents: + + .. rubric:: Getting Started + :name: Getting_Started + + :ref:`mozilla_projects_nss_building` + This page contains information how to download, build and test NSS. + + :ref:`mozilla_projects_nss_releases` + This page contains information about recent releases of NSS. + + :ref:`mozilla_projects_nss_nss_releases` + This page contains information about older releases of NSS. + + :ref:`mozilla_projects_nss_community` + This page contains information about the community and how to reach out. + + +.. warning:: + References below this point are part of the deprecated documentation and will + be ported in the future. You can contribute to refreshing this documentation + by submitting changes directly in the NSS repository (``nss/doc/rst``). + + .. 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_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 + + - :ref:`NSPR` - NSPR project page. + - :ref:`NSPR API 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>`__ diff --git a/security/nss/doc/rst/legacy/an_overview_of_nss_internals/index.rst b/security/nss/doc/rst/legacy/an_overview_of_nss_internals/index.rst new file mode 100644 index 0000000000..7d705198a8 --- /dev/null +++ b/security/nss/doc/rst/legacy/an_overview_of_nss_internals/index.rst @@ -0,0 +1,302 @@ +.. _mozilla_projects_nss_an_overview_of_nss_internals: + +An overview of NSS Internals +============================ + +.. container:: + + | A High-Level Overview to the Internals of `Network Security Services + (NSS) <https://developer.mozilla.org/en-US/docs/NSS>`__ + | Software developed by the Mozilla.org projects traditionally used its own implementation of + security protocols and cryptographic algorithms, originally called Netscape Security Services, + nowadays called Network Security Services (NSS). NSS is a library written in the C programming + language. It's free and open source software, and many other software projects have decided to + use it. In order to support multiple operating systems (OS), it is based on a cross platform + portability layer, called the Netscape Portable Runtime (NSPR), which provides cross platform + application programming interfaces (APIs) for OS specific APIs like file system access, memory + management, network communication, and multithreaded programming. + | NSS offers lots of functionality; we'll walk through the list of modules, design principles, + and important relevant standards. + | In order to allow interoperability between software and devices that perform cryptographic + operations, NSS conforms to a standard called PKCS#11. (Note that it's important to look at the + number 11, as there are other PKCS standards with different numbers that define quite different + topics.) + | A software or hardware module conforming to the PKCS#11 standard implements an interface of C + calls, which allow querying the characteristics and offered services of the module. Multiple + elements of NSS's own modules have been implemented with this interface, and NSS makes use of + this interface when talking to those modules. This strategy allows NSS to work with many + hardware devices (e.g., to speed up the calculations required for cryptographic operations, or + to access smartcards that securely protect a secret key) and software modules (e.g., to allow + to load such modules as a plugin that provides additional algorithms or stores key or trust + information) that implement the PKCS#11 interface. + | A core element of NSS is FreeBL, a base library providing hash functions, big number + calculations, and cryptographic algorithms. + | Softoken is an NSS module that exposes most FreeBL functionality as a PKCS#11 module. + | Some cryptography uses the same secret key for both encrypting and decrypting, for example + password based encryption (PBE). This is often sufficient if you encrypt data for yourself, but + as soon as you need to exchange signed/encrypted data with communication partners, using public + key encryption simplifies the key management. The environment that describes how to use public + key encryption is called Public Key Infrastructure (PKI). The public keys that are exchanged + between parties are transported using a container; the container is called a certificate, + following standard X.509 version 3. A certificate contains lots of other details; for example, + it contains a signature by a third party that expresses trust in the ownership relationship for + the certificate. The trust assigned by the third party might be restricted to certain uses, + which are listed in certificate extensions that are contained in the certificate. + | Many (if not most) of the operations performed by NSS involve the use of X.509 certificates + (often abbreviated as “cert”, unfortunately making it easy to confuse with the term “computer + emergency response team“). + | When checking whether a certificate is trusted or not, it's necessary to find a relevant trust + anchor (root certificate) that represents the signing capability of a trusted third party, + usually called a Certificate Authority (CA). A trust anchor is just another X.509 certificate + that is already known and has been deliberately marked as trusted by a software vendor, + administrators inside an organizational infrastructure, or the software user. NSS ships a + predefined set of CA certificates. This set, including their trust assignments, is provided by + NSS as a software module, called CKBI (“built-in root certificates”), which also implements the + PKCS#11 interface. On an organizational level the contents of the set are managed according to + the Mozilla CA policy. On a technical level the set is a binary software module. + | A cryptographic transaction, such as encryption or decryption related to a data exchange, + usually involves working with the X.509 certs of your communication partners (peer). It's also + required that you safely keep your own secret keys that belong to your own certificates. You + might want to protect the storage of your secret keys with PBE. You might decide to modify the + default trust provided by NSS. All of this requires storing, looking up, and retrieving data. + NSS simplifies performing these operations by offering storage and management APIs. NSS doesn't + require the programmer to manage individual files containing individual certificates or keys. + Instead, NSS offers to use its own database(s). Once you have imported certificates and keys + into the NSS database, you can easily look them up and use them again. + | Because of NSS's expectation to operate with an NSS database, it's mandatory that you perform + an initialization call, where you tell NSS which database you will be using. In the most simple + scenario, the programmer will provide a directory on your filesystem as a parameter to the init + function, and NSS is designed to do the rest. It will detect and open an existing database, or + it can create a new one. Alternatively, should you decide that you don't want to work with any + persistent recording of certificates, you may initialize NSS in a no-database mode. Usually, + NSS will flush all data to disk as soon as new data has been added to permanent storage. + Storage consists of multiple files: a key database file, which contains your secret keys, and a + certificate database file which contains the public portion of your own certificates, the + certificates of peers or CAs, and a list of trust decisions (such as to not trust a built-in + CA, or to explicitly trust other CAs). Examples for the database files are key3.db and + cert8.db, where the numbers are file version numbers. A third file contains the list of + external PKCS#11 modules that have been registered to be used by NSS. The file could be named + secmod.db, but in newer database generations a file named pkcs11.txt is used. + | Only NSS is allowed to access and manipulate these database files directly; a programmer using + NSS must go through the APIs offered by NSS to manipulate the data stored in these files. The + programmer's task is to initialize NSS with the required parameters (such as a database), and + NSS will then transparently manage the database files. + | Most of the time certificates and keys are supposed to be stored in the NSS database. + Therefore, after initial import or creation, the programmer usually doesn't deal with their raw + bytes. Instead, the programmer will use lookup functions, and NSS will provide an access handle + that will be subsequently used by the application's code. Those handles are reference counted. + NSS will usually create an in-memory (RAM) presentation of certificates, once a certificate has + been received from the network, read from disk, or looked up from the database, and prepare + in-memory data structures that contain the certificate's properties, as well as providing a + handle for the programmer to use. Once the application is done with a handle, it should be + released, allowing NSS to free the associated resources. When working with handles to private + keys it's usually difficult (and undesired) that an application gets access to the raw key + data; therefore it may be difficult to extract such data from NSS. The usual minimum + requirement is that private keys must be wrapped using a protective layer (such as + password-based encryption). The intention is to make it easier to review code for security. The + less code that has access to raw secret keys, the less code that must be reviewed. + | NSS has only limited functionality to look up raw keys. The preferred approach is to use + certificates, and to look up certificates by properties such as the contained subject name + (information that describes the owner of the certificate). For example, while NSS supports + random calculation (creation) of a new public/private key pair, it's difficult to work with + such a raw key pair. The usual approach is to create a certificate signing request (CSR) as + soon as an application is done with the creation step, which will have created a handle to the + key pair, and which can be used for the necessary related operations, like producing a + proof-of-ownership of the private key, which is usually required when submitting the public key + with a CSR to a CA. The usual follow up action is receiving a signed certificate from a CA. + (However, it's also possible to use NSS functionality to create a self-signed certificate, + which, however, usually won't be trusted by other parties.) Once received, it's sufficient to + tell NSS to import such a new certificate into the NSS database, and NSS will automatically + perform a lookup of the embedded public key, be able to find the associated private key, and + subsequently be able to treat it as a personal certificate. (A personal certificate is a + certificate for which the private key is in possession, and which could be used for signing + data or for decrypting data.) A unique nickname can/should be assigned to the certificate at + the time of import, which can later be used to easily identify and retrieve it. + | It's important to note that NSS requires strict cleanup for all handles returned by NSS. The + application should always call the appropriate dereference (destroy) functions once a handle is + no longer needed. This is particularly important for applications that might need to close a + database and reinitialize NSS using a different one, without restarting. Such an operation + might fail at runtime if data elements are still being referenced. + | In addition to the FreeBL, Softoken, and CKBI modules, there is an utility library for general + operations (e.g., encoding/decoding between data formats, a list of standardized object + identifiers (OID)). NSS has an SSL/TLS module that implements the Secure Sockets + Layer/Transport Layer Security network protocols, an S/MIME module that implements CMS + messaging used by secure email and some instant messaging implementations, a DBM library that + implements the classic database storage, and finally a core NSS library for the big set of + “everything else”. Newer generations of the database use the SQLite database to allow + concurrent access by multiple applications. + | All of the above are provided as shared libraries. The CRMF library, which is used to produce + certain kinds of certificate requests, is available as a library for static linking only. + | When dealing with certificates (X.509), file formats such as PKCS#12 (certificates and keys), + PKCS#7 (signed data), and message formats as CMS, we should mention ASN.1, which is a syntax + for storing structured data in a very efficient (small sized) presentation. It was originally + developed for telecommunication systems at times where it was critical to minimize data as much + as possible (although it still makes sense to use that principle today for good performance). + In order to process data available in the ASN.1 format, the usual approach is to parse it and + transfer it to a presentation that requires more space but is easier to work with, such as + (nested) C data structures. Over the time NSS has received three different ASN.1 parser + implementations, each having their own specific properties, advantages and disadvantages, which + is why all of them are still being used (nobody has yet dared to replace the older with the + newer ones because of risks for side effects). When using the ASN.1 parser(s), a template + definition is passed to the parser, which will analyze the ASN.1 data stream accordingly. The + templates are usually closely aligned to definitions found in RFC documents. + | A data block described as DER is usually in ASN.1 format. You must know which data you are + expecting, and use the correct template for parsing, based on the context of your software's + interaction. Data described as PEM is a base64 encoded presentation of DER, usually wrapped + between human readable BEGIN/END lines. NSS prefers the binary presentation, but is often + capable to use base64 or ASCII presentations, especially when importing data from files. A + recent development adds support for loading external PEM files that contain private keys, in a + software library called nss-pem, which is separately available, but should eventually become a + core part of NSS. + | Looking at the code level, NSS deals with blocks of raw data all the time. The common structure + to store such an untyped block is SECItem, which contains a size and an untyped C pointer + variable. + | When dealing with memory, NSS makes use of arenas, which are an attempt to simplify management + with the limited offerings of C (because there are no destructors). The idea is to group + multiple memory allocations in order to simplify cleanup. Performing an operation often + involves allocating many individual data items, and the code might be required to abort a task + at many positions in the logic. An arena is requested once processing of a task starts, and all + memory allocations that are logically associated to that task are requested from the associated + arena. The implementation of arenas makes sure that all individual memory blocks are tracked. + Once a task is done, regardless whether it completed or was aborted, the programmer simply + needs to release the arena, and all individually allocated blocks will be released + automatically. Often freeing is combined with immediately erasing (zeroing, zfree) the memory + associated to the arena, in order to make it more difficult for attackers to extract keys from + a memory dump. + | NSS uses many C data structures. Often NSS has multiple implementations for the same or similar + concepts. For example, there are multiple presentations of certificates, and the NSS internals + (and sometimes even the application using NSS) might have to convert between them. + | Key responsibilites of NSS are verification of signatures and certificates. In order to verify + a digital signature, we have to look at the application data (e.g., a document that was + signed), the signature data block (the digital signature), and a public key (as found in a + certificate that is believed to be the signer, e.g., identified by metadata received together + with the signature). The signature is verified if it can be shown that the signature data block + must have been produced by the owner of the public key (because only that owner has the + associated private key). + | Verifying a certificate (A) requires some additional steps. First, you must identify the + potential signer (B) of a certificate (A). This is done by reading the “issuer name” attribute + of a certificate (A), and trying to find that issuer certificate (B) (by looking for a + certificate that uses that name as its “subject name”). Then you attempt to verify the + signature found in (A) using the public key found in (B). It might be necessary to try multiple + certificates (B1, B2, ...) each having the same subject name. + | After succeeding, it might be necessary to repeat this procedure recursively. The goal is to + eventually find a certificate B (or C or ...) that has an appropriate trust assigned (e.g., + because it can be found in the CKBI module and the user hasn't made any overriding trust + decisions, or it can be found in a NSS database file managed by the user or by the local + environment). + | After having successfully verified the signatures in a (chain of) issuer certificate(s), we're + still not done with verifying the certificate A. In a PKI it's suggested/required to perform + additional checks. For example: Certificates were valid at the time the signature was made, + name in certificates matches the expected signer (check subject name, common name, email, based + on application), the trust restrictions recorded inside the certificate (extensions) permit the + use (e.g., encryption might be allowed, but not signing), and based on environment/application + policy it might be required to perform a revocation check (OCSP or CRL), that asks the + issuer(s) of the certificates whether there have been events that made it necessary to revoke + the trust (revoke the validity of the cert). + | Trust anchors contained in the CKBI module are usually self signed, which is defined as having + identical subject name and issuer name fields. If a self-signed certificate is marked as + explicitly trusted, NSS will skip checking the self-signature for validity. + | NSS has multiple APIs to perform verification of certificates. There is a classic engine that + is very stable and works fine in all simple scenarios, for example if all (B) candidate issuer + certificates have the same subject and issuer names and differ by validity period; however, it + works only in a limited amount of more advanced scenarios. Unfortunately, the world of + certificates has become more complex in the recent past. New Certificate Authorities enter the + global PKI market, and in order to get started with their business, they might make deals with + established CAs and receive so-called cross-signing-certificates. As a result, when searching + for a trust path from (A) to a trusted anchor (root) certificate (Z), the set of candidate + issuer certificates might have different issuer names (referring to the second or higher issuer + level). As a consequence, it will be necessary to try multiple different alternative routes + while searching for (Z), in a recursive manner. Only the newer verification engine (internally + named libPKIX) is capable of doing that properly. + | It's worth mentioning the Extended Validation (EV) principle, which is an effort by software + vendors and CAs to define a stricter set of rules for issuing certificates for web site + certificates. Instead of simply verifying that the requester of a certificate is in control of + an administrative email address at the desired web site's domain, it's required that the CA + performs a verification of real world identity documents (such as a company registration + document with the country's authority), and it's also required that a browser software performs + a revocation check with the CA, prior to granting validity to the certificate. In order to + distinguish an EV certificate, CAs will embed a policy OID in the certificate, and the browser + is expected to verify that a trust chain permits the end entity (EE) certificate to make use of + the policy. Only the APIs of the newer libPKIX engine are capable of performing a policy + verification. + | That's a good opportunity to talk about SSL/TLS connections to servers in general (not just EV, + not just websites). Whenever this document mentions SSL, it refers to either SSL or TLS. (TLS + is a newer version of SSL with enhanced features.) + | When establishing an SSL connection to a server, (at least) a server certificate (and its trust + chain) is exchanged from the server to the client (e.g., the browser), and the client verifies + that the certificate can be verified (including matching the name of the expected destination + server). Another part of the handshake between both parties is a key exchange. Because public + key encryption is more expensive (more calculations required) than symmetric encryption (where + both parties use the same key), a key agreement protocol will be executed, where the public and + private keys are used to proof and verify the exchanged initial information. Once the key + agreement is done, a symmetric encryption will be used (until a potential re-handshake on an + existing channel). The combination of the hash and encryption algorithms used for a SSL + connection is called a cipher suite. + | NSS ships with a set of cipher suites that it supports at a technical level. In addition, NSS + ships with a default policy that defines which cipher suites are enabled by default. An + application is able to modify the policy used at program runtime, by using function calls to + modify the set of enabled cipher suites. + | If a programmer wants to influence how NSS verifies certificates or how NSS verifies the data + presented in a SSL connection handshake, it is possible to register application-defined + callback functions which will be called by NSS at the appropriate point of time, and which can + be used to override the decisions made by NSS. + | If you would like to use NSS as a toolkit that implements SSL, remember that you must init NSS + first. But if you don't care about modifying the default trust permanently (recorded on disk), + you can use the no-database init calls. When creating the network socket for data exchange, + note that you must use the operating system independent APIs provided by NSPR and NSS. It might + be interesting to mention a property of the NSPR file descriptors, which are stacked in layers. + This means you can define multiple layers that are involved in data processing. A file + descriptor has a pointer to the first layer handling the data. That layer has a pointer to a + potential second layer, which might have another pointer to a third layer, etc. Each layer + defines its own functions for the open/close/read/write/poll/select (etc.) functions. When + using an SSL network connection, you'll already have two layers, the basic NSPR layer and an + SSL library layer. The Mozilla applications define a third layer where application specific + processing is performed. You can find more details in the NSPR reference documents. + | NSS occassionally has to create outbound network connections, in addition to the connections + requested by the application. Examples are retrieving OCSP (Online Certificate Status Protocol) + information or downloading a CRL (Certificate Revocation List). However, NSS doesn't have an + implementation to work with network proxies. If you must support proxies in your application, + you are able to register your own implementation of an http request callback interface, and NSS + can use your application code that supports proxies. + | When using hashing, encryption, and decryption functions, it is possible to stream data (as + opposed to operating on a large buffer). Create a context handle while providing all the + parameters required for the operation, then call an “update” function multiple times to pass + subsets of the input to NSS. The data will be processed and either returned directly or sent to + a callback function registered in the context. When done, you call a finalization function that + will flush out any pending data and free the resources. + | This line is a placeholder for future sections that should explain how libpkix works and is + designed. + | If you want to work with NSS, it's often helpful to use the command line utilities that are + provided by the NSS developers. There are tools for managing NSS databases, for dumping or + verifying certificates, for registering PKCS#11 modules with a database, for processing CMS + encrypted/signed messages, etc. + | For example, if you wanted to create your own pair of keys and request a new certificate from a + CA, you could use certutil to create an empty database, then use certutil to operate on your + database and create a certificate request (which involves creating the desired key pair) and + export it to a file, submit the request file to the CA, receive the file from the CA, and + import the certificate into your database. You should assign a good nickname to a certificate + when importing it, making it easier for you to refer to it later. + | It should be noted that the first database format that can be accessed simultaneously by + multiple applications is key4.db/cert9.db – database files with lower numbers will most likely + experience unrecoverable corruption if you access them with multiple applications at the same + time. In other words, if your browser or your server operates on an older NSS database format, + don't use the NSS tools to operate on it while the other software is executing. At the time of + writing NSS and the Mozilla applications still use the older database file format by default, + where each application has its own NSS database. + | If you require a copy of a certificate stored in an NSS database, including its private key, + you can use pk12util to export it to the PKCS#12 file format. If you require it in PEM format, + you could use the openssl pkcs12 command (that's not NSS) to convert the PKCS#12 file to PEM. + | This line is a placeholder for how to prepare a database, how to dump a cert, and how to + convert data. + | You might have been motivated to work with NSS because it is used by the Mozilla applications + such as Firefox, Thunderbird, etc. If you build the Mozilla application, it will automatically + build the NSS library, too. However, if you want to work with the NSS command line tools, you + will have to follow the standalone NSS build instructions, and build NSS outside of the Mozilla + application sources. + | The key database file will contain at least one symmetric key, which NSS will automatically + create on demand, and which will be used to protect your secret (private) keys. The symmetric + key can be protected with PBE by setting a master password on the database. As soon as you set + a master password, an attacker stealing your key database will no longer be able to get access + to your private key, unless the attacker would also succeed in stealing the master password. + | Now you might be interest in how to get the + :ref:`mozilla_projects_nss_nss_sources_building_testing`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/blank_function/index.rst b/security/nss/doc/rst/legacy/blank_function/index.rst new file mode 100644 index 0000000000..5541bf1a69 --- /dev/null +++ b/security/nss/doc/rst/legacy/blank_function/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_blank_function: + +Function_Name +============= + +.. container:: + + One-line description of what the function does (more than just what it returns). + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <headers.h> + ReturnType Function_Name( + + ParamType ParamName, + ParamType ParamName, ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +---------------+---------------------------------------------------------------------------------+ + | ``ParamName`` | Sample: *in* pointer to a `CERTCertDBHandle </en-US/NSS/CERTCertDBHandle>`__ | + | | representing the certificate database to look in | + +---------------+---------------------------------------------------------------------------------+ + | ``ParamName`` | Sample: *in* pointer to an `SECItem </en-US/NSS/SECItem>`__ whose ``type`` must | + | | be ``siDERCertBuffer`` and whose ``data`` contains a DER-encoded certificate | + +---------------+---------------------------------------------------------------------------------+ + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Long description of this function, what it does, and why you would use it. Describe all + side-effects on "out" parameters. Avoid describing the return until the next section, for + example: + + This function looks in the NSSCryptoContext and the NSSTrustDomain to find the certificate that + matches the DER-encoded certificate. A match is found when the issuer and serial number of the + DER-encoded certificate are found on a certificate in the certificate database. + +`Returns <#returns>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Full description of the return value, for example: + + A pointer to a `CERTCertificate </en-US/NSS/CERTCertificate>`__ representing the certificate in + the database that matched the ``derCert``, or ``NULL`` if none was found. The certificate is a + shallow copy, use `CERT_DestroyCertificate </en-US/NSS/CERT_DestroyCertificate>`__ to decrement + the reference count on the certificate instance. + +.. _see_also: + +`See Also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Copy of the MXR link, with the following text + + Occurrences of ``Function_Name`` in the current NSS source code (generated by MXR).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/building/index.rst b/security/nss/doc/rst/legacy/building/index.rst new file mode 100644 index 0000000000..153166e904 --- /dev/null +++ b/security/nss/doc/rst/legacy/building/index.rst @@ -0,0 +1,159 @@ +.. _mozilla_projects_nss_building_ported: + +Building NSS +============ + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + This page has detailed information on how to build NSS. Because NSS is a cross-platform library + that builds on many different platforms and has many options, it may be complex to build. Please + read these instructions carefully before attempting to build. + +.. _build_environment: + +`Build environment <#build_environment>`__ +------------------------------------------ + +.. container:: + + NSS needs a C and C++ compiler. It has minimal dependencies, including only standard C and C++ + libraries, plus `zlib <https://www.zlib.net/>`__. + + For building, you also need `make <https://www.gnu.org/software/make/>`__. Ideally, also install + `gyp <https://gyp.gsrc.io/>`__ and `ninja <https://ninja-build.org/>`__ and put them on your + path. This is recommended, as the build is faster and more reliable. + +`Windows <#windows>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS compilation on Windows uses the same shared build system as Mozilla Firefox. You must first + install the `Windows + Prerequisites <https://firefox-source-docs.mozilla.org/setup/windows_build.html>`__, + including **MozillaBuild**. + + You can also build NSS on the Windows Subsystem for Linux, but the resulting binaries aren't + usable by other Windows applications. + +.. _get_the_source: + +`Get the source <#get_the_source>`__ +------------------------------------ + +.. container:: + + NSS and NSPR use Mercurial for source control like other Mozilla projects. To check out the + latest sources for NSS and NSPR--which may not be part of a stable release--use the following + commands: + + .. code:: + + hg clone https://hg.mozilla.org/projects/nspr + hg clone https://hg.mozilla.org/projects/nss + + To get the source of a specific release, see :ref:`mozilla_projects_nss_nss_releases`. + +`Build <#build>`__ +------------------ + +.. container:: + + Build NSS using our build script: + + .. code:: + + nss/build.sh + + This builds both NSPR and NSS. + +.. _build_with_make: + +`Build with make <#build_with_make>`__ +-------------------------------------- + +.. container:: + + Alternatively, there is a ``make`` target called "nss_build_all", which produces a similar + result. This supports some alternative options, but can be a lot slower. + + .. code:: + + make -C nss nss_build_all USE_64=1 + + The make-based build system for NSS uses a variety of variables to control the build. Below are + some of the variables, along with possible values they may be set to. + + BUILD_OPT + 0 + Build a debug (non-optimized) version of NSS. *This is the default.* + 1 + Build an optimized (non-debug) version of NSS. + + USE_64 + 0 + Build for a 32-bit environment/ABI. *This is the default.* + 1 + Build for a 64-bit environment/ABI. *This is recommended.* + + USE_ASAN + 0 + Do not create an `AddressSanitizer <http://clang.llvm.org/docs/AddressSanitizer.html>`__ + build. *This is the default.* + 1 + Create an AddressSanitizer build. + +.. _unit_testing: + +`Unit testing <#unit_testing>`__ +-------------------------------- + +.. container:: + + NSS contains extensive unit tests. Scripts to run these are found in the ``tests`` directory. + Run the standard suite by: + + .. code:: + + HOST=localhost DOMSUF=localdomain USE_64=1 nss/tests/all.sh + +.. _unit_test_configuration: + +`Unit test configuration <#unit_test_configuration>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | NSS tests are configured using environment variables. + | The scripts will attempt to infer values for ``HOST`` and ``DOMSUF``, but can fail. Replace + ``localhost`` and ``localdomain`` with the hostname and domain suffix for your host. You need + to be able to connect to ``$HOST.$DOMSUF``. + + If you don't have a domain suffix you can add an entry to ``/etc/hosts`` (on + Windows,\ ``c:\Windows\System32\drivers\etc\hosts``) as follows: + + .. code:: + + 127.0.0.1 localhost.localdomain + + Validate this opening a command shell and typing: ``ping localhost.localdomain``. + + Remove the ``USE_64=1`` override if using a 32-bit build. + +.. _test_results: + +`Test results <#test_results>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Running all tests can take a considerable amount of time. + + Test output is stored in ``tests_results/security/$HOST.$NUMBER/``. The file ``results.html`` + summarizes the results, ``output.log`` captures all the test output. + + Other subdirectories of ``nss/tests`` contain scripts that run a subset of the full suite. Those + can be run directly instead of ``all.sh``, which might save some time at the cost of coverage. diff --git a/security/nss/doc/rst/legacy/cert_findcertbydercert/index.rst b/security/nss/doc/rst/legacy/cert_findcertbydercert/index.rst new file mode 100644 index 0000000000..7e297a2df5 --- /dev/null +++ b/security/nss/doc/rst/legacy/cert_findcertbydercert/index.rst @@ -0,0 +1,64 @@ +.. _mozilla_projects_nss_cert_findcertbydercert: + +CERT_FindCertByDERCert +====================== + +.. container:: + + Find a certificate in the database that matches a DER-encoded certificate. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <cert.h> + CERTCertificate *CERT_FindCertByDERCert( + + CERTCertDBHandle *handle, + SECItem *derCert ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------+-----------------------------------------------------------------------------------+ + | ``handle`` | *in* pointer to a `CERTCertDBHandle </en-US/NSS/CERTCertDBHandle>`__ representing | + | | the certificate database to look in | + +-------------+-----------------------------------------------------------------------------------+ + | ``derCert`` | *in* pointer to an `SECItem </en-US/NSS/SECItem>`__ whose ``type`` must be | + | | ``siDERCertBuffer`` and whose ``data`` contains a DER-encoded certificate | + +-------------+-----------------------------------------------------------------------------------+ + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This function looks in the ?NSSCryptoContext? and the ?NSSTrustDomain? to find the certificate + that matches the DER-encoded certificate. A match is found when the issuer and serial number of + the DER-encoded certificate are found on a certificate in the certificate database. + +`Returns <#returns>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A pointer to a `CERTCertificate </en-US/NSS/CERTCertificate>`__ representing the certificate in + the database that matched the ``derCert``, or ``NULL`` if none was found. The certificate is a + shallow copy, use `CERT_DestroyCertificate </en-US/NSS/CERT_DestroyCertificate>`__ to decrement + the reference count on the certificate instance. + +.. _see_also: + +`See Also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Occurrences of + ```CERT_FindCertByDERCert`` <http://lxr.mozilla.org/security/ident?i=CERT_FindCertByDERCert>`__ + in the current NSS source code (generated by `LXR <http://lxr.mozilla.org/security/>`__).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/cert_findcertbyissuerandsn/index.rst b/security/nss/doc/rst/legacy/cert_findcertbyissuerandsn/index.rst new file mode 100644 index 0000000000..933fff206c --- /dev/null +++ b/security/nss/doc/rst/legacy/cert_findcertbyissuerandsn/index.rst @@ -0,0 +1,82 @@ +.. _mozilla_projects_nss_cert_findcertbyissuerandsn: + +CERT_FindCertByIssuerAndSN +========================== + +.. container:: + + Find a certificate in the database with the given issuer and serial number. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <cert.h> + CERTCertificate *CERT_FindCertByIssuerAndSN ( + + CERTCertDBHandle *handle, + CERTIssuerAndSN *issuerAndSN ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-----------------+-------------------------------------------------------------------------------+ + | ``handle`` | *in* pointer to a `CERTCertDBHandle </en-US/NSS/CERTCertDBHandle>`__ | + | | representing the certificate database to look in | + +-----------------+-------------------------------------------------------------------------------+ + | ``issuerAndSN`` | *in* pointer to a `CERTIssuerAndSN </en-US/NSS/CERTIssuerAndSN>`__ that must | + | | be properly formed to contain the issuer name and the serial number (see | + | | [Example]) | + +-----------------+-------------------------------------------------------------------------------+ + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This function creates a certificate key using the ``issuerAndSN`` and it then uses the key to + find the matching certificate in the database. + +`Returns <#returns>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A pointer to a `CERTCertificate </en-US/NSS/CERTCertificate>`__ representing the certificate in + the database that matched the issuer and serial number, or ``NULL`` if none was found. The + certificate is a shallow copy, use + `CERT_DestroyCertificate </en-US/NSS/CERT_DestroyCertificate>`__ to decrement the reference count + on the certificate instance. + +`Example <#example>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CERTIssuerAndSN issuerSN; + issuerSN.derIssuer.data = caName->data; + issuerSN.derIssuer.len = caName->len; + issuerSN.serialNumber.data = authorityKeyID->authCertSerialNumber.data; + issuerSN.serialNumber.len = authorityKeyID->authCertSerialNumber.len; + issuerCert = CERT_FindCertByIssuerAndSN(cert->dbhandle, &issuerSN); + if ( issuerCert == NULL ) { + PORT_SetError (SEC_ERROR_UNKNOWN_ISSUER); + } + +.. _see_also: + +`See Also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Occurrences of + ```CERT_FindCertByIssuerAndSN`` <http://lxr.mozilla.org/security/ident?i=CERT_FindCertByIssuerAndSN>`__ + in the current NSS source code (generated by `LXR <http://lxr.mozilla.org/security/>`__).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/certificate_download_specification/index.rst b/security/nss/doc/rst/legacy/certificate_download_specification/index.rst new file mode 100644 index 0000000000..5fe98aa6b9 --- /dev/null +++ b/security/nss/doc/rst/legacy/certificate_download_specification/index.rst @@ -0,0 +1,186 @@ +.. _mozilla_projects_nss_certificate_download_specification: + +NSS Certificate Download Specification +====================================== + +.. container:: + + This document describes the data formats used by NSS 3.x for installing certificates. This + document is currently being revised and has not yet been reviewed for accuracy. + +.. _data_formats: + +`Data Formats <#data_formats>`__ +-------------------------------- + +.. container:: + + NSS can accept certificates in several formats. In all cases the certificates are X509 version 1, + 2, or 3. + +.. _binary_formats: + +`Binary Formats <#binary_formats>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS's certificate loader will recognize several binary formats. They are: + + - **DER encoded certificate:** This is a single binary DER encoded certificate. + - **PKCS#7 certificate chain:** This is a single + `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ ``SignedData`` object. The only + significant field in the ``SignedData`` object is the ``certificates`` field, which may + contain multiple certificates to be imported together. The contents of the ``version``, + ``digestAlgorithms``, ``contentInfo``, ``crls``, and ``signerInfos`` fields are ignored. + - **Netscape Certificate Sequence:** This is another + `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ object format, and like the + ``SignedData`` format, it allows multiple certificates to be imported together. This format is + simpler than the `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ ``SignedData`` + object format. It consists of a `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ + ``ContentInfo`` structure, wrapping a sequence of certificates. The ``contentType`` field OID + must be ``netscape-cert-sequence`` (see + :ref:`mozilla_projects_nss_certificate_download_specification#object_identifiers`). The + ``content`` field is the following ASN.1 structure: + + .. code:: + + CertificateSequence ::= SEQUENCE OF Certificate + + See the section below on + :ref:`mozilla_projects_nss_certificate_download_specification#importing_certificate_chains` for + more information about how multiple certificates are handled. + +.. _text_formats: + +`Text Formats <#text_formats>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Any of the above :ref:`mozilla_projects_nss_certificate_download_specification#binary_formats` + can also be imported in text form. The text form begins with the following line: + + .. code:: + + -----BEGIN CERTIFICATE----- + + Following this line should be the certificate data, which can be in any of the + :ref:`mozilla_projects_nss_certificate_download_specification#binary_formats` described above. + This data must be base64 encoded as described by `RFC + 1113 <https://datatracker.ietf.org/doc/html/rfc1113>`__. Following the data should be the + following line: + + .. code:: + + -----END CERTIFICATE----- + + In a text format download, NSS ignores any text before the first ``BEGIN CERTIFICATE`` line, and + ignores any text after the first ``END CERTIFICATE`` line. Between those two lines, there must be + exactly ONE item of any of the supported binary formats described above, and that one item must + be base64 encoded. Regardless of which of the supported binary formats is used, the ``BEGIN`` and + ``END`` lines must say ``CERTIFICATE``, and not any other word (such as ``KEY``). The ``BEGIN`` + and ``END`` lines must begin and end with 5 dashes, with no extra leading or trailing white space + (excluding the End Of Line characters). + +.. _importing_certificate_chains: + +`Importing Certificate Chains <#importing_certificate_chains>`__ +---------------------------------------------------------------- + +.. container:: + + Several of the formats described above can contain several certificates. When NSS's certificate + decoder encounters one of these collections of multiple certificates they are handled in the + following way: + + - The first certificate is processed in a context specific manner, depending upon how it is + being imported. For Mozilla browsers, this handling will depend upon the mime ``Content-Type`` + that is used on the object being downloaded. For NSS-based servers it will depend upon the + options selected in the server's administration interface. + + - Subsequent certificates are all treated the same. If the certificates contain a + ``BasicConstraints`` certificate extension that indicates they are CA certificates, and do not + already exist in the local certificate database, they are added as untrusted CAs. In this way + they may be used for certificate chain validation, as long as there is a trusted CA somewhere + along the chain. + +.. _importing_certificates_into_mozilla_browsers: + +`Importing Certificates into Mozilla browsers <#importing_certificates_into_mozilla_browsers>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Mozilla browsers import certificates found in HTTP protocol responses. There are several mime + content types that are used to indicate to the browser what type of certificate is being + imported. These mime types are: + + - **``application/x-x509-user-cert``** The certificate being downloaded is a user certificate + belonging to the user operating the browser. If the private key associated with the + certificate does not exist in the user's local key database, then an error dialog is generated + and the certificate is not imported. If a certificate chain is being imported then the first + certificate in the chain must be the user certificate, and any subsequent certificates will be + added as untrusted CA certificates to the local database. + - **``application/x-x509-ca-cert``** The certificate being downloaded represents a Certificate + Authority. When it is downloaded the user will be shown a sequence of dialogs that will guide + them through the process of accepting the Certificate Authority and deciding if they wish to + trust sites certified by the CA. If a certificate chain is being imported then the first + certificate in the chain must be the CA certificate, and any subsequent certificates will be + added as untrusted CA certificates to the local database. + - **``application/x-x509-email-cert``** The certificate being downloaded is a user certificate + belonging to another user for use with S/MIME. If a certificate chain is being imported then + the first certificate in the chain must be the user certificate, and any subsequent + certificates will be added as untrusted CA certificates to the local database. This is + intended to allow people or CAs to post their e-mail certificates on web pages for download by + other users who want to send them encrypted mail. + + Note: the browser checks that the size of the object being downloaded matches the size of the + encoded certificates. Therefore it is important to ensure that no extra characters, such as NULLs + or LineFeeds are added at the end of the object. + +.. _importing_certificates_into_nss-based_servers: + +`Importing Certificates into NSS-based servers <#importing_certificates_into_nss-based_servers>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Consult your server's administration guide for the most accurate information. For some NSS-base + servers, the following information is correct. + + Server certificates are imported via the server admin interface. Certificates are pasted into a + text input field in an HTML form, and then the form is submitted to the admin server. Since the + certificates are pasted into text fields, only the + :ref:`mozilla_projects_nss_certificate_download_specification#text_formats` described above are + supported for servers. The type of certificate being imported (e.g. server or CA or cert chain) + is specified by the server administrator by selections made on the admin pages. If a certificate + chain is being imported then the first certificate in the chain must be the server or CA + certificate, and any subsequent certificates will be added as untrusted CA certificates to the + local database. + +.. _object_identifiers: + +`Object Identifiers <#object_identifiers>`__ +-------------------------------------------- + +.. container:: + + The base of all Netscape object ids is: + + .. code:: + + netscape OBJECT IDENTIFIER ::= { 2 16 840 1 113730 } + + The hexadecimal byte value of this OID when DER encoded is: + + .. code:: + + 0x60, 0x86, 0x48, 0x01, 0x86, 0xf8, 0x42 + + The following OIDs are mentioned in this document: + + .. code:: + + netscape-data-type OBJECT IDENTIFIER :: = { netscape 2 } + netscape-cert-sequence OBJECT IDENTIFIER :: = { netscape-data-type 5 }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/certificate_functions/index.rst b/security/nss/doc/rst/legacy/certificate_functions/index.rst new file mode 100644 index 0000000000..c1fc801c58 --- /dev/null +++ b/security/nss/doc/rst/legacy/certificate_functions/index.rst @@ -0,0 +1,410 @@ +.. _mozilla_projects_nss_certificate_functions: + +Certificate functions +===================== + +.. container:: + + The public functions listed here are used to interact with certificate databases. + + If documentation is available for a function listed below, the function name is linked to either + its MDC wiki page or its entry in the + :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference`. The `Mozilla Cross + Reference <http://mxr.mozilla.org/>`__ (MXR) link for each function provides access to the + function definition, prototype definition, and source code references. The NSS version column + indicates which versions of NSS support the function. + + +-----------------------------------------+-------------+-----------------------------------------+ + | Function name/documentation | Source code | NSS versions | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_AddCertToListTail`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_AddExtension`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_AddOCSPAcceptableResponses`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_AddOKDomainName`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_AddRDN`` | MXR | 3.2.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_AsciiToName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CacheCRL`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_ClearOCSPCache`` | MXR | 3.11.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CertChainFromCert`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CertListFromCert`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CertTimesValid`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_ChangeCertTrust`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1056662` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CheckNameSpace`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CheckCertUsage`` | MXR | 3.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CompareName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CompareValidityTimes`` | MXR | 3.11 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CompleteCRLDecodeEntries`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_ConvertAndDecodeCertificate`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CopyName`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CopyRDN`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateAVA`` | MXR | 3.2.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateCertificate`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateCertificateRequest`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateName`` | MXR | 3.2.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateOCSPCertID`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateOCSPRequest`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateRDN`` | MXR | 3.2.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateSubjectCertList`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CreateValidity`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_CRLCacheRefreshIssuer`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeAltNameExtension`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeAuthInfoAccessExtension`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeAuthKeyID`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeAVAValue`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeBasicConstraintValue`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeCertFromPackage`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CE | MXR | 3.2 and later | + | RT_DecodeCertificatePoliciesExtension`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeCertPackage`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeCRLDistributionPoints`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeDERCrl`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeDERCrlWithFlags`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeGeneralName`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeNameConstraintsExtension`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeOCSPResponse`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeOidSequence`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``C | MXR | 3.10 and later | + | ERT_DecodePrivKeyUsagePeriodExtension`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeTrustString`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DecodeUserNotice`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DerNameToAscii`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyCertArray`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1050532` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyCertificateList`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CER | MXR | 3.2 and later | + | T_DestroyCertificatePoliciesExtension`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyCertificateRequest`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyCertList`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyOCSPCertID`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyOCSPRequest`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyOCSPResponse`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyOidSequence`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyUserNotice`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DestroyValidity`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1058344` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_DupCertList`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EnableOCSPChecking`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeAltNameExtension`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeAndAddBitStrExtension`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeAuthKeyID`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeBasicConstraintValue`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeCertPoliciesExtension`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeCRLDistributionPoints`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeGeneralName`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeInfoAccessExtension`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeInhibitAnyExtension`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeNoticeReference`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeOCSPRequest`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | `` | MXR | 3.12 and later | + | CERT_EncodePolicyConstraintsExtension`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodePolicyMappingExtension`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeSubjectKeyID`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_EncodeUserNotice`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_ExtractPublicKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCertByName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCRLEntryReasonExten`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCRLNumberExten`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindNameConstraintsExten`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FilterCertListByCANames`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FilterCertListByUsage`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FilterCertListForUserCerts`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozil | MXR | 3.2 and later | + | la_projects_nss_cert_findcertbydercert` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_p | MXR | 3.2 and later | + | rojects_nss_cert_findcertbyissuerandsn` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCertByNickname`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCertByNicknameOrEmailAddr`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCertBySubjectKeyID`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCertExtension`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindCertIssuer`` | MXR | 3.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindKeyUsageExtension`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindSMimeProfile`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindSubjectKeyIDExtension`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindUserCertByUsage`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FindUserCertsByUsage`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CE | MXR | 3.10 and later | + | RT_FinishCertificateRequestAttributes`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FinishExtensions`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FormatName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_FreeDistNames`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1050349` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetAVATag`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCertChainFromCert`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCertEmailAddress`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCertificateNames`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ` | MXR | 3.10 and later | + | `CERT_GetCertificateRequestExtensions`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCertIssuerAndSN`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1050346` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCertTrust`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCertUid`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetClassicOCSPDisabledPolicy`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_G | MXR | 3.12 and later | + | etClassicOCSPEnabledHardFailurePolicy`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_G | MXR | 3.12 and later | + | etClassicOCSPEnabledSoftFailurePolicy`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCommonName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetCountryName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetDBContentVersion`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1052308` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetDomainComponentName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetFirstEmailAddress`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetLocalityName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetNextEmailAddress`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetNextGeneralName`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetNextNameConstraint`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetOCSPResponseStatus`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetOCSPStatusForCertID`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetOidString`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetOrgName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetOrgUnitName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CE | MXR | 3.4 and later | + | RT_GetOCSPAuthorityInfoAccessLocation`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``C | MXR | 3.12 and later | + | ERT_GetPKIXVerifyNistRevocationPolicy`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetPrevGeneralName`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetPrevNameConstraint`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetSlopTime`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetSSLCACerts`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetStateName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetUsePKIXForValidation`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GetValidDNSPatternsFromCert`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_GenTime2FormattedAscii`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_Hexify`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_ImportCAChain`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_ImportCerts`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_IsRootDERCert`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_IsUserCert`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_KeyFromDERCrl`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_MakeCANickname`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_MergeExtensions`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_NameToAscii`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_NewCertList`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_NewTempCertificate`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_NicknameStringsFromCertList`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_OpenCertDBFilename`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_OCSPCacheSettings`` | MXR | 3.11.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_PKIXVerifyCert`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_RemoveCertListNode`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_RFC1485_EscapeAndQuote`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_SaveSMimeProfile`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_SetSlopTime`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_SetOCSPFailureMode`` | MXR | 3.11.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_SetOCSPTimeout`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_SetUsePKIXForValidation`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_StartCertExtensions`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``C | MXR | 3.10 and later | + | ERT_StartCertificateRequestAttributes`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_StartCRLEntryExtensions`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_StartCRLExtensions`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_UncacheCRL`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1050342` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_VerifyCACertForUsage`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_VerifyCert`` | MXR | 3.2 and later. If you need to verify | + | | | for multiple usages use | + | | | CERT_VerifyCertificate | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_VerifyCertificate`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_VerifyCertificateNow`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later. If you need to verify | + | jects_nss_ssl_functions_sslcrt#1058011` | | for multiple usages use | + | | | CERT_VerifyCertificateNow | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_VerifyOCSPResponseSignature`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_VerifySignedData`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``CERT_VerifySignedDataWithPublicKey`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``C | MXR | 3.7 and later | + | ERT_VerifySignedDataWithPublicKeyInfo`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1056760` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1056950` | | | + +-----------------------------------------+-------------+-----------------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/certverify_log/index.rst b/security/nss/doc/rst/legacy/certverify_log/index.rst new file mode 100644 index 0000000000..7c1288e0a4 --- /dev/null +++ b/security/nss/doc/rst/legacy/certverify_log/index.rst @@ -0,0 +1,55 @@ +.. _mozilla_projects_nss_certverify_log: + +NSS CERTVerify Log +================== + +`CERTVerifyLog <#certverifylog>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + All the NSS verify functions except, the \*VerifyNow() functions, take a parameter called + 'CERTVerifyLog'. If you supply the log parameter, NSS will continue chain validation after each + error . The log tells you what the problem was with the chain and what certificate in the chain + failed. + + To create a log: + + .. code:: + + #include "secport.h" + #include "certt.h" + + CERTVerifyLog *log; + + arena = PORT_NewArena(512); + log = PORT_ArenaZNew(arena,log); + log->arena = arena; + + You can then pass this log into your favorite cert verify function. On return: + + - log->count is the number of entries. + - log->head is the first entry; + - log->tail is the last entry. + + Each entry is a CERTVerifyLogNode. Defined in certt.h: + + .. code:: + + /* + * This structure is used to keep a log of errors when verifying + * a cert chain. This allows multiple errors to be reported all at + * once. + */ + struct CERTVerifyLogNodeStr { + CERTCertificate *cert; /* what cert had the error */ + long error; /* what error was it? */ + unsigned int depth; /* how far up the chain are we */ + void *arg; /* error specific argument */ + struct CERTVerifyLogNodeStr *next; /* next in the list */ + struct CERTVerifyLogNodeStr *prev; /* next in the list */ + }; + + The list is a doubly linked NULL terminated list sorted from low to high based on depth into the + cert chain. When you are through, you will need to walk the list and free all the cert entries, + then free the arena.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/code_coverage/index.rst b/security/nss/doc/rst/legacy/code_coverage/index.rst new file mode 100644 index 0000000000..1bafb3f6c1 --- /dev/null +++ b/security/nss/doc/rst/legacy/code_coverage/index.rst @@ -0,0 +1,73 @@ +.. _mozilla_projects_nss_code_coverage: + +NSS Code Coverage +================= + +.. _nss_-_code_coverage: + +`NSS - Code Coverage <#nss_-_code_coverage>`__ +---------------------------------------------- + +.. _results_link: + +`Results link <#results_link>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `2007-08-14 - Solaris/Sparc + platform <ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/coverage/20070814-sparc/nss.html>`__ + +.. _results_explanation: + +`Results explanation <#results_explanation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Files + :name: files + + - Results from every C file are on new line. + - If file was tested, link points to annotated source file (in TCOV directory), otherwise to + original source file (CVS directory). + + .. rubric:: Colors + :name: colors + + - Green: 70-100% of blocks tested. + - Yellow: 40-70% of blocks tested. + - Orange: 0-40% of blocks tested. + - Red: file not tested. File is not part of any binary or library used by test suite. + + .. rubric:: Numbers in tested files + :name: numbers_in_tested_files + + - Example: 72.69% (165/227/731) + + - 72.69% - ratio of tested blocks and total blocks in file (generated by TCOV). + - 165 - tested blocks in file (generated by TCOV). + - 227 - total blocks in file (generated by TCOV). + - 31 - total lines in file (by wc -l command). + + .. rubric:: Numbers in not tested files + :name: numbers_in_not_tested_files + + - Example: Not tested (0/?/878). + + - 0 - tested blocks in file (always 0). + - ? - total blocks in file (there is no trivial method to get this number without TCOV). + - 878 - total lines in file (by wc -l command). + + .. rubric:: Numbers in total count + :name: numbers_in_total_count + + - Example: Total: 42% (574/1351). + + - 42% - ratio of tested blocks and total blocks in file. + - 165 - tested blocks in all files in directory (sum of numbers generated by TCOV). + - 227 - total blocks in all files in directory (sum of numbers generated by TCOV). + + - These numbers doesn't count blocks in files which are not tested (marked with red color), + because we don't know number of blocks there. + - Total count at the end of report counts blocks in all tested files in all directories.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/cryptography_functions/index.rst b/security/nss/doc/rst/legacy/cryptography_functions/index.rst new file mode 100644 index 0000000000..ca3fb8601a --- /dev/null +++ b/security/nss/doc/rst/legacy/cryptography_functions/index.rst @@ -0,0 +1,500 @@ +.. _mozilla_projects_nss_cryptography_functions: + +Cryptography functions +====================== + +.. container:: + + The public functions listed here perform cryptographic operations based on the PKCS #11 + interface. + + If documentation is available for a function listed below, the function name is linked to either + its MDC wiki page or its entry in the + :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference`. The `Mozilla Cross + Reference <http://mxr.mozilla.org/>`__ (MXR) link for each function provides access to the + function definition, prototype definition, and source code references. The NSS version column + indicates which versions of NSS support the function. + + +-----------------------------------------+-------------+-----------------------------------------+ + | Function name/documentation | Source code | NSS versions | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_AlgtagToMechanism`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_Authenticate`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_BlockData`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ChangePW`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CheckUserPassword`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CipherOp`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CloneContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ConfigurePKCS11`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK1 | MXR | 3.6 and later | + | 1_ConvertSessionPrivKeyToTokenPrivKey`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``P | MXR | 3.6 and later | + | K11_ConvertSessionSymKeyToTokenSymKey`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | `` | MXR | 3.11 and later | + | PK11_CopyTokenPrivKeyToSessionPrivKey`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CreateContextBySymKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CreateDigestContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CreateGenericObject`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CreateMergeLog`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CreatePBEAlgorithmID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_CreatePBEV2AlgorithmID`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DeleteTokenPrivateKey`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DeleteTokenPublicKey`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DeleteTokenSymKey`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_Derive`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DeriveWithFlags`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DeriveWithFlagsPerm`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DestroyContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DestroyGenericObject`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DestroyGenericObjects`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DestroyMergeLog`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DestroyObject`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DestroyTokenObject`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DigestBegin`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DigestKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DigestOp`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DigestFinal`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_DoesMechanism`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ExportEncryptedPrivateKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ExportEncryptedPrivKeyInfo`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ExportPrivateKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_Finalize`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindBestKEAMatch`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindCertAndKeyByRecipientList`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | `` | MXR | 3.2 and later | + | PK11_FindCertAndKeyByRecipientListNew`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindCertByIssuerAndSN`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindCertFromDERCert`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pr | MXR | 3.2 and later | + | ojects_nss_ssl_functions_pkfnc#1035673` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindCertInSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindGenericObjects`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindFixedKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pr | MXR | 3.2 and later | + | ojects_nss_ssl_functions_pkfnc#1026891` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindKeyByDERCert`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindPrivateKeyFromCert`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindSlotByName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FindSlotsByNames`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FortezzaHasKEA`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FortezzaMapSig`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FreeSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FreeSlotList`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FreeSlotListElement`` | MXR | 3.11 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_FreeSymKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GenerateFortezzaIV`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GenerateKeyPair`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GenerateKeyPairWithFlags`` | MXR | 3.10.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GenerateKeyPairWithOpFlags`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GenerateNewParam`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GenerateRandom`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GenerateRandomOnSlot`` | MXR | 3.11 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetAllTokens`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetAllSlotsForCert`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetBestKeyLength`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetBestSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetBestSlotMultiple`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetBestWrapMechanism`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetBlockSize`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetCertFromPrivateKey`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetCurrentWrapIndex`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetDefaultArray`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetDefaultFlags`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetDisabledReason`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetFirstSafe`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetInternalKeySlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetInternalSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetKeyGen`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetKeyLength`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetKeyStrength`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetMechanism`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetMinimumPwdLength`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetModInfo`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetModule`` | MXR | 3.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetModuleID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetNextGenericObject`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetNextSafe`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetNextSymKey`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPadMechanism`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPBECryptoMechanism`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPBEIV`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPQGParamsFromPrivateKey`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPrevGenericObject`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPrivateKeyNickname`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPrivateModulusLen`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetPublicKeyNickname`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSlotFromKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSlotFromPrivateKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSlotID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSlotInfo`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pr | MXR | 3.2 and later | + | ojects_nss_ssl_functions_pkfnc#1030779` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSlotSeries`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSymKeyNickname`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSymKeyType`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetSymKeyUserData`` | MXR | 3.11 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetTokenInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1026964` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetWindow`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_GetWrapKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_HashBuf`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_HasRootCerts`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportCert`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportCertForKeyToSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportCRL`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportDERCert`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK1 | MXR | 3.4 and later | + | 1_ImportDERPrivateKeyInfoAndReturnKey`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportEncryptedPrivateKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportPrivateKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | `` | MXR | 3.4 and later | + | PK11_ImportPrivateKeyInfoAndReturnKey`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportPublicKey`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ImportSymKeyWithFlags`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_InitPin`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_IsFIPS`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_IsDisabled`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_IsFriendly`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pr | MXR | 3.2 and later | + | ojects_nss_ssl_functions_pkfnc#1026762` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_IsInternal`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslcrt#1026762` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pr | MXR | 3.2 and later | + | ojects_nss_ssl_functions_pkfnc#1022991` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_IsRemovable`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_IVFromParam`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_KeyGen`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_LinkGenericObject`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ListCerts`` | MXR | 3.2 and later. Updated 3.8 with new | + | | | options. See bug | + | | | `215186 <https://bugzilla | + | | | .mozilla.org/show_bug.cgi?id=215186>`__ | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ListFixedKeysInSlot`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ListPrivKeysInSlot`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ListPublicKeysInSlot`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_LoadPrivKey`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_LogoutAll`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_MakeKEAPubKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | `` | MXR | 3.2 and later | + | PK11_MapPBEMechanismToCryptoMechanism`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_MapSignKeyType`` | MXR | 3.11 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_MechanismToAlgtag`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_MergeTokens`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_MoveSymKey`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_NeedLogin`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_NeedUserInit`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ParamFromIV`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ParamFromAlgid`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ParamToAlgid`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PBEKeyGen`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PrivDecryptPKCS1`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ProtectedAuthenticationPath`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubDecryptRaw`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubDerive`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubDeriveWithKDF`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubEncryptPKCS1`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubEncryptRaw`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubUnwrapSymKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubUnwrapSymKeyWithFlags`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubUnwrapSymKeyWithFlagsPerm`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_PubWrapSymKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_RandomUpdate`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ReadRawAttribute`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ReferenceSymKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_ResetToken`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_RestoreContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SaveContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SaveContextAlloc`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SetFortezzaHack`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pr | MXR | 3.2 and later | + | ojects_nss_ssl_functions_pkfnc#1023128` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SetPrivateKeyNickname`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SetPublicKeyNickname`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SetSlotPWValues`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SetSymKeyNickname`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SetSymKeyUserData`` | MXR | 3.11 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SetWrapKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_Sign`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SignatureLen`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_SymKeyFromHandle`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_TokenExists`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_TokenKeyGen`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_TokenKeyGenWithFlags`` | MXR | 3.10.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_TokenRefresh`` | MXR | 3.7.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_TraverseCertsForNicknameInSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_TraverseCertsForSubjectInSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_TraverseSlotCerts`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_UnlinkGenericObject`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_UnwrapSymKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_UnwrapSymKeyWithFlags`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_UnwrapSymKeyWithFlagsPerm`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_UpdateSlotAttribute`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_UserEnableSlot`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_UserDisableSlot`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_Verify`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_VerifyKeyOK`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_WaitForTokenEvent`` | MXR | 3.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_WrapSymKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11_WriteRawAttribute`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11SDR_Encrypt`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PK11SDR_Decrypt`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_DeletePermCertificate`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_DeletePermCRL`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_DerSignData`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_DestroyCrl`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_FindCrlByDERCert`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_FindCrlByName`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_LookupCrls`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_NewCrl`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_QuickDERDecodeItem`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CacheStaticFlags`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_ConvertToPublicKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CopyPrivateKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CopyPublicKey`` | MXR | 3.6 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CopySubjectPublicKeyInfo`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CreateDHPrivateKey`` | MXR | 3.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CreateECPrivateKey`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CreateSubjectPublicKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ` | MXR | 3.4 and later | + | `SECKEY_DecodeDERSubjectPublicKeyInfo`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslkey#1051017` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_ECParamsToBasePointOrderLen`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_ECParamsToKeySize`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_DestroyPublicKeyList`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_DestroySubjectPublicKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_GetPublicKeyType`` | MXR | 3.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_PublicKeyStrengthInBits`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_SignatureLen`` | MXR | 3.11.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/deprecated_ssl_functions/index.rst b/security/nss/doc/rst/legacy/deprecated_ssl_functions/index.rst new file mode 100644 index 0000000000..3db5071502 --- /dev/null +++ b/security/nss/doc/rst/legacy/deprecated_ssl_functions/index.rst @@ -0,0 +1,34 @@ +.. _mozilla_projects_nss_deprecated_ssl_functions: + +Deprecated SSL functions +======================== + +.. container:: + + The following SSL functions have been replaced with newer versions. The deprecated functions are + not supported by the new SSL shared libraries. Applications that want to use the SSL shared + libraries must convert to calling the new replacement functions listed below. + + Each function name is linked to its entry in the + :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference`. The `Mozilla Cross + Reference <http://mxr.mozilla.org/>`__ (MXR) link for each function provides access to the + function definition, prototype definition, and source code references. + + +-----------------------------------------+-------------+-----------------------------------------+ + | Function name/documentation | Source code | Replacement in NSS 3.2 | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | :ref:`mozilla_pro | + | jects_nss_ssl_functions_sslfnc#1220189` | | jects_nss_ssl_functions_sslfnc#1086543` | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | :ref:`mozilla_pro | + | jects_nss_ssl_functions_sslfnc#1207298` | | jects_nss_ssl_functions_sslfnc#1084747` | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | :ref:`mozilla_pro | + | jects_nss_ssl_functions_sslfnc#1206365` | | jects_nss_ssl_functions_sslfnc#1068466` | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | :ref:`mozilla_pro | + | jects_nss_ssl_functions_sslfnc#1231825` | | jects_nss_ssl_functions_sslfnc#1232052` | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | :ref:`mozilla_pro | + | jects_nss_ssl_functions_sslfnc#1207350` | | jects_nss_ssl_functions_sslfnc#1104647` | + +-----------------------------------------+-------------+-----------------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/encrypt_decrypt_mac_keys_as_session_objects/index.rst b/security/nss/doc/rst/legacy/encrypt_decrypt_mac_keys_as_session_objects/index.rst new file mode 100644 index 0000000000..4d6d09bcf0 --- /dev/null +++ b/security/nss/doc/rst/legacy/encrypt_decrypt_mac_keys_as_session_objects/index.rst @@ -0,0 +1,1206 @@ +.. _mozilla_projects_nss_encrypt_decrypt_mac_keys_as_session_objects: + +Encrypt Decrypt MAC Keys As Session Objects +=========================================== + +.. _nss_sample_code_4_encryptiondecryption_and_mac_keys_using_session.: + +`NSS Sample Code 4: Encryption/Decryption and MAC Keys Using Session. <#nss_sample_code_4_encryptiondecryption_and_mac_keys_using_session.>`__ +---------------------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + Generates encryption/mac keys and uses session objects. + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + /* NSPR Headers */ + #include + #include + #include + #include + #include + #include + #include + + /* NSS headers */ + #include + #include + + /* our samples utilities */ + #include "util.h" + + #define BUFFERSIZE 80 + #define DIGESTSIZE 16 + #define PTEXT_MAC_BUFFER_SIZE 96 + #define CIPHERSIZE 96 + #define BLOCKSIZE 32 + + #define CIPHER_HEADER "-----BEGIN CIPHER-----" + #define CIPHER_TRAILER "-----END CIPHER-----" + #define ENCKEY_HEADER "-----BEGIN AESKEY CKAID-----" + #define ENCKEY_TRAILER "-----END AESKEY CKAID-----" + #define MACKEY_HEADER "-----BEGIN MACKEY CKAID-----" + #define MACKEY_TRAILER "-----END MACKEY CKAID-----" + #define IV_HEADER "-----BEGIN IV-----" + #define IV_TRAILER "-----END IV-----" + #define MAC_HEADER "-----BEGIN MAC-----" + #define MAC_TRAILER "-----END MAC-----" + #define PAD_HEADER "-----BEGIN PAD-----" + #define PAD_TRAILER "-----END PAD-----" + + typedef enum { + ENCRYPT, + DECRYPT, + UNKNOWN + } CommandType; + + typedef enum { + SYMKEY = 0, + MACKEY = 1, + IV = 2, + MAC = 3, + PAD = 4 + } HeaderType; + + + /* + * Print usage message and exit + */ + static void + Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s -c -d [-z ] " + "[-p | -f ] -i -o \n\n", + progName); + fprintf(stderr, "%-20s Specify 'a' for encrypt operation\n\n", + "-c "); + fprintf(stderr, "%-20s Specify 'b' for decrypt operation\n\n", + " "); + fprintf(stderr, "%-20s Specify db directory path\n\n", + "-d "); + fprintf(stderr, "%-20s Specify db password [optional]\n\n", + "-p "); + fprintf(stderr, "%-20s Specify db password file [optional]\n\n", + "-f "); + fprintf(stderr, "%-20s Specify noise file name [optional]\n\n", + "-z "); + fprintf(stderr, "%-21s Specify an input file name\n\n", + "-i "); + fprintf(stderr, "%-21s Specify an output file name\n\n", + "-o "); + fprintf(stderr, "%-7s For encrypt, it takes as an input file and produces\n", + "Note :"); + fprintf(stderr, "%-7s .enc and .header as intermediate output files.\n\n", + ""); + fprintf(stderr, "%-7s For decrypt, it takes .enc and .header\n", + ""); + fprintf(stderr, "%-7s as input files and produces as a final output file.\n\n", + ""); + exit(-1); + } + + /* + * Gather a CKA_ID + */ + SECStatus + GatherCKA_ID(PK11SymKey* key, SECItem* buf) + { + SECStatus rv = PK11_ReadRawAttribute(PK11_TypeSymKey, key, CKA_ID, buf); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "PK11_ReadRawAttribute returned (%d)\n", rv); + PR_fprintf(PR_STDERR, "Could not read SymKey CKA_ID attribute\n"); + return rv; + } + return rv; + } + + /* + * Generate a Symmetric Key + */ + PK11SymKey * + GenerateSYMKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE mechanism, + int keySize, SECItem *keyID, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + return NULL; + } + } + + /* Generate the symmetric key */ + key = PK11_TokenKeyGen(slot, mechanism, + NULL, keySize, keyID, PR_TRUE, pwdata); + + if (!key) { + PR_fprintf(PR_STDERR, "Symmetric Key Generation Failed \n"); + } + + return key; + } + + /* + * MacInit + */ + SECStatus + MacInit(PK11Context *ctx) + { + SECStatus rv = PK11_DigestBegin(ctx); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestBegin()\n"); + } + return rv; + } + + /* + * MacUpdate + */ + SECStatus + MacUpdate(PK11Context *ctx, + unsigned char *msg, unsigned int msgLen) + { + SECStatus rv = PK11_DigestOp(ctx, msg, msgLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : DigestOp()\n"); + } + return rv; + } + + /* + * Finalize MACing + */ + SECStatus + MacFinal(PK11Context *ctx, + unsigned char *mac, unsigned int *macLen, unsigned int maxLen) + { + SECStatus rv = PK11_DigestFinal(ctx, mac, macLen, maxLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestFinal()\n"); + } + return SECSuccess; + } + + /* + * Compute Mac + */ + SECStatus + ComputeMac(PK11Context *ctxmac, + unsigned char *ptext, unsigned int ptextLen, + unsigned char *mac, unsigned int *macLen, + unsigned int maxLen) + { + SECStatus rv = MacInit(ctxmac); + if (rv != SECSuccess) return rv; + rv = MacUpdate(ctxmac, ptext, ptextLen); + if (rv != SECSuccess) return rv; + rv = MacFinal(ctxmac, mac, macLen, maxLen); + return rv; + } + + /* + * WriteToHeaderFile + */ + SECStatus + WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, + PRFileDesc *outFile) + { + SECStatus rv; + char header[40]; + char trailer[40]; + char *outString = NULL; + + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + PR_fprintf(outFile, "%s\n", header); + PrintAsHex(outFile, buf, len); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + } + + /* + * Initialize for encryption or decryption - common code + */ + PK11Context * + CryptInit(PK11SymKey *key, + unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type, CK_ATTRIBUTE_TYPE operation) + { + SECItem ivItem = { siBuffer, iv, ivLen }; + PK11Context *ctx = NULL; + + SECItem *secParam = PK11_ParamFromIV(CKM_AES_CBC, &ivItem); + if (secParam == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : secParam NULL\n"); + return NULL; + } + ctx = PK11_CreateContextBySymKey(CKM_AES_CBC, operation, key, secParam); + if (ctx == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : can't create a context\n"); + goto cleanup; + + } + cleanup: + if (secParam) { + SECITEM_FreeItem(secParam, PR_TRUE); + } + return ctx; + } + + /* + * Common encryption and decryption code + */ + SECStatus + Crypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxOut, + unsigned char *in, unsigned int inLen) + { + SECStatus rv; + + rv = PK11_CipherOp(ctx, out, outLen, maxOut, in, inLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Crypt Failed : PK11_CipherOp returned %d\n", rv); + goto cleanup; + } + + cleanup: + if (rv != SECSuccess) { + return rv; + } + return SECSuccess; + } + + /* + * Decrypt + */ + SECStatus + Decrypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * Encrypt + */ + SECStatus + Encrypt(PK11Context* ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * EncryptInit + */ + PK11Context * + EncryptInit(PK11SymKey *ek, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(ek, iv, ivLen, type, CKA_ENCRYPT); + } + + /* + * DecryptInit + */ + PK11Context * + DecryptInit(PK11SymKey *dk, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(dk, iv, ivLen, type, CKA_DECRYPT); + } + + /* + * Read cryptographic parameters from the header file + */ + SECStatus + ReadFromHeaderFile(const char *fileName, HeaderType type, + SECItem *item, PRBool isHexData) + { + SECStatus rv; + PRFileDesc* file; + SECItem filedata; + SECItem outbuf; + unsigned char *nonbody; + unsigned char *body; + char header[40]; + char trailer[40]; + + outbuf.type = siBuffer; + file = PR_Open(fileName, PR_RDONLY, 0); + if (!file) { + PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); + return SECFailure; + } + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + rv = FileToItem(&filedata, file); + nonbody = (char *)filedata.data; + if (!nonbody) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* check for headers and trailers and remove them */ + if ((body = strstr(nonbody, header)) != NULL) { + char *trail = NULL; + nonbody = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(nonbody, '\r'); /* maybe this is a MAC file */ + if (body) + trail = strstr(++body, trailer); + if (trail != NULL) { + *trail = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + return SECFailure; + } + } else { + body = nonbody; + } + + cleanup: + PR_Close(file); + HexToBuf(body, item, isHexData); + return SECSuccess; + } + + /* + * EncryptAndMac + */ + SECStatus + EncryptAndMac(PRFileDesc *inFile, + PRFileDesc *headerFile, + PRFileDesc *encFile, + PK11SymKey *ek, + PK11SymKey *mk, + unsigned char *iv, unsigned int ivLen, + PRBool ascii) + { + SECStatus rv; + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen; + unsigned char mac[DIGESTSIZE]; + unsigned int macLen; + unsigned int nwritten; + unsigned char encbuf[BLOCKSIZE]; + unsigned int encbufLen; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + unsigned int pad[1]; + SECItem padItem; + unsigned int paddingLength; + + static unsigned int firstTime = 1; + int j; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + rv = MacInit(ctxmac); + if (rv != SECSuccess) { + goto cleanup; + } + + ctxenc = EncryptInit(ek, iv, ivLen, CKM_AES_CBC); + + /* read a buffer of plaintext from input file */ + while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { + + /* Encrypt using it using CBC, using previously created IV */ + if (ptextLen != BLOCKSIZE) { + paddingLength = BLOCKSIZE - ptextLen; + for ( j=0; j < paddingLength; j++) { + ptext[ptextLen+j] = (unsigned char)paddingLength; + } + ptextLen = BLOCKSIZE; + } + rv = Encrypt(ctxenc, + encbuf, &encbufLen, sizeof(encbuf), + ptext, ptextLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Encrypt Failure\n"); + goto cleanup; + } + + /* save the last block of ciphertext as the next IV */ + iv = encbuf; + ivLen = encbufLen; + + /* write the cipher text to intermediate file */ + nwritten = PR_Write(encFile, encbuf, encbufLen); + /*PR_Assert(nwritten == encbufLen);*/ + + rv = MacUpdate(ctxmac, ptext, ptextLen); + } + + rv = MacFinal(ctxmac, mac, &macLen, DIGESTSIZE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "MacFinal Failure\n"); + goto cleanup; + } + if (macLen == 0) { + PR_fprintf(PR_STDERR, "Bad MAC length\n"); + rv = SECFailure; + goto cleanup; + } + WriteToHeaderFile(mac, macLen, MAC, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write MAC Failure\n"); + goto cleanup; + } + + pad[0] = paddingLength; + padItem.type = siBuffer; + padItem.data = (unsigned char *)pad; + padItem.len = sizeof(pad[0]); + + WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write PAD Failure\n"); + goto cleanup; + } + + rv = SECSuccess; + + cleanup: + if (ctxmac != NULL) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc != NULL) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + + return rv; + } + + /* + * Find the Key for the given mechanism + */ + PK11SymKey* + FindKey(PK11SlotInfo *slot, + CK_MECHANISM_TYPE mechanism, + SECItem *keyBuf, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + if (slot) { + PK11_FreeSlot(slot); + } + return NULL; + } + } + + key = PK11_FindFixedKey(slot, mechanism, keyBuf, 0); + if (!key) { + PR_fprintf(PR_STDERR, + "PK11_FindFixedKey failed (err %d)\n", + PR_GetError()); + PK11_FreeSlot(slot); + return NULL; + } + return key; + } + + /* + * Decrypt and Verify MAC + */ + SECStatus + DecryptAndVerifyMac(const char* outFileName, + char *encryptedFileName, + SECItem *cItem, SECItem *macItem, + PK11SymKey* ek, PK11SymKey* mk, SECItem *ivItem, SECItem *padItem) + { + SECStatus rv; + PRFileDesc* inFile; + PRFileDesc* outFile; + + unsigned char decbuf[64]; + unsigned int decbufLen; + + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen = 0; + unsigned char ctext[64]; + unsigned int ctextLen; + unsigned char newmac[DIGESTSIZE]; + unsigned int newmacLen = 0; + unsigned int newptextLen = 0; + unsigned int count = 0; + unsigned int temp = 0; + unsigned int blockNumber = 0; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + + unsigned char iv[BLOCKSIZE]; + unsigned int ivLen = ivItem->len; + unsigned int fileLength; + unsigned int paddingLength; + int j; + + memcpy(iv, ivItem->data, ivItem->len); + paddingLength = (unsigned int)padItem->data[0]; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(encryptedFileName, PR_RDONLY , 0); + if (!inFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* Open the output file. */ + outFile = PR_Open(outFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR , 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + outFileName); + return SECFailure; + } + + rv = MacInit(ctxmac); + if (rv != SECSuccess) goto cleanup; + + ctxenc = DecryptInit(ek, iv, ivLen, CKM_AES_CBC); + fileLength = FileSize(encryptedFileName); + + while ((ctextLen = PR_Read(inFile, ctext, sizeof(ctext))) > 0) { + + count += ctextLen; + + /* decrypt cipher text buffer using CBC and IV */ + + rv = Decrypt(ctxenc, decbuf, &decbufLen, sizeof(decbuf), + ctext, ctextLen); + + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Decrypt Failure\n"); + goto cleanup; + } + + if (decbufLen == 0) break; + + rv = MacUpdate(ctxmac, decbuf, decbufLen); + if (rv != SECSuccess) { goto cleanup; } + if (count == fileLength) { + decbufLen = decbufLen-paddingLength; + } + + /* write the plain text to out file */ + temp = PR_Write(outFile, decbuf, decbufLen); + if (temp != decbufLen) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + break; + } + + /* save last block of ciphertext */ + memcpy(iv, decbuf, decbufLen); + ivLen = decbufLen; + blockNumber++; + } + + if (rv != SECSuccess) { goto cleanup; } + + rv = MacFinal(ctxmac, newmac, &newmacLen, sizeof(newmac)); + if (rv != SECSuccess) { goto cleanup; } + + if (PORT_Memcmp(macItem->data, newmac, newmacLen) == 0) { + rv = SECSuccess; + } else { + PR_fprintf(PR_STDERR, "Check MAC : Failure\n"); + PR_fprintf(PR_STDERR, "Extracted : "); + PrintAsHex(PR_STDERR, macItem->data, macItem->len); + PR_fprintf(PR_STDERR, "Computed : "); + PrintAsHex(PR_STDERR, newmac, newmacLen); + rv = SECFailure; + } + cleanup: + if (ctxmac) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + if (outFile) { + PR_Close(outFile); + } + + return rv; + } + + /* + * Gets IV and CKAIDS From Header File + */ + SECStatus + GetIVandCKAIDSFromHeader(const char *cipherFileName, + SECItem *ivItem, SECItem *encKeyItem, SECItem *macKeyItem) + { + SECStatus rv; + + /* open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it + */ + rv = ReadFromHeaderFile(cipherFileName, IV, ivItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not retrieve IV from cipher file\n"); + goto cleanup; + } + + rv = ReadFromHeaderFile(cipherFileName, SYMKEY, encKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve AES CKA_ID from cipher file\n"); + goto cleanup; + } + rv = ReadFromHeaderFile(cipherFileName, MACKEY, macKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC CKA_ID from cipher file\n"); + goto cleanup; + } + cleanup: + return rv; + } + + /* + * DecryptFile + */ + SECStatus + DecryptFile(PK11SlotInfo *slot, + const char *dbdir, + const char *outFileName, + const char *headerFileName, + char *encryptedFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open read only and we have authenticated to it + * open input file, read in header, get IV and CKA_IDs of two keys from it + * find those keys in the DB token + * Open output file + * loop until EOF(input): + * read a buffer of ciphertext from input file, + * Save last block of ciphertext + * decrypt ciphertext buffer using CBC and IV, + * compute and check MAC, then remove MAC from plaintext + * replace IV with saved last block of ciphertext + * write the plain text to output file + * close files + * report success + */ + + SECStatus rv; + SECItem ivItem; + SECItem encKeyItem; + SECItem macKeyItem; + SECItem cipherItem; + SECItem macItem; + SECItem padItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + + + /* open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it + */ + rv = GetIVandCKAIDSFromHeader(headerFileName, + &ivItem, &encKeyItem, &macKeyItem); + if (rv != SECSuccess) { + goto cleanup; + } + + /* find those keys in the DB token */ + encKey = FindKey(slot, CKM_AES_CBC, &encKeyItem, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "Can't find the encryption key\n"); + rv = SECFailure; + goto cleanup; + } + /* CKM_MD5_HMAC or CKM_EXTRACT_KEY_FROM_KEY */ + macKey = FindKey(slot, CKM_MD5_HMAC, &macKeyItem, pwdata); + if (macKey == NULL) { + rv = SECFailure; + goto cleanup; + } + + /* Read in the Mac into item from the intermediate file */ + rv = ReadFromHeaderFile(headerFileName, MAC, &macItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC from cipher file\n"); + goto cleanup; + } + if (macItem.data == NULL) { + PR_fprintf(PR_STDERR, "MAC has NULL data\n"); + rv = SECFailure; + goto cleanup; + } + if (macItem.len == 0) { + PR_fprintf(PR_STDERR, "MAC has data has 0 length\n"); + /*rv = SECFailure; + goto cleanup;*/ + } + + rv = ReadFromHeaderFile(headerFileName, PAD, &padItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve PAD detail from header file\n"); + goto cleanup; + } + + if (rv == SECSuccess) { + /* Decrypt and Remove Mac */ + rv = DecryptAndVerifyMac(outFileName, encryptedFileName, + &cipherItem, &macItem, encKey, macKey, &ivItem, &padItem); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed while decrypting and removing MAC\n"); + } + } + + cleanup: + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * EncryptFile + */ + SECStatus + EncryptFile(PK11SlotInfo *slot, + const char *dbdir, + const char *inFileName, + const char *headerFileName, + const char *encryptedFileName, + const char *noiseFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open for read/write and we have authenticated to it. + * generate a symmetric AES key as a token object. + * generate a second key to use for MACing, also a token object. + * get their CKA_IDs + * generate a random value to use as IV for AES CBC + * open an input file and an output file, + * write a header to the output that identifies the two keys by + * their CKA_IDs, May include original file name and length. + * loop until EOF(input) + * read a buffer of plaintext from input file, + * MAC it, append the MAC to the plaintext + * encrypt it using CBC, using previously created IV, + * store the last block of ciphertext as the new IV, + * write the cipher text to intermediate file + * close files + * report success + */ + SECStatus rv; + PRFileDesc *inFile; + PRFileDesc *headerFile; + PRFileDesc *encFile; + + unsigned char *encKeyId = (unsigned char *) "Encrypt Key"; + unsigned char *macKeyId = (unsigned char *) "MAC Key"; + SECItem encKeyID = { siAsciiString, encKeyId, PL_strlen(encKeyId) }; + SECItem macKeyID = { siAsciiString, macKeyId, PL_strlen(macKeyId) }; + + SECItem encCKAID; + SECItem macCKAID; + unsigned char iv[BLOCKSIZE]; + SECItem ivItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + SECItem temp; + unsigned char c; + + /* generate a symmetric AES key as a token object. */ + encKey = GenerateSYMKey(slot, CKM_AES_KEY_GEN, 128/8, &encKeyID, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for AES returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* generate a second key to use for MACing, also a token object. */ + macKey = GenerateSYMKey(slot, CKM_GENERIC_SECRET_KEY_GEN, 160/8, + &macKeyID, pwdata); + if (macKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for MACing returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* get the encrypt key CKA_ID */ + rv = GatherCKA_ID(encKey, &encCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error while wrapping encrypt key\n"); + goto cleanup; + } + + /* get the MAC key CKA_ID */ + rv = GatherCKA_ID(macKey, &macCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Can't get the MAC key CKA_ID.\n"); + goto cleanup; + } + + if (noiseFileName) { + rv = SeedFromNoiseFile(noiseFileName); + if (rv != SECSuccess) { + PORT_SetError(PR_END_OF_FILE_ERROR); + return SECFailure; + } + rv = PK11_GenerateRandom(iv, BLOCKSIZE); + if (rv != SECSuccess) { + goto cleanup; + } + + } else { + /* generate a random value to use as IV for AES CBC */ + GenerateRandom(iv, BLOCKSIZE); + } + + headerFile = PR_Open(headerFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + headerFileName); + return SECFailure; + } + encFile = PR_Open(encryptedFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!encFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* write to a header file the IV and the CKA_IDs + * identifying the two keys + */ + ivItem.type = siBuffer; + ivItem.data = iv; + ivItem.len = BLOCKSIZE; + + rv = WriteToHeaderFile(iv, BLOCKSIZE, IV, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing IV to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + rv = WriteToHeaderFile(encCKAID.data, encCKAID.len, SYMKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing AES CKA_ID to cipher file - %s\n", + encryptedFileName); + goto cleanup; + } + rv = WriteToHeaderFile(macCKAID.data, macCKAID.len, MACKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing MAC CKA_ID to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + + /* Macing and Encryption */ + if (rv == SECSuccess) { + rv = EncryptAndMac(inFile, headerFile, encFile, + encKey, macKey, ivItem.data, ivItem.len, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : Macing and Encryption\n"); + goto cleanup; + } + } + + cleanup: + if (inFile) { + PR_Close(inFile); + } + if (headerFile) { + PR_Close(headerFile); + } + if (encFile) { + PR_Close(encFile); + } + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * This example illustrates basic encryption/decryption and MACing + * Generates the encryption/mac keys and uses token for storing. + * Encrypts the input file and appends MAC before storing in intermediate + * header file. + * Writes the CKA_IDs of the encryption keys into intermediate header file. + * Reads the intermediate headerfile for CKA_IDs and encrypted + * contents and decrypts into output file. + */ + int + main(int argc, char **argv) + { + SECStatus rv; + SECStatus rvShutdown; + PK11SlotInfo *slot = NULL; + PLOptState *optstate; + PLOptStatus status; + char headerFileName[50]; + char encryptedFileName[50]; + PRFileDesc *inFile; + PRFileDesc *outFile; + PRBool ascii = PR_FALSE; + CommandType cmd = UNKNOWN; + const char *command = NULL; + const char *dbdir = NULL; + const char *inFileName = NULL; + const char *outFileName = NULL; + const char *noiseFileName = NULL; + secuPWData pwdata = { PW_NONE, 0 }; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "c:d:i:o:f:p:z:a"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'a': + ascii = PR_TRUE; + break; + case 'c': + command = strdup(optstate->value); + break; + case 'd': + dbdir = strdup(optstate->value); + break; + case 'f': + pwdata.source = PW_FROMFILE; + pwdata.data = strdup(optstate->value); + break; + case 'p': + pwdata.source = PW_PLAINTEXT; + pwdata.data = strdup(optstate->value); + break; + case 'i': + inFileName = strdup(optstate->value); + break; + case 'o': + outFileName = strdup(optstate->value); + break; + case 'z': + noiseFileName = strdup(optstate->value); + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (!command || !dbdir || !inFileName || !outFileName) + Usage(progName); + if (PL_strlen(command)==0) + Usage(progName); + + cmd = command[0] == 'a' ? ENCRYPT : command[0] == 'b' ? DECRYPT : UNKNOWN; + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + PR_Close(inFile); + + /* For intermediate header file, choose filename as inputfile name + with extension ".header" */ + strcpy(headerFileName, inFileName); + strcat(headerFileName, ".header"); + + /* For intermediate encrypted file, choose filename as inputfile name + with extension ".enc" */ + strcpy(encryptedFileName, inFileName); + strcat(encryptedFileName, ".enc"); + + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + + switch (cmd) { + case ENCRYPT: + /* If the intermediate header file already exists, delete it */ + if (PR_Access(headerFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(headerFileName); + } + /* If the intermediate encrypted already exists, delete it */ + if (PR_Access(encryptedFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(encryptedFileName); + } + + /* Open DB for read/write and authenticate to it. */ + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); + goto cleanup; + } + + PK11_SetPasswordFunc(GetModulePassword); + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + rv = EncryptFile(slot, dbdir, + inFileName, headerFileName, encryptedFileName, + noiseFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "EncryptFile : Failed\n"); + return SECFailure; + } + break; + case DECRYPT: + /* Open DB read only, authenticate to it */ + PK11_SetPasswordFunc(GetModulePassword); + + rv = NSS_Init(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_Init Failed\n"); + return SECFailure; + } + + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + + rv = DecryptFile(slot, dbdir, + outFileName, headerFileName, + encryptedFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "DecryptFile : Failed\n"); + return SECFailure; + } + break; + } + + cleanup: + rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); + rv = SECFailure; + } + + PR_Cleanup(); + + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/encrypt_decrypt_mac_using_token/index.rst b/security/nss/doc/rst/legacy/encrypt_decrypt_mac_using_token/index.rst new file mode 100644 index 0000000000..e2f399166b --- /dev/null +++ b/security/nss/doc/rst/legacy/encrypt_decrypt_mac_using_token/index.rst @@ -0,0 +1,1206 @@ +.. _mozilla_projects_nss_encrypt_decrypt_mac_using_token: + +Encrypt and decrypt MAC using token +=================================== + +.. _nss_sample_code_3_encryptiondecryption_and_mac_using_token_object.: + +`NSS sample code 3: encryption/decryption and MAC using token object. <#nss_sample_code_3_encryptiondecryption_and_mac_using_token_object.>`__ +---------------------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + Generates encryption/mac keys and uses token for storing. + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + /* NSPR Headers */ + #include + #include + #include + #include + #include + #include + #include + + /* NSS headers */ + #include + #include + + /* our samples utilities */ + #include "util.h" + + #define BUFFERSIZE 80 + #define DIGESTSIZE 16 + #define PTEXT_MAC_BUFFER_SIZE 96 + #define CIPHERSIZE 96 + #define BLOCKSIZE 32 + + #define CIPHER_HEADER "-----BEGIN CIPHER-----" + #define CIPHER_TRAILER "-----END CIPHER-----" + #define ENCKEY_HEADER "-----BEGIN AESKEY CKAID-----" + #define ENCKEY_TRAILER "-----END AESKEY CKAID-----" + #define MACKEY_HEADER "-----BEGIN MACKEY CKAID-----" + #define MACKEY_TRAILER "-----END MACKEY CKAID-----" + #define IV_HEADER "-----BEGIN IV-----" + #define IV_TRAILER "-----END IV-----" + #define MAC_HEADER "-----BEGIN MAC-----" + #define MAC_TRAILER "-----END MAC-----" + #define PAD_HEADER "-----BEGIN PAD-----" + #define PAD_TRAILER "-----END PAD-----" + + typedef enum { + ENCRYPT, + DECRYPT, + UNKNOWN + } CommandType; + + typedef enum { + SYMKEY = 0, + MACKEY = 1, + IV = 2, + MAC = 3, + PAD = 4 + } HeaderType; + + + /* + * Print usage message and exit + */ + static void + Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s -c -d [-z ] " + "[-p | -f ] -i -o \n\n", + progName); + fprintf(stderr, "%-20s Specify 'a' for encrypt operation\n\n", + "-c "); + fprintf(stderr, "%-20s Specify 'b' for decrypt operation\n\n", + " "); + fprintf(stderr, "%-20s Specify db directory path\n\n", + "-d "); + fprintf(stderr, "%-20s Specify db password [optional]\n\n", + "-p "); + fprintf(stderr, "%-20s Specify db password file [optional]\n\n", + "-f "); + fprintf(stderr, "%-20s Specify noise file name [optional]\n\n", + "-z "); + fprintf(stderr, "%-21s Specify an input file name\n\n", + "-i "); + fprintf(stderr, "%-21s Specify an output file name\n\n", + "-o "); + fprintf(stderr, "%-7s For encrypt, it takes as an input file and produces\n", + "Note :"); + fprintf(stderr, "%-7s .enc and .header as intermediate output files.\n\n", + ""); + fprintf(stderr, "%-7s For decrypt, it takes .enc and .header\n", + ""); + fprintf(stderr, "%-7s as input files and produces as a final output file.\n\n", + ""); + exit(-1); + } + + /* + * Gather a CKA_ID + */ + SECStatus + GatherCKA_ID(PK11SymKey* key, SECItem* buf) + { + SECStatus rv = PK11_ReadRawAttribute(PK11_TypeSymKey, key, CKA_ID, buf); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "PK11_ReadRawAttribute returned (%d)\n", rv); + PR_fprintf(PR_STDERR, "Could not read SymKey CKA_ID attribute\n"); + return rv; + } + return rv; + } + + /* + * Generate a Symmetric Key + */ + PK11SymKey * + GenerateSYMKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE mechanism, + int keySize, SECItem *keyID, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + return NULL; + } + } + + /* Generate the symmetric key */ + key = PK11_TokenKeyGen(slot, mechanism, + NULL, keySize, keyID, PR_TRUE, pwdata); + + if (!key) { + PR_fprintf(PR_STDERR, "Symmetric Key Generation Failed \n"); + } + + return key; + } + + /* + * MacInit + */ + SECStatus + MacInit(PK11Context *ctx) + { + SECStatus rv = PK11_DigestBegin(ctx); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestBegin()\n"); + } + return rv; + } + + /* + * MacUpdate + */ + SECStatus + MacUpdate(PK11Context *ctx, + unsigned char *msg, unsigned int msgLen) + { + SECStatus rv = PK11_DigestOp(ctx, msg, msgLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : DigestOp()\n"); + } + return rv; + } + + /* + * Finalize MACing + */ + SECStatus + MacFinal(PK11Context *ctx, + unsigned char *mac, unsigned int *macLen, unsigned int maxLen) + { + SECStatus rv = PK11_DigestFinal(ctx, mac, macLen, maxLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestFinal()\n"); + } + return SECSuccess; + } + + /* + * Compute Mac + */ + SECStatus + ComputeMac(PK11Context *ctxmac, + unsigned char *ptext, unsigned int ptextLen, + unsigned char *mac, unsigned int *macLen, + unsigned int maxLen) + { + SECStatus rv = MacInit(ctxmac); + if (rv != SECSuccess) return rv; + rv = MacUpdate(ctxmac, ptext, ptextLen); + if (rv != SECSuccess) return rv; + rv = MacFinal(ctxmac, mac, macLen, maxLen); + return rv; + } + + /* + * WriteToHeaderFile + */ + SECStatus + WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, + PRFileDesc *outFile) + { + SECStatus rv; + char header[40]; + char trailer[40]; + char *outString = NULL; + + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + PR_fprintf(outFile, "%s\n", header); + PrintAsHex(outFile, buf, len); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + } + + /* + * Initialize for encryption or decryption - common code + */ + PK11Context * + CryptInit(PK11SymKey *key, + unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type, CK_ATTRIBUTE_TYPE operation) + { + SECItem ivItem = { siBuffer, iv, ivLen }; + PK11Context *ctx = NULL; + + SECItem *secParam = PK11_ParamFromIV(CKM_AES_CBC, &ivItem); + if (secParam == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : secParam NULL\n"); + return NULL; + } + ctx = PK11_CreateContextBySymKey(CKM_AES_CBC, operation, key, secParam); + if (ctx == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : can't create a context\n"); + goto cleanup; + + } + cleanup: + if (secParam) { + SECITEM_FreeItem(secParam, PR_TRUE); + } + return ctx; + } + + /* + * Common encryption and decryption code + */ + SECStatus + Crypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxOut, + unsigned char *in, unsigned int inLen) + { + SECStatus rv; + + rv = PK11_CipherOp(ctx, out, outLen, maxOut, in, inLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Crypt Failed : PK11_CipherOp returned %d\n", rv); + goto cleanup; + } + + cleanup: + if (rv != SECSuccess) { + return rv; + } + return SECSuccess; + } + + /* + * Decrypt + */ + SECStatus + Decrypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * Encrypt + */ + SECStatus + Encrypt(PK11Context* ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * EncryptInit + */ + PK11Context * + EncryptInit(PK11SymKey *ek, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(ek, iv, ivLen, type, CKA_ENCRYPT); + } + + /* + * DecryptInit + */ + PK11Context * + DecryptInit(PK11SymKey *dk, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(dk, iv, ivLen, type, CKA_DECRYPT); + } + + /* + * Read cryptographic parameters from the header file + */ + SECStatus + ReadFromHeaderFile(const char *fileName, HeaderType type, + SECItem *item, PRBool isHexData) + { + SECStatus rv; + PRFileDesc* file; + SECItem filedata; + SECItem outbuf; + unsigned char *nonbody; + unsigned char *body; + char header[40]; + char trailer[40]; + + outbuf.type = siBuffer; + file = PR_Open(fileName, PR_RDONLY, 0); + if (!file) { + PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); + return SECFailure; + } + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + rv = FileToItem(&filedata, file); + nonbody = (char *)filedata.data; + if (!nonbody) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* check for headers and trailers and remove them */ + if ((body = strstr(nonbody, header)) != NULL) { + char *trail = NULL; + nonbody = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(nonbody, '\r'); /* maybe this is a MAC file */ + if (body) + trail = strstr(++body, trailer); + if (trail != NULL) { + *trail = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + return SECFailure; + } + } else { + body = nonbody; + } + + cleanup: + PR_Close(file); + HexToBuf(body, item, isHexData); + return SECSuccess; + } + + /* + * EncryptAndMac + */ + SECStatus + EncryptAndMac(PRFileDesc *inFile, + PRFileDesc *headerFile, + PRFileDesc *encFile, + PK11SymKey *ek, + PK11SymKey *mk, + unsigned char *iv, unsigned int ivLen, + PRBool ascii) + { + SECStatus rv; + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen; + unsigned char mac[DIGESTSIZE]; + unsigned int macLen; + unsigned int nwritten; + unsigned char encbuf[BLOCKSIZE]; + unsigned int encbufLen; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + unsigned int pad[1]; + SECItem padItem; + unsigned int paddingLength; + + static unsigned int firstTime = 1; + int j; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + rv = MacInit(ctxmac); + if (rv != SECSuccess) { + goto cleanup; + } + + ctxenc = EncryptInit(ek, iv, ivLen, CKM_AES_CBC); + + /* read a buffer of plaintext from input file */ + while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { + + /* Encrypt using it using CBC, using previously created IV */ + if (ptextLen != BLOCKSIZE) { + paddingLength = BLOCKSIZE - ptextLen; + for ( j=0; j < paddingLength; j++) { + ptext[ptextLen+j] = (unsigned char)paddingLength; + } + ptextLen = BLOCKSIZE; + } + rv = Encrypt(ctxenc, + encbuf, &encbufLen, sizeof(encbuf), + ptext, ptextLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Encrypt Failure\n"); + goto cleanup; + } + + /* save the last block of ciphertext as the next IV */ + iv = encbuf; + ivLen = encbufLen; + + /* write the cipher text to intermediate file */ + nwritten = PR_Write(encFile, encbuf, encbufLen); + /*PR_Assert(nwritten == encbufLen);*/ + + rv = MacUpdate(ctxmac, ptext, ptextLen); + } + + rv = MacFinal(ctxmac, mac, &macLen, DIGESTSIZE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "MacFinal Failure\n"); + goto cleanup; + } + if (macLen == 0) { + PR_fprintf(PR_STDERR, "Bad MAC length\n"); + rv = SECFailure; + goto cleanup; + } + WriteToHeaderFile(mac, macLen, MAC, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write MAC Failure\n"); + goto cleanup; + } + + pad[0] = paddingLength; + padItem.type = siBuffer; + padItem.data = (unsigned char *)pad; + padItem.len = sizeof(pad[0]); + + WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write PAD Failure\n"); + goto cleanup; + } + + rv = SECSuccess; + + cleanup: + if (ctxmac != NULL) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc != NULL) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + + return rv; + } + + /* + * Find the Key for the given mechanism + */ + PK11SymKey* + FindKey(PK11SlotInfo *slot, + CK_MECHANISM_TYPE mechanism, + SECItem *keyBuf, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + if (slot) { + PK11_FreeSlot(slot); + } + return NULL; + } + } + + key = PK11_FindFixedKey(slot, mechanism, keyBuf, 0); + if (!key) { + PR_fprintf(PR_STDERR, + "PK11_FindFixedKey failed (err %d)\n", + PR_GetError()); + PK11_FreeSlot(slot); + return NULL; + } + return key; + } + + /* + * Decrypt and Verify MAC + */ + SECStatus + DecryptAndVerifyMac(const char* outFileName, + char *encryptedFileName, + SECItem *cItem, SECItem *macItem, + PK11SymKey* ek, PK11SymKey* mk, SECItem *ivItem, SECItem *padItem) + { + SECStatus rv; + PRFileDesc* inFile; + PRFileDesc* outFile; + + unsigned char decbuf[64]; + unsigned int decbufLen; + + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen = 0; + unsigned char ctext[64]; + unsigned int ctextLen; + unsigned char newmac[DIGESTSIZE]; + unsigned int newmacLen = 0; + unsigned int newptextLen = 0; + unsigned int count = 0; + unsigned int temp = 0; + unsigned int blockNumber = 0; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + + unsigned char iv[BLOCKSIZE]; + unsigned int ivLen = ivItem->len; + unsigned int fileLength; + unsigned int paddingLength; + int j; + + memcpy(iv, ivItem->data, ivItem->len); + paddingLength = (unsigned int)padItem->data[0]; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(encryptedFileName, PR_RDONLY , 0); + if (!inFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* Open the output file. */ + outFile = PR_Open(outFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR , 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + outFileName); + return SECFailure; + } + + rv = MacInit(ctxmac); + if (rv != SECSuccess) goto cleanup; + + ctxenc = DecryptInit(ek, iv, ivLen, CKM_AES_CBC); + fileLength = FileSize(encryptedFileName); + + while ((ctextLen = PR_Read(inFile, ctext, sizeof(ctext))) > 0) { + + count += ctextLen; + + /* decrypt cipher text buffer using CBC and IV */ + + rv = Decrypt(ctxenc, decbuf, &decbufLen, sizeof(decbuf), + ctext, ctextLen); + + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Decrypt Failure\n"); + goto cleanup; + } + + if (decbufLen == 0) break; + + rv = MacUpdate(ctxmac, decbuf, decbufLen); + if (rv != SECSuccess) { goto cleanup; } + if (count == fileLength) { + decbufLen = decbufLen-paddingLength; + } + + /* write the plain text to out file */ + temp = PR_Write(outFile, decbuf, decbufLen); + if (temp != decbufLen) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + break; + } + + /* save last block of ciphertext */ + memcpy(iv, decbuf, decbufLen); + ivLen = decbufLen; + blockNumber++; + } + + if (rv != SECSuccess) { goto cleanup; } + + rv = MacFinal(ctxmac, newmac, &newmacLen, sizeof(newmac)); + if (rv != SECSuccess) { goto cleanup; } + + if (PORT_Memcmp(macItem->data, newmac, newmacLen) == 0) { + rv = SECSuccess; + } else { + PR_fprintf(PR_STDERR, "Check MAC : Failure\n"); + PR_fprintf(PR_STDERR, "Extracted : "); + PrintAsHex(PR_STDERR, macItem->data, macItem->len); + PR_fprintf(PR_STDERR, "Computed : "); + PrintAsHex(PR_STDERR, newmac, newmacLen); + rv = SECFailure; + } + cleanup: + if (ctxmac) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + if (outFile) { + PR_Close(outFile); + } + + return rv; + } + + /* + * Gets IV and CKAIDS From Header File + */ + SECStatus + GetIVandCKAIDSFromHeader(const char *cipherFileName, + SECItem *ivItem, SECItem *encKeyItem, SECItem *macKeyItem) + { + SECStatus rv; + + /* open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it + */ + rv = ReadFromHeaderFile(cipherFileName, IV, ivItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not retrieve IV from cipher file\n"); + goto cleanup; + } + + rv = ReadFromHeaderFile(cipherFileName, SYMKEY, encKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve AES CKA_ID from cipher file\n"); + goto cleanup; + } + rv = ReadFromHeaderFile(cipherFileName, MACKEY, macKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC CKA_ID from cipher file\n"); + goto cleanup; + } + cleanup: + return rv; + } + + /* + * DecryptFile + */ + SECStatus + DecryptFile(PK11SlotInfo *slot, + const char *dbdir, + const char *outFileName, + const char *headerFileName, + char *encryptedFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open read only and we have authenticated to it + * open input file, read in header, get IV and CKA_IDs of two keys from it + * find those keys in the DB token + * Open output file + * loop until EOF(input): + * read a buffer of ciphertext from input file, + * Save last block of ciphertext + * decrypt ciphertext buffer using CBC and IV, + * compute and check MAC, then remove MAC from plaintext + * replace IV with saved last block of ciphertext + * write the plain text to output file + * close files + * report success + */ + + SECStatus rv; + SECItem ivItem; + SECItem encKeyItem; + SECItem macKeyItem; + SECItem cipherItem; + SECItem macItem; + SECItem padItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + + + /* open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it + */ + rv = GetIVandCKAIDSFromHeader(headerFileName, + &ivItem, &encKeyItem, &macKeyItem); + if (rv != SECSuccess) { + goto cleanup; + } + + /* find those keys in the DB token */ + encKey = FindKey(slot, CKM_AES_CBC, &encKeyItem, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "Can't find the encryption key\n"); + rv = SECFailure; + goto cleanup; + } + /* CKM_MD5_HMAC or CKM_EXTRACT_KEY_FROM_KEY */ + macKey = FindKey(slot, CKM_MD5_HMAC, &macKeyItem, pwdata); + if (macKey == NULL) { + rv = SECFailure; + goto cleanup; + } + + /* Read in the Mac into item from the intermediate file */ + rv = ReadFromHeaderFile(headerFileName, MAC, &macItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC from cipher file\n"); + goto cleanup; + } + if (macItem.data == NULL) { + PR_fprintf(PR_STDERR, "MAC has NULL data\n"); + rv = SECFailure; + goto cleanup; + } + if (macItem.len == 0) { + PR_fprintf(PR_STDERR, "MAC has data has 0 length\n"); + /*rv = SECFailure; + goto cleanup;*/ + } + + rv = ReadFromHeaderFile(headerFileName, PAD, &padItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve PAD detail from header file\n"); + goto cleanup; + } + + if (rv == SECSuccess) { + /* Decrypt and Remove Mac */ + rv = DecryptAndVerifyMac(outFileName, encryptedFileName, + &cipherItem, &macItem, encKey, macKey, &ivItem, &padItem); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed while decrypting and removing MAC\n"); + } + } + + cleanup: + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * EncryptFile + */ + SECStatus + EncryptFile(PK11SlotInfo *slot, + const char *dbdir, + const char *inFileName, + const char *headerFileName, + const char *encryptedFileName, + const char *noiseFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open for read/write and we have authenticated to it. + * generate a symmetric AES key as a token object. + * generate a second key to use for MACing, also a token object. + * get their CKA_IDs + * generate a random value to use as IV for AES CBC + * open an input file and an output file, + * write a header to the output that identifies the two keys by + * their CKA_IDs, May include original file name and length. + * loop until EOF(input) + * read a buffer of plaintext from input file, + * MAC it, append the MAC to the plaintext + * encrypt it using CBC, using previously created IV, + * store the last block of ciphertext as the new IV, + * write the cipher text to intermediate file + * close files + * report success + */ + SECStatus rv; + PRFileDesc *inFile; + PRFileDesc *headerFile; + PRFileDesc *encFile; + + unsigned char *encKeyId = (unsigned char *) "Encrypt Key"; + unsigned char *macKeyId = (unsigned char *) "MAC Key"; + SECItem encKeyID = { siAsciiString, encKeyId, PL_strlen(encKeyId) }; + SECItem macKeyID = { siAsciiString, macKeyId, PL_strlen(macKeyId) }; + + SECItem encCKAID; + SECItem macCKAID; + unsigned char iv[BLOCKSIZE]; + SECItem ivItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + SECItem temp; + unsigned char c; + + /* generate a symmetric AES key as a token object. */ + encKey = GenerateSYMKey(slot, CKM_AES_KEY_GEN, 128/8, &encKeyID, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for AES returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* generate a second key to use for MACing, also a token object. */ + macKey = GenerateSYMKey(slot, CKM_GENERIC_SECRET_KEY_GEN, 160/8, + &macKeyID, pwdata); + if (macKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for MACing returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* get the encrypt key CKA_ID */ + rv = GatherCKA_ID(encKey, &encCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error while wrapping encrypt key\n"); + goto cleanup; + } + + /* get the MAC key CKA_ID */ + rv = GatherCKA_ID(macKey, &macCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Can't get the MAC key CKA_ID.\n"); + goto cleanup; + } + + if (noiseFileName) { + rv = SeedFromNoiseFile(noiseFileName); + if (rv != SECSuccess) { + PORT_SetError(PR_END_OF_FILE_ERROR); + return SECFailure; + } + rv = PK11_GenerateRandom(iv, BLOCKSIZE); + if (rv != SECSuccess) { + goto cleanup; + } + + } else { + /* generate a random value to use as IV for AES CBC */ + GenerateRandom(iv, BLOCKSIZE); + } + + headerFile = PR_Open(headerFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + headerFileName); + return SECFailure; + } + encFile = PR_Open(encryptedFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!encFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* write to a header file the IV and the CKA_IDs + * identifying the two keys + */ + ivItem.type = siBuffer; + ivItem.data = iv; + ivItem.len = BLOCKSIZE; + + rv = WriteToHeaderFile(iv, BLOCKSIZE, IV, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing IV to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + rv = WriteToHeaderFile(encCKAID.data, encCKAID.len, SYMKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing AES CKA_ID to cipher file - %s\n", + encryptedFileName); + goto cleanup; + } + rv = WriteToHeaderFile(macCKAID.data, macCKAID.len, MACKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing MAC CKA_ID to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + + /* Macing and Encryption */ + if (rv == SECSuccess) { + rv = EncryptAndMac(inFile, headerFile, encFile, + encKey, macKey, ivItem.data, ivItem.len, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : Macing and Encryption\n"); + goto cleanup; + } + } + + cleanup: + if (inFile) { + PR_Close(inFile); + } + if (headerFile) { + PR_Close(headerFile); + } + if (encFile) { + PR_Close(encFile); + } + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * This example illustrates basic encryption/decryption and MACing + * Generates the encryption/mac keys and uses token for storing. + * Encrypts the input file and appends MAC before storing in intermediate + * header file. + * Writes the CKA_IDs of the encryption keys into intermediate header file. + * Reads the intermediate headerfile for CKA_IDs and encrypted + * contents and decrypts into output file. + */ + int + main(int argc, char **argv) + { + SECStatus rv; + SECStatus rvShutdown; + PK11SlotInfo *slot = NULL; + PLOptState *optstate; + PLOptStatus status; + char headerFileName[50]; + char encryptedFileName[50]; + PRFileDesc *inFile; + PRFileDesc *outFile; + PRBool ascii = PR_FALSE; + CommandType cmd = UNKNOWN; + const char *command = NULL; + const char *dbdir = NULL; + const char *inFileName = NULL; + const char *outFileName = NULL; + const char *noiseFileName = NULL; + secuPWData pwdata = { PW_NONE, 0 }; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "c:d:i:o:f:p:z:a"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'a': + ascii = PR_TRUE; + break; + case 'c': + command = strdup(optstate->value); + break; + case 'd': + dbdir = strdup(optstate->value); + break; + case 'f': + pwdata.source = PW_FROMFILE; + pwdata.data = strdup(optstate->value); + break; + case 'p': + pwdata.source = PW_PLAINTEXT; + pwdata.data = strdup(optstate->value); + break; + case 'i': + inFileName = strdup(optstate->value); + break; + case 'o': + outFileName = strdup(optstate->value); + break; + case 'z': + noiseFileName = strdup(optstate->value); + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (!command || !dbdir || !inFileName || !outFileName) + Usage(progName); + if (PL_strlen(command)==0) + Usage(progName); + + cmd = command[0] == 'a' ? ENCRYPT : command[0] == 'b' ? DECRYPT : UNKNOWN; + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + PR_Close(inFile); + + /* For intermediate header file, choose filename as inputfile name + with extension ".header" */ + strcpy(headerFileName, inFileName); + strcat(headerFileName, ".header"); + + /* For intermediate encrypted file, choose filename as inputfile name + with extension ".enc" */ + strcpy(encryptedFileName, inFileName); + strcat(encryptedFileName, ".enc"); + + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + + switch (cmd) { + case ENCRYPT: + /* If the intermediate header file already exists, delete it */ + if (PR_Access(headerFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(headerFileName); + } + /* If the intermediate encrypted already exists, delete it */ + if (PR_Access(encryptedFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(encryptedFileName); + } + + /* Open DB for read/write and authenticate to it. */ + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); + goto cleanup; + } + + PK11_SetPasswordFunc(GetModulePassword); + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + rv = EncryptFile(slot, dbdir, + inFileName, headerFileName, encryptedFileName, + noiseFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "EncryptFile : Failed\n"); + return SECFailure; + } + break; + case DECRYPT: + /* Open DB read only, authenticate to it */ + PK11_SetPasswordFunc(GetModulePassword); + + rv = NSS_Init(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_Init Failed\n"); + return SECFailure; + } + + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + + rv = DecryptFile(slot, dbdir, + outFileName, headerFileName, + encryptedFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "DecryptFile : Failed\n"); + return SECFailure; + } + break; + } + + cleanup: + rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); + rv = SECFailure; + } + + PR_Cleanup(); + + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/faq/index.rst b/security/nss/doc/rst/legacy/faq/index.rst new file mode 100644 index 0000000000..6c022e7ff1 --- /dev/null +++ b/security/nss/doc/rst/legacy/faq/index.rst @@ -0,0 +1,280 @@ +.. _mozilla_projects_nss_faq: + +NSS FAQ +======= + +.. _general_questions: + +`General Questions <#general_questions>`__ +------------------------------------------ + +.. _what_is_network_security_services_.28nss.29: + +`What is Network Security Services (NSS) <#what_is_network_security_services_.28nss.29>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS is set of libraries, APIs, utilities, and documentation designed to support cross-platform + development of security-enabled client and server applications. It provides a complete + open-source implementation of the crypto libraries used by Mozilla and other companies in the + Firefox browser, AOL Instant Messenger (AIM), server products from Red Hat, and other products. + + For an overview of NSS, see :ref:`mozilla_projects_nss_overview`. For detailed information on the + open-source NSS project, see `NSS Project Page <https://wiki.mozilla.org/NSS>`__. + +.. _what_can_i_do_with_nss.3f_is_nss_appropriate_for_my_application.3f: + +`What can I do with NSS? Is NSS appropriate for my application? <#what_can_i_do_with_nss.3f_is_nss_appropriate_for_my_application.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + If you want add support for SSL, S/MIME, or other Internet security standards to your + application, you can use Network Security Services (NSS) to do so. Because NSS provides complete + support for all versions of SSL and TLS, it is particularly well-suited for applications that + need to communicate with the many clients and servers that already support the SSL protocol. + + The PKCS #11 interface included in NSS means that your application can use `hardware + accelerators <#what_hardware_accelerators_are_supported.3f>`__ on the server and + :ref:`mozilla_projects_nss_faq#how_do_i_integrate_smart_cards_into_my_application_using_nss_3f` + for two-factor authentication. + +.. _how_does_nss_compare_to_openssl.3f: + +`How does NSS compare to OpenSSL? <#how_does_nss_compare_to_openssl.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + `OpenSSL <https://www.openssl.org/>`__ is an open source project that implements server-side SSL, + TLS, and a general-purpose cryptography library. It does not support PKCS #11. It is based on the + SSLeay library developed by Eric A. Young and Tim J. Hudson. OpenSSL is widely used in Apache + servers and is licensed under an Apache-style licence. + + NSS supports both server and client applications as well as + :ref:`mozilla_projects_nss_pkcs11_faq` and S/MIME. To permit its use in as many contexts as + possible, NSS is licensed under the `Mozilla Public License <https://www.mozilla.org/MPL/>`__, + version 2. + +.. _how_does_nss_compare_to_sslref.3f: + +`How does NSS compare to SSLRef? <#how_does_nss_compare_to_sslref.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + SSLRef was an early reference implementation of the SSL protocol. It contains bugs that were + never fixed, doesn't support TLS or the new 56-bit export cipher suites, and does not contain the + fix to the Bleichenbacher attack on PKCS#1. + + Netscape no longer maintains SSLRef or makes it available. It was built as an example of an SSL + implementation, not for creating production applications. + + NSS was designed from the ground up for use by commercial developers. It provides a complete + software development kit that uses the same architecture used to support security features in + many client and server products from Netscape and other companies. + +.. _what_platforms_and_development_environments_are_supported.3f: + +`What platforms and development environments are supported? <#what_platforms_and_development_environments_are_supported.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. warning:: + + This section is out of date + + iPlanet E-Commerce Solutions has certified NSS 3.1 on 18 platforms, including AIX 4.3, HP-UX + 11.0, Red Hat Linux 6.0, Solaris (2.6 or later), Windows NT (4.0 or later), and Windows 2000. + Other contributors are in the process of certifying additional platforms. The NSS 3.1 API + requires C or C++ development environments. + + For the latest NSS release notes and detailed platform information, see `Project + Information <https://wiki.mozilla.org/NSS>`__. + +.. _what_cryptography_standards_are_supported.3f: + +`What cryptography standards are supported? <#what_cryptography_standards_are_supported.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS supports `SSL v2 and v3 <https://developer.mozilla.org/en-US/docs/Glossary/SSL>`__, + `TLS <https://developer.mozilla.org/en-US/docs/Glossary/TLS>`__, `PKCS + #5 <https://developer.mozilla.org/en-US/docs/Glossary/PKCS_.235>`__, `PKCS + #7 <https://developer.mozilla.org/en-US/docs/Glossary/PKCS_.237>`__, `PKCS + #11 <https://developer.mozilla.org/en-US/docs/Glossary/PKCS_.2311>`__, `PKCS + #12 <https://developer.mozilla.org/en-US/docs/Glossary/PKCS_.2312>`__, + `S/MIME <https://developer.mozilla.org/en-US/Glossary/en-US/docs/Glossary/S.2FMIME>`__, and + `X.509 v3 <https://developer.mozilla.org/en-US/docs/Mozilla/Security/x509_Certificates>`__ + certificates. For complete details, see `Encryption Technologies Available in NSS + 3.11 <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11/nss-3.11-algorithms.html>`__ + +.. _what_is_the_relationship_between_nss_and_psm.3f: + +`What is the relationship between NSS and PSM? <#what_is_the_relationship_between_nss_and_psm.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Personal Security Manager (PSM) is built on top of NSS. It consists of libraries and a daemon + designed to support cross-platform development of security-enabled client applications. The PSM + binary provides a client module that performs cryptographic operations on behalf of applications. + Netscape Personal Security Manager ships with Netscape 6 and the Gateway Connected Touch Pad with + Instant AOL, and is also available for use with Communicator 4.7x. + +.. _where_can_i_get_the_source.3f: + +`Where can I get the source? <#where_can_i_get_the_source.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For instructions on how to check out and build the NSS source code, see + :ref:`mozilla_projects_nss_nss_sources_building_testing`. + +.. _how_much_does_it_cost.3f: + +`How much does it cost? <#how_much_does_it_cost.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS source code and binaries (when they become available) are completely free. No license fees, + no royalty fees, no subscription fees. + +.. _developer_questions: + +`Developer Questions <#developer_questions>`__ +---------------------------------------------- + +.. _what_hardware_accelerators_are_supported.3f: + +`What hardware accelerators are supported? <#what_hardware_accelerators_are_supported.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS supports the PKCS #11 interface for hardware acceleration. Since leading accelerator vendors + such as Chrysalis-IT, nCipher, and Rainbow Technologies also support this interface, NSS-enabled + applications can support a wide variety of hardware accelerators. + +.. _how_do_i_integrate_smart_cards_into_my_application_using_nss.3f: + +`How do I integrate smart cards into my application using NSS? <#how_do_i_integrate_smart_cards_into_my_application_using_nss.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS supports the PKCS #11 interface for smart card integration. Applications that use the PKCS + #11 interface provided by NSS will therefore support smart cards from leading vendors such as + ActiveCard, Litronic, SafeNet, and SecureID Technologies that also support the PKCS #11 + interface. + +.. _does_nss_require_netscape_portable_runtime_.28nspr.29.3f: + +`Does NSS require Netscape Portable Runtime (NSPR)? <#does_nss_require_netscape_portable_runtime_.28nspr.29.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: To provide cross-platform support, NSS utilizes Netscape Portable Runtime (NSPR) + libraries as a portability interface and implementation that provides consistent + cross-platform semantics for network I/O and threading models. You can use NSPR throughout + your application or only in the portion that calls into NSS. Mozilla strongly recommends that + multithreaded applications use the NSPR or native OS threading model. (In recent NSPR + releases, the NSPR threading model is compatible with the native threading model if the OS has + native threads.) Alternatively, you can adapt the open-source NSPR implementation to be + compatible with your existing application's threading models. More information about NSPR may + be found at `Netscape Portable + Runtime <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR>`__. + :name: to_provide_cross-platform_support_nss_utilizes_netscape_portable_runtime_nspr_libraries_as_a_portability_interface_and_implementation_that_provides_consistent_cross-platform_semantics_for_network_io_and_threading_models._you_can_use_nspr_throughout_your_application_or_only_in_the_portion_that_calls_into_nss._mozilla_strongly_recommends_that_multithreaded_applications_use_the_nspr_or_native_os_threading_model._in_recent_nspr_releases_the_nspr_threading_model_is_compatible_with_the_native_threading_model_if_the_os_has_native_threads._alternatively_you_can_adapt_the_open-source_nspr_implementation_to_be_compatible_with_your_existing_applications_threading_models._more_information_about_nspr_may_be_found_at_netscape_portable_runtime. + +.. _can_i_use_nss_even_if_my_application_protocol_isn.27t_http.3f: + +`Can I use NSS even if my application protocol isn't HTTP? <#can_i_use_nss_even_if_my_application_protocol_isn.27t_http.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Yes, TLS is independent of application protocols. It works with common Internet standard + application protocols (HTTP, POP3, FTP, SMTP, etc.) as well as custom application protocols using + TCP/IP. + +.. _how_long_does_it_take_to_integrate_nss_into_my_application.3f: + +`How long does it take to integrate NSS into my application? <#how_long_does_it_take_to_integrate_nss_into_my_application.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The integration effort depends on an number of factors, such as developer skill set, application + complexity, and the level of security required for your application. NSS includes detailed + documentation of the SSL API and sample code that demonstrates basic SSL functionality (setting + up an encrypted session, server authentication, and client authentication) to help jump start the + integration process. However, there is little or no documentation currently available for the + rest of the NSS API. If your application requires sophisticated certificate management, smart + card support, or hardware acceleration, your integration effort will be more extensive. + +.. _where_can_i_download_the_nss_tools.3f: + +`Where can I download the NSS tools? <#where_can_i_download_the_nss_tools.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Binary builds of NSS for several platforms including the command-line tools can be downloaded + from + `http://ftp.mozilla.org/pub/mozilla.o...y/nss/releases/ <http://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/>`__. + NSPR, which you will need as well, can be downloaded from + http://ftp.mozilla.org/pub/mozilla.org/nspr/releases/. + +.. _how_can_i_learn_more_about_ssl.3f: + +`How can I learn more about TLS? <#how_can_i_learn_more_about_ssl.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + See https://developer.mozilla.org/en-US/docs/Glossary/TLS. + +.. _licensing_questions: + +`Licensing Questions <#licensing_questions>`__ +---------------------------------------------- + +.. _how_is_nss_licensed.3f: + +`How is NSS licensed? <#how_is_nss_licensed.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS is available under the `Mozilla Public License <https://www.mozilla.org/MPL/>`__, version 2. + +.. _is_nss_available_outside_the_united_states.3f: + +`Is NSS available outside the United States? <#is_nss_available_outside_the_united_states.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. warning:: + + This section is out of date + + Yes; see `Build Instructions for NSS + 3.1. <NSS_reference/Building_and_installing_NSS/Build_instructions>`__ and + ftp://ftp.mozilla.org/pub/mozilla.org/security/. However, NSS source code is subject to the U.S. + Export Administration Regulations and other U.S. law, and may not be exported or re-exported to + certain countries (Cuba, Iran, Iraq, Libya, North Korea, Serbia, Sudan, Syria, and + Taleban-controlled areas of Afghanistan as of January 2000) or to persons or entities prohibited + from receiving U.S. exports (including those (a) on the Bureau of Industry and Security Denied + Parties List or Entity List, (b) on the Office of Foreign Assets Control list of Specially + Designated Nationals and Blocked Persons, and (c) involved with missile technology or nuclear, + chemical or biological weapons). + + For more information about U.S. export controls on encryption software, see the `Mozilla Crypto + FAQ <Mozilla_Crypto_FAQ#1-3>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/fips_mode_-_an_explanation/index.rst b/security/nss/doc/rst/legacy/fips_mode_-_an_explanation/index.rst new file mode 100644 index 0000000000..3e141cca5d --- /dev/null +++ b/security/nss/doc/rst/legacy/fips_mode_-_an_explanation/index.rst @@ -0,0 +1,129 @@ +.. _mozilla_projects_nss_fips_mode_-_an_explanation: + +FIPS Mode - an explanation +========================== + +.. container:: + + NSS has a "FIPS Mode" that can be enabled when NSS is compiled in a specific way. (Note: Mozilla + does not distribute a "FIPS Mode"-ready NSS with Firefox.) This page attempts to provide an + informal explanation of what it is, who would use it, and why. + +.. _what's_a_fips: + +`What's a FIPS? <#what's_a_fips>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The United States government defines many (several hundred) "Federal Information Processing + Standard" (FIPS) documents. (FIPS sounds plural, but is singular; one FIPS document is a FIPS, + not a FIP.) FIPS documents define rules, regulations, and standards for many aspects of handling + of information by computers and by people. They apply to all US government employees and + personnel, including soldiers in the armed forces. Generally speaking, any use of a computer by + US government personnel must conform to all the relevant FIPS regulations. If you're a + US government worker, and you want to use a Mozilla software product such as Firefox, or any + product that uses NSS, you will want to use it in a way that is fully conformant with all the + relevant FIPS regulations. Some other governments have also adopted many of the FIPS + regulations, so their applicability is somewhat wider than just the US government's personnel. + +.. _what_is_fips_mode: + +`What is "FIPS Mode"? <#what_is_fips_mode>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + One of the FIPS regulations, FIPS 140, governs the use of encryption and cryptographic services. + It requires that ALL cryptography done by US government personnel MUST be done in "devices" that + have been independently tested, and certified by NIST, to meet the extensive requirements of that + document. These devices may be hardware or software, but either way, they must function and + behave as prescribed. So, in order for Mozilla Firefox and Thunderbird to be usable by people + who are subject to the FIPS regulations, Mozilla's cryptographic software must be able to operate + in a mode that is fully compliant with FIPS 140. To that end, Mozilla products can function in a + "FIPS Mode", which is really "FIPS 140 Mode", when paired with a compliant copy of NSS. (Note, + the current version of FIPS 140 is revision 2, a.k.a. FIPS 140-2. FIPS 140-3 is being devised by + NIST now for adoption in the future.) Users who are subject to the FIPS regulations must ensure + that they have Mozilla's FIPS Mode enabled when they use Mozilla software, in order to be fully + conformant. Instructions for how to configure Firefox into FIPS mode may be found on + `support.mozilla.com <https://support.mozilla.com/en-US/kb/Configuring+Firefox+for+FIPS+140-2>`__. + +.. _is_nss_fips-140_compliant: + +`Is NSS FIPS-140 compliant? <#is_nss_fips-140_compliant>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Mozilla's NSS cryptographic software has been tested by government-approved independent testing + labs and certified by NIST as being FIPS 140 compliant *when operated in FIPS mode* on 4 previous + occasions. As of this writing, NSS is now being retested to be recertified for the fifth time. + NSS was the first open source cryptographic library to be FIPS certified. + +.. _what_is_fips_mode_all_about: + +`What is FIPS Mode all about? <#what_is_fips_mode_all_about>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A FIPS-140 compliant application must do ALL of its cryptography in a FIPS-140 certified + "device". Whether it is hardware or software, that device will have all the cryptographic + engines in it, and also will stores keys and perhaps certificates inside. The device must have a + way for users to authenticate to it (to "login" to it), to prove to it that they are authorized + to use the cryptographic engines and keys it contains. It may not do ANY cryptographic + operations that involve the use of cryptographic keys, nor allow ANY of the keys or certificates + it holds to be seen or used, except when a user has successfully authenticated to it. If users + authenticate to it with a password, it must ensure that their passwords are strong passwords. It + must implement the US government standard algorithms (also specified in other FIPS documents) + such as AES, triple-DES, SHA-1 and SHA-256, that are needed to do whatever job the application + wants it to perform. It must generate or derive cryptographic keys and store them internally. + Except for "public keys", it must not allow any keys to leave it (to get outside of it) unless + they are encrypted ("wrapped") in a special way. This makes it difficult to move keys from one + device to another, and consequently, all crypto engines and key storage must be in a single + device rather than being split up into several devices. + +.. _how_does_this_affect_firefox_users: + +`How does this affect Firefox users? <#how_does_this_affect_firefox_users>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These requirements have several implications for users. In FIPS Mode, every user must have a + good strong "master password", and must enter it each time they start or restart Firefox before + they can visit any web sites that use cryptography (https). Firefox can only use the latest + version of SSL, known as "TLS", and not the older SSL 2 or SSL 3.0 protocols, and Firefox can + only talk to those servers that use FIPS standard encryption algorithms such as AES or + triple-DES. Servers that can only use non-FIPS-approved encryption, such as RC4, cannot be used + in FIPS mode. + +.. _how_is_fips_mode_different_from_normal_non-fips_mode: + +`How is FIPS Mode different from normal non-FIPS Mode? <#how_is_fips_mode_different_from_normal_non-fips_mode>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + In normal non-FIPS Mode, the "master password" is optional and is allowed to be a weak short + password. The user is only required to enter his master password to use his own private keys (if + he has any) or to access his stored web-site passwords. The user is not required to enter the + master password to visit ordinary https servers, nor to view certificates he has previously + stored. In non-FIPS mode, NSS is willing and able to use popular non-FIPS approved cryptographic + algorithms, such as RC4 and MD5, to communicate with older https servers. NSS divides its + operations up into two "devices" rather than just one. One device does all the operations that + may be done without needing to authenticate, and the other device stores the user's certificates + and private keys and performs operations that use those private keys. + +.. _how_do_i_put_firefox_into_fips_mode: + +`How do I put Firefox into FIPS Mode? <#how_do_i_put_firefox_into_fips_mode>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Instructions for how to configure Firefox into FIPS mode may be found on + `support.mozilla.com <https://support.mozilla.com/en-US/kb/Configuring+Firefox+for+FIPS+140-2>`__. + Some third-parties distribute Firefox ready for FIPS mode, `a partial list can be found at the + NSS + wiki <https://wiki.mozilla.org/FIPS_Validation#Products_Implementing_FIPS_140-2_Validated_NSS>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/http_delegation/index.rst b/security/nss/doc/rst/legacy/http_delegation/index.rst new file mode 100644 index 0000000000..f0288507d9 --- /dev/null +++ b/security/nss/doc/rst/legacy/http_delegation/index.rst @@ -0,0 +1,105 @@ +.. _mozilla_projects_nss_http_delegation: + +HTTP delegation +=============== + +`Background <#background>`__ +---------------------------- + +.. container:: + + Up to version 3.11, :ref:`mozilla_projects_nss` connects directly over + `HTTP <https://developer.mozilla.org/en-US/docs/Web/HTTP>`__ to an OCSP responder to make the + request and fetch the response. It does so in a blocking fashion, and also directly to the + responder, ignoring any proxy the application may wish to use. This causes OCSP requests to fail + if the network environment requires the use of a proxy. + + There are two possible solutions to this limitation. Instead of improving the simple HTTP client + in NSS, the NSS team has decided to provide an NSS API to register application callback + functions. If provided by the application, NSS will use the registered HTTP client for querying + an OSCP responder. + + This NSS feature is currently targeted to first appear in NSS version 3.11.1. More details can be + found in `bug 152426 <https://bugzilla.mozilla.org/show_bug.cgi?id=152426>`__. + + In order to use the HTTP Delegation feature in your NSS-based application, you need to implement + several callback functions. Your callback functions might be a full implementation of a HTTP + client. Or you might choose to leverage an existing HTTP client library and implement the + callback functions as a thin layer that forwards requests from NSS to the HTTP client library. + + To learn about all the details, please read the documentation contained in the NSS C header + files. Look for function SEC_RegisterDefaultHttpClient and all functions having names that start + with SEC_Http. + + To find an example implementation, you may look at + `bug 111384 <https://bugzilla.mozilla.org/show_bug.cgi?id=111384>`__, which tracks the + implementation in Mozilla client applications. + +.. _instructions_for_specifying_an_ocsp_proxy: + +`Specifying an OCSP proxy <#instructions_for_specifying_an_ocsp_proxy>`__ +------------------------------------------------------------------------- + +.. container:: + + The remainder of this document is a short HOWTO. + + One might expect the API defines a simple function that accepts the URI and data to be sent, and + returns the result data. But there is no such simple interface. + + The API should allow NSS to use the HTTP client either asynchronously or synchronously. In + addition, during an application session with OCSP enabled, a large number of OCSP requests might + have to be sent. Therefore the API should allow for keep-alive (persistent) HTTP connections. + + HTTP URIs consist of host:port and a path, e.g. + http://ocsp.provider.com:80/cgi-bin/ocsp-responder + + If NSS needs to access a HTTP server, it will request that an "http server session object" be + created (SEC_HttpServer_CreateSessionFcn). + + The http server session object is logically associated with host and port destination + information, in our example this is "host ocsp.provider.com port 80". The object may be used by + the application to associate it with a physical network connection. + + (NSS might choose to be smart, and only create a single http server session object for each + server encountered. NSS might also choose to be simple, and request multiple objects for the same + server. The application must support both strategies.) + + The logical http server session object is expected to remain valid until explicitly destroyed + (SEC_HttpServer_FreeSessionFcn). Should the application be unable to keep a physical connection + alive all the time, the application is expected to create new connections automatically. + + NSS may choose to repeatedly call a "network connection keep alive" function + (SEC_HttpServer_KeepAliveSessionFcn) on the server session object, giving application code a + chance to do whatever is required. + + For each individual HTTP request, NSS will request the creation of a "http request object" + (SEC_HttpRequest_CreateFcn). No full URI is provided as a parameter. Instead, the parameters are + a server session object (that carries host and port information already) and the request path. In + our example the path is "/cgi-bin/ocsp-responder". (When issueing GET requests, the + "?query-string=data" portion should already be appended to the request path) + + After creation, NSS might call functions to provide additional details of the HTTP request (e.g. + SEC_HttpRequest_SetPostDataFcn). The application is expected to collect the details for later + use. + + Once NSS is finished providing all details, it will request to initiate the actual network + communication (SEC_HttpRequest_TrySendAndReceiveFcn). The application should try to reuse + existing network connections associated with the server session object. + + Once the HTTP response has been obtained from the HTTP server, the function will provide the + results in its "out parameters". + + Please read the source code documentation to learn how to use this API synchronously or + asynchronously. + + Now that we have explained the interaction between NSS, the callback functions and the + application, let's look at the steps required by the application to initially register the + callbacks. + + Make sure you have completed the NSS initialization before you attempt to register the callbacks. + + Look at SEC_HttpClientFcn, which is a (versioned) table of function pointers. Create an instance + of this type and supply a pointer to your implementation for each entry in the function table. + + Finally register your HTTP client implementation with a call to SEC_RegisterDefaultHttpClient.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/http_delegation_clone/index.rst b/security/nss/doc/rst/legacy/http_delegation_clone/index.rst new file mode 100644 index 0000000000..ac305b2dd3 --- /dev/null +++ b/security/nss/doc/rst/legacy/http_delegation_clone/index.rst @@ -0,0 +1,105 @@ +.. _mozilla_projects_nss_http_delegation_clone: + +HTTP delegation +=============== + +`Background <#background>`__ +---------------------------- + +.. container:: + + Up to version 3.11, :ref:`mozilla_projects_nss` connects directly over + `HTTP <https://developer.mozilla.org/en-US/docs/Web/HTTP>`__ to an OCSP responder to make the + request and fetch the response. It does so in a blocking fashion, and also directly to the + responder, ignoring any proxy the application may wish to use. This causes OCSP requests to fail + if the network environment requires the use of a proxy. + + There are two possible solutions to this limitation. Instead of improving the simple HTTP client + in NSS, the NSS team has decided to provide an NSS API to register application callback + functions. If provided by the application, NSS will use the registered HTTP client for querying + an OSCP responder. + + This NSS feature is currently targeted to first appear in NSS version 3.11.1. More details can be + found in `bug 152426 <https://bugzilla.mozilla.org/show_bug.cgi?id=152426>`__. + + In order to use the HTTP Delegation feature in your NSS-based application, you need to implement + several callback functions. Your callback functions might be a full implementation of a HTTP + client. Or you might choose to leverage an existing HTTP client library and implement the + callback functions as a thin layer that forwards requests from NSS to the HTTP client library. + + To learn about all the details, please read the documentation contained in the NSS C header + files. Look for function SEC_RegisterDefaultHttpClient and all functions having names that start + with SEC_Http. + + To find an example implementation, you may look at + `bug 111384 <https://bugzilla.mozilla.org/show_bug.cgi?id=111384>`__, which tracks the + implementation in Mozilla client applications. + +.. _instructions_for_specifying_an_ocsp_proxy: + +`Specifying an OCSP proxy <#instructions_for_specifying_an_ocsp_proxy>`__ +------------------------------------------------------------------------- + +.. container:: + + The remainder of this document is a short HOWTO. + + One might expect the API defines a simple function that accepts the URI and data to be sent, and + returns the result data. But there is no such simple interface. + + The API should allow NSS to use the HTTP client either asynchronously or synchronously. In + addition, during an application session with OCSP enabled, a large number of OCSP requests might + have to be sent. Therefore the API should allow for keep-alive (persistent) HTTP connections. + + HTTP URIs consist of host:port and a path, e.g. + http://ocsp.provider.com:80/cgi-bin/ocsp-responder + + If NSS needs to access a HTTP server, it will request that an "http server session object" be + created (SEC_HttpServer_CreateSessionFcn). + + The http server session object is logically associated with host and port destination + information, in our example this is "host ocsp.provider.com port 80". The object may be used by + the application to associate it with a physical network connection. + + (NSS might choose to be smart, and only create a single http server session object for each + server encountered. NSS might also choose to be simple, and request multiple objects for the same + server. The application must support both strategies.) + + The logical http server session object is expected to remain valid until explicitly destroyed + (SEC_HttpServer_FreeSessionFcn). Should the application be unable to keep a physical connection + alive all the time, the application is expected to create new connections automatically. + + NSS may choose to repeatedly call a "network connection keep alive" function + (SEC_HttpServer_KeepAliveSessionFcn) on the server session object, giving application code a + chance to do whatever is required. + + For each individual HTTP request, NSS will request the creation of a "http request object" + (SEC_HttpRequest_CreateFcn). No full URI is provided as a parameter. Instead, the parameters are + a server session object (that carries host and port information already) and the request path. In + our example the path is "/cgi-bin/ocsp-responder". (When issuing GET requests, the + "?query-string=data" portion should already be appended to the request path) + + After creation, NSS might call functions to provide additional details of the HTTP request (e.g. + SEC_HttpRequest_SetPostDataFcn). The application is expected to collect the details for later + use. + + Once NSS is finished providing all details, it will request to initiate the actual network + communication (SEC_HttpRequest_TrySendAndReceiveFcn). The application should try to reuse + existing network connections associated with the server session object. + + Once the HTTP response has been obtained from the HTTP server, the function will provide the + results in its "out parameters". + + Please read the source code documentation to learn how to use this API synchronously or + asynchronously. + + Now that we have explained the interaction between NSS, the callback functions and the + application, let's look at the steps required by the application to initially register the + callbacks. + + Make sure you have completed the NSS initialization before you attempt to register the callbacks. + + Look at SEC_HttpClientFcn, which is a (versioned) table of function pointers. Create an instance + of this type and supply a pointer to your implementation for each entry in the function table. + + Finally register your HTTP client implementation with a call to SEC_RegisterDefaultHttpClient.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/index.rst b/security/nss/doc/rst/legacy/index.rst new file mode 100644 index 0000000000..fd55e1ac10 --- /dev/null +++ b/security/nss/doc/rst/legacy/index.rst @@ -0,0 +1,178 @@ +.. _mozilla_projects_nss: + +Legacy documentation +==================== + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + getting_started_with_nss/index.rst + introduction_to_network_security_services/index.rst + More documentation <more_docs> + +.. 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. + +Legacy 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 +~~~~~~~~~ + +- 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 +~~~~~~~~~~~~~~ + +- `Security <https://developer.mozilla.org/en-US/docs/Security>`__ + diff --git a/security/nss/doc/rst/legacy/introduction_to_network_security_services/index.rst b/security/nss/doc/rst/legacy/introduction_to_network_security_services/index.rst new file mode 100644 index 0000000000..b2010de17b --- /dev/null +++ b/security/nss/doc/rst/legacy/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 diff --git a/security/nss/doc/rst/legacy/jss/4.3.1_release_notes/index.rst b/security/nss/doc/rst/legacy/jss/4.3.1_release_notes/index.rst new file mode 100644 index 0000000000..68c920c63b --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/4.3.1_release_notes/index.rst @@ -0,0 +1,174 @@ +.. _mozilla_projects_nss_jss_4_3_1_release_notes: + +4.3.1 Release Notes +=================== + +.. _release_date_2009-12-02: + +`Release Date: 2009-12-02 <#release_date_2009-12-02>`__ +------------------------------------------------------- + +.. container:: + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services for Java (JSS) 4.3.1 is a minor release with the following new + features: + + - Support for SSL3 & TLS Renegotiation Vulnerability + - Support to explicitly set the key usage for the generated private key + + JSS 4.3.1 is `tri-licensed <https://www.mozilla.org/MPL>`__ under MPL 1.1/GPL 2.0/LGPL 2.1. + +.. _new_in_jss_4.3.1: + +`New in JSS 4.3.1 <#new_in_jss_4.3.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A list of bug fixes and enhancement requests were implemented in this release can be obtained by + running this `bugzilla + query <http://bugzilla.mozilla.org/buglist.cgi?product=JSS&target_milestone=4.3.1&target_milestone=4.3.1&bug_status=RESOLVED&resolution=FIXED>`__ + + **JSS 4.3.1 requires :ref:`mozilla_projects_nss_3_12_5_release_notes` or higher.** + + .. rubric:: SSL3 & TLS Renegotiation Vulnerability + :name: ssl3_tls_renegotiation_vulnerability + + See `CVE-2009-3555 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-3555>`__ and `US-CERT + VU#120541 <http://www.kb.cert.org/vuls/id/120541>`__ for more information about this security + vulnerability. + + All SSL/TLS renegotiation is disabled by default in NSS 3.12.5 and therefore will be disabled by + default with JSS 4.3.1. This will cause programs that attempt to perform renegotiation to + experience failures where they formerly experienced successes, and is necessary for them to not + be vulnerable, until such time as a new safe renegotiation scheme is standardized by the IETF. + + If an application depends on renegotiation feature, it can be enabled by setting the environment + variable NSS_SSL_ENABLE_RENEGOTIATION to 1. By setting this environmental variable, the fix + provided by these patches will have no effect and the application may become vulnerable to the + issue. + + This default setting can also be changed within the application by using the following JSS + methods: + + - SSLServerSocket.enableRenegotiation(int mode) + - SSLSocket.enableRenegotiation(int mode) + - SSLSocket.enableRenegotiationDefault(int mode) + + The mode of renegotiation that the peer must use can be set to the following: + + - SSLSocket.SSL_RENEGOTIATE_NEVER - Never renegotiate at all. (Default) + - SSLSocket.SSL_RENEGOTIATE_UNRESTRICTED - Renegotiate without + restriction, whether or not the peer's client hello bears the + renegotiation info extension (like we always did in the past). + - SSLSocket.SSL_RENEGOTIATE_REQUIRES_XTN - NOT YET IMPLEMENTED + + .. rubric:: Explicitly set the key usage for the generated private key + :name: explicitly_set_the_key_usage_for_the_generated_private_key + + | In PKCS #11, each keypair can be marked with the operations it will + | be used to perform. Some tokens require that a key be marked for + | an operation before the key can be used to perform that operation; + | other tokens don't care. NSS/JSS provides a way to specify a set of + | flags and a corresponding mask for these flags. + + - see generateECKeyPairWithOpFlags + - see generateRSAKeyPairWithOpFlags + - see generateDSAKeyPairWithOpFlags + + + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS is checked into ``mozilla/security/jss/``. + - The CVS tag for the JSS 4.3.1 release is ``JSS_4_3_1_RTM``. + - Source tarballs are available from + `ftp://ftp.mozilla.org/pub/mozilla.or...-4.3.1.tar.bz2 <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM/src/jss-4.3.1.tar.bz2>`__ + - Binary releases are no longer available on mozilla. JSS is a JNI library we provide the + jss4.jar but expect you to build the JSS's matching JNI shared library. We provide the + jss4.jar in case you do not want to obtain your own JCE code signing certificate. JSS is a + JCE provider and therefore the jss4.jar must be signed. + `ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM/>`__. + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Documentation for JSS 4.3.1 is available as follows: + + - `Build Instructions for JSS 4.3.1 </jss_build_4.3.1.html>`__ + - Javadoc `[online] </javadoc>`__ + `[zipped] <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM/doc/JSS_4_3_1_RTM-doc.zip>`__ + - Read the instructions on `using JSS </using_jss.html>`__. + - Source may be viewed with a browser (via the MXR tool) at + http://mxr.mozilla.org/mozilla/source/security/jss/ + - The RUN TIME behavior of JSS can be affected by the + :ref:`mozilla_projects_nss_reference_nss_environment_variables`. + +.. _platform_information: + +`Platform Information <#platform_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - You can check out the source from CVS by + + .. note:: + + cvs co -r JSS_4_3_1_RTM JSS + + - JSS 4.3.1 works with JDK versions 4 or higher we suggest the latest. + + - JSS 4.3.1 requires :ref:`mozilla_projects_nss_3_12_5` or higher. + + - JSS 4.3.1 requires `NSPR 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/>`__ or + higher. + + - JSS only supports the native threading model (no green threads). + +.. _known_bugs_and_issues: + +`Known Bugs and Issues <#known_bugs_and_issues>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - For a list of reported bugs that have not yet been fixed, `click + here. <http://bugzilla.mozilla.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&&product=JSS>`__ + Note that some bugs may have been fixed since JSS 4.3.1 was released. + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 4.3.1 is backwards compatible with JSS 4.2. Applications compiled against JSS 4.2 will + work with JSS 4.3.1. + - The 4.3.1 version of libjss4.so/jss4.dll must only be used with jss4.jar. In general, a JSS + JAR file must be used with the JSS shared library from the exact same release. + - To obtain the version info from the jar file use, + "System.out.println(org.mozilla.jss.CryptoManager.JAR_JSS_VERSION)" and to check the shared + library: strings libjss4.so \| grep -i header + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Bugs discovered should be reported by filing a bug report with + `bugzilla <http://bugzilla.mozilla.org/enter_bug.cgi?product=JSS>`__. + - You can also give feedback directly to the developers on the 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>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/4_3_releasenotes/index.rst b/security/nss/doc/rst/legacy/jss/4_3_releasenotes/index.rst new file mode 100644 index 0000000000..7f65d1d4ed --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/4_3_releasenotes/index.rst @@ -0,0 +1,175 @@ +.. _mozilla_projects_nss_jss_4_3_releasenotes: + +4.3 Release Notes +================= + +.. _release_date_01_april_2009: + +`Release Date: 01 April 2009 <#release_date_01_april_2009>`__ +------------------------------------------------------------- + +.. container:: + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services for Java (JSS) 4.3 is a minor release with the following new features: + + - SQLite-Based Shareable Certificate and Key Databases + - libpkix: an RFC 3280 Compliant Certificate Path Validation Library + - PKCS11 needsLogin method + - support HmacSHA256, HmacSHA384, and HmacSHA512 + - support for all NSS 3.12 initialization options + + JSS 4.3 is `tri-licensed <https://www.mozilla.org/MPL>`__ under MPL 1.1/GPL 2.0/LGPL 2.1. + +.. _new_in_jss_4.3: + +`New in JSS 4.3 <#new_in_jss_4.3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A list of bug fixes and enhancement requests were implemented in this release can be obtained by + running this `bugzilla + query <http://bugzilla.mozilla.org/buglist.cgi?product=JSS&target_milestone=4.2.5&target_milestone=4.3&bug_status=RESOLVED&resolution=FIXED>`__ + + **JSS 4.3 requires**\ `NSS + 3.12 <https://www.mozilla.org/projects/security/pki/nss/nss-3.12/nss-3.12-release-notes.html>`__\ **or + higher.** + + - New `SQLite-Based Shareable Certificate and Key + Databases <https://wiki.mozilla.org/NSS_Shared_DB>`__ by prepending the string "sql:" to the + directory path passed to configdir parameter for Crypomanager.initialize method or using the + NSS environment variable :ref:`mozilla_projects_nss_reference_nss_environment_variables`. + - Libpkix: an RFC 3280 Compliant Certificate Path Validation Library (see + `PKIXVerify <http://mxr.mozilla.org/mozilla/ident?i=PKIXVerify>`__) + - PK11Token.needsLogin method (see needsLogin) + - support HmacSHA256, HmacSHA384, and HmacSHA512 (see + `HMACTest.java <http://mxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/tests/HMACTest.java>`__) + - support for all NSS 3.12 initialization options (see InitializationValues) + - New SSL error codes (see https://mxr.mozilla.org/security/sour...util/SSLerrs.h) + + - SSL_ERROR_UNSUPPORTED_EXTENSION_ALERT + SSL_ERROR_CERTIFICATE_UNOBTAINABLE_ALERT + SSL_ERROR_UNRECOGNIZED_NAME_ALERT + SSL_ERROR_BAD_CERT_STATUS_RESPONSE_ALERT + SSL_ERROR_BAD_CERT_HASH_VALUE_ALERT + + - New TLS cipher suites (see https://mxr.mozilla.org/security/sour...SSLSocket.java): + + - TLS_RSA_WITH_CAMELLIA_128_CBC_SHA + TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA + TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA + TLS_RSA_WITH_CAMELLIA_256_CBC_SHA + TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA + TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA + + - Note: the following TLS cipher suites are declared but are not yet implemented: + + - TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA + TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA + TLS_DH_ANON_WITH_CAMELLIA_128_CBC_SHA + TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA + TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA + TLS_DH_ANON_WITH_CAMELLIA_256_CBC_SHA + TLS_ECDH_anon_WITH_NULL_SHA + TLS_ECDH_anon_WITH_RC4_128_SHA + TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA + TLS_ECDH_anon_WITH_AES_128_CBC_SHA + TLS_ECDH_anon_WITH_AES_256_CBC_SHA + + + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS is checked into ``mozilla/security/jss/``. + - The CVS tag for the JSS 4.3 release is ``JSS_4_3_RTM``. + - Source tarballs are available from + https://archive.mozilla.org/pub/security/jss/releases/JSS_4_3_RTM/src/jss-4.3.tar.bz2 + - Binary releases are no longer available on mozilla. JSS is a JNI library we provide the + jss4.jar but expect you to build the JSS's matching JNI shared library. We provide the + jss4.jar in case you do not want to obtain your own JCE code signing certificate. JSS is a + JCE provider and therefore the jss4.jar must be signed. + https://archive.mozilla.org/pub/security/jss/releases/JSS_4_3_RTM/ + + -------------- + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Documentation for JSS 4.3 is available as follows: + + - `Build Instructions for JSS 4.3 </jss_build_4.3.html>`__ + - Javadoc `[online] </javadoc>`__ + `[zipped] <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__ + - Read the instructions on `using JSS </using_jss.html>`__. + - Source may be viewed with a browser (via the MXR tool) at + http://mxr.mozilla.org/mozilla/source/security/jss/ + - The RUN TIME behavior of JSS can be affected by the + :ref:`mozilla_projects_nss_reference_nss_environment_variables`. + +.. _platform_information: + +`Platform Information <#platform_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 4.3 works with JDK versions 4 or higher we suggest the latest. + - JSS 4.3 requires `NSS + 3.12 <https://www.mozilla.org/projects/security/pki/nss/nss-3.12/nss-3.12-release-notes.html>`__ + or higher. + - JSS 4.3 requires `NSPR 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/>`__ or + higher. + - JSS only supports the native threading model (no green threads). + + -------------- + +.. _known_bugs_and_issues: + +`Known Bugs and Issues <#known_bugs_and_issues>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - For a list of reported bugs that have not yet been fixed, `click + here. <http://bugzilla.mozilla.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&&product=JSS>`__ + Note that some bugs may have been fixed since JSS 4.3 was released. + + -------------- + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 4.3 is backwards compatible with JSS 4.2. Applications compiled against JSS 4.2 will work + with JSS 4.3. + - The 4.3 version of libjss4.so/jss4.dll must only be used with jss4.jar. In general, a JSS JAR + file must be used with the JSS shared library from the exact same release. + - To obtain the version info from the jar file use, + "System.out.println(org.mozilla.jss.CryptoManager.JAR_JSS_VERSION)" and to check the shared + library: strings libjss4.so \| grep -i header + + -------------- + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Bugs discovered should be reported by filing a bug report with + `bugzilla <http://bugzilla.mozilla.org/enter_bug.cgi?product=JSS>`__. + - You can also give feedback directly to the developers on the 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>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.3.x/index.rst b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.3.x/index.rst new file mode 100644 index 0000000000..a864a452ee --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.3.x/index.rst @@ -0,0 +1,99 @@ +.. _mozilla_projects_nss_jss_build_instructions_for_jss_4_3_x: + +Build instructions for JSS 4.3.x +================================ + +.. _build_instructions_for_jss_4.3.x: + +`Build Instructions for JSS 4.3.x <#build_instructions_for_jss_4.3.x>`__ +------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + Before building JSS, you need to set up your system as follows: + + #. Build NSPR/NSS by following the + :ref:`mozilla_projects_nss_reference_building_and_installing_nss_build_instructions`, + #. To check that NSS built correctly, run ``all.sh`` (in ``mozilla/security/nss/tests``) and + examine the results (in + ``mozilla/test_results/security/``\ *computername*.#\ ``/results.html``. + #. Install a Java compiler and runtime. JSS supports Java version 1.5 or later. We suggest you + use the latest. + #. You must have Perl version 5.005 or later. + + Now you are ready to build JSS. Follow these steps: + + #. Switch to the appropriate directory and check out JSS from the root of your source tree. + + .. code:: + + cvs co -r JSS_4_3_1_RTM mozilla/security/jss + + or + + .. code:: + + cvs co -r JSS_4_3_RTM mozilla/security/jss + + #. Setup environment variables needed for compiling Java source. The ``JAVA_HOME`` variable + indicates the directory containing your Java SDK installation. Note, on Windows platforms it + is best to have JAVA_HOME set to a directory path that doest not have spaces. + + **Unix** + + .. code:: + + setenv JAVA_HOME /usr/local/jdk1.5.0 (or wherever your JDK is installed) + + **Windows** + + .. code:: + + set JAVA_HOME=c:\programs\jdk1.5.0 (or wherever your JDK is installed) + + **Windows (Cygnus)** + + .. code:: + + JAVA_HOME=/cygdrive/c/programs/jdk1.5.0 (or wherever your JDK is installed) + export JAVA_HOME + + | **Windows build Configurations WINNT vs WIN95** + + .. code:: + + As of NSS 3.15.4, NSPR/NSS/JSS build generates a "WIN95" configuration by default on Windows. + We recommend most applications use the "WIN95" configuration. If you want JSS to be used + with your applet and the Firefox browser than you must build WIN95. (See JSS FAQ) + The "WIN95" configuration supports all versions of Windows. The "WIN95" name is historical; + it should have been named "WIN32". + To generate a "WINNT" configuration, set OS_TARGET=WINNT and build NSPR/NSS/JSS WIN95. + + | Mac OS X + | It has been recently reported that special build instructions are necessary to succeed + building JSS on OSX. Please + see `HOWTO_successfully_compile_JSS_and_NSS_for_32_and_64_bits_on_OSX_10.6_(10.6.7) </HOWTO_successfully_compile_JSS_and_NSS_for_32_and_64_bits_on_OSX_10.6_(10.6.7)>`__ + for contributed instructions. + | + + #. Build JSS. + + .. code:: + + cd mozilla/security/jss + gmake + + #. Sign the JSS jar. + + .. code:: + + If you're intention is to modify and build the JSS source you + need to Apply for your own JCE code-signing certificate + + If you made no changes and your goal is to build JSS you can use the + signed binary release of the jss4.jar from ftp.mozilla.org. + with your built jss4 JNI shared library. + + Next, you should read the instructions on `using JSS <Using_JSS>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.4.x/index.rst b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.4.x/index.rst new file mode 100644 index 0000000000..bdbea81953 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.4.x/index.rst @@ -0,0 +1,19 @@ +.. _mozilla_projects_nss_jss_build_instructions_for_jss_4_4_x: + +Build instructions for JSS 4.4.x +================================ + +.. _build_instructions_for_jss_4.4.x: + +`Build Instructions for JSS 4.4.x <#build_instructions_for_jss_4.4.x>`__ +------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + To build JSS see `Upstream JSS Build/Test + Instructions <https://hg.mozilla.org/projects/jss/file/tip/README>`__ + + `Next, you should read the instructions + on <https://hg.mozilla.org/projects/jss/file/tip/README>`__ `using JSS <Using_JSS>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/index.rst b/security/nss/doc/rst/legacy/jss/index.rst new file mode 100644 index 0000000000..c09374dbc6 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/index.rst @@ -0,0 +1,165 @@ +.. _mozilla_projects_nss_jss: + +JSS +=== + +`Documentation <#documentation>`__ +---------------------------------- + +.. container:: + + .. warning:: + + **The JSS project has been relocated!** + + As of April 6, 2018, JSS has been migrated from Mercurial on Mozilla to Git on Github. + + JSS source should now be checked out from the Github: + + - git clone git@github.com:dogtagpki/jss.git + -- OR -- + - git clone https://github.com/dogtagpki/jss.git + + All future upstream enquiries to JSS should now use the Pagure Issue Tracker system: + + - https://pagure.io/jss/issues + + Documentation regarding the JSS project should now be viewed at: + + - http://www.dogtagpki.org/wiki/JSS + + **NOTE: As much of the JSS documentation is sorely out-of-date, updated information will be a + work in progress, and many portions of any legacy documentation will be re-written over the + course of time. Stay tuned!** + + Legacy JSS information can still be found at: + + - SOURCE: https://hg.mozilla.org/projects/jss + - ISSUES: https://bugzilla.mozilla.org/buglist.cgi?product=JSS + - WIKI: :ref:`mozilla_projects_nss_jss` + + Network Security Services for Java (JSS) is a Java interface to + `NSS <https://developer.mozilla.org/en-US/docs/NSS>`__. JSS supports most of the security + standards and encryption technologies supported by :ref:`mozilla_projects_nss_reference`. JSS + also provides a pure Java interface for ASN.1 types and BER/DER encoding. + + JSS offers a implementation of Java SSL sockets that uses NSS's SSL/TLS implementation rather + than Sun's JSSE implementation. You might want to use JSS's own `SSL + classes <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases>`__ if you want to use some + of the capabilities found in NSS's SSL/TLS library but not found in JSSE. + + NSS is the cryptographic module where all cryptographic operations are performed. JSS essentially + provides a Java JNI bridge to NSS C shared libraries. When NSS is put in FIPS mode, JSS ensures + FIPS compliance by ensuring that all cryptographic operations are performed by the NSS + cryptographic module. + + JSS offers a JCE provider, `"Mozilla-JSS" JCA Provider notes <JSS/JSS_Provider_Notes>`__. + + JSS, jss4.jar, is still built with JDK 1.4.2. While JDK 1.4.2 is EOL'd and all new product + development should be using the latest + `JavaSE <http://java.sun.com/javase/downloads/index.jsp>`__, legacy business products that must + use JDK 1.4 or 1.5 can continue to add NSS/JSS security fixes/enhancements. + + JSS is used by Red Hat and Sun products that do crypto in Java. JSS is available under the + Mozilla Public License, the GNU General Public License, and the GNU Lesser General Public + License. JSS requires `NSPR <https://developer.mozilla.org/en-US/docs/NSPR>`__ and + `NSS <https://developer.mozilla.org/en-US/docs/NSS>`__. + + Java provides a JCE provider called SunPKCS11 (see `Java PKCS#11 Reference + Guide <http://download.java.net/jdk7/docs/technotes/guides/security/p11guide.html>`__.) SunPKCS11 + can be configured to use the NSS module as the crytographic provider. If you are planning to just + use JSS JCE provider as a bridge to NSS's FIPS validated PKCS#11 module, then the SunPKCS11 JCE + provider may do all that you need. Note that Java 1.5 claimed no FIPS compliance, and `Java + 1.6 <http://java.sun.com/javase/6/docs/technotes/guides/security/enhancements.html>`__ or higher + needs to be used. A current limitation to the configured SunPKCS11-NSS bridge configuration is if + you add a PKCS#11 module to the NSS database such as for a smartcard, you won't be able to access + that smartcard through the SunPKCS11-NSS bridge. If you use JSS, you can easily get lists of + modules and tokens that are configured in the NSS DB and freely access all of it. + + +-------------------------------------------------+-------------------------------------------------+ + | Before you use JSS, you should have a good | .. rubric:: Community | + | understanding of the crypto technologies it | :name: Community | + | uses. You might want to read these documents: | | + | | - View Mozilla Cryptography forums... | + | - `Introduction to Public-Key | | + | Crypt | - `Mailing | + | ography <https://developer.mozilla.org/en-US/do | list <https:/ | + | cs/Introduction_to_Public-Key_Cryptography>`__. | /lists.mozilla.org/listinfo/dev-tech-crypto>`__ | + | Explains the basic concepts of public-key | - `Newsgroup <http://grou | + | cryptography that underlie NSS and JSS. | ps.google.com/group/mozilla.dev.tech.crypto>`__ | + | - `Introduction to | - `RSS | + | SSL <https://developer. | feed <http://groups.goo | + | mozilla.org/en-US/docs/Introduction_to_SSL>`__. | gle.com/group/mozilla.dev.tech.crypto/feeds>`__ | + | Introduces the SSL protocol, including | | + | information about cryptographic ciphers | .. rubric:: Related Topics | + | supported by SSL and the steps involved in | :name: Related_Topics | + | the SSL handshake. | | + | | - `Security <https: | + | For information on downloading NSS releases, | //developer.mozilla.org/en-US/docs/Security>`__ | + | see `NSS sources building | | + | testing <NSS_Sources_Building_Te | | + | sting>`__\ `. <NSS_Sources_Building_Testing>`__ | | + | | | + | Read `Using JSS <JSS/Using_JSS>`__ to get you | | + | started with development after you've built and | | + | downloaded it. | | + | | | + | .. rubric:: Release Notes | | + | :name: Release_Notes | | + | | | + | - `4.3.1 Release | | + | Notes </4.3.1_Release_Notes>`__ | | + | - `4.3 Release | | + | Notes <https://developer. | | + | mozilla.org/en-US/docs/JSS/4_3_ReleaseNotes>`__ | | + | - `Older Release | | + | Notes <http://www-archive.mozil | | + | la.org/projects/security/pki/jss/index.html>`__ | | + | | | + | .. rubric:: Build Instructions | | + | :name: Build_Instructions | | + | | | + | - :re | | + | f:`mozilla_projects_nss_jss_build_instructions_ | | + | for_jss_4_4_x#build_instructions_for_jss_4_4_x` | | + | - `Building JSS | | + | 4.3.x <https://developer.mozilla.org/en-U | | + | S/docs/JSS/Build_instructions_for_JSS_4.3.x>`__ | | + | - `Older Build | | + | Instructions <http://www-archive.mozil | | + | la.org/projects/security/pki/jss/index.html>`__ | | + | | | + | .. rubric:: Download or View Source | | + | :name: Download_or_View_Source | | + | | | + | - `Download binaries, source, and | | + | javadoc <ftp://ftp.mozilla | | + | .org/pub/mozilla.org/security/jss/releases/>`__ | | + | - `View the source | | + | online <http://m | | + | xr.mozilla.org/mozilla/source/security/jss/>`__ | | + | | | + | .. rubric:: Testing | | + | :name: Testing | | + | | | + | - `JSS | | + | tests <https:// | | + | hg.mozilla.org/projects/jss/file/tip/README>`__ | | + | | | + | .. rubric:: Frequently Asked Questions | | + | :name: Frequently_Asked_Questions | | + | | | + | - `JSS FAQ <JSS/JSS_FAQ>`__ | | + | | | + | Information on JSS planning can be found at | | + | `wik | | + | i.mozilla.org <http://wiki.mozilla.org/NSS>`__, | | + | including: | | + | | | + | - `NSS FIPS | | + | Validati | | + | on <http://wiki.mozilla.org/FIPS_Validation>`__ | | + | - `NSS Roadmap | | + | | | + | page <http://wiki.mozilla.org/NSS:Roadmap>`__ | | + +-------------------------------------------------+-------------------------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/jss_faq/index.rst b/security/nss/doc/rst/legacy/jss/jss_faq/index.rst new file mode 100644 index 0000000000..d419586452 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/jss_faq/index.rst @@ -0,0 +1,217 @@ +.. _mozilla_projects_nss_jss_jss_faq: + +JSS FAQ +======= + +.. _jss_frequently_asked_questions: + +`JSS Frequently Asked Questions <#jss_frequently_asked_questions>`__ +-------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org:119/mozilla.dev.tech.crypto>`__ + + **Content:** + + - `What versions of JDK and JCE do you suggest? <#jdkjce1>`__ + - `Does JSS have 64 bit support? <#64bit>`__ + - `Is JSS FIPS Compliant? <#fips>`__ + - `Is there any sample code and documentation? <#sample>`__ + - `If I don't call setCipherPolicy, is the DOMESTIC policy used by + default? <#setcipherpolicy>`__ + - `My SSL connection is hanging on Windows? <#ssl_hanging>`__ + - `How can I tell which SSL/TLS ciphers JSS supports? <#ssltls_cipher>`__ + - `How can I debug my SSL connection? <#ssl_debug>`__ + - `Can you explain JSS SSL certificate approval callbacks? <#ssl_callback>`__ + - `Can I have multiple JSS instances reading separate db's? <#jss_instance>`__ + - `Once JSS initialized, I can't get anymore instances with + CertificateFactory.getInstance(X.509)? <#jss_init>`__ + - `Is it possible to sign data in Java with JSS? <#sign_date>`__ + - `How do I convert org.mozilla.jss.crypto.X509Certificate to + org.mozilla.jss.pkix.cert.Certificate? <#convertx509>`__ + - `How do I convert org.mozilla.jss.pkix.cert to + org.mozilla.jss.crypto.X509Certificate? <#convertpkix>`__ + - `Is it possible to use JSS to access cipher functionality from pkcs11 modules? <#pkc11>`__ + - `Can you explain token names and keys with regards to JSS? <#token_name>`__ + - `JSS 3.2 has JCA support. When will JSS have JSSE support? <#jssjsse>`__ + + **What versions of JDK and JRE do you suggest?** + + - JSS 3.x works with JDK versions 1.2 or higher, except version 1.3.0. Most attention for future + development and bug fixing will go to JDK 1.4 and later, so use that if you can. If you are + using JDK 1.3.x, you will need to use at least version 1.3.1--see `bug + 113808 <http://bugzilla.mozilla.org/show_bug.cgi?id=113808>`__. JSS only supports the native + threading model (no green threads). For JSS 3.2 and higher, if you use JDK 1.4 or higher you + will not need to install the JCE, but if you using an earlier version of the JDK then you will + also have to install JCE 1.2.1. See also the document `Using JSS <Using_JSS>`__. + + **Does JSS have 64 bit support?** + + - Yes, JSS 3.2 and higher supports 64 bit. You will need JDK 1.4 or higher and all the 64 bit + versions of NSPR, and NSS. As well you must use the java flag -d64 to specify the 64-bit data + model. + + **Is JSS FIPS Compliant?** + + - NSS is a FIPS-certified software library. JSS is considered a FIPS-compliant software library + since it only uses NSS for any and all crypto routines. + + **Is there any sample code and documentation?** + + - The `Using JSS <Using_JSS>`__ document describes how to set up your environment to run JSS. + The only other documentation is the + `Javadoc <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__. + + JSS example code is essentially developer test code; with that understanding, the best + directory to look for sample code is in the org/mozilla/jss/tests directory: + + http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/tests + + | `org/mozilla/jss/tests/CloseDBs.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/CloseDBs.java#47>`__ + | `org/mozilla/jss/tests/KeyFactoryTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/KeyFactoryTest.java#81>`__ + | `org/mozilla/jss/tests/DigestTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/DigestTest.java#44>`__ + | `org/mozilla/jss/tests/JCASigTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/JCASigTest.java#50>`__ + | `org/mozilla/jss/tests/KeyWrapping.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/KeyWrapping.java#45>`__ + | `org/mozilla/jss/tests/ListCerts.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/ListCerts.java#40>`__ + | `org/mozilla/jss/tests/PK10Gen.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/PK10Gen.java#43>`__ + | `org/mozilla/jss/tests/SDR.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SDR.java#47>`__ + | `org/mozilla/jss/tests/SelfTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SelfTest.java#46>`__ + | `org/mozilla/jss/tests/SetupDBs.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SetupDBs.java#42>`__ + | `org/mozilla/jss/tests/SigTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SigTest.java#64>`__ + | `org/mozilla/jss/tests/SymKeyGen.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SymKeyGen.java#44>`__ + | `org/mozilla/jss/tests/TestKeyGen.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/TestKeyGen.java#64>`__ + | `org/mozilla/jss/tests/SSLClientAuth.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SSLClientAuth.java#99>`__ + | `org/mozilla/jss/tests/ListCACerts.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/ListCACerts.java#8>`__ + | `org/mozilla/jss/tests/KeyStoreTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/KeyStoreTest.java#68>`__ + | `org/mozilla/jss/tests/VerifyCert.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/VerifyCert.java#86>`__ + + SSL examples: + + | `org/mozilla/jss/tests/SSLClientAuth.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/tests/SSLClientAuth.java>`__ + | `org/mozilla/jss/ssl/SSLClient.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLClient.java>`__ + | `org/mozilla/jss/ssl/SSLServer.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLServer.java>`__ + | `org/mozilla/jss/ssl/SSLTest.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLTest.java>`__ + + Other test code that may prove useful: + + | `org/mozilla/jss/asn1/INTEGER.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/asn1/INTEGER.java#131>`__ + | `org/mozilla/jss/asn1/SEQUENCE.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/asn1/SEQUENCE.java#574>`__ + | `org/mozilla/jss/asn1/SET.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/asn1/SET.java#876>`__ + | `org/mozilla/jss/pkcs10/CertificationRequest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkcs10/CertificationRequest.java#269>`__ + | `org/mozilla/jss/pkcs12/PFX.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkcs12/PFX.java#329>`__ + | `org/mozilla/jss/pkix/cert/Certificate.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/cert/Certificate.java#279>`__ + | `org/mozilla/jss/pkix/cmmf/CertRepContent.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/cmmf/CertRepContent.java#148>`__ + | `org/mozilla/jss/pkix/crmf/CertReqMsg.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/crmf/CertReqMsg.java#265>`__ + | `org/mozilla/jss/pkix/crmf/CertTemplate.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/crmf/CertTemplate.java#530>`__ + | `org/mozilla/jss/pkix/primitive/Name.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/primitive/Name.java#276>`__ + | `org/mozilla/jss/provider/javax/crypto/JSSSecretKeyFactorySpi.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/provider/javax/crypto/JSSSecretKeyFactorySpi.java#287>`__ + | `org/mozilla/jss/util/UTF8Converter.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/util/UTF8Converter.java#302>`__ + | `org/mozilla/jss/util/Base64InputStream.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/util/Base64InputStream.java#237>`__ + | `jss/samples/PQGGen.java <http://lxr.mozilla.org/security/source/security/jss/samples/PQGGen.java#44>`__ + | `jss/samples/pkcs12.java <http://lxr.mozilla.org/security/source/security/jss/samples/pkcs12.java#57>`__ + + **If I don't call setCipherPolicy, is the DOMESTIC policy used by default?** + + - Yes, domestic is the default because we call NSS_SetDomesticPolicy() during + CryptoManager.initialize(). setCipherPolicy does not need to be called by a JSS app unless + that app wants to limit itself to export-allowed cipher suites. + + **My SSL connection is hanging on Windows?** + + - NSPR makes use of 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. The NT fiber problem affects applications that call blocking + system calls from the primordial thread. Either use the WIN 95 version of NSPR/NSS/JSS + components (essentially all non-fiber builds) or set the environment variable + NSPR_NATIVE_THREADS_ONLY=1. You can find more information in bugzilla bug + `102251 <http://bugzilla.mozilla.org/show_bug.cgi?id=102251>`__ SSL session cache locking + issue with NT fibers + + **How can I tell which SSL/TLS ciphers JSS supports?** + + - Check + http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLSocket.java#730 + + **How can I debug my SSL connection?** + + - By using the NSS tool :ref:`mozilla_projects_nss_tools_ssltap` + + **Can you explain JSS SSL certificate approval callbacks?** + + - NSS has three callbacks related to certificates. JSS has two. But JSS combines two of the NSS + callbacks into one. + + - NSS's three SSL cert callbacks are: + + #. SSL_AuthCertificateHook sets a callback to authenticate the peer's certificate. It is + called instead of NSS's routine for authenticating certificates. + #. SSL_BadCertHook sets a callback that is called when NSS's routine fails to authenticate the + certificate. + #. SSL_GetClientAuthDataHook sets a callback to return the local certificate for SSL client + auth. + + JSS's two callbacks are: + + #. SSLCertificateApprovalCallback is a combination of SSL_AuthCertificateHook and + SSL_BadCertHook. It runs NSS's cert authentication check, then calls the callback + regardless of whether the cert passed or failed. The callback is told whether the cert + passed, and then can do anything extra that it wants to do before making a final decision. + #. SSLClientCertificateSelectionCallback is analogous to SSL_GetClientAuthDataHook. + + | + | **Can I have multiple JSS instances reading separate db's?** + + - No, you can only have one initialized instance of JSS for each database. + + **Once JSS initialized, I can't get anymore instances with + CertificateFactory.getInstance("X.509")?** + + - In version previous to JSS 3.1, JSS removes the default SUN provider on startup. Upgrade to + the latest JSS, or, in the ``CryptoManager.InitializationValues`` object you pass to + ``CryptoManager.initialize()``, set ``removeSunProivider=true``. + + **Is it possible to sign data in Java with JSS? What I am trying to do is write a Java applet + that will access the Netscape certificate store, retrieve a X509 certificate and then sign some + data.** + + - The best way to do this is with the PKCS #7 signedData type. Check out the + `javadoc <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__. + + **How do I convert org.mozilla.jss.crypto.X509Certificate to + org.mozilla.jss.pkix.cert.Certificate?** + + - .. code:: + + import java.io.ByteArrayInputStream; + + [...] + + Certificate cert = (Certificate) ASN1Util.decode( + Certificate.getTemplate(),x509Cert.getEncoded() ); + + **How do I convert org.mozilla.jss.pkix.cert to org.mozilla.jss.crypto.X509Certificate?** + + - `Cryptomanager.importCertPackage() <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__ + + **Is it possible to use JSS to acces cipher functionality from pkcs11 modules?** + + - Yes. Before JSS 3.2 you would use CryptoManager to obtain the CryptoToken you want to use, + then call CryptoToken.getCipherContext() to get an encryption engine. But as of JSS 3.2 you + would use the `JSS JCA provider <JSS_Provider_Notes>`__. + + **Can you explain token names and keys with regards to JSS?** + + - The token name is different depending on which application you are running. In JSS, the token + is called "Internal Key Storage Token". You can look it up by name using + CryptoManager.getTokenByName(), but a better way is to call + CryptoManager.getInternalKeyStorageToken(), which works no matter what the token is named. In + general, a key is a handle to an underlying object on a PKCS #11 token, not merely a Java + object residing in memory. Symmetric Key usage: basically encrypt/decrypt is for data and + wrap/unwrap is for keys. + + J\ **SS 3.2 has JCA support. When will JSS have JSSE support?** + + - Not in the near future due to pluggability is disabled in the JSSE version included in J2SE + 1.4.x for export control reasons.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/jss_provider_notes/index.rst b/security/nss/doc/rst/legacy/jss/jss_provider_notes/index.rst new file mode 100644 index 0000000000..9db0654c2c --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/jss_provider_notes/index.rst @@ -0,0 +1,489 @@ +.. _mozilla_projects_nss_jss_jss_provider_notes: + +JSS Provider Notes +================== + +.. container:: + + .. warning:: + + This page has been moved to http://www.dogtagpki.org/wiki/JSS_Provider. + +.. _the_mozilla-jss_jca_provider: + +`The Mozilla-JSS JCA Provider <#the_mozilla-jss_jca_provider>`__ +---------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Overview <#overview>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This document describes the JCA Provider shipped with JSS. The provider's name is "Mozilla-JSS". + It implements cryptographic operations in native code using the `NSS <../nss>`__ libraries. + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Signed JAR file <#signed-jar>`__ + - `Installing the Provider <#installing-provider>`__ + - `Specifying the CryptoToken <#specifying-token>`__ + - `Supported Classes <#supported-classes>`__ + - `What's Not Supported <#not-supported>`__ + + -------------- + +.. _signed_jar_file: + +`Signed JAR file <#signed_jar_file>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 3.2 implements several JCE (Java Cryptography Extension) algorithms. These algorithms have + at various times been export-controlled by the US government. Sun therefore requires that JAR + files implementing JCE algorithms be digitally signed by an approved organization. Netscape + has this approval and signs the official builds of ``jss32.jar``. At runtime, the JRE + automatically verifies this signature whenever a JSS class is loaded that implements a JCE + algorithm. The verification is transparent to the application (unless it fails and throws an + exception). If you are curious, you can verify the signature on the JAR file using the + ``jarsigner`` tool, which is distributed with the JDK. + + If you build JSS yourself from source instead of using binaries downloaded from mozilla.org, + your JAR file will not have a valid signature. This means you will not be able to use the JSS + provider for JCE algorithms. You have two choices. + + #. Use the binary release of JSS from mozilla.org. + #. Apply for your own JCE code-signing certificate following the procedure at `How to + Implement a Provider for the Java\ TM Cryptography + Extension <http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/HowToImplAProvider.html#Step61>`__. + Then you can sign your own JSS JAR file. + +.. _installing_the_provider: + +`Installing the Provider <#installing_the_provider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - In order to use any part of JSS, including the JCA provider, you must first call + ``CryptoManager.initialize()``. By default, the JCA provider will be installed in the list of + providers maintained by the ``java.security.Security`` class. If you do not wish the provider + to be installed, create a + :ref:`mozilla_projects_nss_jss_cryptomanager_cryptomanager_initializationvalues` object, set + its ``installJSSProvider`` field to ``false``, and pass the ``InitializationValues`` object to + ``CryptoManager.initialize()``. + +.. _specifying_the_cryptotoken: + +`Specifying the CryptoToken <#specifying_the_cryptotoken>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - All cryptographic operations in JSS and NSS occur on a particular PKCS #11 token, implemented + in software or hardware. There is no clean way to specify this token through the JCA API. By + default, the JSS provider carries out all operations except MessageDigest on the Internal Key + Storage Token, a software token included in JSS/NSS. MessageDigest operations take place by + default on the Internal Crypto Token, another internal software token in JSS/NSS. There is no + good design reason for this difference, but it is necessitated by a quirk in the NSS + implementation. + + In order to use a different token, use ``CryptoManager.setThreadToken()``. This sets the token + to be used by the JSS JCA provider in the current thread. When you call ``getInstance()`` on a + JCA class, the JSS provider checks the current per-thread default token (by calling + ``CryptoManager.getThreadToken()``) and instructs the new object to use that token for + cryptographic operations. The per-thread default token setting is only consulted inside + ``getInstance()``. Once a JCA object has been created it will continue to use the same token, + even if the application later changes the per-thread default token. + + Whenever a new thread is created, its token is initialized to the default, the Internal Key + Storage Token. Thus, the thread token is not inherited from the parent thread. + + The following example shows how you can specify which token is used for various JCA + operations: + + .. code:: + + // Lookup PKCS #11 tokens + CryptoManager manager = CryptoManager.getInstance(); + CryptoToken tokenA = manager.getTokenByName("TokenA"); + CryptoToken tokenB = manager.getTokenByName("TokenB"); + + // Create an RSA KeyPairGenerator using TokenA + manager.setThreadToken(tokenA); + KeyPairGenerator rsaKpg = KeyPairGenerator.getInstance("RSA", "Mozilla-JSS"); + + // Create a DSA KeyPairGenerator using TokenB + manager.setThreadToken(tokenB); + KeyPairGenerator dsaKpg = KeyPairGenerator.getInstance("DSA", "Mozilla-JSS"); + + // Generate an RSA KeyPair. This will happen on TokenA because TokenA + // was the per-thread default token when rsaKpg was created. + rsaKpg.initialize(1024); + KeyPair rsaPair = rsaKpg.generateKeyPair(); + + // Generate a DSA KeyPair. This will happen on TokenB because TokenB + // was the per-thread default token when dsaKpg was created. + dsaKpg.initialize(1024); + KeyPair dsaPair = dsaKpg.generateKeyPair(); + +.. _supported_classes: + +`Supported Classes <#supported_classes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Cipher <#cipher>`__ + + - `DSAPrivateKey <#dsaprivatekey>`__ + + - DSAPublicKey + + - `KeyFactory <#keyfactory>`__ + + - `KeyGenerator <#keygenerator>`__ + + - `KeyPairGenerator <#keypairgenerator>`__ + + - `Mac <#mac>`__ + + - `MessageDigest <#messagedigest>`__ + + - `RSAPrivateKey <#rsaprivatekey>`__ + + - RSAPublicKey + + - `SecretKeyFactory <#secretkeyfactory>`__ + + - `SecretKey <#secretkey>`__ + + - `SecureRandom <#securerandom>`__ + + - `Signature <#signature>`__ + + .. rubric:: What's Not Supported + :name: What's_Not_Supported + + - The following classes don't work very well: + + - **KeyStore:** There are many serious problems mapping the JCA keystore interface onto + NSS's model of PKCS #11 modules. The current implementation is almost useless. Since + these problems lie deep in the NSS design and implementation, there is no clear + timeframe for fixing them. Meanwhile, the ``org.mozilla.jss.crypto.CryptoStore`` class + can be used for some of this functionality. + +.. rubric:: Cipher + :name: Cipher_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms + +.. rubric:: Notes + :name: notes + +- + + - AES + - DES + - DESede (*DES3* ) + - RC2 + - RC4 + - RSA + + - The following modes and padding schemes are supported: + + + +------------------------------+------------------------------+------------------------------+ + | Algorithm | Mode | Padding | + +------------------------------+------------------------------+------------------------------+ + | DES | ECB | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5 Padding | + +------------------------------+------------------------------+------------------------------+ + | DESede | ECB | NoPadding | + | *DES3* | | | + +------------------------------+------------------------------+------------------------------+ + | | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5 Padding | + +------------------------------+------------------------------+------------------------------+ + | AES | ECB | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5 Padding | + +------------------------------+------------------------------+------------------------------+ + | RC4 | *None* | *None* | + +------------------------------+------------------------------+------------------------------+ + | RC2 | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5Padding | + +------------------------------+------------------------------+------------------------------+ + + - The SecureRandom argument passed to ``initSign()`` and ``initVerify()`` is ignored, because + NSS does not support specifying an external source of randomness. + +.. rubric:: DSAPrivateKey + :name: DSAPrivateKey_2 + +- ``getX()`` is not supported because NSS does not support extracting data from private keys. + +.. rubric:: KeyFactory + :name: KeyFactory_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_2 + +.. rubric:: Notes + :name: notes_2 + +- + + - DSA + - RSA + + - The following transformations are supported for ``generatePublic()`` and + ``generatePrivate()``: + + + +----------------------------------------------+----------------------------------------------+ + | From | To | + +----------------------------------------------+----------------------------------------------+ + | ``RSAPublicKeySpec`` | ``RSAPublicKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``DSAPublicKeySpec`` | ``DSAPublicKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``X509EncodedKeySpec`` | ``RSAPublicKey`` | + | | ``DSAPublicKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``RSAPrivateCrtKeySpec`` | ``RSAPrivateKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``DSAPrivateKeySpec`` | ``DSAPrivateKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``PKCS8EncodedKeySpec`` | ``RSAPrivateKey`` | + | | ``DSAPrivateKey`` | + +----------------------------------------------+----------------------------------------------+ + + - ``getKeySpec()`` is not supported. This method exports key material in plaintext and is + therefore insecure. Note that a public key's data can be accessed directly from the key. + - ``translateKey()`` simply gets the encoded form of the given key and then tries to import + it by calling ``generatePublic()`` or ``generatePrivate()``. Only ``X509EncodedKeySpec`` is + supported for public keys, and only ``PKCS8EncodedKeySpec`` is supported for private keys. + +.. rubric:: KeyGenerator + :name: KeyGenerator_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_3 + +.. rubric:: Notes + :name: notes_3 + +- + + - AES + - DES + - DESede (*DES3* ) + - RC4 + + - The SecureRandom argument passed to ``init()`` is ignored, because NSS does not support + specifying an external source of randomness. + - None of the key generation algorithms accepts an ``AlgorithmParameterSpec``. + +.. rubric:: KeyPairGenerator + :name: KeyPairGenerator_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_4 + +.. rubric:: Notes + :name: notes_4 + +- + + - DSA + - RSA + + - The SecureRandom argument passed to initialize() is ignored, because NSS does not support + specifying an external source of randomness. + +.. rubric:: Mac + :name: Mac_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_5 + +.. rubric:: Notes + :name: notes_5 + +- + + - HmacSHA1 (*Hmac-SHA1* ) + + - Any secret key type (AES, DES, etc.) can be used as the MAC key, but it must be a JSS key. + That is, it must be an ``instanceof org.mozilla.jss.crypto.SecretKeyFacade``. + - The params passed to ``init()`` are ignored. + +.. rubric:: MessageDigest + :name: MessageDigest_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_6 + +- + + - MD5 + - MD2 + - SHA-1 (*SHA1, SHA* ) + +.. rubric:: RSAPrivateKey + :name: RSAPrivateKey_2 + +.. rubric:: Notes + :name: notes_6 + +- + + - ``getModulus()`` is not supported because NSS does not support extracting data from private + keys. + - ``getPrivateExponent()`` is not supported because NSS does not support extracting data from + private keys. + +.. rubric:: SecretKeyFactory + :name: SecretKeyFactory_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_7 + +.. rubric:: Notes + :name: notes_7 + +- + + - AES + - DES + - DESede (*DES3* ) + - PBAHmacSHA1 + - PBEWithMD5AndDES + - PBEWithSHA1AndDES + - PBEWithSHA1AndDESede (*PBEWithSHA1AndDES3* ) + - PBEWithSHA1And128RC4 + - RC4 + + - ``generateSecret`` supports the following transformations: + + + +----------------------------------------------+----------------------------------------------+ + | KeySpec Class | Key Algorithm | + +----------------------------------------------+----------------------------------------------+ + | PBEKeySpec | *Using the appropriate PBE algorithm:* | + | org.mozilla.jss.crypto.PBEKeyGenParams | DES | + | | DESede | + | | RC4 | + +----------------------------------------------+----------------------------------------------+ + | DESedeKeySpec | DESede | + +----------------------------------------------+----------------------------------------------+ + | DESKeySpec | DES | + +----------------------------------------------+----------------------------------------------+ + | SecretKeySpec | AES | + | | DES | + | | DESede | + | | RC4 | + +----------------------------------------------+----------------------------------------------+ + + - ``getKeySpec`` supports the following transformations: + + + +----------------------------------------------+----------------------------------------------+ + | Key Algorithm | KeySpec Class | + +----------------------------------------------+----------------------------------------------+ + | DESede | DESedeKeySpec | + +----------------------------------------------+----------------------------------------------+ + | DES | DESKeySpec | + +----------------------------------------------+----------------------------------------------+ + | DESede | SecretKeySpec | + | DES | | + | AES | | + | RC4 | | + +----------------------------------------------+----------------------------------------------+ + + - For increased security, some SecretKeys may not be extractable from their PKCS #11 token. + In this case, the key should be wrapped (encrypted with another key), and then the + encrypted key might be extractable from the token. This policy varies across PKCS #11 + tokens. + - ``translateKey`` tries two approaches to copying keys. First, it tries to copy the key + material directly using NSS calls to PKCS #11. If that fails, it calls ``getEncoded()`` on + the source key, and then tries to create a new key on the target token from the encoded + bits. Both of these operations will fail if the source key is not extractable. + - The class ``java.security.spec.PBEKeySpec`` in JDK versions earlier than 1.4 does not + contain the salt and iteration fields, which are necessary for PBE key generation. These + fields were added in JDK 1.4. If you are using a JDK (or JRE) version earlier than 1.4, you + cannot use class ``java.security.spec.PBEKeySpec``. Instead, you can use + ``org.mozilla.jss.crypto.PBEKeyGenParams``. If you are using JDK (or JRE) 1.4 or later, you + can use ``java.security.spec.PBEKeySpec`` or ``org.mozilla.jss.crypto.PBEKeyGenParams``. + +.. rubric:: SecretKey + :name: SecretKey_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_8 + +.. rubric:: Notes + :name: notes_8 + +- + + - AES + - DES + - DESede (*DES3* ) + - HmacSHA1 + - RC2 + - RC4 + + - ``SecretKey`` is implemented by the class ``org.mozilla.jss.crypto.SecretKeyFacade``, which + acts as a wrapper around the JSS class ``SymmetricKey``. Any ``SecretKeys`` handled by JSS + will actually be ``SecretKeyFacades``. This should usually be transparent. + +.. rubric:: SecureRandom + :name: SecureRandom_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_9 + +.. rubric:: Notes + :name: notes_9 + +- + + - pkcs11prng + + - This invokes the NSS internal pseudorandom number generator. + +.. rubric:: Signature + :name: Signature_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_10 + +.. rubric:: Notes + :name: notes_10 + +- + + - SHA1withDSA (*DSA, DSS, SHA/DSA, SHA-1/DSA, SHA1/DSA, DSAWithSHA1, SHAwithDSA* ) + - SHA-1/RSA (*SHA1/RSA, SHA1withRSA* ) + - MD5/RSA (*MD5withRSA* ) + - MD2/RSA + + - The ``SecureRandom`` argument passed to ``initSign()`` and ``initVerify()`` is ignored, + because NSS does not support specifying an external source of randomness. diff --git a/security/nss/doc/rst/legacy/jss/mozilla-jss_jca_provider_notes/index.rst b/security/nss/doc/rst/legacy/jss/mozilla-jss_jca_provider_notes/index.rst new file mode 100644 index 0000000000..f8edb0953c --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/mozilla-jss_jca_provider_notes/index.rst @@ -0,0 +1,472 @@ +.. _mozilla_projects_nss_jss_mozilla-jss_jca_provider_notes: + +Mozilla-JSS JCA Provider notes +============================== + +.. _the_mozilla-jss_jca_provider: + +`The Mozilla-JSS JCA Provider <#the_mozilla-jss_jca_provider>`__ +---------------------------------------------------------------- + +.. container:: + + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Overview <#overview>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This document describes the JCA Provider shipped with JSS. The provider's name is "Mozilla-JSS". + It implements cryptographic operations in native code using the + `NSS <https://www.mozilla.org/projects/security/pki/nss>`__ libraries. + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Signed JAR + file <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#signed-jar>`__ + - `Installing the + Provider <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#installing-provider>`__ + - `Specifying the + CryptoToken <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#specifying-token>`__ + - `Supported + Classes <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#supported-classes>`__ + - `What's Not + Supported <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#not-supported>`__ + +.. _signed_jar_file: + +`Signed JAR file <#signed_jar_file>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + JSS implements several JCE (Java Cryptography Extension) algorithms. These algorithms have at + various times been export-controlled by the US government. JRE therefore requires that JAR files + implementing JCE algorithms be digitally signed by an approved organization. The maintainers of + JSS, Sun, Red Hat, and Mozilla, have this approval and signs the official builds of ``jss4.jar``. + At runtime, the JRE automatically verifies this signature whenever a JSS class is loaded that + implements a JCE algorithm. The verification is transparent to the application (unless it fails + and throws an exception). If you are curious, you can verify the signature on the JAR file using + the ``jarsigner`` tool, which is distributed with the JDK. + + If you build JSS yourself from source instead of using binaries downloaded from mozilla.org, your + JAR file will not have a valid signature. This means you will not be able to use the JSS provider + for JCE algorithms. You have two choices. + + #. Use the binary release of JSS from mozilla.org. + #. Apply for your own JCE code-signing certificate following the procedure at `How to Implement a + Provider for the Java\ TM Cryptography + Extension <http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/HowToImplAProvider.html#Step61>`__. + Then you can sign your own JSS JAR file. + +.. _installing_the_provider: + +`Installing the Provider <#installing_the_provider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + In order to use any part of JSS, including the JCA provider, you must first call + ``CryptoManager.initialize()``. By default, the JCA provider will be installed in the list of + providers maintained by the ``java.security.Security`` class. If you do not wish the provider to + be installed, create a + ```CryptoManager.InitializationValues`` <https://www.mozilla.org/projects/security/pki/jss/javadoc/org/mozilla/jss/CryptoManager.InitializationValues.html>`__ + object, set its ``installJSSProvider`` field to ``false``, and pass the ``InitializationValues`` + object to ``CryptoManager.initialize()``. + +.. _specifying_the_cryptotoken: + +`Specifying the CryptoToken <#specifying_the_cryptotoken>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + All cryptographic operations in JSS and NSS occur on a particular PKCS #11 token, implemented in + software or hardware. There is no clean way to specify this token through the JCA API. By + default, the JSS provider carries out all operations except MessageDigest on the Internal Key + Storage Token, a software token included in JSS/NSS. MessageDigest operations take place by + default on the Internal Crypto Token, another internal software token in JSS/NSS. There is no + good design reason for this difference, but it is necessitated by a quirk in the NSS + implementation. + + In order to use a different token, use ``CryptoManager.setThreadToken()``. This sets the token to + be used by the JSS JCA provider in the current thread. When you call ``getInstance()`` on a JCA + class, the JSS provider checks the current per-thread default token (by calling + ``CryptoManager.getThreadToken()``) and instructs the new object to use that token for + cryptographic operations. The per-thread default token setting is only consulted inside + ``getInstance()``. Once a JCA object has been created it will continue to use the same token, + even if the application later changes the per-thread default token. + + Whenever a new thread is created, its token is initialized to the default, the Internal Key + Storage Token. Thus, the thread token is not inherited from the parent thread. + + The following example shows how you can specify which token is used for various JCA operations: + + .. code:: + + // Lookup PKCS #11 tokens + CryptoManager manager = CryptoManager.getInstance(); + CryptoToken tokenA = manager.getTokenByName("TokenA"); + CryptoToken tokenB = manager.getTokenByName("TokenB"); + + // Create an RSA KeyPairGenerator using TokenA + manager.setThreadToken(tokenA); + KeyPairGenerator rsaKpg = KeyPairGenerator.getInstance("Mozilla-JSS", "RSA"); + + // Create a DSA KeyPairGenerator using TokenB + manager.setThreadToken(tokenB); + KeyPairGenerator dsaKpg = KeyPairGenerator.getInstance("Mozilla-JSS", "DSA"); + + // Generate an RSA KeyPair. This will happen on TokenA because TokenA + // was the per-thread default token when rsaKpg was created. + rsaKpg.initialize(1024); + KeyPair rsaPair = rsaKpg.generateKeyPair(); + + // Generate a DSA KeyPair. This will happen on TokenB because TokenB + // was the per-thread default token when dsaKpg was created. + dsaKpg.initialize(1024); + KeyPair dsaPair = dsaKpg.generateKeyPair(); + +.. _supported_classes: + +`Supported Classes <#supported_classes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Cipher <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#Cipher>`__ + - `DSAPrivateKey <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#DSAPrivateKey>`__ + - DSAPublicKey + - `KeyFactory <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#KeyFactory>`__ + - `KeyGenerator <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#KeyGenerator>`__ + - `KeyPairGenerator <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#KeyPairGenerator>`__ + - `Mac <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#Mac>`__ + - `MessageDigest <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#MessageDigest>`__ + - `RSAPrivateKey <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#RSAPrivateKey>`__ + - RSAPublicKey + - `SecretKeyFactory <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#SecretKeyFactory>`__ + - `SecretKey <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#SecretKey>`__ + - `SecureRandom <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#SecureRandom>`__ + - `Signature <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#Signature>`__ + +`Cipher <#cipher>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms + + .. rubric:: Notes + :name: notes + + - AES + - DES + - DESede (*DES3*) + - RC2 + - RC4 + - RSA + + - The following modes and padding schemes are supported: + + +--------------------------------+--------------------------------+--------------------------------+ + | Algorithm | Mode | Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | DES | ECB | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5 Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | DESede | ECB | NoPadding | + | *DES3* | | | + +--------------------------------+--------------------------------+--------------------------------+ + | | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5 Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | AES | ECB | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5 Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | RC4 | *None* | *None* | + +--------------------------------+--------------------------------+--------------------------------+ + | RC2 | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5Padding | + +--------------------------------+--------------------------------+--------------------------------+ + + - The SecureRandom argument passed to ``initSign()`` and ``initVerify()`` is ignored, because + NSS does not support specifying an external source of randomness. + +`DSAPrivateKey <#dsaprivatekey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - ``getX()`` is not supported because NSS does not support extracting data from private keys. + +`KeyFactory <#keyfactory>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_2 + + .. rubric:: Notes + :name: notes_2 + + - DSA + - RSA + - The following transformations are supported for ``generatePublic()`` and + ``generatePrivate()``: + + +-------------------------------------------------+-------------------------------------------------+ + | From | To | + +-------------------------------------------------+-------------------------------------------------+ + | ``RSAPublicKeySpec`` | ``RSAPublicKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``DSAPublicKeySpec`` | ``DSAPublicKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``X509EncodedKeySpec`` | ``RSAPublicKey`` | + | | ``DSAPublicKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``RSAPrivateCrtKeySpec`` | ``RSAPrivateKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``DSAPrivateKeySpec`` | ``DSAPrivateKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``PKCS8EncodedKeySpec`` | ``RSAPrivateKey`` | + | | ``DSAPrivateKey`` | + +-------------------------------------------------+-------------------------------------------------+ + + - ``getKeySpec()`` is not supported. This method exports key material in plaintext and is + therefore insecure. Note that a public key's data can be accessed directly from the key. + - ``translateKey()`` simply gets the encoded form of the given key and then tries to import it + by calling ``generatePublic()`` or ``generatePrivate()``. Only ``X509EncodedKeySpec`` is + supported for public keys, and only ``PKCS8EncodedKeySpec`` is supported for private keys. + +`KeyGenerator <#keygenerator>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_3 + + .. rubric:: Notes + :name: notes_3 + + - AES + - DES + - DESede (*DES3*) + - RC4 + - The SecureRandom argument passed to ``init()`` is ignored, because NSS does not support + specifying an external source of randomness. + - None of the key generation algorithms accepts an ``AlgorithmParameterSpec``. + +`KeyPairGenerator <#keypairgenerator>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_4 + + .. rubric:: Notes + :name: notes_4 + + - DSA + - RSA + + - The SecureRandom argument passed to initialize() is ignored, because NSS does not support + specifying an external source of randomness. + +`Mac <#mac>`__ +~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_5 + + .. rubric:: Notes + :name: notes_5 + + - HmacSHA1 (*Hmac-SHA1*) + + - Any secret key type (AES, DES, etc.) can be used as the MAC key, but it must be a JSS key. + That is, it must be an ``instanceof org.mozilla.jss.crypto.SecretKeyFacade``. + - The params passed to ``init()`` are ignored. + +`MessageDigest <#messagedigest>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_6 + + - MD5 + - MD2 + - SHA-1 (*SHA1, SHA*) + +`RSAPrivateKey <#rsaprivatekey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Notes + :name: notes_6 + + - ``getModulus()`` is not supported because NSS does not support extracting data from private + keys. + - ``getPrivateExponent()`` is not supported because NSS does not support extracting data from + private keys. + +`SecretKeyFactory <#secretkeyfactory>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_7 + + .. rubric:: Notes + :name: notes_7 + + - AES + - DES + - DESede (*DES3*) + - PBAHmacSHA1 + - PBEWithMD5AndDES + - PBEWithSHA1AndDES + - PBEWithSHA1AndDESede (*PBEWithSHA1AndDES3*) + - PBEWithSHA1And128RC4 + - RC4 + + - ``generateSecret`` supports the following transformations: + + +-------------------------------------------------+-------------------------------------------------+ + | KeySpec Class | Key Algorithm | + +-------------------------------------------------+-------------------------------------------------+ + | PBEKeySpec | *Using the appropriate PBE algorithm:* | + | org.mozilla.jss.crypto.PBEKeyGenParams | DES | + | | DESede | + | | RC4 | + +-------------------------------------------------+-------------------------------------------------+ + | DESedeKeySpec | DESede | + +-------------------------------------------------+-------------------------------------------------+ + | DESKeySpec | DES | + +-------------------------------------------------+-------------------------------------------------+ + | SecretKeySpec | AES | + | | DES | + | | DESede | + | | RC4 | + +-------------------------------------------------+-------------------------------------------------+ + + - ``getKeySpec`` supports the following transformations: + + +-------------------------------------------------+-------------------------------------------------+ + | Key Algorithm | KeySpec Class | + +-------------------------------------------------+-------------------------------------------------+ + | DESede | DESedeKeySpec | + +-------------------------------------------------+-------------------------------------------------+ + | DES | DESKeySpec | + +-------------------------------------------------+-------------------------------------------------+ + | DESede | SecretKeySpec | + | DES | | + | AES | | + | RC4 | | + +-------------------------------------------------+-------------------------------------------------+ + + - For increased security, some SecretKeys may not be extractable from their PKCS #11 token. In + this case, the key should be wrapped (encrypted with another key), and then the encrypted key + might be extractable from the token. This policy varies across PKCS #11 tokens. + - ``translateKey`` tries two approaches to copying keys. First, it tries to copy the key + material directly using NSS calls to PKCS #11. If that fails, it calls ``getEncoded()`` on the + source key, and then tries to create a new key on the target token from the encoded bits. Both + of these operations will fail if the source key is not extractable. + - The class ``java.security.spec.PBEKeySpec`` in JDK versions earlier than 1.4 does not contain + the salt and iteration fields, which are necessary for PBE key generation. These fields were + added in JDK 1.4. If you are using a JDK (or JRE) version earlier than 1.4, you cannot use + class ``java.security.spec.PBEKeySpec``. Instead, you can use + ``org.mozilla.jss.crypto.PBEKeyGenParams``. If you are using JDK (or JRE) 1.4 or later, you + can use ``java.security.spec.PBEKeySpec`` or ``org.mozilla.jss.crypto.PBEKeyGenParams``. + +`SecretKey <#secretkey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_8 + + .. rubric:: Notes + :name: notes_8 + + - AES + - DES + - DESede (*DES3*) + - HmacSHA1 + - RC2 + - RC4 + + - ``SecretKey`` is implemented by the class ``org.mozilla.jss.crypto.SecretKeyFacade``, which + acts as a wrapper around the JSS class ``SymmetricKey``. Any ``SecretKeys`` handled by JSS + will actually be ``SecretKeyFacades``. This should usually be transparent. + +`SecureRandom <#securerandom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_9 + + .. rubric:: Notes + :name: notes_9 + + - pkcs11prng + + - This invokes the NSS internal pseudorandom number generator. + +`Signature <#signature>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_10 + + .. rubric:: Notes + :name: notes_10 + + - SHA1withDSA (*DSA, DSS, SHA/DSA, SHA-1/DSA, SHA1/DSA, DSAWithSHA1, SHAwithDSA*) + - SHA-1/RSA (*SHA1/RSA, SHA1withRSA*) + - MD5/RSA (*MD5withRSA*) + - MD2/RSA + + - The SecureRandom argument passed to ``initSign()`` and ``initVerify()`` is ignored, because + NSS does not support specifying an external source of randomness. + +.. _what's_not_supported: + +`What's Not Supported <#what's_not_supported>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following classes don't work very well: + + - **KeyStore:** There are many serious problems mapping the JCA keystore interface onto NSS's + model of PKCS #11 modules. The current implementation is almost useless. Since these problems + lie deep in the NSS design and implementation, there is no clear timeframe for fixing them. + Meanwhile, the ``org.mozilla.jss.crypto.CryptoStore`` class can be used for some of this + functionality.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/using_jss/index.rst b/security/nss/doc/rst/legacy/jss/using_jss/index.rst new file mode 100644 index 0000000000..3a5f19f9c7 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/using_jss/index.rst @@ -0,0 +1,152 @@ +.. _mozilla_projects_nss_jss_using_jss: + +Using JSS +========= + +.. _using_jss: + +`Using JSS <#using_jss>`__ +-------------------------- + +.. container:: + + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org:119/mozilla.dev.tech.crypto>`__ + + If you have already `built + JSS <https://developer.mozilla.org/en-US/docs/JSS/Build_instructions_for_JSS_4.3.x>`__, or if you + are planning to use a binary release of JSS, here's how to get JSS working with your code. + + | `Gather Components <#components>`__ + | `Setup your runtime environment <#runtime>`__ + | `Initialize JSS in your application <#init>`__ + +.. _gather_components: + +`Gather components <#gather_components>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. You need the JSS classes and the NSPR, NSS, and JSS shared libraries. + + #. **NSPR and NSS Shared Libraries** + + JSS uses the NSPR and NSS libraries for I/O and crypto. JSS version 3.0 linked statically with + NSS, so it only required NSPR. JSS versions 3.1 and later link dynamically with NSS, so they + also require the NSS shared libraries. + + The exact library names vary according to the convention for each platform. For example, the + NSPR library is called ``nspr4.dll`` or ``libnspr4.dll`` on Windows and ``libnspr4.so`` on + Solaris. The following table gives the core names of the libraries, omitting the + platform-specific prefix and suffix. + + +-------------------+-------------------------------------+--------------------------------------+ + | JSS Dependencies | | | + +-------------------+-------------------------------------+--------------------------------------+ + | Core Library Name | Description | Binary Release Location | + +-------------------+-------------------------------------+--------------------------------------+ + | nspr4 | NSPR OS abstraction layer | `htt | + | | | p://ftp.mozilla.org/pub/mozilla.org/ | + | | | nspr/releases <http://ftp.mozilla.or | + | | | g/pub/mozilla.org/nspr/releases/>`__ | + +-------------------+-------------------------------------+--------------------------------------+ + | plc4 | | NSPR standard C library replacement | + | | | functions | + +-------------------+-------------------------------------+--------------------------------------+ + | plds4 | | NSPR data structure types | + +-------------------+-------------------------------------+--------------------------------------+ + | nss3 | NSS crypto, PKCS #11, and utilities | `http://ftp.mozilla. | + | | | org/pub/mozilla.org/security/nss/rel | + | | | eases <http://ftp.mozilla.org/pub/mo | + | | | zilla.org/security/nss/releases/>`__ | + +-------------------+-------------------------------------+--------------------------------------+ + | ssl3 | | NSS SSL library | + +-------------------+-------------------------------------+--------------------------------------+ + | smime3 | | NSS S/MIME functions and types | + +-------------------+-------------------------------------+--------------------------------------+ + | nssckbi | | PKCS #11 module containing built-in | + | | | root CA certificates. Optional. | + +-------------------+-------------------------------------+--------------------------------------+ + | freebl_\* | | Processor-specific optimized | + | | | big-number arithmetic library. Not | + | | | present on all platforms. | + | | | :ref:`mozilla_projects_nss_introd | + | | | uction_to_network_security_services` | + +-------------------+-------------------------------------+--------------------------------------+ + | fort | | FORTEZZA support. Optional | + +-------------------+-------------------------------------+--------------------------------------+ + | swft | | PKCS #11 module implementing | + | | | FORTEZZA in software. Optional. | + +-------------------+-------------------------------------+--------------------------------------+ + + If you built JSS from source, you have these libraries in the ``mozilla/dist/<platform>/lib`` + directory of your build tree. If you are downloading binaries, get them from the binary + release locations in the above table. You need to select the right version of the components, + based on the version of JSS you are using. Generally, it is safe to use a later version of a + component than what JSS was tested with. For example, although JSS 4.2 was tested with NSS + 3.11. + + ================== ========= ============== + Component Versions + JSS Version Component Tested Version + JSS 4.2 NSPR 4.6.4 + \ NSS 3.11.4 + JSS 3.4 NSPR 4.2.2 + \ NSS 3.7.3 + JSS 3.3 NSPR 4.2.2 + \ NSS 3.6.1 or 3.7 + JSS 3.2 NSPR 4.2 or 4.1.2 + \ NSS 3.4.2 + JSS 3.1.1 NSPR 4.1.2 + \ NSS 3.3.1 + JSS 3.1 NSPR 4.1.2 + \ NSS 3.3 + JSS 3.0 NSPR 3.5.1 + ================== ========= ============== + + #. **JSS Shared Library** + + The JSS shared library is ``jss4.dll`` (Windows) or ``libjss4.so`` (Unix). If you built JSS + from source, it is in ``mozilla/dist/<platform>/lib``. If you are downloading binaries, get it + from http://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/. + + #. **JSS classes** + + If you built JSS from source, the compiled JSS classes are in ``mozilla/dist/classes[_dbg]``. + You can put this directory in your classpath to run applications locally; or, you can package + the class files into a JAR file for easier distribution: + + .. code:: + + cd mozilla/dist/classes[_dbg] + zip -r ../jss42.jar . + + If you are downloading binaries, get jss42.jar + from http://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/. + +.. _setup_your_runtime_environment: + +`Setup your runtime environment <#setup_your_runtime_environment>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + You need to set some environment variables before building and running Java applications with + JSS. + + ``CLASSPATH`` + Include the path containing the JSS classes you built, or the path to ``jss42.jar``. (The path + to ``jss34.jar`` ends with the string "/jss42.jar". It is not just the directory that contains + ``jss42.jar``.) + ``LD_LIBRARY_PATH`` (Unix) / ``PATH`` (Windows) + Include the path to the NSPR, NSS, and JSS shared libraries. + +.. _initialize_jss_in_your_application: + +`Initialize JSS in your application <#initialize_jss_in_your_application>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Before calling any JSS methods, you must initialize JSS by calling one of the + ``CryptoManager.initialize`` methods. See the `javadoc <javadoc>`__ for more details.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/key_log_format/index.rst b/security/nss/doc/rst/legacy/key_log_format/index.rst new file mode 100644 index 0000000000..99bdf87e1d --- /dev/null +++ b/security/nss/doc/rst/legacy/key_log_format/index.rst @@ -0,0 +1,61 @@ +.. _mozilla_projects_nss_key_log_format: + +NSS Key Log Format +================== + +.. container:: + + Key logs can be written by NSS so that external programs can decrypt TLS connections. Wireshark + 1.6.0 and above can use these log files to decrypt packets. You can tell Wireshark where to find + the key file via *Edit→Preferences→Protocols→TLS→(Pre)-Master-Secret log filename*. + + Key logging is enabled by setting the environment variable ``SSLKEYLOGFILE`` to point to a file. + Note: starting with :ref:`mozilla_projects_nss_nss_3_24_release_notes` (used by Firefox 48 and 49 + only), the ``SSLKEYLOGFILE`` approach is disabled by default for optimized builds using the + Makefile (those using gyp via ``build.sh`` are *not* affected). Distributors can re-enable it at + compile time though (using the ``NSS_ALLOW_SSLKEYLOGFILE=1`` make variable) which is done for the + official Firefox binaries. (See `bug + 1188657 <https://bugzilla.mozilla.org/show_bug.cgi?id=1188657>`__.) Notably, Debian does not have + this option enabled, see `Debian bug + 842292 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=842292>`__. + + This key log file is a series of lines. Comment lines begin with a sharp character ('#') and are + ignored. Secrets follow the format ``<Label> <space> <ClientRandom> <space> <Secret>`` where: + + - ``<Label>`` describes the following secret. + - ``<ClientRandom>`` is 32 bytes Random value from the Client Hello message, encoded as 64 + hexadecimal characters. + - ``<Secret>`` depends on the Label (see below). + + The following labels are defined, followed by a description of the secret: + + - ``RSA``: 48 bytes for the premaster secret, encoded as 96 hexadecimal characters (removed in + NSS 3.34) + - ``CLIENT_RANDOM``: 48 bytes for the master secret, encoded as 96 hexadecimal characters (for + SSL 3.0, TLS 1.0, 1.1 and 1.2) + - ``CLIENT_EARLY_TRAFFIC_SECRET``: the hex-encoded early traffic secret for the client side (for + TLS 1.3) + - ``CLIENT_HANDSHAKE_TRAFFIC_SECRET``: the hex-encoded handshake traffic secret for the client + side (for TLS 1.3) + - ``SERVER_HANDSHAKE_TRAFFIC_SECRET``: the hex-encoded handshake traffic secret for the server + side (for TLS 1.3) + - ``CLIENT_TRAFFIC_SECRET_0``: the first hex-encoded application traffic secret for the client + side (for TLS 1.3) + - ``SERVER_TRAFFIC_SECRET_0``: the first hex-encoded application traffic secret for the server + side (for TLS 1.3) + - ``EARLY_EXPORTER_SECRET``: the hex-encoded early exporter secret (for TLS 1.3). + - ``EXPORTER_SECRET``: the hex-encoded exporter secret (for TLS 1.3) + + The ``RSA`` form allows ciphersuites using RSA key-agreement to be logged and was the first form + supported by Wireshark 1.6.0. It has been superseded by ``CLIENT_RANDOM`` which also works with + other key-agreement algorithms (such as those based on Diffie-Hellman) and is supported since + Wireshark 1.8.0. + + The TLS 1.3 lines are supported since NSS 3.34 (`bug + 1287711 <https://bugzilla.mozilla.org/show_bug.cgi?id=1287711>`__) and Wireshark 2.4 + (``EARLY_EXPORTER_SECRET`` exists since NSS 3.35, `bug + 1417331 <https://bugzilla.mozilla.org/show_bug.cgi?id=1417331>`__). The size of the hex-encoded + secret depends on the selected cipher suite. It is 64, 96 or 128 characters for SHA256, SHA384 or + SHA512 respectively. + + For Wireshark usage, see `TLS - Wireshark Wiki <https://wiki.wireshark.org/TLS>`__. diff --git a/security/nss/doc/rst/legacy/memory_allocation/index.rst b/security/nss/doc/rst/legacy/memory_allocation/index.rst new file mode 100644 index 0000000000..96d9807ee9 --- /dev/null +++ b/security/nss/doc/rst/legacy/memory_allocation/index.rst @@ -0,0 +1,52 @@ +.. _mozilla_projects_nss_memory_allocation: + +NSS Memory allocation +===================== + +.. container:: + + NSS makes extensive use of NSPR's PLArenaPools for memory allocation. + + Each block of memory allocated in a PLArenaPool is called a PLArena. When a PLArenaPool is freed, + all the arenas in that pool are put on an arena free list. When NSS attempts to allocate more + memory for an arena pool, the PLArenaPool code attempts to use an arena from its free list, and + only gets a new arena from the heap if there are no arenas in the free list that are large enough + to satisfy the request. + + There are two consequences of the use of PLArenaPools that affect leak analysis. They are: + + 1. At the end of execution of a program, all the arenas in the free list will appear to have been + leaked. This makes it difficult to tell arenas that are truly leaked from those that are merely + in the free list. + + There is a function named PL_ArenaFinish that really frees all the arenas on the free list. See + the prototype at + `http://mxr.mozilla.org/nspr/source/n.../ds/plarenas.h <http://mxr.mozilla.org/nspr/source/nsprpub/lib/ds/plarenas.h>`__ + + A program should call that function at the very end, after having shutdown NSS and NSPR, to + really free the contents of the free list. After that function returns, any arenas that still + appear to be leaked have truly been leaked, and are not merely on the free list. + + 2. Leak analysis tools will frequently report the wrong call stack for the allocation of leaked + arenas. + + When the arena free list is in use, the first user of an arena will allocate it from the heap, + but will then free it to the free list. The second user will allocated it from the free list and + return it to the free list. If and when an arena is leaked, the developer wants to see the call + stack of the most recent allocation of the arena, not the stack of the oldest allocation of that + arena. But leak analysis tools only record the allocation of memory from the heap, not memory + from the arena free list, so they will always show the first allocation (from the heap) and not + the most recent allocation (from the arena free list). + + Consequently, when the arena free list is in use, the allocation call stacks shown will typically + NOT be the stack of the code that most recently allocated that arena, but rather will be the + stack of the code that FIRST allocated that arena from the heap, and then placed it on the free + list. + + To solve that problem, it is generally necessary to disable the arena free list, so that arenas + are actually freed back to the heap each time they are freed, and are allocated afresh from the + heap each time they are allocated. This makes NSS slower, but produces accurate leak allocation + stacks. To accomplish that, set an environment variable prior to the initialization of NSS and + NSPR. This can be done outside the program entirely, or can be done by the program itself, in the + main() function. Set the environment variable NSS_DISABLE_ARENA_FREE_LIST to have any non-empty + value, e.g. NSS_DISABLE_ARENA_FREE_LIST=1.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/modutil-tasks.html/index.rst b/security/nss/doc/rst/legacy/modutil-tasks.html/index.rst new file mode 100644 index 0000000000..4232bfa7b7 --- /dev/null +++ b/security/nss/doc/rst/legacy/modutil-tasks.html/index.rst @@ -0,0 +1,24 @@ +.. _mozilla_projects_nss_modutil-tasks_html: + +modutil-tasks.html +================== + +.. _nss_security_tools_modutil_tasks: + +`NSS Security Tools: modutil Tasks <#nss_security_tools_modutil_tasks>`__ +------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. The jar installation script is very fragile with respect to platform definitions (especially + version numbers). A fix was made for "HPUX B.11.00," but issues may still arise for platforms + like "Linux 2.2.12-20." Documentation needs to be explicit about the use of Fo
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/more_docs.rst b/security/nss/doc/rst/legacy/more_docs.rst new file mode 100644 index 0000000000..49694f816b --- /dev/null +++ b/security/nss/doc/rst/legacy/more_docs.rst @@ -0,0 +1,10 @@ + +More documentation +================== + +.. toctree:: + :maxdepth: 5 + :glob: + + **/* + diff --git a/security/nss/doc/rst/legacy/new_nss_samples/index.rst b/security/nss/doc/rst/legacy/new_nss_samples/index.rst new file mode 100644 index 0000000000..9a9b0c10a7 --- /dev/null +++ b/security/nss/doc/rst/legacy/new_nss_samples/index.rst @@ -0,0 +1,41 @@ +.. _mozilla_projects_nss_new_nss_samples: + +New NSS Samples +=============== + +.. _new_nss_sample_code: + +`New NSS Sample Code <#new_nss_sample_code>`__ +---------------------------------------------- + +.. container:: + + This collection of sample code demonstrates how NSS can be used for cryptographic operations, + certificate handling, SSL, etc. It also demonstrates some best practices in the application of + cryptography. + + | + | These new examples are a work in progress. See + https://bugzilla.mozilla.org/show_bug.cgi?id=490238 + + How to download the samples: + + .. code:: sh + + hg clone https://hg.mozilla.org/projects/nss; cd nss; hg update SAMPLES_BRANCH + + Samples list: + + #. :ref:`mozilla_projects_nss_nss_sample_code_sample1_-_hashing` + #. :ref:`mozilla_projects_nss_nss_sample_code_sample2_-_initialize_nss_database` + #. :ref:`mozilla_projects_nss_encrypt_decrypt_mac_using_token` + #. :ref:`mozilla_projects_nss_encrypt_decrypt_mac_keys_as_session_objects` + #. :ref:`mozilla_projects_nss_nss_sample_code_enc_dec_mac_output_plblic_key_as_csr` + #. :ref:`mozilla_projects_nss_nss_sample_code_enc_dec_mac_using_key_wrap_certreq_pkcs10_csr` + + Common code used by these samples: + + #. :ref:`mozilla_projects_nss_nss_sample_code_utiltiies_for_nss_samples` + + Thanks are due to Shailendra Jain, Mozilla Community member, who is the principal author of these + samples.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/notes_on_tls_-_ssl_3.0_intolerant_servers/index.rst b/security/nss/doc/rst/legacy/notes_on_tls_-_ssl_3.0_intolerant_servers/index.rst new file mode 100644 index 0000000000..6dd0d47de2 --- /dev/null +++ b/security/nss/doc/rst/legacy/notes_on_tls_-_ssl_3.0_intolerant_servers/index.rst @@ -0,0 +1,172 @@ +.. _mozilla_projects_nss_notes_on_tls_-_ssl_3_0_intolerant_servers: + +Notes on TLS - SSL 3.0 Intolerant Servers +========================================= + +`Problem <#problem>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A number of Netscape 6.x/7.x and Mozilla users have reported that some secure sites -- typically + sites featuring online transactions or online banking over the HTTPS protocol -- do not display + any content at all. The connection seems terminated and a blank page is displayed. This is the + main symptom of the problem when Mozilla based browsers encounter TLS/SSL 3.0 intolerant servers. + +`Cause <#cause>`__ +~~~~~~~~~~~~~~~~~~ + +.. container:: + + There are some number of web servers in production today which incorrectly implement the SSL 3.0 + specification. This incorrect implementation causes them to reject connection attempts from + clients that are compliant with the **SSL 3.0** and **TLS (aka SSL 3.1)** specifications. + + Netscape 6.x/7.x and Mozilla browsers (0.9.1 and later versions) correctly implement the TLS + specification, and the users cannot utilize sites which have this problem. + +.. _technical_information: + +`Technical Information <#technical_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The **SSL 3.0** and **TLS (aka SSL 3.1)** specs both contain a provision -- the same provision -- + for detecting "version rollback attacks". It is designed to permit a server to detect a + man-in-the-middle that is altering the SSL client hello (connection) requests as they pass from + the client to the server, altering them by changing the protocol version number to a lower + version number. This feature was kind of meaningless until **TLS (SSL 3.1)** came along because + there was no version higher than 3.0 from which to be rolled back. TLS is now available and used, + and products that have implemented the roll-back detection incorrectly are not interoperable with + TLS/SSL spec-compliant clients. Normally the servers which have this problem are not equipped to + deal with the TLS protocol, but instead of rolling back to SSL 3.0 as the rollback provision + provides, they terminate/drop the connection, thus resulting in most cases a blank page display. + + For up-to-date information, you can read a Bugzilla bug report which keeps track of this problem + with Mozilla-based browsers. See + `bug 59321 <https://bugzilla.mozilla.org/show_bug.cgi?id=59321>`__. + +.. _servers_currently_known_to_exhibit_this_intolerant_behavior: + +`Servers currently known to exhibit this intolerant behavior <#servers_currently_known_to_exhibit_this_intolerant_behavior>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + As of this writing, this problem has been reported for the following servers: (Wherever there is + an upgraded version which fixes the problem, it is indicated by an asterisked remark in the + parentheses. ) + + - Domino-Go-Webserver/4.6.2.6 (and perhaps some later versions) + - IBM_HTTP_Server/1.3.6.3 or earlier (\* Update to 1.3.6.4) + - IBM_HTTP_Server/1.3.12.1 or earlier (\* `Update to + 1.3.12.2 <http://www6.software.ibm.com/dl/websphere/http-p>`__) + - Java Web Server 2 + - OSU/3.2 - DECthreads HTTP server for OpenVM + - Stronghold/2.2 + - Webmail v. 3.6.1 by Infinite Technologies (\* Update available) + + N.B. There might be servers other than those listed above which exhibit this problem. If you find + such a server, feel free to add it to this page. For up-to-date information, you can read this + `bug 59321 <https://bugzilla.mozilla.org/show_bug.cgi?id=59321>`__ which keeps a list of TLS/SSL + 3.0 intolerant servers. + +.. _users:_how_to_avoid_this_problem.3f: + +`Users: How to avoid this problem? <#users:_how_to_avoid_this_problem.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Netscape 6.1 Preview Release 1, or Mozilla 0.9.1 and earlier + :name: netscape_6.1_preview_release_1.2c_or_mozilla_0.9.1_and_earlier + + These versions shipped with the TLS option turned **ON** as the default but with no way to deal + with the problem servers. If you are using these old versions, please update to the latest + Netscape or Mozilla versions. You can also avoid such a problem by editing an existing profile -- + check the preference option setting at: Edit \| Preferences \| Privacy and Security \| SSL \| + Enable TLS, and turn it **OFF** if it is **ON** for these earlier browsers. + + .. rubric:: Netscape 6.1 or Mozilla 0.9.2 and later + :name: netscape_6.1_or_mozilla_0.9.2_and_later + + These browsers shipped with the TLS option **ON** but also included a graceful rollback mechanism + on the client side when they encounter known TLS/SSL 3.0 intolerant servers. + + .. rubric:: Firefox 2 and later + :name: firefox_2_and_later + + Starting with Firefox 2, support for SSL 2.0 has been disabled by default; unless it is expressly + re-enabled by the user using about:config. See `Security in Firefox + 2 <https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/2/Security_changes>`__ for + details. + +.. _website_administrators:_how_to_avoid_this_problem.3f: + +`Website Administrators: How to avoid this problem? <#website_administrators:_how_to_avoid_this_problem.3f>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Upgrade to a newer version if available, which corrects this problem. There will be other + network clients which implement TLS/SSL 3.0 specification correctly and have a problem with + your site. Let's not perpetuate the problem servers. + - Contact the manufacturer and inquire if there is a new version available which fixes this + problem. + - Post a note on your site instructing users of old versions of browsers like Netscape + 6.0/6.01/6.1 Preview Release 1 and Mozilla 0.9.1 and earlier to turn **OFF** the TLS option + at: Edit \| Preferences \| Privacy and Security \| SSL \| Enable TLS. However, this is a + temporary workaround at best. We recommend strongly that you urge users to upgrade to the + latest Netscape version (or at least Netscape 6.1) since the newer versions have the graceful + rollback implemented in the code. + - If you have questions concerning Netscape browsers and problem servers, please contact us + using the feedback address at the top of this page. + +.. _detecting_intolerant_servers: + +`Detecting intolerant servers <#detecting_intolerant_servers>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Because newer versions of Netscape and Mozilla have built-in workaround for the problem servers, + it is now unlikely that you will experience this problem. But if you're running Netscape + 6.0/6.01/6.1 PR 1 or Mozilla build (prior to 6/11/2001), you should look out for the symptom + described below. You may also run this test with versions later than the older versions of + Netscape 6.x or Mozilla -- just in case code changes in Netscape 6.1/Mozilla 0.9.2 or later may + not catch all problem servers. + + - When you find a secure site which simply does not display any page content or drops the + connection, check to see if the preference option Edit \| Preferences \| Privacy and Security + \| SSL \| Enable TLS is turned **ON**. If so, turn it **OFF**. + - Now re-visit the problem site. If the content displays this time, you are most likely + witnessing a TLS/SSL 3.0 intolerant server. + - Report such a problem to the server's administrator. + +.. _how_to_report_an_intolerant_server: + +`How to report an intolerant server <#how_to_report_an_intolerant_server>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - *Optional:*\ Get the name of the SSL server software used by the website. To do so, add + ``http://toolbar.netcraft.com/site_report?url=`` to the beginning of the URL. The server + software will appear next to **Server** under **SSL Certificate Information**. + For instance, to check ``https://bugzilla.mozilla.org/``, then visit + `http://toolbar.netcraft.com/site_rep...a.mozilla.org/ <http://toolbar.netcraft.com/site_report?url=https://bugzilla.mozilla.org/>`__. + - Add the information on such a server (software, URL) to + `bug 59321 <https://bugzilla.mozilla.org/show_bug.cgi?id=59321>`__ at Bugzilla. (Note: You + will be asked to provide your email address before you can file a bug at Bugzilla.) + +.. _original_document_information: + +`Original Document Information <#original_document_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Author : Katsuhiko Momoi + - Last Updated Date: January 27th, 2003 + - Copyright © 2001-2003 Netscape. All rights reserved.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nroff/certutil.1 b/security/nss/doc/rst/legacy/nroff/certutil.1 new file mode 100644 index 0000000000..9ff62f2f9e --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/certutil.1 @@ -0,0 +1,2165 @@ +'\" t +.\" Title: CERTUTIL +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "CERTUTIL" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +certutil \- Manage keys and certificate in both NSS databases and other NSS tokens +.SH "SYNOPSIS" +.HP \w'\fBcertutil\fR\ 'u +\fBcertutil\fR [\fIoptions\fR] [[\fIarguments\fR]] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The Certificate Database Tool, +\fBcertutil\fR, is a command\-line utility that can create and modify certificate and key databases\&. It can specifically list, generate, modify, or delete certificates, create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the key database\&. +.PP +Certificate issuance, part of the key and certificate management process, requires that keys and certificates be created in the key database\&. This document discusses certificate and key database management\&. For information on the security module database management, see the +\fBmodutil\fR +manpage\&. +.SH "COMMAND OPTIONS AND ARGUMENTS" +.PP +Running +\fBcertutil\fR +always requires one and only one command option to specify the type of certificate operation\&. Each command option may take zero or more arguments\&. The command option +\fB\-H\fR +will list all the command options and their relevant arguments\&. +.PP +\fBCommand Options\fR +.PP +\-A +.RS 4 +Add an existing certificate to a certificate database\&. The certificate database should already exist; if one is not present, this command option will initialize one by default\&. +.RE +.PP +\-B +.RS 4 +Run a series of commands from the specified batch file\&. This requires the +\fB\-i\fR +argument\&. +.RE +.PP +\-C +.RS 4 +Create a new binary certificate file from a binary certificate request file\&. Use the +\fB\-i\fR +argument to specify the certificate request file\&. If this argument is not used, +\fBcertutil\fR +prompts for a filename\&. +.RE +.PP +\-D +.RS 4 +Delete a certificate from the certificate database\&. +.RE +.PP +\-\-rename +.RS 4 +Change the database nickname of a certificate\&. +.RE +.PP +\-E +.RS 4 +Add an email certificate to the certificate database\&. +.RE +.PP +\-F +.RS 4 +Delete a private key and the associated certificate from a database\&. Specify the key to delete with the \-n argument or the \-k argument\&. Specify the database from which to delete the key with the +\fB\-d\fR +argument\&. +.sp +Some smart cards do not let you remove a public key you have generated\&. In such a case, only the private key is deleted from the key pair\&. +.RE +.PP +\-G +.RS 4 +Generate a new public and private key pair within a key database\&. The key database should already exist; if one is not present, this command option will initialize one by default\&. Some smart cards can store only one key pair\&. If you create a new key pair for such a card, the previous pair is overwritten\&. +.RE +.PP +\-H +.RS 4 +Display a list of the command options and arguments\&. +.RE +.PP +\-K +.RS 4 +List the key ID of keys in the key database\&. A key ID is the modulus of the RSA key or the publicValue of the DSA key\&. IDs are displayed in hexadecimal ("0x" is not shown)\&. +.RE +.PP +\-L +.RS 4 +List all the certificates, or display information about a named certificate, in a certificate database\&. Use the \-h tokenname argument to specify the certificate database on a particular hardware or software token\&. +.RE +.PP +\-M +.RS 4 +Modify a certificate\*(Aqs trust attributes using the values of the \-t argument\&. +.RE +.PP +\-N +.RS 4 +Create new certificate and key databases\&. +.RE +.PP +\-O +.RS 4 +Print the certificate chain\&. +.RE +.PP +\-R +.RS 4 +Create a certificate request file that can be submitted to a Certificate Authority (CA) for processing into a finished certificate\&. Output defaults to standard out unless you use \-o output\-file argument\&. Use the \-a argument to specify ASCII output\&. +.RE +.PP +\-S +.RS 4 +Create an individual certificate and add it to a certificate database\&. +.RE +.PP +\-T +.RS 4 +Reset the key database or token\&. +.RE +.PP +\-U +.RS 4 +List all available modules or print a single named module\&. +.RE +.PP +\-V +.RS 4 +Check the validity of a certificate and its attributes\&. +.RE +.PP +\-W +.RS 4 +Change the password to a key database\&. +.RE +.PP +\-\-merge +.RS 4 +Merge two databases into one\&. +.RE +.PP +\-\-upgrade\-merge +.RS 4 +Upgrade an old database and merge it into a new database\&. This is used to migrate legacy NSS databases (cert8\&.db +and +key3\&.db) into the newer SQLite databases (cert9\&.db +and +key4\&.db)\&. +.RE +.PP +\fBArguments\fR +.PP +Arguments modify a command option and are usually lower case, numbers, or symbols\&. +.PP +\-a +.RS 4 +Use ASCII format or allow the use of ASCII format for input or output\&. This formatting follows RFC 1113\&. For certificate requests, ASCII output defaults to standard output unless redirected\&. +.RE +.PP +\-\-simple\-self\-signed +.RS 4 +When printing the certificate chain, don\*(Aqt search for a chain if issuer name equals to subject name\&. +.RE +.PP +\-b validity\-time +.RS 4 +Specify a time at which a certificate is required to be valid\&. Use when checking certificate validity with the +\fB\-V\fR +option\&. The format of the +\fIvalidity\-time\fR +argument is +\fIYYMMDDHHMMSS[+HHMM|\-HHMM|Z]\fR, which allows offsets to be set relative to the validity end time\&. Specifying seconds (\fISS\fR) is optional\&. When specifying an explicit time, use a Z at the end of the term, +\fIYYMMDDHHMMSSZ\fR, to close it\&. When specifying an offset time, use +\fIYYMMDDHHMMSS+HHMM\fR +or +\fIYYMMDDHHMMSS\-HHMM\fR +for adding or subtracting time, respectively\&. +.sp +If this option is not used, the validity check defaults to the current system time\&. +.RE +.PP +\-c issuer +.RS 4 +Identify the certificate of the CA from which a new certificate will derive its authenticity\&. Use the exact nickname or alias of the CA certificate, or use the CA\*(Aqs email address\&. Bracket the issuer string with quotation marks if it contains spaces\&. +.RE +.PP +\-d [prefix]directory +.RS 4 +Specify the database directory containing the certificate and key database files\&. +.sp +\fBcertutil\fR +supports two types of databases: the legacy security databases (cert8\&.db, +key3\&.db, and +secmod\&.db) and new SQLite databases (cert9\&.db, +key4\&.db, and +pkcs11\&.txt)\&. +.sp +NSS recognizes the following prefixes: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBsql:\fR +requests the newer database +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBdbm:\fR +requests the legacy database +.RE +.sp +If no prefix is specified the default type is retrieved from NSS_DEFAULT_DB_TYPE\&. If NSS_DEFAULT_DB_TYPE is not set then +\fBsql:\fR +is the default\&. +.RE +.PP +\-\-dump\-ext\-val OID +.RS 4 +For single cert, print binary DER encoding of extension OID\&. +.RE +.PP +\-e +.RS 4 +Check a certificate\*(Aqs signature during the process of validating a certificate\&. +.RE +.PP +\-\-email email\-address +.RS 4 +Specify the email address of a certificate to list\&. Used with the \-L command option\&. +.RE +.PP +\-\-extGeneric OID:critical\-flag:filename[,OID:critical\-flag:filename]\&.\&.\&. +.RS 4 +Add one or multiple extensions that certutil cannot encode yet, by loading their encodings from external files\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +OID (example): 1\&.2\&.3\&.4 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +critical\-flag: critical or not\-critical +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +filename: full path to a file containing an encoded extension +.RE +.RE +.PP +\-f password\-file +.RS 4 +Specify a file that will automatically supply the password to include in a certificate or to access a certificate database\&. This is a plain\-text file containing one password\&. Be sure to prevent unauthorized access to this file\&. +.RE +.PP +\-g keysize +.RS 4 +Set a key size to use when generating new public and private key pairs\&. The minimum is 512 bits and the maximum is 16384 bits\&. The default is 2048 bits\&. Any size between the minimum and maximum is allowed\&. +.RE +.PP +\-h tokenname +.RS 4 +Specify the name of a token to use or act on\&. If not specified the default token is the internal database slot\&. +.sp +The name can also be a PKCS #11 URI\&. For example, the NSS internal certificate store can be unambiguously specified as "pkcs11:token=NSS%20Certificate%20DB"\&. For details about the format, see RFC 7512\&. +.RE +.PP +\-i input_file +.RS 4 +Pass an input file to the command\&. Depending on the command option, an input file can be a specific certificate, a certificate request file, or a batch file of commands\&. +.RE +.PP +\-k key\-type\-or\-id +.RS 4 +Specify the type or specific ID of a key\&. +.sp +The valid key type options are rsa, dsa, ec, or all\&. The default value is rsa\&. Specifying the type of key can avoid mistakes caused by duplicate nicknames\&. Giving a key type generates a new key pair; giving the ID of an existing key reuses that key pair (which is required to renew certificates)\&. +.RE +.PP +\-l +.RS 4 +Display detailed information when validating a certificate with the \-V option\&. +.RE +.PP +\-m serial\-number +.RS 4 +Assign a unique serial number to a certificate being created\&. This operation should be performed by a CA\&. If no serial number is provided a default serial number is made from the current time\&. Serial numbers are limited to integers +.RE +.PP +\-n nickname +.RS 4 +Specify the nickname of a certificate or key to list, create, add to a database, modify, or validate\&. Bracket the nickname string with quotation marks if it contains spaces\&. +.sp +The nickname can also be a PKCS #11 URI\&. For example, if you have a certificate named "my\-server\-cert" on the internal certificate store, it can be unambiguously specified as "pkcs11:token=NSS%20Certificate%20DB;object=my\-server\-cert"\&. For details about the format, see RFC 7512\&. +.RE +.PP +\-o output\-file +.RS 4 +Specify the output file name for new certificates or binary certificate requests\&. Bracket the output\-file string with quotation marks if it contains spaces\&. If this argument is not used the output destination defaults to standard output\&. +.RE +.PP +\-P dbPrefix +.RS 4 +Specify the prefix used on the certificate and key database file\&. This argument is provided to support legacy servers\&. Most applications do not use a database prefix\&. +.RE +.PP +\-p phone +.RS 4 +Specify a contact telephone number to include in new certificates or certificate requests\&. Bracket this string with quotation marks if it contains spaces\&. +.RE +.PP +\-q pqgfile or curve\-name +.RS 4 +Read an alternate PQG value from the specified file when generating DSA key pairs\&. If this argument is not used, +\fBcertutil\fR +generates its own PQG value\&. PQG files are created with a separate DSA utility\&. +.sp +Elliptic curve name is one of the ones from nistp256, nistp384, nistp521, curve25519\&. +.sp +If a token is available that supports more curves, the foolowing curves are supported as well: sect163k1, nistk163, sect163r1, sect163r2, nistb163, sect193r1, sect193r2, sect233k1, nistk233, sect233r1, nistb233, sect239k1, sect283k1, nistk283, sect283r1, nistb283, sect409k1, nistk409, sect409r1, nistb409, sect571k1, nistk571, sect571r1, nistb571, secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, nistp192, secp224k1, secp224r1, nistp224, secp256k1, secp256r1, secp384r1, secp521r1, prime192v1, prime192v2, prime192v3, prime239v1, prime239v2, prime239v3, c2pnb163v1, c2pnb163v2, c2pnb163v3, c2pnb176v1, c2tnb191v1, c2tnb191v2, c2tnb191v3, c2pnb208w1, c2tnb239v1, c2tnb239v2, c2tnb239v3, c2pnb272w1, c2pnb304w1, c2tnb359w1, c2pnb368w1, c2tnb431r1, secp112r1, secp112r2, secp128r1, secp128r2, sect113r1, sect113r2, sect131r1, sect131r2 +.RE +.PP +\-r +.RS 4 +Display a certificate\*(Aqs binary DER encoding when listing information about that certificate with the \-L option\&. +.RE +.PP +\-s subject +.RS 4 +Identify a particular certificate owner for new certificates or certificate requests\&. Bracket this string with quotation marks if it contains spaces\&. The subject identification format follows RFC #1485\&. +.RE +.PP +\-t trustargs +.RS 4 +Specify the trust attributes to modify in an existing certificate or to apply to a certificate when creating it or adding it to a database\&. There are three available trust categories for each certificate, expressed in the order +\fISSL, email, object signing\fR +for each trust setting\&. In each category position, use none, any, or all of the attribute codes: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBp\fR +\- Valid peer +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBP\fR +\- Trusted peer (implies p) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBc\fR +\- Valid CA +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBC\fR +\- Trusted CA (implies c) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBT\fR +\- trusted CA for client authentication (ssl server only) +.RE +.sp +The attribute codes for the categories are separated by commas, and the entire set of attributes enclosed by quotation marks\&. For example: +.sp +\fB\-t "TC,C,T"\fR +.sp +Use the \-L option to see a list of the current certificates and trust attributes in a certificate database\&. +.sp +Note that the output of the \-L option may include "u" flag, which means that there is a private key associated with the certificate\&. It is a dynamic flag and you cannot set it with certutil\&. +.RE +.PP +\-u certusage +.RS 4 +Specify a usage context to apply when validating a certificate with the \-V option\&. +.sp +The contexts are the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBC\fR +(as an SSL client) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBV\fR +(as an SSL server) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBL\fR +(as an SSL CA) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBA\fR +(as Any CA) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBY\fR +(Verify CA) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBS\fR +(as an email signer) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBR\fR +(as an email recipient) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBO\fR +(as an OCSP status responder) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBJ\fR +(as an object signer) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBI\fR +(as an IPSEC user) +.RE +.RE +.PP +\-v valid\-months +.RS 4 +Set the number of months a new certificate will be valid\&. The validity period begins at the current system time unless an offset is added or subtracted with the +\fB\-w\fR +option\&. If this argument is not used, the default validity period is three months\&. +.RE +.PP +\-w offset\-months +.RS 4 +Set an offset from the current system time, in months, for the beginning of a certificate\*(Aqs validity period\&. Use when creating the certificate or adding it to a database\&. Express the offset in integers, using a minus sign (\-) to indicate a negative offset\&. If this argument is not used, the validity period begins at the current system time\&. The length of the validity period is set with the \-v argument\&. +.RE +.PP +\-X +.RS 4 +Force the key and certificate database to open in read\-write mode\&. This is used with the +\fB\-U\fR +and +\fB\-L\fR +command options\&. +.RE +.PP +\-x +.RS 4 +Use +\fBcertutil\fR +to generate the signature for a certificate being created or added to a database, rather than obtaining a signature from a separate CA\&. +.RE +.PP +\-y exp +.RS 4 +Set an alternate exponent value to use in generating a new RSA public key for the database, instead of the default value of 65537\&. The available alternate values are 3 and 17\&. +.RE +.PP +\-\-pss +.RS 4 +Restrict the generated certificate (with the +\fB\-S\fR +option) or certificate request (with the +\fB\-R\fR +option) to be used with the RSA\-PSS signature scheme\&. This only works when the private key of the certificate or certificate request is RSA\&. +.RE +.PP +\-\-pss\-sign +.RS 4 +Sign the generated certificate with the RSA\-PSS signature scheme (with the +\fB\-C\fR +or +\fB\-S\fR +option)\&. This only works when the private key of the signer\*(Aqs certificate is RSA\&. If the signer\*(Aqs certificate is restricted to RSA\-PSS, it is not necessary to specify this option\&. +.RE +.PP +\-z noise\-file +.RS 4 +Read a seed value from the specified file to generate a new private and public key pair\&. This argument makes it possible to use hardware\-generated seed values or manually create a value from the keyboard\&. The minimum file size is 20 bytes\&. +.RE +.PP +\-Z hashAlg +.RS 4 +Specify the hash algorithm to use with the \-C, \-S or \-R command options\&. Possible keywords: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +MD2 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +MD4 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +MD5 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA1 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA224 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA256 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA384 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA512 +.RE +.RE +.PP +\-0 SSO_password +.RS 4 +Set a site security officer password on a token\&. +.RE +.PP +\-1 | \-\-keyUsage keyword,keyword +.RS 4 +Set an X\&.509 V3 Certificate Type Extension in the certificate\&. There are several available keywords: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +digitalSignature +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +nonRepudiation +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +keyEncipherment +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +dataEncipherment +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +keyAgreement +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +certSigning +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +crlSigning +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +critical +.RE +.RE +.PP +\-2 +.RS 4 +Add a basic constraint extension to a certificate that is being created or added to a database\&. This extension supports the certificate chain verification process\&. +\fBcertutil\fR +prompts for the certificate constraint extension to select\&. +.sp +X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-3 +.RS 4 +Add an authority key ID extension to a certificate that is being created or added to a database\&. This extension supports the identification of a particular certificate, from among multiple certificates associated with one subject name, as the correct issuer of a certificate\&. The Certificate Database Tool will prompt you to select the authority key ID extension\&. +.sp +X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-4 +.RS 4 +Add a CRL distribution point extension to a certificate that is being created or added to a database\&. This extension identifies the URL of a certificate\*(Aqs associated certificate revocation list (CRL)\&. +\fBcertutil\fR +prompts for the URL\&. +.sp +X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-5 | \-\-nsCertType keyword,keyword +.RS 4 +Add an X\&.509 V3 certificate type extension to a certificate that is being created or added to the database\&. There are several available keywords: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +sslClient +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +sslServer +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +smime +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +objectSigning +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +sslCA +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +smimeCA +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +objectSigningCA +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +critical +.RE +.sp +X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-6 | \-\-extKeyUsage keyword,keyword +.RS 4 +Add an extended key usage extension to a certificate that is being created or added to the database\&. Several keywords are available: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +serverAuth +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +clientAuth +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +codeSigning +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +emailProtection +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +timeStamp +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ocspResponder +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +stepUp +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +msTrustListSign +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +critical +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +x509Any +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ipsecIKE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ipsecIKEEnd +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ipsecIKEIntermediate +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ipsecEnd +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ipsecTunnel +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ipsecUser +.RE +.sp +X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-7 emailAddrs +.RS 4 +Add a comma\-separated list of email addresses to the subject alternative name extension of a certificate or certificate request that is being created or added to the database\&. Subject alternative name extensions are described in Section 4\&.2\&.1\&.7 of RFC 3280\&. +.RE +.PP +\-8 dns\-names +.RS 4 +Add a comma\-separated list of DNS names to the subject alternative name extension of a certificate or certificate request that is being created or added to the database\&. Subject alternative name extensions are described in Section 4\&.2\&.1\&.7 of RFC 3280\&. +.RE +.PP +\-\-extAIA +.RS 4 +Add the Authority Information Access extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extSIA +.RS 4 +Add the Subject Information Access extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extCP +.RS 4 +Add the Certificate Policies extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extPM +.RS 4 +Add the Policy Mappings extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extPC +.RS 4 +Add the Policy Constraints extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extIA +.RS 4 +Add the Inhibit Any Policy Access extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extSKID +.RS 4 +Add the Subject Key ID extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extNC +.RS 4 +Add a Name Constraint extension to the certificate\&. X\&.509 certificate extensions are described in RFC 5280\&. +.RE +.PP +\-\-extSAN type:name[,type:name]\&.\&.\&. +.RS 4 +Create a Subject Alt Name extension with one or multiple names\&. +.sp +\-type: directory, dn, dns, edi, ediparty, email, ip, ipaddr, other, registerid, rfc822, uri, x400, x400addr +.RE +.PP +\-\-empty\-password +.RS 4 +Use empty password when creating new certificate database with \-N\&. +.RE +.PP +\-\-keyAttrFlags attrflags +.RS 4 +PKCS #11 key Attributes\&. Comma separated list of key attribute flags, selected from the following list of choices: {token | session} {public | private} {sensitive | insensitive} {modifiable | unmodifiable} {extractable | unextractable} +.RE +.PP +\-\-keyOpFlagsOn opflags, \-\-keyOpFlagsOff opflags +.RS 4 +PKCS #11 key Operation Flags\&. Comma separated list of one or more of the following: {token | session} {public | private} {sensitive | insensitive} {modifiable | unmodifiable} {extractable | unextractable} +.RE +.PP +\-\-new\-n nickname +.RS 4 +A new nickname, used when renaming a certificate\&. +.RE +.PP +\-\-source\-dir certdir +.RS 4 +Identify the certificate database directory to upgrade\&. +.RE +.PP +\-\-source\-prefix certdir +.RS 4 +Give the prefix of the certificate and key databases to upgrade\&. +.RE +.PP +\-\-upgrade\-id uniqueID +.RS 4 +Give the unique ID of the database to upgrade\&. +.RE +.PP +\-\-upgrade\-token\-name name +.RS 4 +Set the name of the token to use while it is being upgraded\&. +.RE +.PP +\-@ pwfile +.RS 4 +Give the name of a password file to use for the database being upgraded\&. +.RE +.SH "USAGE AND EXAMPLES" +.PP +Most of the command options in the examples listed here have more arguments available\&. The arguments included in these examples are the most common ones or are used to illustrate a specific scenario\&. Use the +\fB\-H\fR +option to show the complete list of arguments for each command option\&. +.PP +\fBCreating New Security Databases\fR +.PP +Certificates, keys, and security modules related to managing certificates are stored in three related databases: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert8\&.db or cert9\&.db +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key3\&.db or key4\&.db +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +secmod\&.db or pkcs11\&.txt +.RE +.PP +These databases must be created before certificates or keys can be generated\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-N \-d directory +.fi +.if n \{\ +.RE +.\} +.PP +\fBCreating a Certificate Request\fR +.PP +A certificate request contains most or all of the information that is used to generate the final certificate\&. This request is submitted separately to a certificate authority and is then approved by some mechanism (automatically or by human review)\&. Once the request is approved, then the certificate is generated\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-R \-k key\-type\-or\-id [\-q pqgfile|curve\-name] \-g key\-size \-s subject [\-h tokenname] \-d directory [\-p phone] [\-o output\-file] [\-a] +.fi +.if n \{\ +.RE +.\} +.PP +The +\fB\-R\fR +command options requires four arguments: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB\-k\fR +to specify either the key type to generate or, when renewing a certificate, the existing key pair to use +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB\-g\fR +to set the keysize of the key to generate +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB\-s\fR +to set the subject name of the certificate +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB\-d\fR +to give the security database directory +.RE +.PP +The new certificate request can be output in ASCII format (\fB\-a\fR) or can be written to a specified file (\fB\-o\fR)\&. +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-R \-k rsa \-g 1024 \-s "CN=John Smith,O=Example Corp,L=Mountain View,ST=California,C=US" \-d $HOME/nssdb \-p 650\-555\-0123 \-a \-o cert\&.cer + +Generating key\&. This may take a few moments\&.\&.\&. + +.fi +.if n \{\ +.RE +.\} +.PP +\fBCreating a Certificate\fR +.PP +A valid certificate must be issued by a trusted CA\&. This can be done by specifying a CA certificate (\fB\-c\fR) that is stored in the certificate database\&. If a CA key pair is not available, you can create a self\-signed certificate using the +\fB\-x\fR +argument with the +\fB\-S\fR +command option\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-S \-k rsa|dsa|ec \-n certname \-s subject [\-c issuer |\-x] \-t trustargs \-d directory [\-m serial\-number] [\-v valid\-months] [\-w offset\-months] [\-p phone] [\-1] [\-2] [\-3] [\-4] [\-5 keyword] [\-6 keyword] [\-7 emailAddress] [\-8 dns\-names] [\-\-extAIA] [\-\-extSIA] [\-\-extCP] [\-\-extPM] [\-\-extPC] [\-\-extIA] [\-\-extSKID] +.fi +.if n \{\ +.RE +.\} +.PP +The series of numbers and +\fB\-\-ext*\fR +options set certificate extensions that can be added to the certificate when it is generated by the CA\&. Interactive prompts will result\&. +.PP +For example, this creates a self\-signed certificate: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-S \-s "CN=Example CA" \-n my\-ca\-cert \-x \-t "C,C,C" \-1 \-2 \-5 \-m 3650 +.fi +.if n \{\ +.RE +.\} +.PP +The interative prompts for key usage and whether any extensions are critical and responses have been ommitted for brevity\&. +.PP +From there, new certificates can reference the self\-signed certificate: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-S \-s "CN=My Server Cert" \-n my\-server\-cert \-c "my\-ca\-cert" \-t ",," \-1 \-5 \-6 \-8 \-m 730 +.fi +.if n \{\ +.RE +.\} +.PP +\fBGenerating a Certificate from a Certificate Request\fR +.PP +When a certificate request is created, a certificate can be generated by using the request and then referencing a certificate authority signing certificate (the +\fIissuer\fR +specified in the +\fB\-c\fR +argument)\&. The issuing certificate must be in the certificate database in the specified directory\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-C \-c issuer \-i cert\-request\-file \-o output\-file [\-m serial\-number] [\-v valid\-months] [\-w offset\-months] \-d directory [\-1] [\-2] [\-3] [\-4] [\-5 keyword] [\-6 keyword] [\-7 emailAddress] [\-8 dns\-names] +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-C \-c "my\-ca\-cert" \-i /home/certs/cert\&.req \-o cert\&.cer \-m 010 \-v 12 \-w 1 \-d $HOME/nssdb \-1 nonRepudiation,dataEncipherment \-5 sslClient \-6 clientAuth \-7 jsmith@example\&.com +.fi +.if n \{\ +.RE +.\} +.PP +\fBListing Certificates\fR +.PP +The +\fB\-L\fR +command option lists all of the certificates listed in the certificate database\&. The path to the directory (\fB\-d\fR) is required\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-L \-d /home/my/sharednssdb + +Certificate Nickname Trust Attributes + SSL,S/MIME,JAR/XPI + +CA Administrator of Instance pki\-ca1\*(Aqs Example Domain ID u,u,u +TPS Administrator\*(Aqs Example Domain ID u,u,u +Google Internet Authority ,, +Certificate Authority \- Example Domain CT,C,C +.fi +.if n \{\ +.RE +.\} +.PP +Using additional arguments with +\fB\-L\fR +can return and print the information for a single, specific certificate\&. For example, the +\fB\-n\fR +argument passes the certificate name, while the +\fB\-a\fR +argument prints the certificate in ASCII format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-L \-d $HOME/nssdb \-a \-n my\-ca\-cert +\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\- +MIIB1DCCAT2gAwIBAgICDkIwDQYJKoZIhvcNAQEFBQAwFTETMBEGA1UEAxMKRXhh +bXBsZSBDQTAeFw0xMzAzMTMxOTEwMjlaFw0xMzA2MTMxOTEwMjlaMBUxEzARBgNV +BAMTCkV4YW1wbGUgQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJ4Kzqvz +JyBVgFqDXRYSyTBNw1DrxUU/3GvWA/ngjAwHEv0Cul/6sO/gsCvnABHiH6unns6x +XRzPORlC2WY3gkk7vmlsLvYpyecNazAi/NAwVnU/66HOsaoVFWE+gBQo99UrN2yk +0BiK/GMFlLm5dXQROgA9ZKKyFdI0LIXtf6SbAgMBAAGjMzAxMBEGCWCGSAGG+EIB +AQQEAwIHADAMBgNVHRMEBTADAQH/MA4GA1UdDwEB/wQEAwICBDANBgkqhkiG9w0B +AQUFAAOBgQA6chkzkACN281d1jKMrc+RHG2UMaQyxiteaLVZO+Ro1nnRUvseDf09 +XKYFwPMJjWCihVku6bw/ihZfuMHhxK22Nue6inNQ6eDu7WmrqL8z3iUrQwxs+WiF +ob2rb8XRVVJkzXdXxlk4uo3UtNvw8sAz7sWD71qxKaIHU5q49zijfg== +\-\-\-\-\-END CERTIFICATE\-\-\-\-\- +.fi +.if n \{\ +.RE +.\} +.PP +For a human\-readable display +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-L \-d $HOME/nssdb \-n my\-ca\-cert +Certificate: + Data: + Version: 3 (0x2) + Serial Number: 3650 (0xe42) + Signature Algorithm: PKCS #1 SHA\-1 With RSA Encryption + Issuer: "CN=Example CA" + Validity: + Not Before: Wed Mar 13 19:10:29 2013 + Not After : Thu Jun 13 19:10:29 2013 + Subject: "CN=Example CA" + Subject Public Key Info: + Public Key Algorithm: PKCS #1 RSA Encryption + RSA Public Key: + Modulus: + 9e:0a:ce:ab:f3:27:20:55:80:5a:83:5d:16:12:c9:30: + 4d:c3:50:eb:c5:45:3f:dc:6b:d6:03:f9:e0:8c:0c:07: + 12:fd:02:ba:5f:fa:b0:ef:e0:b0:2b:e7:00:11:e2:1f: + ab:a7:9e:ce:b1:5d:1c:cf:39:19:42:d9:66:37:82:49: + 3b:be:69:6c:2e:f6:29:c9:e7:0d:6b:30:22:fc:d0:30: + 56:75:3f:eb:a1:ce:b1:aa:15:15:61:3e:80:14:28:f7: + d5:2b:37:6c:a4:d0:18:8a:fc:63:05:94:b9:b9:75:74: + 11:3a:00:3d:64:a2:b2:15:d2:34:2c:85:ed:7f:a4:9b + Exponent: 65537 (0x10001) + Signed Extensions: + Name: Certificate Type + Data: none + + Name: Certificate Basic Constraints + Data: Is a CA with no maximum path length\&. + + Name: Certificate Key Usage + Critical: True + Usages: Certificate Signing + + Signature Algorithm: PKCS #1 SHA\-1 With RSA Encryption + Signature: + 3a:72:19:33:90:00:8d:db:cd:5d:d6:32:8c:ad:cf:91: + 1c:6d:94:31:a4:32:c6:2b:5e:68:b5:59:3b:e4:68:d6: + 79:d1:52:fb:1e:0d:fd:3d:5c:a6:05:c0:f3:09:8d:60: + a2:85:59:2e:e9:bc:3f:8a:16:5f:b8:c1:e1:c4:ad:b6: + 36:e7:ba:8a:73:50:e9:e0:ee:ed:69:ab:a8:bf:33:de: + 25:2b:43:0c:6c:f9:68:85:a1:bd:ab:6f:c5:d1:55:52: + 64:cd:77:57:c6:59:38:ba:8d:d4:b4:db:f0:f2:c0:33: + ee:c5:83:ef:5a:b1:29:a2:07:53:9a:b8:f7:38:a3:7e + Fingerprint (MD5): + 86:D8:A5:8B:8A:26:BE:9E:17:A8:7B:66:10:6B:27:80 + Fingerprint (SHA1): + 48:78:09:EF:C5:D4:0C:BD:D2:64:45:59:EB:03:13:15:F7:A9:D6:F7 + + Certificate Trust Flags: + SSL Flags: + Valid CA + Trusted CA + User + Email Flags: + Valid CA + Trusted CA + User + Object Signing Flags: + Valid CA + Trusted CA + User + +.fi +.if n \{\ +.RE +.\} +.PP +\fBListing Keys\fR +.PP +Keys are the original material used to encrypt certificate data\&. The keys generated for certificates are stored separately, in the key database\&. +.PP +To list all keys in the database, use the +\fB\-K\fR +command option and the (required) +\fB\-d\fR +argument to give the path to the directory\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-K \-d $HOME/nssdb +certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services " +< 0> rsa 455a6673bde9375c2887ec8bf8016b3f9f35861d Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID +< 1> rsa 40defeeb522ade11090eacebaaf1196a172127df Example Domain Administrator Cert +< 2> rsa 1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5 John Smith user cert +.fi +.if n \{\ +.RE +.\} +.PP +There are ways to narrow the keys listed in the search results: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +To return a specific key, use the +\fB\-n\fR +\fIname\fR +argument with the name of the key\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If there are multiple security devices loaded, then the +\fB\-h\fR +\fItokenname\fR +argument can search a specific token or all tokens\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If there are multiple key types available, then the +\fB\-k\fR +\fIkey\-type\fR +argument can search a specific type of key, like RSA, DSA, or ECC\&. +.RE +.PP +\fBListing Security Modules\fR +.PP +The devices that can be used to store certificates \-\- both internal databases and external devices like smart cards \-\- are recognized and used by loading security modules\&. The +\fB\-U\fR +command option lists all of the security modules listed in the +secmod\&.db +database\&. The path to the directory (\fB\-d\fR) is required\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-U \-d /home/my/sharednssdb + + slot: NSS User Private Key and Certificate Services + token: NSS Certificate DB + uri: pkcs11:token=NSS%20Certificate%20DB;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203 + + slot: NSS Internal Cryptographic Services + token: NSS Generic Crypto Services + uri: pkcs11:token=NSS%20Generic%20Crypto%20Services;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203 +.fi +.if n \{\ +.RE +.\} +.PP +\fBAdding Certificates to the Database\fR +.PP +Existing certificates or certificate requests can be added manually to the certificate database, even if they were generated elsewhere\&. This uses the +\fB\-A\fR +command option\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-A \-n certname \-t trustargs \-d directory [\-a] [\-i input\-file] +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-A \-n "CN=My SSL Certificate" \-t ",," \-d /home/my/sharednssdb \-i /home/example\-certs/cert\&.cer +.fi +.if n \{\ +.RE +.\} +.PP +A related command option, +\fB\-E\fR, is used specifically to add email certificates to the certificate database\&. The +\fB\-E\fR +command has the same arguments as the +\fB\-A\fR +command\&. The trust arguments for certificates have the format +\fISSL,S/MIME,Code\-signing\fR, so the middle trust settings relate most to email certificates (though the others can be set)\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-E \-n "CN=John Smith Email Cert" \-t ",P," \-d /home/my/sharednssdb \-i /home/example\-certs/email\&.cer +.fi +.if n \{\ +.RE +.\} +.PP +\fBDeleting Certificates to the Database\fR +.PP +Certificates can be deleted from a database using the +\fB\-D\fR +option\&. The only required options are to give the security database directory and to identify the certificate nickname\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-D \-d directory \-n "nickname" +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-D \-d /home/my/sharednssdb \-n "my\-ssl\-cert" +.fi +.if n \{\ +.RE +.\} +.PP +\fBValidating Certificates\fR +.PP +A certificate contains an expiration date in itself, and expired certificates are easily rejected\&. However, certificates can also be revoked before they hit their expiration date\&. Checking whether a certificate has been revoked requires validating the certificate\&. Validation can also be used to ensure that the certificate is only used for the purposes it was initially issued for\&. Validation is carried out by the +\fB\-V\fR +command option\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-V \-n certificate\-name [\-b time] [\-e] [\-u cert\-usage] \-d directory +.fi +.if n \{\ +.RE +.\} +.PP +For example, to validate an email certificate: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-V \-n "John Smith\*(Aqs Email Cert" \-e \-u S,R \-d /home/my/sharednssdb +.fi +.if n \{\ +.RE +.\} +.PP +\fBModifying Certificate Trust Settings\fR +.PP +The trust settings (which relate to the operations that a certificate is allowed to be used for) can be changed after a certificate is created or added to the database\&. This is especially useful for CA certificates, but it can be performed for any type of certificate\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-M \-n certificate\-name \-t trust\-args \-d directory +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-M \-n "My CA Certificate" \-d /home/my/sharednssdb \-t "CT,CT,CT" +.fi +.if n \{\ +.RE +.\} +.PP +\fBPrinting the Certificate Chain\fR +.PP +Certificates can be issued in +\fIchains\fR +because every certificate authority itself has a certificate; when a CA issues a certificate, it essentially stamps that certificate with its own fingerprint\&. The +\fB\-O\fR +prints the full chain of a certificate, going from the initial CA (the root CA) through ever intermediary CA to the actual certificate\&. For example, for an email certificate with two CAs in the chain: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-d /home/my/sharednssdb \-O \-n "jsmith@example\&.com" +"Builtin Object Token:Thawte Personal Freemail CA" [E=personal\-freemail@thawte\&.com,CN=Thawte Personal Freemail CA,OU=Certification Services Division,O=Thawte Consulting,L=Cape Town,ST=Western Cape,C=ZA] + + "Thawte Personal Freemail Issuing CA \- Thawte Consulting" [CN=Thawte Personal Freemail Issuing CA,O=Thawte Consulting (Pty) Ltd\&.,C=ZA] + + "(null)" [E=jsmith@example\&.com,CN=Thawte Freemail Member] +.fi +.if n \{\ +.RE +.\} +.PP +\fBResetting a Token\fR +.PP +The device which stores certificates \-\- both external hardware devices and internal software databases \-\- can be blanked and reused\&. This operation is performed on the device which stores the data, not directly on the security databases, so the location must be referenced through the token name (\fB\-h\fR) as well as any directory path\&. If there is no external token used, the default value is internal\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-T \-d directory \-h token\-name \-0 security\-officer\-password +.fi +.if n \{\ +.RE +.\} +.PP +Many networks have dedicated personnel who handle changes to security tokens (the security officer)\&. This person must supply the password to access the specified token\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-T \-d /home/my/sharednssdb \-h nethsm \-0 secret +.fi +.if n \{\ +.RE +.\} +.PP +\fBUpgrading or Merging the Security Databases\fR +.PP +Many networks or applications may be using older BerkeleyDB versions of the certificate database (cert8\&.db)\&. Databases can be upgraded to the new SQLite version of the database (cert9\&.db) using the +\fB\-\-upgrade\-merge\fR +command option or existing databases can be merged with the new +cert9\&.db +databases using the +\fB\-\-\-merge\fR +command\&. +.PP +The +\fB\-\-upgrade\-merge\fR +command must give information about the original database and then use the standard arguments (like +\fB\-d\fR) to give the information about the new databases\&. The command also requires information that the tool uses for the process to upgrade and write over the original database\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-\-upgrade\-merge \-d directory [\-P dbprefix] \-\-source\-dir directory \-\-source\-prefix dbprefix \-\-upgrade\-id id \-\-upgrade\-token\-name name [\-@ password\-file] +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-\-upgrade\-merge \-d /home/my/sharednssdb \-\-source\-dir /opt/my\-app/alias/ \-\-source\-prefix serverapp\- \-\-upgrade\-id 1 \-\-upgrade\-token\-name internal +.fi +.if n \{\ +.RE +.\} +.PP +The +\fB\-\-merge\fR +command only requires information about the location of the original database; since it doesn\*(Aqt change the format of the database, it can write over information without performing interim step\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +certutil \-\-merge \-d directory [\-P dbprefix] \-\-source\-dir directory \-\-source\-prefix dbprefix [\-@ password\-file] +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-\-merge \-d /home/my/sharednssdb \-\-source\-dir /opt/my\-app/alias/ \-\-source\-prefix serverapp\- +.fi +.if n \{\ +.RE +.\} +.PP +\fBRunning certutil Commands from a Batch File\fR +.PP +A series of commands can be run sequentially from a text file with the +\fB\-B\fR +command option\&. The only argument for this specifies the input file\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-B \-i /path/to/batch\-file +.fi +.if n \{\ +.RE +.\} +.SH "NSS DATABASE TYPES" +.PP +NSS originally used BerkeleyDB databases to store security information\&. The last versions of these +\fIlegacy\fR +databases are: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert8\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key3\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +secmod\&.db for PKCS #11 module information +.RE +.PP +BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously\&. NSS has some flexibility that allows applications to use their own, independent database engine while keeping a shared database and working around the access issues\&. Still, NSS requires more flexibility to provide a truly shared security database\&. +.PP +In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkeleyDB\&. These new databases provide more accessibility and performance: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert9\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key4\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +pkcs11\&.txt, a listing of all of the PKCS #11 modules, contained in a new subdirectory in the security databases directory +.RE +.PP +Because the SQLite databases are designed to be shared, these are the +\fIshared\fR +database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&. +.PP +By default, the tools (\fBcertutil\fR, +\fBpk12util\fR, +\fBmodutil\fR) assume that the given security databases use the SQLite type\&. Using the legacy databases must be manually specified by using the +\fBdbm:\fR +prefix with the given security directory\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ certutil \-L \-d dbm:/home/my/sharednssdb +.fi +.if n \{\ +.RE +.\} +.PP +To set the legacy database type as the default type for the tools, set the +\fBNSS_DEFAULT_DB_TYPE\fR +environment variable to +\fBdbm\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +export NSS_DEFAULT_DB_TYPE="dbm" +.fi +.if n \{\ +.RE +.\} +.PP +This line can be set added to the +~/\&.bashrc +file to make the change permanent\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.PP +For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "SEE ALSO" +.PP +pk12util (1) +.PP +modutil (1) +.PP +\fBcertutil\fR +has arguments or operations that use features defined in several IETF RFCs\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +http://tools\&.ietf\&.org/html/rfc5280 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +http://tools\&.ietf\&.org/html/rfc1113 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +http://tools\&.ietf\&.org/html/rfc1485 +.RE +.PP +The NSS wiki has information on the new database design and how to configure applications to use it\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/cmsutil.1 b/security/nss/doc/rst/legacy/nroff/cmsutil.1 new file mode 100644 index 0000000000..9c0bb48e98 --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/cmsutil.1 @@ -0,0 +1,271 @@ +'\" t +.\" Title: CMSUTIL +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 5 June 2014 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "CMSUTIL" "1" "5 June 2014" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +cmsutil \- Performs basic cryptograpic operations, such as encryption and decryption, on Cryptographic Message Syntax (CMS) messages\&. +.SH "SYNOPSIS" +.HP \w'\fBcmsutil\fR\ 'u +\fBcmsutil\fR [\fIoptions\fR] [[\fIarguments\fR]] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The +\fBcmsutil\fR +command\-line uses the S/MIME Toolkit to perform basic operations, such as encryption and decryption, on Cryptographic Message Syntax (CMS) messages\&. +.PP +To run cmsutil, type the command cmsutil option [arguments] where option and arguments are combinations of the options and arguments listed in the following section\&. Each command takes one option\&. Each option may take zero or more arguments\&. To see a usage string, issue the command without options\&. +.SH "OPTIONS AND ARGUMENTS" +.PP +.PP +\fBOptions\fR +.PP +Options specify an action\&. Option arguments modify an action\&. The options and arguments for the cmsutil command are defined as follows: +.PP +\-C +.RS 4 +Encrypt a message\&. +.RE +.PP +\-D +.RS 4 +Decode a message\&. +.RE +.PP +\-E +.RS 4 +Envelope a message\&. +.RE +.PP +\-O +.RS 4 +Create a certificates\-only message\&. +.RE +.PP +\-S +.RS 4 +Sign a message\&. +.RE +.PP +\fBArguments\fR +.PP +Option arguments modify an action\&. +.PP +\-b +.RS 4 +Decode a batch of files named in infile\&. +.RE +.PP +\-c content +.RS 4 +Use this detached content (decode only)\&. +.RE +.PP +\-d dbdir +.RS 4 +Specify the key/certificate database directory (default is "\&.") +.RE +.PP +\-e envfile +.RS 4 +Specify a file containing an enveloped message for a set of recipients to which you would like to send an encrypted message\&. If this is the first encrypted message for that set of recipients, a new enveloped message will be created that you can then use for future messages (encrypt only)\&. +.RE +.PP +\-f pwfile +.RS 4 +Use password file to set password on all PKCS#11 tokens\&. +.RE +.PP +\-G +.RS 4 +Include a signing time attribute (sign only)\&. +.RE +.PP +\-H hash +.RS 4 +Use specified hash algorithm (default:SHA1)\&. +.RE +.PP +\-h num +.RS 4 +Generate email headers with info about CMS message (decode only)\&. +.RE +.PP +\-i infile +.RS 4 +Use infile as a source of data (default is stdin)\&. +.RE +.PP +\-k +.RS 4 +Keep decoded encryption certs in permanent cert db\&. +.RE +.PP +\-N nickname +.RS 4 +Specify nickname of certificate to sign with (sign only)\&. +.RE +.PP +\-n +.RS 4 +Suppress output of contents (decode only)\&. +.RE +.PP +\-o outfile +.RS 4 +Use outfile as a destination of data (default is stdout)\&. +.RE +.PP +\-P +.RS 4 +Include an S/MIME capabilities attribute\&. +.RE +.PP +\-p password +.RS 4 +Use password as key database password\&. +.RE +.PP +\-r recipient1,recipient2, \&.\&.\&. +.RS 4 +Specify list of recipients (email addresses) for an encrypted or enveloped message\&. For certificates\-only message, list of certificates to send\&. +.RE +.PP +\-T +.RS 4 +Suppress content in CMS message (sign only)\&. +.RE +.PP +\-u certusage +.RS 4 +Set type of cert usage (default is certUsageEmailSigner)\&. +.RE +.PP +\-v +.RS 4 +Print debugging information\&. +.RE +.PP +\-Y ekprefnick +.RS 4 +Specify an encryption key preference by nickname\&. +.RE +.SH "USAGE" +.PP +Encrypt Example +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmsutil \-C [\-i infile] [\-o outfile] [\-d dbdir] [\-p password] \-r "recipient1,recipient2, \&. \&. \&." \-e envfile + +.fi +.if n \{\ +.RE +.\} +.PP +Decode Example +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmsutil \-D [\-i infile] [\-o outfile] [\-d dbdir] [\-p password] [\-c content] [\-n] [\-h num] + +.fi +.if n \{\ +.RE +.\} +.PP +Envelope Example +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmsutil \-E [\-i infile] [\-o outfile] [\-d dbdir] [\-p password] \-r "recipient1,recipient2, \&.\&.\&." + +.fi +.if n \{\ +.RE +.\} +.PP +Certificate\-only Example +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmsutil \-O [\-i infile] [\-o outfile] [\-d dbdir] [\-p password] \-r "cert1,cert2, \&. \&. \&." + +.fi +.if n \{\ +.RE +.\} +.PP +Sign Message Example +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmsutil \-S [\-i infile] [\-o outfile] [\-d dbdir] [\-p password] \-N nickname[\-TGP] [\-Y ekprefnick] + +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +certutil(1) +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/crlutil.1 b/security/nss/doc/rst/legacy/nroff/crlutil.1 new file mode 100644 index 0000000000..e895f28750 --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/crlutil.1 @@ -0,0 +1,389 @@ +'\" t +.\" Title: CRLUTIL +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "CRLUTIL" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +crlutil \- List, generate, modify, or delete CRLs within the NSS security database file(s) and list, create, modify or delete certificates entries in a particular CRL\&. +.SH "SYNOPSIS" +.HP \w'\fBcrlutil\fR\ 'u +\fBcrlutil\fR [\fIoptions\fR] [[\fIarguments\fR]] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The Certificate Revocation List (CRL) Management Tool, +\fBcrlutil\fR, is a command\-line utility that can list, generate, modify, or delete CRLs within the NSS security database file(s) and list, create, modify or delete certificates entries in a particular CRL\&. +.PP +The key and certificate management process generally begins with creating keys in the key database, then generating and managing certificates in the certificate database(see certutil tool) and continues with certificates expiration or revocation\&. +.PP +This document discusses certificate revocation list management\&. For information on security module database management, see Using the Security Module Database Tool\&. For information on certificate and key database management, see Using the Certificate Database Tool\&. +.PP +To run the Certificate Revocation List Management Tool, type the command +.PP +crlutil option [arguments] +.PP +where options and arguments are combinations of the options and arguments listed in the following section\&. Each command takes one option\&. Each option may take zero or more arguments\&. To see a usage string, issue the command without options, or with the \-H option\&. +.SH "OPTIONS AND ARGUMENTS" +.PP +.PP +\fBOptions\fR +.PP +Options specify an action\&. Option arguments modify an action\&. The options and arguments for the crlutil command are defined as follows: +.PP +\-D +.RS 4 +Delete Certificate Revocation List from cert database\&. +.RE +.PP +\-E +.RS 4 +Erase all CRLs of specified type from the cert database +.RE +.PP +\-G +.RS 4 +Create new Certificate Revocation List (CRL)\&. +.RE +.PP +\-I +.RS 4 +Import a CRL to the cert database +.RE +.PP +\-L +.RS 4 +List existing CRL located in cert database file\&. +.RE +.PP +\-M +.RS 4 +Modify existing CRL which can be located in cert db or in arbitrary file\&. If located in file it should be encoded in ASN\&.1 encode format\&. +.RE +.PP +\-S +.RS 4 +Show contents of a CRL file which isn\*(Aqt stored in the database\&. +.RE +.PP +\fBArguments\fR +.PP +Option arguments modify an action\&. +.PP +\-a +.RS 4 +Use ASCII format or allow the use of ASCII format for input and output\&. This formatting follows RFC #1113\&. +.RE +.PP +\-B +.RS 4 +Bypass CA signature checks\&. +.RE +.PP +\-c crl\-gen\-file +.RS 4 +Specify script file that will be used to control crl generation/modification\&. See crl\-cript\-file format below\&. If options \-M|\-G is used and \-c crl\-script\-file is not specified, crlutil will read script data from standard input\&. +.RE +.PP +\-d directory +.RS 4 +Specify the database directory containing the certificate and key database files\&. On Unix the Certificate Database Tool defaults to $HOME/\&.netscape (that is, ~/\&.netscape)\&. On Windows NT the default is the current directory\&. +.sp +The NSS database files must reside in the same directory\&. +.RE +.PP +\-f password\-file +.RS 4 +Specify a file that will automatically supply the password to include in a certificate or to access a certificate database\&. This is a plain\-text file containing one password\&. Be sure to prevent unauthorized access to this file\&. +.RE +.PP +\-i crl\-file +.RS 4 +Specify the file which contains the CRL to import or show\&. +.RE +.PP +\-l algorithm\-name +.RS 4 +Specify a specific signature algorithm\&. List of possible algorithms: MD2 | MD4 | MD5 | SHA1 | SHA256 | SHA384 | SHA512 +.RE +.PP +\-n nickname +.RS 4 +Specify the nickname of a certificate or key to list, create, add to a database, modify, or validate\&. Bracket the nickname string with quotation marks if it contains spaces\&. +.RE +.PP +\-o output\-file +.RS 4 +Specify the output file name for new CRL\&. Bracket the output\-file string with quotation marks if it contains spaces\&. If this argument is not used the output destination defaults to standard output\&. +.RE +.PP +\-P dbprefix +.RS 4 +Specify the prefix used on the NSS security database files (for example, my_cert8\&.db and my_key3\&.db)\&. This option is provided as a special case\&. Changing the names of the certificate and key databases is not recommended\&. +.RE +.PP +\-t crl\-type +.RS 4 +Specify type of CRL\&. possible types are: 0 \- SEC_KRL_TYPE, 1 \- SEC_CRL_TYPE\&. This option is obsolete +.RE +.PP +\-u url +.RS 4 +Specify the url\&. +.RE +.PP +\-w pwd\-string +.RS 4 +Provide db password in command line\&. +.RE +.PP +\-Z algorithm +.RS 4 +Specify the hash algorithm to use for signing the CRL\&. +.RE +.SH "CRL GENERATION SCRIPT SYNTAX" +.PP +CRL generation script file has the following syntax: +.PP +* Line with comments should have # as a first symbol of a line +.PP +* Set "this update" or "next update" CRL fields: +.PP +update=YYYYMMDDhhmmssZ nextupdate=YYYYMMDDhhmmssZ +.PP +Field "next update" is optional\&. Time should be in GeneralizedTime format (YYYYMMDDhhmmssZ)\&. For example: 20050204153000Z +.PP +* Add an extension to a CRL or a crl certificate entry: +.PP +addext extension\-name critical/non\-critical [arg1[arg2 \&.\&.\&.]] +.PP +Where: +.PP +extension\-name: string value of a name of known extensions\&. critical/non\-critical: is 1 when extension is critical and 0 otherwise\&. arg1, arg2: specific to extension type extension parameters +.PP +addext uses the range that was set earlier by addcert and will install an extension to every cert entries within the range\&. +.PP +* Add certificate entries(s) to CRL: +.PP +addcert range date +.PP +range: two integer values separated by dash: range of certificates that will be added by this command\&. dash is used as a delimiter\&. Only one cert will be added if there is no delimiter\&. date: revocation date of a cert\&. Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ)\&. +.PP +* Remove certificate entry(s) from CRL +.PP +rmcert range +.PP +Where: +.PP +range: two integer values separated by dash: range of certificates that will be added by this command\&. dash is used as a delimiter\&. Only one cert will be added if there is no delimiter\&. +.PP +* Change range of certificate entry(s) in CRL +.PP +range new\-range +.PP +Where: +.PP +new\-range: two integer values separated by dash: range of certificates that will be added by this command\&. dash is used as a delimiter\&. Only one cert will be added if there is no delimiter\&. +.PP +Implemented Extensions +.PP +The extensions defined for CRL provide methods for associating additional attributes with CRLs of theirs entries\&. For more information see RFC #3280 +.PP +* Add The Authority Key Identifier extension: +.PP +The authority key identifier extension provides a means of identifying the public key corresponding to the private key used to sign a CRL\&. +.PP +authKeyId critical [key\-id | dn cert\-serial] +.PP +Where: +.PP +authKeyIdent: identifies the name of an extension critical: value of 1 of 0\&. Should be set to 1 if this extension is critical or 0 otherwise\&. key\-id: key identifier represented in octet string\&. dn:: is a CA distinguished name cert\-serial: authority certificate serial number\&. +.PP +* Add Issuer Alternative Name extension: +.PP +The issuer alternative names extension allows additional identities to be associated with the issuer of the CRL\&. Defined options include an rfc822 name (electronic mail address), a DNS name, an IP address, and a URI\&. +.PP +issuerAltNames non\-critical name\-list +.PP +Where: +.PP +subjAltNames: identifies the name of an extension should be set to 0 since this is non\-critical extension name\-list: comma separated list of names +.PP +* Add CRL Number extension: +.PP +The CRL number is a non\-critical CRL extension which conveys a monotonically increasing sequence number for a given CRL scope and CRL issuer\&. This extension allows users to easily determine when a particular CRL supersedes another CRL +.PP +crlNumber non\-critical number +.PP +Where: +.PP +crlNumber: identifies the name of an extension critical: should be set to 0 since this is non\-critical extension number: value of long which identifies the sequential number of a CRL\&. +.PP +* Add Revocation Reason Code extension: +.PP +The reasonCode is a non\-critical CRL entry extension that identifies the reason for the certificate revocation\&. +.PP +reasonCode non\-critical code +.PP +Where: +.PP +reasonCode: identifies the name of an extension non\-critical: should be set to 0 since this is non\-critical extension code: the following codes are available: +.PP +unspecified (0), keyCompromise (1), cACompromise (2), affiliationChanged (3), superseded (4), cessationOfOperation (5), certificateHold (6), removeFromCRL (8), privilegeWithdrawn (9), aACompromise (10) +.PP +* Add Invalidity Date extension: +.PP +The invalidity date is a non\-critical CRL entry extension that provides the date on which it is known or suspected that the private key was compromised or that the certificate otherwise became invalid\&. +.PP +invalidityDate non\-critical date +.PP +Where: +.PP +crlNumber: identifies the name of an extension non\-critical: should be set to 0 since this is non\-critical extension date: invalidity date of a cert\&. Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ)\&. +.SH "USAGE" +.PP +The Certificate Revocation List Management Tool\*(Aqs capabilities are grouped as follows, using these combinations of options and arguments\&. Options and arguments in square brackets are optional, those without square brackets are required\&. +.PP +See "Implemented extensions" for more information regarding extensions and their parameters\&. +.PP +* Creating or modifying a CRL: +.sp +.if n \{\ +.RS 4 +.\} +.nf +crlutil \-G|\-M \-c crl\-gen\-file \-n nickname [\-i crl] [\-u url] [\-d keydir] [\-P dbprefix] [\-l alg] [\-a] [\-B] + +.fi +.if n \{\ +.RE +.\} +.PP +* Listing all CRls or a named CRL: +.sp +.if n \{\ +.RS 4 +.\} +.nf + crlutil \-L [\-n crl\-name] [\-d krydir] + +.fi +.if n \{\ +.RE +.\} +.PP +* Deleting CRL from db: +.sp +.if n \{\ +.RS 4 +.\} +.nf + crlutil \-D \-n nickname [\-d keydir] [\-P dbprefix] + +.fi +.if n \{\ +.RE +.\} +.PP +* Erasing CRLs from db: +.sp +.if n \{\ +.RS 4 +.\} +.nf + crlutil \-E [\-d keydir] [\-P dbprefix] + +.fi +.if n \{\ +.RE +.\} +.PP +* Deleting CRL from db: +.sp +.if n \{\ +.RS 4 +.\} +.nf + crlutil \-D \-n nickname [\-d keydir] [\-P dbprefix] + +.fi +.if n \{\ +.RE +.\} +.PP +* Erasing CRLs from db: +.sp +.if n \{\ +.RS 4 +.\} +.nf + crlutil \-E [\-d keydir] [\-P dbprefix] + +.fi +.if n \{\ +.RE +.\} +.PP +* Import CRL from file: +.sp +.if n \{\ +.RS 4 +.\} +.nf + crlutil \-I \-i crl [\-t crlType] [\-u url] [\-d keydir] [\-P dbprefix] [\-B] + +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +certutil(1) +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/derdump.1 b/security/nss/doc/rst/legacy/nroff/derdump.1 new file mode 100644 index 0000000000..18f3974c74 --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/derdump.1 @@ -0,0 +1,92 @@ +'\" t +.\" Title: DERDUMP +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "DERDUMP" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +derdump_ \- Dumps C\-sequence strings from a DER encoded certificate file +.SH "SYNOPSIS" +.HP \w'\fBderdump\fR\ 'u +\fBderdump\fR [\fB\-r\fR] [\fB\-i\ \fR\fB\fIinput\-file\fR\fR] [\fB\-o\ \fR\fB\fIoutput\-file\fR\fR] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +\fBderdump \fRdumps C\-sequence strings from a DER encode certificate file +.SH "OPTIONS" +.PP +\fB\-r \fR +.RS 4 +For formatted items, dump raw bytes as well +.RE +.PP +\fB\-i \fR \fIDER encoded file\fR +.RS 4 +Define an input file to use (default is stdin) +.RE +.PP +\fB\-o \fR \fIoutput file\fR +.RS 4 +Define an output file to use (default is stdout)\&. +.RE +.SH "ADDITIONAL RESOURCES" +.PP +NSS is maintained in conjunction with PKI and security\-related projects through Mozilla dn Fedora\&. The most closely\-related project is Dogtag PKI, with a project wiki at +\m[blue]\fBPKI Wiki\fR\m[]\&\s-2\u[2]\d\s+2\&. +.PP +For information specifically about NSS, the NSS project wiki is located at +\m[blue]\fBMozilla NSS site\fR\m[]\&\s-2\u[3]\d\s+2\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: pki\-devel@redhat\&.com and pki\-users@redhat\&.com +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Gerhardus Geldenhuis <gerhardus\&.geldenhuis@gmail\&.com>\&. Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com> +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE +.IP " 2." 4 +PKI Wiki +.RS 4 +\%http://pki.fedoraproject.org/wiki/ +.RE +.IP " 3." 4 +Mozilla NSS site +.RS 4 +\%http://www.mozilla.org/projects/security/pki/nss/ +.RE diff --git a/security/nss/doc/rst/legacy/nroff/modutil.1 b/security/nss/doc/rst/legacy/nroff/modutil.1 new file mode 100644 index 0000000000..05c04946fe --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/modutil.1 @@ -0,0 +1,1452 @@ +'\" t +.\" Title: MODUTIL +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "MODUTIL" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +modutil \- Manage PKCS #11 module information within the security module database\&. +.SH "SYNOPSIS" +.HP \w'\fBmodutil\fR\ 'u +\fBmodutil\fR [\fIoptions\fR] [[\fIarguments\fR]] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The Security Module Database Tool, +\fBmodutil\fR, is a command\-line utility for managing PKCS #11 module information both within +secmod\&.db +files and within hardware tokens\&. +\fBmodutil\fR +can add and delete PKCS #11 modules, change passwords on security databases, set defaults, list module contents, enable or disable slots, enable or disable FIPS 140\-2 compliance, and assign default providers for cryptographic operations\&. This tool can also create certificate, key, and module security database files\&. +.PP +The tasks associated with security module database management are part of a process that typically also involves managing key databases and certificate databases\&. +.SH "OPTIONS" +.PP +Running +\fBmodutil\fR +always requires one (and only one) option to specify the type of module operation\&. Each option may take arguments, anywhere from none to multiple arguments\&. +.PP +\fBOptions\fR +.PP +\-add modulename +.RS 4 +Add the named PKCS #11 module to the database\&. Use this option with the +\fB\-libfile\fR, +\fB\-ciphers\fR, and +\fB\-mechanisms\fR +arguments\&. +.RE +.PP +\-changepw tokenname +.RS 4 +Change the password on the named token\&. If the token has not been initialized, this option initializes the password\&. Use this option with the +\fB\-pwfile\fR +and +\fB\-newpwfile\fR +arguments\&. A +\fIpassword\fR +is equivalent to a personal identification number (PIN)\&. +.RE +.PP +\-chkfips +.RS 4 +Verify whether the module is in the given FIPS mode\&. +\fBtrue\fR +means to verify that the module is in FIPS mode, while +\fBfalse\fR +means to verify that the module is not in FIPS mode\&. +.RE +.PP +\-create +.RS 4 +Create new certificate, key, and module databases\&. Use the +\fB\-dbdir\fR +directory argument to specify a directory\&. If any of these databases already exist in a specified directory, +\fBmodutil\fR +returns an error message\&. +.RE +.PP +\-default modulename +.RS 4 +Specify the security mechanisms for which the named module will be a default provider\&. The security mechanisms are specified with the +\fB\-mechanisms\fR +argument\&. +.RE +.PP +\-delete modulename +.RS 4 +Delete the named module\&. The default NSS PKCS #11 module cannot be deleted\&. +.RE +.PP +\-disable modulename +.RS 4 +Disable all slots on the named module\&. Use the +\fB\-slot\fR +argument to disable a specific slot\&. +.sp +The internal NSS PKCS #11 module cannot be disabled\&. +.RE +.PP +\-enable modulename +.RS 4 +Enable all slots on the named module\&. Use the +\fB\-slot\fR +argument to enable a specific slot\&. +.RE +.PP +\-fips [true | false] +.RS 4 +Enable (true) or disable (false) FIPS 140\-2 compliance for the default NSS module\&. +.RE +.PP +\-force +.RS 4 +Disable +\fBmodutil\fR\*(Aqs interactive prompts so it can be run from a script\&. Use this option only after manually testing each planned operation to check for warnings and to ensure that bypassing the prompts will cause no security lapses or loss of database integrity\&. +.RE +.PP +\-jar JAR\-file +.RS 4 +Add a new PKCS #11 module to the database using the named JAR file\&. Use this command with the +\fB\-installdir\fR +and +\fB\-tempdir\fR +arguments\&. The JAR file uses the NSS PKCS #11 JAR format to identify all the files to be installed, the module\*(Aqs name, the mechanism flags, and the cipher flags, as well as any files to be installed on the target machine, including the PKCS #11 module library file and other files such as documentation\&. This is covered in the JAR installation file section in the man page, which details the special script needed to perform an installation through a server or with +\fBmodutil\fR\&. +.RE +.PP +\-list [modulename] +.RS 4 +Display basic information about the contents of the +secmod\&.db +file\&. Specifying a +\fImodulename\fR +displays detailed information about a particular module and its slots and tokens\&. +.RE +.PP +\-rawadd +.RS 4 +Add the module spec string to the +secmod\&.db +database\&. +.RE +.PP +\-rawlist +.RS 4 +Display the module specs for a specified module or for all loadable modules\&. +.RE +.PP +\-undefault modulename +.RS 4 +Specify the security mechanisms for which the named module will not be a default provider\&. The security mechanisms are specified with the +\fB\-mechanisms\fR +argument\&. +.RE +.PP +\fBArguments\fR +.PP +MODULE +.RS 4 +Give the security module to access\&. +.RE +.PP +MODULESPEC +.RS 4 +Give the security module spec to load into the security database\&. +.RE +.PP +\-ciphers cipher\-enable\-list +.RS 4 +Enable specific ciphers in a module that is being added to the database\&. The +\fIcipher\-enable\-list\fR +is a colon\-delimited list of cipher names\&. Enclose this list in quotation marks if it contains spaces\&. +.RE +.PP +\-dbdir directory +.RS 4 +Specify the database directory in which to access or create security module database files\&. +.sp +\fBmodutil\fR +supports two types of databases: the legacy security databases (cert8\&.db, +key3\&.db, and +secmod\&.db) and SQLite databases (cert9\&.db, +key4\&.db, and +pkcs11\&.txt)\&. If the prefix +\fBdbm:\fR +is not used, then the tool assumes that the given databases are in SQLite format\&. +.RE +.PP +\-\-dbprefix prefix +.RS 4 +Specify the prefix used on the database files, such as +my_ +for +my_cert9\&.db\&. This option is provided as a special case\&. Changing the names of the certificate and key databases is not recommended\&. +.RE +.PP +\-installdir root\-installation\-directory +.RS 4 +Specify the root installation directory relative to which files will be installed by the +\fB\-jar\fR +option\&. This directory should be one below which it is appropriate to store dynamic library files, such as a server\*(Aqs root directory\&. +.RE +.PP +\-libfile library\-file +.RS 4 +Specify a path to a library file containing the implementation of the PKCS #11 interface module that is being added to the database\&. +.RE +.PP +\-mechanisms mechanism\-list +.RS 4 +Specify the security mechanisms for which a particular module will be flagged as a default provider\&. The +\fImechanism\-list\fR +is a colon\-delimited list of mechanism names\&. Enclose this list in quotation marks if it contains spaces\&. +.sp +The module becomes a default provider for the listed mechanisms when those mechanisms are enabled\&. If more than one module claims to be a particular mechanism\*(Aqs default provider, that mechanism\*(Aqs default provider is undefined\&. +.sp +\fBmodutil\fR +supports several mechanisms: RSA, DSA, RC2, RC4, RC5, AES, DES, DH, SHA1, SHA256, SHA512, SSL, TLS, MD5, MD2, RANDOM (for random number generation), and FRIENDLY (meaning certificates are publicly readable)\&. +.RE +.PP +\-newpwfile new\-password\-file +.RS 4 +Specify a text file containing a token\*(Aqs new or replacement password so that a password can be entered automatically with the +\fB\-changepw\fR +option\&. +.RE +.PP +\-nocertdb +.RS 4 +Do not open the certificate or key databases\&. This has several effects: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +With the +\fB\-create\fR +command, only a module security file is created; certificate and key databases are not created\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +With the +\fB\-jar\fR +command, signatures on the JAR file are not checked\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +With the +\fB\-changepw\fR +command, the password on the NSS internal module cannot be set or changed, since this password is stored in the key database\&. +.RE +.RE +.PP +\-pwfile old\-password\-file +.RS 4 +Specify a text file containing a token\*(Aqs existing password so that a password can be entered automatically when the +\fB\-changepw\fR +option is used to change passwords\&. +.RE +.PP +\-secmod secmodname +.RS 4 +Give the name of the security module database (like +secmod\&.db) to load\&. +.RE +.PP +\-slot slotname +.RS 4 +Specify a particular slot to be enabled or disabled with the +\fB\-enable\fR +or +\fB\-disable\fR +options\&. +.RE +.PP +\-string CONFIG_STRING +.RS 4 +Pass a configuration string for the module being added to the database\&. +.RE +.PP +\-tempdir temporary\-directory +.RS 4 +Give a directory location where temporary files are created during the installation by the +\fB\-jar\fR +option\&. If no temporary directory is specified, the current directory is used\&. +.RE +.SH "USAGE AND EXAMPLES" +.PP +\fBCreating Database Files\fR +.PP +Before any operations can be performed, there must be a set of security databases available\&. +\fBmodutil\fR +can be used to create these files\&. The only required argument is the database that where the databases will be located\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-create \-dbdir directory +.fi +.if n \{\ +.RE +.\} +.PP +\fBAdding a Cryptographic Module\fR +.PP +Adding a PKCS #11 module means submitting a supporting library file, enabling its ciphers, and setting default provider status for various security mechanisms\&. This can be done by supplying all of the information through +\fBmodutil\fR +directly or by running a JAR file and install script\&. For the most basic case, simply upload the library: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-add modulename \-libfile library\-file [\-ciphers cipher\-enable\-list] [\-mechanisms mechanism\-list] +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-dbdir /home/my/sharednssdb \-add "Example PKCS #11 Module" \-libfile "/tmp/crypto\&.so" \-mechanisms RSA:DSA:RC2:RANDOM + +Using database directory \&.\&.\&. +Module "Example PKCS #11 Module" added to database\&. +.fi +.if n \{\ +.RE +.\} +.PP +\fBInstalling a Cryptographic Module from a JAR File\fR +.PP +PKCS #11 modules can also be loaded using a JAR file, which contains all of the required libraries and an installation script that describes how to install the module\&. The JAR install script is described in more detail in +the section called \(lqJAR INSTALLATION FILE FORMAT\(rq\&. +.PP +The JAR installation script defines the setup information for each platform that the module can be installed on\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Platforms { + Linux:5\&.4\&.08:x86 { + ModuleName { "Example PKCS #11 Module" } + ModuleFile { crypto\&.so } + DefaultMechanismFlags{0x0000} + CipherEnableFlags{0x0000} + Files { + crypto\&.so { + Path{ /tmp/crypto\&.so } + } + setup\&.sh { + Executable + Path{ /tmp/setup\&.sh } + } + } + } + Linux:6\&.0\&.0:x86 { + EquivalentPlatform { Linux:5\&.4\&.08:x86 } + } +} +.fi +.if n \{\ +.RE +.\} +.PP +Both the install script and the required libraries must be bundled in a JAR file, which is specified with the +\fB\-jar\fR +argument\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-dbdir /home/mt"jar\-install\-filey/sharednssdb \-jar install\&.jar \-installdir /home/my/sharednssdb + +This installation JAR file was signed by: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +**SUBJECT NAME** + +C=US, ST=California, L=Mountain View, CN=Cryptorific Inc\&., OU=Digital ID +Class 3 \- Netscape Object Signing, OU="www\&.verisign\&.com/repository/CPS +Incorp\&. by Ref\&.,LIAB\&.LTD(c)9 6", OU=www\&.verisign\&.com/CPS Incorp\&.by Ref +\&. LIABILITY LTD\&.(c)97 VeriSign, OU=VeriSign Object Signing CA \- Class 3 +Organization, OU="VeriSign, Inc\&.", O=VeriSign Trust Network **ISSUER +NAME**, OU=www\&.verisign\&.com/CPS Incorp\&.by Ref\&. LIABILITY LTD\&.(c)97 +VeriSign, OU=VeriSign Object Signing CA \- Class 3 Organization, +OU="VeriSign, Inc\&.", O=VeriSign Trust Network +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +Do you wish to continue this installation? (y/n) y +Using installer script "installer_script" +Successfully parsed installation script +Current platform is Linux:5\&.4\&.08:x86 +Using installation parameters for platform Linux:5\&.4\&.08:x86 +Installed file crypto\&.so to /tmp/crypto\&.so +Installed file setup\&.sh to \&./pk11inst\&.dir/setup\&.sh +Executing "\&./pk11inst\&.dir/setup\&.sh"\&.\&.\&. +"\&./pk11inst\&.dir/setup\&.sh" executed successfully +Installed module "Example PKCS #11 Module" into module database + +Installation completed successfully +.fi +.if n \{\ +.RE +.\} +.PP +\fBAdding Module Spec\fR +.PP +Each module has information stored in the security database about its configuration and parameters\&. These can be added or edited using the +\fB\-rawadd\fR +command\&. For the current settings or to see the format of the module spec in the database, use the +\fB\-rawlist\fR +option\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-rawadd modulespec +.fi +.if n \{\ +.RE +.\} +.PP +\fBDeleting a Module\fR +.PP +A specific PKCS #11 module can be deleted from the +secmod\&.db +database: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-delete modulename \-dbdir directory +.fi +.if n \{\ +.RE +.\} +.PP +\fBDisplaying Module Information\fR +.PP +The +secmod\&.db +database contains information about the PKCS #11 modules that are available to an application or server to use\&. The list of all modules, information about specific modules, and database configuration specs for modules can all be viewed\&. +.PP +To simply get a list of modules in the database, use the +\fB\-list\fR +command\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-list [modulename] \-dbdir directory +.fi +.if n \{\ +.RE +.\} +.PP +Listing the modules shows the module name, their status, and other associated security databases for certificates and keys\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-list \-dbdir /home/my/sharednssdb + +Listing of PKCS #11 Modules +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 1\&. NSS Internal PKCS #11 Module + slots: 2 slots attached + status: loaded + + slot: NSS Internal Cryptographic Services + token: NSS Generic Crypto Services + uri: pkcs11:token=NSS%20Generic%20Crypto%20Services;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203 + + slot: NSS User Private Key and Certificate Services + token: NSS Certificate DB + uri: pkcs11:token=NSS%20Certificate%20DB;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.fi +.if n \{\ +.RE +.\} +.PP +Passing a specific module name with the +\fB\-list\fR +returns details information about the module itself, like supported cipher mechanisms, version numbers, serial numbers, and other information about the module and the token it is loaded on\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf + modutil \-list "NSS Internal PKCS #11 Module" \-dbdir /home/my/sharednssdb + +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +Name: NSS Internal PKCS #11 Module +Library file: **Internal ONLY module** +Manufacturer: Mozilla Foundation +Description: NSS Internal Crypto Services +PKCS #11 Version 2\&.20 +Library Version: 3\&.11 +Cipher Enable Flags: None +Default Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + + Slot: NSS Internal Cryptographic Services + Slot Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + Manufacturer: Mozilla Foundation + Type: Software + Version Number: 3\&.11 + Firmware Version: 0\&.0 + Status: Enabled + Token Name: NSS Generic Crypto Services + Token Manufacturer: Mozilla Foundation + Token Model: NSS 3 + Token Serial Number: 0000000000000000 + Token Version: 4\&.0 + Token Firmware Version: 0\&.0 + Access: Write Protected + Login Type: Public (no login required) + User Pin: NOT Initialized + + Slot: NSS User Private Key and Certificate Services + Slot Mechanism Flags: None + Manufacturer: Mozilla Foundation + Type: Software + Version Number: 3\&.11 + Firmware Version: 0\&.0 + Status: Enabled + Token Name: NSS Certificate DB + Token Manufacturer: Mozilla Foundation + Token Model: NSS 3 + Token Serial Number: 0000000000000000 + Token Version: 8\&.3 + Token Firmware Version: 0\&.0 + Access: NOT Write Protected + Login Type: Login required + User Pin: Initialized +.fi +.if n \{\ +.RE +.\} +.PP +A related command, +\fB\-rawlist\fR +returns information about the database configuration for the modules\&. (This information can be edited by loading new specs using the +\fB\-rawadd\fR +command\&.) +.sp +.if n \{\ +.RS 4 +.\} +.nf + modutil \-rawlist \-dbdir /home/my/sharednssdb + name="NSS Internal PKCS #11 Module" parameters="configdir=\&. certPrefix= keyPrefix= secmod=secmod\&.db flags=readOnly " NSS="trustOrder=75 cipherOrder=100 slotParams={0x00000001=[slotFlags=RSA,RC4,RC2,DES,DH,SHA1,MD5,MD2,SSL,TLS,AES,RANDOM askpw=any timeout=30 ] } Flags=internal,critical" +.fi +.if n \{\ +.RE +.\} +.PP +\fBSetting a Default Provider for Security Mechanisms\fR +.PP +Multiple security modules may provide support for the same security mechanisms\&. It is possible to set a specific security module as the default provider for a specific security mechanism (or, conversely, to prohibit a provider from supplying those mechanisms)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-default modulename \-mechanisms mechanism\-list +.fi +.if n \{\ +.RE +.\} +.PP +To set a module as the default provider for mechanisms, use the +\fB\-default\fR +command with a colon\-separated list of mechanisms\&. The available mechanisms depend on the module; NSS supplies almost all common mechanisms\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-default "NSS Internal PKCS #11 Module" \-dbdir \-mechanisms RSA:DSA:RC2 + +Using database directory c:\edatabases\&.\&.\&. + +Successfully changed defaults\&. +.fi +.if n \{\ +.RE +.\} +.PP +Clearing the default provider has the same format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-undefault "NSS Internal PKCS #11 Module" \-dbdir \-mechanisms MD2:MD5 +.fi +.if n \{\ +.RE +.\} +.PP +\fBEnabling and Disabling Modules and Slots\fR +.PP +Modules, and specific slots on modules, can be selectively enabled or disabled using +\fBmodutil\fR\&. Both commands have the same format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-enable|\-disable modulename [\-slot slotname] +.fi +.if n \{\ +.RE +.\} +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-enable "NSS Internal PKCS #11 Module" \-slot "NSS Internal Cryptographic Services " \-dbdir \&. + +Slot "NSS Internal Cryptographic Services " enabled\&. +.fi +.if n \{\ +.RE +.\} +.PP +Be sure that the appropriate amount of trailing whitespace is after the slot name\&. Some slot names have a significant amount of whitespace that must be included, or the operation will fail\&. +.PP +\fBEnabling and Verifying FIPS Compliance\fR +.PP +The NSS modules can have FIPS 140\-2 compliance enabled or disabled using +\fBmodutil\fR +with the +\fB\-fips\fR +option\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-fips true \-dbdir /home/my/sharednssdb/ + +FIPS mode enabled\&. +.fi +.if n \{\ +.RE +.\} +.PP +To verify that status of FIPS mode, run the +\fB\-chkfips\fR +command with either a true or false flag (it doesn\*(Aqt matter which)\&. The tool returns the current FIPS setting\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-chkfips false \-dbdir /home/my/sharednssdb/ + +FIPS mode enabled\&. +.fi +.if n \{\ +.RE +.\} +.PP +\fBChanging the Password on a Token\fR +.PP +Initializing or changing a token\*(Aqs password: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-changepw tokenname [\-pwfile old\-password\-file] [\-newpwfile new\-password\-file] +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-dbdir /home/my/sharednssdb \-changepw "NSS Certificate DB" + +Enter old password: +Incorrect password, try again\&.\&.\&. +Enter old password: +Enter new password: +Re\-enter new password: +Token "Communicator Certificate DB" password changed successfully\&. +.fi +.if n \{\ +.RE +.\} +.SH "JAR INSTALLATION FILE FORMAT" +.PP +When a JAR file is run by a server, by +\fBmodutil\fR, or by any program that does not interpret JavaScript, a special information file must be included to install the libraries\&. There are several things to keep in mind with this file: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +It must be declared in the JAR archive\*(Aqs manifest file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The script can have any name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The metainfo tag for this is +\fBPkcs11_install_script\fR\&. To declare meta\-information in the manifest file, put it in a file that is passed to +\fBsigntool\fR\&. +.RE +.PP +\fBSample Script\fR +.PP +For example, the PKCS #11 installer script could be in the file pk11install\&. If so, the metainfo file for +\fBsigntool\fR +includes a line such as this: +.sp +.if n \{\ +.RS 4 +.\} +.nf ++ Pkcs11_install_script: pk11install +.fi +.if n \{\ +.RE +.\} +.PP +The script must define the platform and version number, the module name and file, and any optional information like supported ciphers and mechanisms\&. Multiple platforms can be defined in a single install file\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +ForwardCompatible { IRIX:6\&.2:mips SUNOS:5\&.5\&.1:sparc } +Platforms { + WINNT::x86 { + ModuleName { "Example Module" } + ModuleFile { win32/fort32\&.dll } + DefaultMechanismFlags{0x0001} + DefaultCipherFlags{0x0001} + Files { + win32/setup\&.exe { + Executable + RelativePath { %temp%/setup\&.exe } + } + win32/setup\&.hlp { + RelativePath { %temp%/setup\&.hlp } + } + win32/setup\&.cab { + RelativePath { %temp%/setup\&.cab } + } + } + } + WIN95::x86 { + EquivalentPlatform {WINNT::x86} + } + SUNOS:5\&.5\&.1:sparc { + ModuleName { "Example UNIX Module" } + ModuleFile { unix/fort\&.so } + DefaultMechanismFlags{0x0001} + CipherEnableFlags{0x0001} + Files { + unix/fort\&.so { + RelativePath{%root%/lib/fort\&.so} + AbsolutePath{/usr/local/netscape/lib/fort\&.so} + FilePermissions{555} + } + xplat/instr\&.html { + RelativePath{%root%/docs/inst\&.html} + AbsolutePath{/usr/local/netscape/docs/inst\&.html} + FilePermissions{555} + } + } + } + IRIX:6\&.2:mips { + EquivalentPlatform { SUNOS:5\&.5\&.1:sparc } + } +} +.fi +.if n \{\ +.RE +.\} +.PP +\fBScript Grammar\fR +.PP +The script is basic Java, allowing lists, key\-value pairs, strings, and combinations of all of them\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +\-\-> valuelist + +valuelist \-\-> value valuelist + <null> + +value \-\-\-> key_value_pair + string + +key_value_pair \-\-> key { valuelist } + +key \-\-> string + +string \-\-> simple_string + "complex_string" + +simple_string \-\-> [^ \et\en\e""{""}"]+ + +complex_string \-\-> ([^\e"\e\e\er\en]|(\e\e\e")|(\e\e\e\e))+ +.fi +.if n \{\ +.RE +.\} +.PP +Quotes and backslashes must be escaped with a backslash\&. A complex string must not include newlines or carriage returns\&.Outside of complex strings, all white space (for example, spaces, tabs, and carriage returns) is considered equal and is used only to delimit tokens\&. +.PP +\fBKeys\fR +.PP +The Java install file uses keys to define the platform and module information\&. +.PP +\fBForwardCompatible\fR +gives a list of platforms that are forward compatible\&. If the current platform cannot be found in the list of supported platforms, then the +\fBForwardCompatible\fR +list is checked for any platforms that have the same OS and architecture in an earlier version\&. If one is found, its attributes are used for the current platform\&. +.PP +\fBPlatforms\fR +(required) Gives a list of platforms\&. Each entry in the list is itself a key\-value pair: the key is the name of the platform and the value list contains various attributes of the platform\&. The platform string is in the format +\fIsystem name:OS release:architecture\fR\&. The installer obtains these values from NSPR\&. OS release is an empty string on non\-Unix operating systems\&. NSPR supports these platforms: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +AIX (rs6000) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +BSDI (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +FREEBSD (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +HPUX (hppa1\&.1) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +IRIX (mips) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +LINUX (ppc, alpha, x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +MacOS (PowerPC) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +NCR (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +NEC (mips) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +OS2 (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +OSF (alpha) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ReliantUNIX (mips) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SCO (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SOLARIS (sparc) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SONY (mips) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SUNOS (sparc) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +UnixWare (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +WIN16 (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +WIN95 (x86) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +WINNT (x86) +.RE +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +IRIX:6\&.2:mips +SUNOS:5\&.5\&.1:sparc +Linux:2\&.0\&.32:x86 +WIN95::x86 +.fi +.if n \{\ +.RE +.\} +.PP +The module information is defined independently for each platform in the +\fBModuleName\fR, +\fBModuleFile\fR, and +\fBFiles\fR +attributes\&. These attributes must be given unless an +\fBEquivalentPlatform\fR +attribute is specified\&. +.PP +\fBPer\-Platform Keys\fR +.PP +Per\-platform keys have meaning only within the value list of an entry in the +\fBPlatforms\fR +list\&. +.PP +\fBModuleName\fR +(required) gives the common name for the module\&. This name is used to reference the module by servers and by the +\fBmodutil\fR +tool\&. +.PP +\fBModuleFile\fR +(required) names the PKCS #11 module file for this platform\&. The name is given as the relative path of the file within the JAR archive\&. +.PP +\fBFiles\fR +(required) lists the files that need to be installed for this module\&. Each entry in the file list is a key\-value pair\&. The key is the path of the file in the JAR archive, and the value list contains attributes of the file\&. At least +\fBRelativePath\fR +or +\fBAbsolutePath\fR +must be specified for each file\&. +.PP +\fBDefaultMechanismFlags\fR +specifies mechanisms for which this module is the default provider; this is equivalent to the +\fB\-mechanism\fR +option with the +\fB\-add\fR +command\&. This key\-value pair is a bitstring specified in hexadecimal (0x) format\&. It is constructed as a bitwise OR\&. If the DefaultMechanismFlags entry is omitted, the value defaults to 0x0\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +RSA: 0x00000001 +DSA: 0x00000002 +RC2: 0x00000004 +RC4: 0x00000008 +DES: 0x00000010 +DH: 0x00000020 +FORTEZZA: 0x00000040 +RC5: 0x00000080 +SHA1: 0x00000100 +MD5: 0x00000200 +MD2: 0x00000400 +RANDOM: 0x08000000 +FRIENDLY: 0x10000000 +OWN_PW_DEFAULTS: 0x20000000 +DISABLE: 0x40000000 +.fi +.if n \{\ +.RE +.\} +.PP +\fBCipherEnableFlags\fR +specifies ciphers that this module provides that NSS does not provide (so that the module enables those ciphers for NSS)\&. This is equivalent to the +\fB\-cipher\fR +argument with the +\fB\-add\fR +command\&. This key is a bitstring specified in hexadecimal (0x) format\&. It is constructed as a bitwise OR\&. If the +\fBCipherEnableFlags\fR +entry is omitted, the value defaults to 0x0\&. +.PP +\fBEquivalentPlatform\fR +specifies that the attributes of the named platform should also be used for the current platform\&. This makes it easier when more than one platform uses the same settings\&. +.PP +\fBPer\-File Keys\fR +.PP +Some keys have meaning only within the value list of an entry in a +\fBFiles\fR +list\&. +.PP +Each file requires a path key the identifies where the file is\&. Either +\fBRelativePath\fR +or +\fBAbsolutePath\fR +must be specified\&. If both are specified, the relative path is tried first, and the absolute path is used only if no relative root directory is provided by the installer program\&. +.PP +\fBRelativePath\fR +specifies the destination directory of the file, relative to some directory decided at install time\&. Two variables can be used in the relative path: +\fB%root%\fR +and +\fB%temp%\fR\&. +\fB%root%\fR +is replaced at run time with the directory relative to which files should be installed; for example, it may be the server\*(Aqs root directory\&. The +\fB%temp%\fR +directory is created at the beginning of the installation and destroyed at the end\&. The purpose of +\fB%temp%\fR +is to hold executable files (such as setup programs) or files that are used by these programs\&. Files destined for the temporary directory are guaranteed to be in place before any executable file is run; they are not deleted until all executable files have finished\&. +.PP +\fBAbsolutePath\fR +specifies the destination directory of the file as an absolute path\&. +.PP +\fBExecutable\fR +specifies that the file is to be executed during the course of the installation\&. Typically, this string is used for a setup program provided by a module vendor, such as a self\-extracting setup executable\&. More than one file can be specified as executable, in which case the files are run in the order in which they are specified in the script file\&. +.PP +\fBFilePermissions\fR +sets permissions on any referenced files in a string of octal digits, according to the standard Unix format\&. This string is a bitwise OR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +user read: 0400 +user write: 0200 +user execute: 0100 +group read: 0040 +group write: 0020 +group execute: 0010 +other read: 0004 +other write: 0002 +other execute: 0001 +.fi +.if n \{\ +.RE +.\} +.PP +Some platforms may not understand these permissions\&. They are applied only insofar as they make sense for the current platform\&. If this attribute is omitted, a default of 777 is assumed\&. +.SH "NSS DATABASE TYPES" +.PP +NSS originally used BerkeleyDB databases to store security information\&. The last versions of these +\fIlegacy\fR +databases are: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert8\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key3\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +secmod\&.db for PKCS #11 module information +.RE +.PP +BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously\&. NSS has some flexibility that allows applications to use their own, independent database engine while keeping a shared database and working around the access issues\&. Still, NSS requires more flexibility to provide a truly shared security database\&. +.PP +In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert9\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key4\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory +.RE +.PP +Because the SQLite databases are designed to be shared, these are the +\fIshared\fR +database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&. +.PP +By default, the tools (\fBcertutil\fR, +\fBpk12util\fR, +\fBmodutil\fR) assume that the given security databases use the SQLite type\&. Using the legacy databases must be manually specified by using the +\fBdbm:\fR +prefix with the given security directory\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +modutil \-create \-dbdir dbm:/home/my/sharednssdb +.fi +.if n \{\ +.RE +.\} +.PP +To set the legacy database type as the default type for the tools, set the +\fBNSS_DEFAULT_DB_TYPE\fR +environment variable to +\fBdbm\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +export NSS_DEFAULT_DB_TYPE="dbm" +.fi +.if n \{\ +.RE +.\} +.PP +This line can be added to the +~/\&.bashrc +file to make the change permanent for the user\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.PP +For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "SEE ALSO" +.PP +certutil (1) +.PP +pk12util (1) +.PP +signtool (1) +.PP +The NSS wiki has information on the new database design and how to configure applications to use it\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/pk12util.1 b/security/nss/doc/rst/legacy/nroff/pk12util.1 new file mode 100644 index 0000000000..9cf7c88906 --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/pk12util.1 @@ -0,0 +1,872 @@ +'\" t +.\" Title: PK12UTIL +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "PK12UTIL" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pk12util \- Export and import keys and certificate to or from a PKCS #12 file and the NSS database +.SH "SYNOPSIS" +.HP \w'\fBpk12util\fR\ 'u +\fBpk12util\fR [\-i\ p12File|\-l\ p12File|\-o\ p12File] [\-c\ keyCipher] [\-C\ certCipher] [\-d\ directory] [\-h\ tokenname] [\-m\ |\ \-\-key\-len\ keyLength] [\-M\ hashAlg] [\-n\ certname] [\-P\ dbprefix] [\-r] [\-v] [\-\-cert\-key\-len\ certKeyLength] [\-k\ slotPasswordFile|\-K\ slotPassword] [\-w\ p12filePasswordFile|\-W\ p12filePassword] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The PKCS #12 utility, +\fBpk12util\fR, enables sharing certificates among any server that supports PKCS #12\&. The tool can import certificates and keys from PKCS #12 files into security databases, export certificates, and list certificates and keys\&. +.SH "OPTIONS AND ARGUMENTS" +.PP +\fBOptions\fR +.PP +\-i p12file +.RS 4 +Import keys and certificates from a PKCS #12 file into a security database\&. +.RE +.PP +\-l p12file +.RS 4 +List the keys and certificates in PKCS #12 file\&. +.RE +.PP +\-o p12file +.RS 4 +Export keys and certificates from the security database to a PKCS #12 file\&. +.RE +.PP +\fBArguments\fR +.PP +\-c keyCipher +.RS 4 +Specify the key encryption algorithm\&. +.RE +.PP +\-C certCipher +.RS 4 +Specify the certiticate encryption algorithm\&. +.RE +.PP +\-d directory +.RS 4 +Specify the database directory into which to import to or export from certificates and keys\&. +.sp +\fBpk12util\fR +supports two types of databases: the legacy security databases (cert8\&.db, +key3\&.db, and +secmod\&.db) and new SQLite databases (cert9\&.db, +key4\&.db, and +pkcs11\&.txt)\&. If the prefix +\fBdbm:\fR +is not used, then the tool assumes that the given databases are in the SQLite format\&. +.RE +.PP +\-h tokenname +.RS 4 +Specify the name of the token to import into or export from\&. +.RE +.PP +\-k slotPasswordFile +.RS 4 +Specify the text file containing the slot\*(Aqs password\&. +.RE +.PP +\-K slotPassword +.RS 4 +Specify the slot\*(Aqs password\&. +.RE +.PP +\-m | \-\-key\-len keyLength +.RS 4 +Specify the desired length of the symmetric key to be used to encrypt the private key\&. +.RE +.PP +\-M hashAlg +.RS 4 +Specify the hash algorithm used in the pkcs #12 mac\&. This algorithm also specifies the HMAC used in the prf when using pkcs #5 v2\&. +.RE +.PP +\-\-cert\-key\-len certKeyLength +.RS 4 +Specify the desired length of the symmetric key to be used to encrypt the certificates and other meta\-data\&. +.RE +.PP +\-n certname +.RS 4 +Specify the nickname of the cert and private key to export\&. +.sp +The nickname can also be a PKCS #11 URI\&. For example, if you have a certificate named "my\-server\-cert" on the internal certificate store, it can be unambiguously specified as "pkcs11:token=NSS%20Certificate%20DB;object=my\-server\-cert"\&. For details about the format, see RFC 7512\&. +.RE +.PP +\-P prefix +.RS 4 +Specify the prefix used on the certificate and key databases\&. This option is provided as a special case\&. Changing the names of the certificate and key databases is not recommended\&. +.RE +.PP +\-r +.RS 4 +Dumps all of the data in raw (binary) form\&. This must be saved as a DER file\&. The default is to return information in a pretty\-print ASCII format, which displays the information about the certificates and public keys in the p12 file\&. +.RE +.PP +\-v +.RS 4 +Enable debug logging when importing\&. +.RE +.PP +\-w p12filePasswordFile +.RS 4 +Specify the text file containing the pkcs #12 file password\&. +.RE +.PP +\-W p12filePassword +.RS 4 +Specify the pkcs #12 file password\&. +.RE +.SH "RETURN CODES" +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +0 \- No error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +1 \- User Cancelled +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +2 \- Usage error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +6 \- NLS init error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +8 \- Certificate DB open error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +9 \- Key DB open error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +10 \- File initialization error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +11 \- Unicode conversion error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +12 \- Temporary file creation error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +13 \- PKCS11 get slot error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +14 \- PKCS12 decoder start error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +15 \- error read from import file +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +16 \- pkcs12 decode error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +17 \- pkcs12 decoder verify error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +18 \- pkcs12 decoder validate bags error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +19 \- pkcs12 decoder import bags error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +20 \- key db conversion version 3 to version 2 error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +21 \- cert db conversion version 7 to version 5 error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +22 \- cert and key dbs patch error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +23 \- get default cert db error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +24 \- find cert by nickname error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +25 \- create export context error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +26 \- PKCS12 add password itegrity error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +27 \- cert and key Safes creation error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +28 \- PKCS12 add cert and key error +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +29 \- PKCS12 encode error +.RE +.SH "EXAMPLES" +.PP +\fBImporting Keys and Certificates\fR +.PP +The most basic usage of +\fBpk12util\fR +for importing a certificate or key is the PKCS #12 input file (\fB\-i\fR) and some way to specify the security database being accessed (either +\fB\-d\fR +for a directory or +\fB\-h\fR +for a token)\&. +.PP +pk12util \-i p12File [\-h tokenname] [\-v] [\-d directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword] +.PP +For example: +.PP + +.sp +.if n \{\ +.RS 4 +.\} +.nf +# pk12util \-i /tmp/cert\-files/users\&.p12 \-d /home/my/sharednssdb + +Enter a password which will be used to encrypt your keys\&. +The password should be at least 8 characters long, +and should contain at least one non\-alphabetic character\&. + +Enter new password: +Re\-enter password: +Enter password for PKCS12 file: +pk12util: PKCS12 IMPORT SUCCESSFUL +.fi +.if n \{\ +.RE +.\} +.PP +\fBExporting Keys and Certificates\fR +.PP +Using the +\fBpk12util\fR +command to export certificates and keys requires both the name of the certificate to extract from the database (\fB\-n\fR) and the PKCS #12\-formatted output file to write to\&. There are optional parameters that can be used to encrypt the file to protect the certificate material\&. +.PP +pk12util \-o p12File \-n certname [\-c keyCipher] [\-C certCipher] [\-m|\-\-key_len keyLen] [\-n|\-\-cert_key_len certKeyLen] [\-d directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword] +.PP +For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# pk12util \-o certs\&.p12 \-n Server\-Cert \-d /home/my/sharednssdb +Enter password for PKCS12 file: +Re\-enter password: +.fi +.if n \{\ +.RE +.\} +.PP +\fBListing Keys and Certificates\fR +.PP +The information in a +\&.p12 +file are not human\-readable\&. The certificates and keys in the file can be printed (listed) in a human\-readable pretty\-print format that shows information for every certificate and any public keys in the +\&.p12 +file\&. +.PP +pk12util \-l p12File [\-h tokenname] [\-r] [\-d directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword] +.PP +For example, this prints the default ASCII output: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# pk12util \-l certs\&.p12 + +Enter password for PKCS12 file: +Key(shrouded): + Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID + + Encryption algorithm: PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC + Parameters: + Salt: + 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f + Iteration Count: 1 (0x1) +Certificate: + Data: + Version: 3 (0x2) + Serial Number: 13 (0xd) + Signature Algorithm: PKCS #1 SHA\-1 With RSA Encryption + Issuer: "E=personal\-freemail@thawte\&.com,CN=Thawte Personal Freemail C + A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T + own,ST=Western Cape,C=ZA" + +.fi +.if n \{\ +.RE +.\} +.PP +Alternatively, the +\fB\-r\fR +prints the certificates and then exports them into separate DER binary files\&. This allows the certificates to be fed to another application that supports +\&.p12 +files\&. Each certificate is written to a sequentially\-number file, beginning with +file0001\&.der +and continuing through +file000N\&.der, incrementing the number for every certificate: +.sp +.if n \{\ +.RS 4 +.\} +.nf +pk12util \-l test\&.p12 \-r +Enter password for PKCS12 file: +Key(shrouded): + Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID + + Encryption algorithm: PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC + Parameters: + Salt: + 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f + Iteration Count: 1 (0x1) +Certificate Friendly Name: Thawte Personal Freemail Issuing CA \- Thawte Consulting + +Certificate Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID + +.fi +.if n \{\ +.RE +.\} +.SH "PASSWORD ENCRYPTION" +.PP +PKCS #12 provides for not only the protection of the private keys but also the certificate and meta\-data associated with the keys\&. Password\-based encryption is used to protect private keys on export to a PKCS #12 file and, optionally, the associated certificates\&. If no algorithm is specified, the tool defaults to using PKCS #12 SHA\-1 and 3\-key triple DES for private key encryption\&. When not in FIPS mode, PKCS #12 SHA\-1 and 40\-bit RC4 is used for certificate encryption\&. When in FIPS mode, there is no certificate encryption\&. If certificate encryption is not wanted, specify +\fB"NONE"\fR +as the argument of the +\fB\-C\fR +option\&. +.PP +The private key is always protected with strong encryption by default\&. +.PP +Several types of ciphers are supported\&. +.PP +PKCS #5 password\-based encryption +.RS 4 +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +PBES2 with AES\-CBC\-Pad as underlying encryption scheme (\fB"AES\-128\-CBC"\fR, +\fB"AES\-192\-CBC"\fR, and +\fB"AES\-256\-CBC"\fR) +.RE +.RE +.PP +PKCS #12 password\-based encryption +.RS 4 +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA\-1 and 128\-bit RC4 (\fB"PKCS #12 V2 PBE With SHA\-1 And 128 Bit RC4"\fR +or +\fB"RC4"\fR) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA\-1 and 40\-bit RC4 (\fB"PKCS #12 V2 PBE With SHA\-1 And 40 Bit RC4"\fR) (used by default for certificate encryption in non\-FIPS mode) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA\-1 and 3\-key triple\-DES (\fB"PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC"\fR +or +\fB"DES\-EDE3\-CBC"\fR) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA\-1 and 128\-bit RC2 (\fB"PKCS #12 V2 PBE With SHA\-1 And 128 Bit RC2 CBC"\fR +or +\fB"RC2\-CBC"\fR) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SHA\-1 and 40\-bit RC2 (\fB"PKCS #12 V2 PBE With SHA\-1 And 40 Bit RC2 CBC"\fR) +.RE +.RE +.PP +With PKCS #12, the crypto provider may be the soft token module or an external hardware module\&. If the cryptographic module does not support the requested algorithm, then the next best fit will be selected (usually the default)\&. If no suitable replacement for the desired algorithm can be found, the tool returns the error +\fIno security module can perform the requested operation\fR\&. +.SH "NSS DATABASE TYPES" +.PP +NSS originally used BerkeleyDB databases to store security information\&. The last versions of these +\fIlegacy\fR +databases are: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert8\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key3\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +secmod\&.db for PKCS #11 module information +.RE +.PP +BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously\&. NSS has some flexibility that allows applications to use their own, independent database engine while keeping a shared database and working around the access issues\&. Still, NSS requires more flexibility to provide a truly shared security database\&. +.PP +In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert9\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key4\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory +.RE +.PP +Because the SQLite databases are designed to be shared, these are the +\fIshared\fR +database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&. +.PP +By default, the tools (\fBcertutil\fR, +\fBpk12util\fR, +\fBmodutil\fR) assume that the given security databases use the SQLite type Using the legacy databases must be manually specified by using the +\fBdbm:\fR +prefix with the given security directory\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# pk12util \-i /tmp/cert\-files/users\&.p12 \-d dbm:/home/my/sharednssdb +.fi +.if n \{\ +.RE +.\} +.PP +To set the legacy database type as the default type for the tools, set the +\fBNSS_DEFAULT_DB_TYPE\fR +environment variable to +\fBdbm\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +export NSS_DEFAULT_DB_TYPE="dbm" +.fi +.if n \{\ +.RE +.\} +.PP +This line can be set added to the +~/\&.bashrc +file to make the change permanent\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.PP +For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "COMPATIBILITY NOTES" +.PP +The exporting behavior of +\fBpk12util\fR +has changed over time, while importing files exported with older versions of NSS is still supported\&. +.PP +Until the 3\&.30 release, +\fBpk12util\fR +used the UTF\-16 encoding for the PKCS #5 password\-based encryption schemes, while the recommendation is to encode passwords in UTF\-8 if the used encryption scheme is defined outside of the PKCS #12 standard\&. +.PP +Until the 3\&.31 release, even when +\fB"AES\-128\-CBC"\fR +or +\fB"AES\-192\-CBC"\fR +is given from the command line, +\fBpk12util\fR +always used 256\-bit AES as the underlying encryption scheme\&. +.PP +For historical reasons, +\fBpk12util\fR +accepts password\-based encryption schemes not listed in this document\&. However, those schemes are not officially supported and may have issues in interoperability with other tools\&. +.SH "SEE ALSO" +.PP +certutil (1) +.PP +modutil (1) +.PP +The NSS wiki has information on the new database design and how to configure applications to use it\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/pp.1 b/security/nss/doc/rst/legacy/nroff/pp.1 new file mode 100644 index 0000000000..ce536817ed --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/pp.1 @@ -0,0 +1,108 @@ +'\" t +.\" Title: PP +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "PP" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pp \- Prints certificates, keys, crls, and pkcs7 files +.SH "SYNOPSIS" +.HP \w'\fBpp\ \-t\ type\ [\-a]\ [\-i\ input]\ [\-o\ output]\ [\-u]\ [\-w]\fR\ 'u +\fBpp \-t type [\-a] [\-i input] [\-o output] [\-u] [\-w]\fR +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +\fBpp \fRpretty\-prints private and public key, certificate, certificate\-request, pkcs7, pkcs12 or crl files +.SH "OPTIONS" +.PP +\fB\-t \fR \fItype\fR +.RS 4 +specify the input, one of {private\-key | public\-key | certificate | certificate\-request | pkcs7 | pkcs12 | crl | name} +.sp +.RE +.PP +\fB\-a \fR +.RS 4 +Input is in ascii encoded form (RFC1113) +.RE +.PP +\fB\-i \fR \fIinputfile\fR +.RS 4 +Define an input file to use (default is stdin) +.RE +.PP +\fB\-o \fR \fIoutputfile\fR +.RS 4 +Define an output file to use (default is stdout) +.RE +.PP +\fB\-u \fR +.RS 4 +Use UTF\-8 (default is to show non\-ascii as \&.) +.RE +.PP +\fB\-w \fR +.RS 4 +Don\*(Aqt wrap long output lines +.RE +.SH "ADDITIONAL RESOURCES" +.PP +NSS is maintained in conjunction with PKI and security\-related projects through Mozilla and Fedora\&. The most closely\-related project is Dogtag PKI, with a project wiki at +\m[blue]\fBPKI Wiki\fR\m[]\&\s-2\u[2]\d\s+2\&. +.PP +For information specifically about NSS, the NSS project wiki is located at +\m[blue]\fBMozilla NSS site\fR\m[]\&\s-2\u[3]\d\s+2\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: pki\-devel@redhat\&.com and pki\-users@redhat\&.com +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE +.IP " 2." 4 +PKI Wiki +.RS 4 +\%http://pki.fedoraproject.org/wiki/ +.RE +.IP " 3." 4 +Mozilla NSS site +.RS 4 +\%http://www.mozilla.org/projects/security/pki/nss/ +.RE diff --git a/security/nss/doc/rst/legacy/nroff/signtool.1 b/security/nss/doc/rst/legacy/nroff/signtool.1 new file mode 100644 index 0000000000..1acfd7856a --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/signtool.1 @@ -0,0 +1,681 @@ +'\" t +.\" Title: signtool +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "SIGNTOOL" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +signtool \- Digitally sign objects and files\&. +.SH "SYNOPSIS" +.HP \w'\fBsigntool\fR\ 'u +\fBsigntool\fR [[\-b\ basename]] [[\-c\ Compression\ Level]] [[\-d\ cert\-dir]] [[\-e\ extension]] [[\-f\ filename]] [[\-i\ installer\ script]] [[\-h]] [[\-H]] [[\-v]] [[\-w]] [[\-G\ nickname]] [[\-J]] [[\-j\ directory]] [\-k\ keyName] [[\-\-keysize\ |\ \-s\ size]] [[\-l]] [[\-L]] [[\-M]] [[\-m\ metafile]] [[\-\-norecurse]] [[\-O]] [[\-o]] [[\-\-outfile]] [[\-p\ password]] [[\-t|\-\-token\ tokenname]] [[\-z]] [[\-X]] [[\-x\ name]] [[\-\-verbose\ value]] [[\-\-leavearc]] [[\-Z\ jarfile]] [directory\-tree] [archive] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The Signing Tool, +\fBsigntool\fR, creates digital signatures and uses a Java Archive (JAR) file to associate the signatures with files in a directory\&. Electronic software distribution over any network involves potential security problems\&. To help address some of these problems, you can associate digital signatures with the files in a JAR archive\&. Digital signatures allow SSL\-enabled clients to perform two important operations: +.PP +* Confirm the identity of the individual, company, or other entity whose digital signature is associated with the files +.PP +* Check whether the files have been tampered with since being signed +.PP +If you have a signing certificate, you can use Netscape Signing Tool to digitally sign files and package them as a JAR file\&. An object\-signing certificate is a special kind of certificate that allows you to associate your digital signature with one or more files\&. +.PP +An individual file can potentially be signed with multiple digital signatures\&. For example, a commercial software developer might sign the files that constitute a software product to prove that the files are indeed from a particular company\&. A network administrator manager might sign the same files with an additional digital signature based on a company\-generated certificate to indicate that the product is approved for use within the company\&. +.PP +The significance of a digital signature is comparable to the significance of a handwritten signature\&. Once you have signed a file, it is difficult to claim later that you didn\*(Aqt sign it\&. In some situations, a digital signature may be considered as legally binding as a handwritten signature\&. Therefore, you should take great care to ensure that you can stand behind any file you sign and distribute\&. +.PP +For example, if you are a software developer, you should test your code to make sure it is virus\-free before signing it\&. Similarly, if you are a network administrator, you should make sure, before signing any code, that it comes from a reliable source and will run correctly with the software installed on the machines to which you are distributing it\&. +.PP +Before you can use Netscape Signing Tool to sign files, you must have an object\-signing certificate, which is a special certificate whose associated private key is used to create digital signatures\&. For testing purposes only, you can create an object\-signing certificate with Netscape Signing Tool 1\&.3\&. When testing is finished and you are ready to disitribute your software, you should obtain an object\-signing certificate from one of two kinds of sources: +.PP +* An independent certificate authority (CA) that authenticates your identity and charges you a fee\&. You typically get a certificate from an independent CA if you want to sign software that will be distributed over the Internet\&. +.PP +* CA server software running on your corporate intranet or extranet\&. Netscape Certificate Management System provides a complete management solution for creating, deploying, and managing certificates, including CAs that issue object\-signing certificates\&. +.PP +You must also have a certificate for the CA that issues your signing certificate before you can sign files\&. If the certificate authority\*(Aqs certificate isn\*(Aqt already installed in your copy of Communicator, you typically install it by clicking the appropriate link on the certificate authority\*(Aqs web site, for example on the page from which you initiated enrollment for your signing certificate\&. This is the case for some test certificates, as well as certificates issued by Netscape Certificate Management System: you must download the the CA certificate in addition to obtaining your own signing certificate\&. CA certificates for several certificate authorities are preinstalled in the Communicator certificate database\&. +.PP +When you receive an object\-signing certificate for your own use, it is automatically installed in your copy of the Communicator client software\&. Communicator supports the public\-key cryptography standard known as PKCS #12, which governs key portability\&. You can, for example, move an object\-signing certificate and its associated private key from one computer to another on a credit\-card\-sized device called a smart card\&. +.SH "OPTIONS" +.PP +\-b basename +.RS 4 +Specifies the base filename for the \&.rsa and \&.sf files in the META\-INF directory to conform with the JAR format\&. For example, +\fI\-b signatures\fR +causes the files to be named signatures\&.rsa and signatures\&.sf\&. The default is signtool\&. +.RE +.PP +\-c# +.RS 4 +Specifies the compression level for the \-J or \-Z option\&. The symbol # represents a number from 0 to 9, where 0 means no compression and 9 means maximum compression\&. The higher the level of compression, the smaller the output but the longer the operation takes\&. If the \-c# option is not used with either the \-J or the \-Z option, the default compression value used by both the \-J and \-Z options is 6\&. +.RE +.PP +\-d certdir +.RS 4 +Specifies your certificate database directory; that is, the directory in which you placed your key3\&.db and cert7\&.db files\&. To specify the current directory, use "\-d\&." (including the period)\&. The Unix version of signtool assumes ~/\&.netscape unless told otherwise\&. The NT version of signtool always requires the use of the \-d option to specify where the database files are located\&. +.RE +.PP +\-e extension +.RS 4 +Tells signtool to sign only files with the given extension; for example, use \-e"\&.class" to sign only Java class files\&. Note that with Netscape Signing Tool version 1\&.1 and later this option can appear multiple times on one command line, making it possible to specify multiple file types or classes to include\&. +.RE +.PP +\-f commandfile +.RS 4 +Specifies a text file containing Netscape Signing Tool options and arguments in keyword=value format\&. All options and arguments can be expressed through this file\&. For more information about the syntax used with this file, see "Tips and Techniques"\&. +.RE +.PP +\-G nickname +.RS 4 +Generates a new private\-public key pair and corresponding object\-signing certificate with the given nickname\&. The newly generated keys and certificate are installed into the key and certificate databases in the directory specified by the \-d option\&. With the NT version of Netscape Signing Tool, you must use the \-d option with the \-G option\&. With the Unix version of Netscape Signing Tool, omitting the \-d option causes the tool to install the keys and certificate in the Communicator key and certificate databases\&. If you are installing the keys and certificate in the Communicator databases, you must exit Communicator before using this option; otherwise, you risk corrupting the databases\&. In all cases, the certificate is also output to a file named x509\&.cacert, which has the MIME\-type application/x\-x509\-ca\-cert\&. Unlike certificates normally used to sign finished code to be distributed over a network, a test certificate created with \-G is not signed by a recognized certificate authority\&. Instead, it is self\-signed\&. In addition, a single test signing certificate functions as both an object\-signing certificate and a CA\&. When you are using it to sign objects, it behaves like an object\-signing certificate\&. When it is imported into browser software such as Communicator, it behaves like an object\-signing CA and cannot be used to sign objects\&. The \-G option is available in Netscape Signing Tool 1\&.0 and later versions only\&. By default, it produces only RSA certificates with 1024\-byte keys in the internal token\&. However, you can use the \-s option specify the required key size and the \-t option to specify the token\&. +.RE +.PP +\-i scriptname +.RS 4 +Specifies the name of an installer script for SmartUpdate\&. This script installs files from the JAR archive in the local system after SmartUpdate has validated the digital signature\&. For more details, see the description of \-m that follows\&. The \-i option provides a straightforward way to provide this information if you don\*(Aqt need to specify any metadata other than an installer script\&. +.RE +.PP +\-J +.RS 4 +Signs a directory of HTML files containing JavaScript and creates as many archive files as are specified in the HTML tags\&. Even if signtool creates more than one archive file, you need to supply the key database password only once\&. The \-J option is available only in Netscape Signing Tool 1\&.0 and later versions\&. The \-J option cannot be used at the same time as the \-Z option\&. If the \-c# option is not used with the \-J option, the default compression value is 6\&. Note that versions 1\&.1 and later of Netscape Signing Tool correctly recognizes the CODEBASE attribute, allows paths to be expressed for the CLASS and SRC attributes instead of filenames only, processes LINK tags and parses HTML correctly, and offers clearer error messages\&. +.RE +.PP +\-j directory +.RS 4 +Specifies a special JavaScript directory\&. This option causes the specified directory to be signed and tags its entries as inline JavaScript\&. This special type of entry does not have to appear in the JAR file itself\&. Instead, it is located in the HTML page containing the inline scripts\&. When you use signtool \-v, these entries are displayed with the string NOT PRESENT\&. +.RE +.PP +\-k key \&.\&.\&. directory +.RS 4 +Specifies the nickname (key) of the certificate you want to sign with and signs the files in the specified directory\&. The directory to sign is always specified as the last command\-line argument\&. Thus, it is possible to write signtool \-k MyCert \-d \&. signdir You may have trouble if the nickname contains a single quotation mark\&. To avoid problems, escape the quotation mark using the escape conventions for your platform\&. It\*(Aqs also possible to use the \-k option without signing any files or specifying a directory\&. For example, you can use it with the \-l option to get detailed information about a particular signing certificate\&. +.RE +.PP +\-l +.RS 4 +Lists signing certificates, including issuing CAs\&. If any of your certificates are expired or invalid, the list will so specify\&. This option can be used with the \-k option to list detailed information about a particular signing certificate\&. The \-l option is available in Netscape Signing Tool 1\&.0 and later versions only\&. +.RE +.PP +\-L +.RS 4 +Lists the certificates in your database\&. An asterisk appears to the left of the nickname for any certificate that can be used to sign objects with signtool\&. +.RE +.PP +\-\-leavearc +.RS 4 +Retains the temporary \&.arc (archive) directories that the \-J option creates\&. These directories are automatically erased by default\&. Retaining the temporary directories can be an aid to debugging\&. +.RE +.PP +\-m metafile +.RS 4 +Specifies the name of a metadata control file\&. Metadata is signed information attached either to the JAR archive itself or to files within the archive\&. This metadata can be any ASCII string, but is used mainly for specifying an installer script\&. The metadata file contains one entry per line, each with three fields: field #1: file specification, or + if you want to specify global metadata (that is, metadata about the JAR archive itself or all entries in the archive) field #2: the name of the data you are specifying; for example: Install\-Script field #3: data corresponding to the name in field #2 For example, the \-i option uses the equivalent of this line: + Install\-Script: script\&.js This example associates a MIME type with a file: movie\&.qt MIME\-Type: video/quicktime For information about the way installer script information appears in the manifest file for a JAR archive, see The JAR Format on Netscape DevEdge\&. +.RE +.PP +\-M +.RS 4 +Lists the PKCS #11 modules available to signtool, including smart cards\&. The \-M option is available in Netscape Signing Tool 1\&.0 and later versions only\&. For information on using Netscape Signing Tool with smart cards, see "Using Netscape Signing Tool with Smart Cards"\&. For information on using the \-M option to verify FIPS\-140\-1 validated mode, see "Netscape Signing Tool and FIPS\-140\-1"\&. +.RE +.PP +\-\-norecurse +.RS 4 +Blocks recursion into subdirectories when signing a directory\*(Aqs contents or when parsing HTML\&. +.RE +.PP +\-o +.RS 4 +Optimizes the archive for size\&. Use this only if you are signing very large archives containing hundreds of files\&. This option makes the manifest files (required by the JAR format) considerably smaller, but they contain slightly less information\&. +.RE +.PP +\-\-outfile outputfile +.RS 4 +Specifies a file to receive redirected output from Netscape Signing Tool\&. +.RE +.PP +\-p password +.RS 4 +Specifies a password for the private\-key database\&. Note that the password entered on the command line is displayed as plain text\&. +.RE +.PP +\-s keysize +.RS 4 +Specifies the size of the key for generated certificate\&. Use the \-M option to find out what tokens are available\&. The \-s option can be used with the \-G option only\&. +.RE +.PP +\-t token +.RS 4 +Specifies which available token should generate the key and receive the certificate\&. Use the \-M option to find out what tokens are available\&. The \-t option can be used with the \-G option only\&. +.RE +.PP +\-v archive +.RS 4 +Displays the contents of an archive and verifies the cryptographic integrity of the digital signatures it contains and the files with which they are associated\&. This includes checking that the certificate for the issuer of the object\-signing certificate is listed in the certificate database, that the CA\*(Aqs digital signature on the object\-signing certificate is valid, that the relevant certificates have not expired, and so on\&. +.RE +.PP +\-\-verbosity value +.RS 4 +Sets the quantity of information Netscape Signing Tool generates in operation\&. A value of 0 (zero) is the default and gives full information\&. A value of \-1 suppresses most messages, but not error messages\&. +.RE +.PP +\-w archive +.RS 4 +Displays the names of signers of any files in the archive\&. +.RE +.PP +\-x directory +.RS 4 +Excludes the specified directory from signing\&. Note that with Netscape Signing Tool version 1\&.1 and later this option can appear multiple times on one command line, making it possible to specify several particular directories to exclude\&. +.RE +.PP +\-z +.RS 4 +Tells signtool not to store the signing time in the digital signature\&. This option is useful if you want the expiration date of the signature checked against the current date and time rather than the time the files were signed\&. +.RE +.PP +\-Z jarfile +.RS 4 +Creates a JAR file with the specified name\&. You must specify this option if you want signtool to create the JAR file; it does not do so automatically\&. If you don\*(Aqt specify \-Z, you must use an external ZIP tool to create the JAR file\&. The \-Z option cannot be used at the same time as the \-J option\&. If the \-c# option is not used with the \-Z option, the default compression value is 6\&. +.RE +.SH "THE COMMAND FILE FORMAT" +.PP +Entries in a Netscape Signing Tool command file have this general format: keyword=value Everything before the = sign on a single line is a keyword, and everything from the = sign to the end of line is a value\&. The value may include = signs; only the first = sign on a line is interpreted\&. Blank lines are ignored, but white space on a line with keywords and values is assumed to be part of the keyword (if it comes before the equal sign) or part of the value (if it comes after the first equal sign)\&. Keywords are case insensitive, values are generally case sensitive\&. Since the = sign and newline delimit the value, it should not be quoted\&. +.PP +\fBSubsection\fR +.PP +basename +.RS 4 +Same as \-b option\&. +.RE +.PP +compression +.RS 4 +Same as \-c option\&. +.RE +.PP +certdir +.RS 4 +Same as \-d option\&. +.RE +.PP +extension +.RS 4 +Same as \-e option\&. +.RE +.PP +generate +.RS 4 +Same as \-G option\&. +.RE +.PP +installscript +.RS 4 +Same as \-i option\&. +.RE +.PP +javascriptdir +.RS 4 +Same as \-j option\&. +.RE +.PP +htmldir +.RS 4 +Same as \-J option\&. +.RE +.PP +certname +.RS 4 +Nickname of certificate, as with \-k and \-l \-k options\&. +.RE +.PP +signdir +.RS 4 +The directory to be signed, as with \-k option\&. +.RE +.PP +list +.RS 4 +Same as \-l option\&. Value is ignored, but = sign must be present\&. +.RE +.PP +listall +.RS 4 +Same as \-L option\&. Value is ignored, but = sign must be present\&. +.RE +.PP +metafile +.RS 4 +Same as \-m option\&. +.RE +.PP +modules +.RS 4 +Same as \-M option\&. Value is ignored, but = sign must be present\&. +.RE +.PP +optimize +.RS 4 +Same as \-o option\&. Value is ignored, but = sign must be present\&. +.RE +.PP +password +.RS 4 +Same as \-p option\&. +.RE +.PP +keysize +.RS 4 +Same as \-s option\&. +.RE +.PP +token +.RS 4 +Same as \-t option\&. +.RE +.PP +verify +.RS 4 +Same as \-v option\&. +.RE +.PP +who +.RS 4 +Same as \-w option\&. +.RE +.PP +exclude +.RS 4 +Same as \-x option\&. +.RE +.PP +notime +.RS 4 +Same as \-z option\&. value is ignored, but = sign must be present\&. +.RE +.PP +jarfile +.RS 4 +Same as \-Z option\&. +.RE +.PP +outfile +.RS 4 +Name of a file to which output and error messages will be redirected\&. This option has no command\-line equivalent\&. +.RE +.SH "EXTENDED EXAMPLES" +.PP +The following example will do this and that +.PP +\fBListing Available Signing Certificates\fR +.PP +You use the \-L option to list the nicknames for all available certificates and check which ones are signing certificates\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-L + +using certificate directory: /u/jsmith/\&.netscape +S Certificates +\- \-\-\-\-\-\-\-\-\-\-\-\- + BBN Certificate Services CA Root 1 + IBM World Registry CA + VeriSign Class 1 CA \- Individual Subscriber \- VeriSign, Inc\&. + GTE CyberTrust Root CA + Uptime Group Plc\&. Class 4 CA +* Verisign Object Signing Cert + Integrion CA + GTE CyberTrust Secure Server CA + AT&T Directory Services +* test object signing cert + Uptime Group Plc\&. Class 1 CA + VeriSign Class 1 Primary CA +\- \-\-\-\-\-\-\-\-\-\-\-\- + +Certificates that can be used to sign objects have *\*(Aqs to their left\&. +.fi +.if n \{\ +.RE +.\} +.PP +Two signing certificates are displayed: Verisign Object Signing Cert and test object signing cert\&. +.PP +You use the \-l option to get a list of signing certificates only, including the signing CA for each\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-l + +using certificate directory: /u/jsmith/\&.netscape +Object signing certificates +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +Verisign Object Signing Cert + Issued by: VeriSign, Inc\&. \- Verisign, Inc\&. + Expires: Tue May 19, 1998 +test object signing cert + Issued by: test object signing cert (Signtool 1\&.0 Testing +Certificate (960187691)) + Expires: Sun May 17, 1998 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.fi +.if n \{\ +.RE +.\} +.PP +For a list including CAs, use the +\fB\-L\fR +option\&. +.PP +\fBSigning a File\fR +.PP +1\&. Create an empty directory\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +mkdir signdir +.fi +.if n \{\ +.RE +.\} +.PP +2\&. Put some file into it\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +echo boo > signdir/test\&.f +.fi +.if n \{\ +.RE +.\} +.PP +3\&. Specify the name of your object\-signing certificate and sign the directory\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-k MySignCert \-Z testjar\&.jar signdir + +using key "MySignCert" +using certificate directory: /u/jsmith/\&.netscape +Generating signdir/META\-INF/manifest\&.mf file\&.\&. +\-\-> test\&.f +adding signdir/test\&.f to testjar\&.jar +Generating signtool\&.sf file\&.\&. +Enter Password or Pin for "Communicator Certificate DB": + +adding signdir/META\-INF/manifest\&.mf to testjar\&.jar +adding signdir/META\-INF/signtool\&.sf to testjar\&.jar +adding signdir/META\-INF/signtool\&.rsa to testjar\&.jar + +tree "signdir" signed successfully +.fi +.if n \{\ +.RE +.\} +.PP +4\&. Test the archive you just created\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-v testjar\&.jar + +using certificate directory: /u/jsmith/\&.netscape +archive "testjar\&.jar" has passed crypto verification\&. + status path + \-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + verified test\&.f +.fi +.if n \{\ +.RE +.\} +.PP +\fBUsing Netscape Signing Tool with a ZIP Utility\fR +.PP +To use Netscape Signing Tool with a ZIP utility, you must have the utility in your path environment variable\&. You should use the zip\&.exe utility rather than pkzip\&.exe, which cannot handle long filenames\&. You can use a ZIP utility instead of the \-Z option to package a signed archive into a JAR file after you have signed it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +cd signdir + + zip \-r \&.\&./myjar\&.jar * + adding: META\-INF/ (stored 0%) + adding: META\-INF/manifest\&.mf (deflated 15%) + adding: META\-INF/signtool\&.sf (deflated 28%) + adding: META\-INF/signtool\&.rsa (stored 0%) + adding: text\&.txt (stored 0%) +.fi +.if n \{\ +.RE +.\} +.PP +\fBGenerating the Keys and Certificate\fR +.PP +The signtool option \-G generates a new public\-private key pair and certificate\&. It takes the nickname of the new certificate as an argument\&. The newly generated keys and certificate are installed into the key and certificate databases in the directory specified by the \-d option\&. With the NT version of Netscape Signing Tool, you must use the \-d option with the \-G option\&. With the Unix version of Netscape Signing Tool, omitting the \-d option causes the tool to install the keys and certificate in the Communicator key and certificate databases\&. In all cases, the certificate is also output to a file named x509\&.cacert, which has the MIME\-type application/x\-x509\-ca\-cert\&. +.PP +Certificates contain standard information about the entity they identify, such as the common name and organization name\&. Netscape Signing Tool prompts you for this information when you run the command with the \-G option\&. However, all of the requested fields are optional for test certificates\&. If you do not enter a common name, the tool provides a default name\&. In the following example, the user input is in boldface: +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-G MyTestCert + +using certificate directory: /u/someuser/\&.netscape +Enter certificate information\&. All fields are optional\&. Acceptable +characters are numbers, letters, spaces, and apostrophes\&. +certificate common name: Test Object Signing Certificate +organization: Netscape Communications Corp\&. +organization unit: Server Products Division +state or province: California +country (must be exactly 2 characters): US +username: someuser +email address: someuser@netscape\&.com +Enter Password or Pin for "Communicator Certificate DB": [Password will not echo] +generated public/private key pair +certificate request generated +certificate has been signed +certificate "MyTestCert" added to database +Exported certificate to x509\&.raw and x509\&.cacert\&. +.fi +.if n \{\ +.RE +.\} +.PP +The certificate information is read from standard input\&. Therefore, the information can be read from a file using the redirection operator (<) in some operating systems\&. To create a file for this purpose, enter each of the seven input fields, in order, on a separate line\&. Make sure there is a newline character at the end of the last line\&. Then run signtool with standard input redirected from your file as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-G MyTestCert inputfile +.fi +.if n \{\ +.RE +.\} +.PP +The prompts show up on the screen, but the responses will be automatically read from the file\&. The password will still be read from the console unless you use the \-p option to give the password on the command line\&. +.PP +\fBUsing the \-M Option to List Smart Cards\fR +.PP +You can use the \-M option to list the PKCS #11 modules, including smart cards, that are available to signtool: +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-d "c:\enetscape\eusers\ejsmith" \-M + +using certificate directory: c:\enetscape\eusers\eusername +Listing of PKCS11 modules +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 1\&. Netscape Internal PKCS #11 Module + (this module is internally loaded) + slots: 2 slots attached + status: loaded + slot: Communicator Internal Cryptographic Services Version 4\&.0 + token: Communicator Generic Crypto Svcs + slot: Communicator User Private Key and Certificate Services + token: Communicator Certificate DB + 2\&. CryptOS + (this is an external module) + DLL name: core32 + slots: 1 slots attached + status: loaded + slot: Litronic 210 + token: + \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.fi +.if n \{\ +.RE +.\} +.PP +\fBUsing Netscape Signing Tool and a Smart Card to Sign Files\fR +.PP +The signtool command normally takes an argument of the \-k option to specify a signing certificate\&. To sign with a smart card, you supply only the fully qualified name of the certificate\&. +.PP +To see fully qualified certificate names when you run Communicator, click the Security button in Navigator, then click Yours under Certificates in the left frame\&. Fully qualified names are of the format smart card:certificate, for example "MyCard:My Signing Cert"\&. You use this name with the \-k argument as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-k "MyCard:My Signing Cert" directory +.fi +.if n \{\ +.RE +.\} +.PP +\fBVerifying FIPS Mode\fR +.PP +Use the \-M option to verify that you are using the FIPS\-140\-1 module\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-d "c:\enetscape\eusers\ejsmith" \-M + +using certificate directory: c:\enetscape\eusers\ejsmith +Listing of PKCS11 modules +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 1\&. Netscape Internal PKCS #11 Module + (this module is internally loaded) + slots: 2 slots attached + status: loaded + slot: Communicator Internal Cryptographic Services Version 4\&.0 + token: Communicator Generic Crypto Svcs + slot: Communicator User Private Key and Certificate Services + token: Communicator Certificate DB +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.fi +.if n \{\ +.RE +.\} +.PP +This Unix example shows that Netscape Signing Tool is using a FIPS\-140\-1 module: +.sp +.if n \{\ +.RS 4 +.\} +.nf +signtool \-d "c:\enetscape\eusers\ejsmith" \-M +using certificate directory: c:\enetscape\eusers\ejsmith +Enter Password or Pin for "Communicator Certificate DB": [password will not echo] +Listing of PKCS11 modules +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +1\&. Netscape Internal FIPS PKCS #11 Module +(this module is internally loaded) +slots: 1 slots attached +status: loaded +slot: Netscape Internal FIPS\-140\-1 Cryptographic Services +token: Communicator Certificate DB +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +signver (1) +.PP +The NSS wiki has information on the new database design and how to configure applications to use it\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/signver.1 b/security/nss/doc/rst/legacy/nroff/signver.1 new file mode 100644 index 0000000000..e42b4a8eee --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/signver.1 @@ -0,0 +1,318 @@ +'\" t +.\" Title: SIGNVER +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "SIGNVER" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +signver \- Verify a detached PKCS#7 signature for a file\&. +.SH "SYNOPSIS" +.HP \w'\fBsigntool\fR\ 'u +\fBsigntool\fR \-A | \-V \-d\ \fIdirectory\fR [\-a] [\-i\ \fIinput_file\fR] [\-o\ \fIoutput_file\fR] [\-s\ \fIsignature_file\fR] [\-v] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The Signature Verification Tool, +\fBsignver\fR, is a simple command\-line utility that unpacks a base\-64\-encoded PKCS#7 signed object and verifies the digital signature using standard cryptographic techniques\&. The Signature Verification Tool can also display the contents of the signed object\&. +.SH "OPTIONS" +.PP +\-A +.RS 4 +Displays all of the information in the PKCS#7 signature\&. +.RE +.PP +\-V +.RS 4 +Verifies the digital signature\&. +.RE +.PP +\-d \fIdirectory\fR +.RS 4 +Specify the database directory which contains the certificates and keys\&. +.sp +\fBsignver\fR +supports two types of databases: the legacy security databases (cert8\&.db, +key3\&.db, and +secmod\&.db) and new SQLite databases (cert9\&.db, +key4\&.db, and +pkcs11\&.txt)\&. If the prefix +\fBdbm:\fR +is not used, then the tool assumes that the given databases are in the SQLite format\&. +.RE +.PP +\-a +.RS 4 +Sets that the given signature file is in ASCII format\&. +.RE +.PP +\-i \fIinput_file\fR +.RS 4 +Gives the input file for the object with signed data\&. +.RE +.PP +\-o \fIoutput_file\fR +.RS 4 +Gives the output file to which to write the results\&. +.RE +.PP +\-s \fIsignature_file\fR +.RS 4 +Gives the input file for the digital signature\&. +.RE +.PP +\-v +.RS 4 +Enables verbose output\&. +.RE +.SH "EXTENDED EXAMPLES" +.SS "Verifying a Signature" +.PP +The +\fB\-V\fR +option verifies that the signature in a given signature file is valid when used to sign the given object (from the input file)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +signver \-V \-s \fIsignature_file\fR \-i \fIsigned_file\fR \-d /home/my/sharednssdb + +signatureValid=yes +.fi +.if n \{\ +.RE +.\} +.SS "Printing Signature Data" +.PP +The +\fB\-A\fR +option prints all of the information contained in a signature file\&. Using the +\fB\-o\fR +option prints the signature file information to the given output file rather than stdout\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +signver \-A \-s \fIsignature_file\fR \-o \fIoutput_file\fR +.fi +.if n \{\ +.RE +.\} +.SH "NSS DATABASE TYPES" +.PP +NSS originally used BerkeleyDB databases to store security information\&. The last versions of these +\fIlegacy\fR +databases are: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert8\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key3\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +secmod\&.db for PKCS #11 module information +.RE +.PP +BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously\&. NSS has some flexibility that allows applications to use their own, independent database engine while keeping a shared database and working around the access issues\&. Still, NSS requires more flexibility to provide a truly shared security database\&. +.PP +In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +cert9\&.db for certificates +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +key4\&.db for keys +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory +.RE +.PP +Because the SQLite databases are designed to be shared, these are the +\fIshared\fR +database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&. +.PP +By default, the tools (\fBcertutil\fR, +\fBpk12util\fR, +\fBmodutil\fR) assume that the given security databases use the SQLite type Using the legacy databases must be manually specified by using the +\fBdbm:\fR +prefix with the given security directory\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# signver \-A \-s \fIsignature\fR \-d dbm:/home/my/sharednssdb +.fi +.if n \{\ +.RE +.\} +.PP +To set the legacy database type as the default type for the tools, set the +\fBNSS_DEFAULT_DB_TYPE\fR +environment variable to +\fBdbm\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +export NSS_DEFAULT_DB_TYPE="dbm" +.fi +.if n \{\ +.RE +.\} +.PP +This line can be added to the +~/\&.bashrc +file to make the change permanent for the user\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.PP +For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "SEE ALSO" +.PP +signtool (1) +.PP +The NSS wiki has information on the new database design and how to configure applications to use it\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Setting up the shared NSS database +.sp +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Engineering and technical information about the shared NSS database +.sp +https://wiki\&.mozilla\&.org/NSS_Shared_DB +.RE +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/ssltap.1 b/security/nss/doc/rst/legacy/nroff/ssltap.1 new file mode 100644 index 0000000000..d3c15364a1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/ssltap.1 @@ -0,0 +1,609 @@ +'\" t +.\" Title: SSLTAP +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "SSLTAP" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ssltap \- Tap into SSL connections and display the data going by +.SH "SYNOPSIS" +.HP \w'\fBssltap\fR\ 'u +\fBssltap\fR [\-fhlsvx] [\-p\ port] [hostname:port] +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The SSL Debugging Tool +\fBssltap\fR +is an SSL\-aware command\-line proxy\&. It watches TCP connections and displays the data going by\&. If a connection is SSL, the data display includes interpreted SSL records and handshaking +.SH "OPTIONS" +.PP +\-f +.RS 4 +Turn on fancy printing\&. Output is printed in colored HTML\&. Data sent from the client to the server is in blue; the server\*(Aqs reply is in red\&. When used with looping mode, the different connections are separated with horizontal lines\&. You can use this option to upload the output into a browser\&. +.RE +.PP +\-h +.RS 4 +Turn on hex/ASCII printing\&. Instead of outputting raw data, the command interprets each record as a numbered line of hex values, followed by the same data as ASCII characters\&. The two parts are separated by a vertical bar\&. Nonprinting characters are replaced by dots\&. +.RE +.PP +\-l prefix +.RS 4 +Turn on looping; that is, continue to accept connections rather than stopping after the first connection is complete\&. +.RE +.PP +\-p port +.RS 4 +Change the default rendezvous port (1924) to another port\&. +.sp +The following are well\-known port numbers: +.sp +* HTTP 80 +.sp +* HTTPS 443 +.sp +* SMTP 25 +.sp +* FTP 21 +.sp +* IMAP 143 +.sp +* IMAPS 993 (IMAP over SSL) +.sp +* NNTP 119 +.sp +* NNTPS 563 (NNTP over SSL) +.RE +.PP +\-s +.RS 4 +Turn on SSL parsing and decoding\&. The tool does not automatically detect SSL sessions\&. If you are intercepting an SSL connection, use this option so that the tool can detect and decode SSL structures\&. +.sp +If the tool detects a certificate chain, it saves the DER\-encoded certificates into files in the current directory\&. The files are named cert\&.0x, where x is the sequence number of the certificate\&. +.sp +If the \-s option is used with \-h, two separate parts are printed for each record: the plain hex/ASCII output, and the parsed SSL output\&. +.RE +.PP +\-v +.RS 4 +Print a version string for the tool\&. +.RE +.PP +\-x +.RS 4 +Turn on extra SSL hex dumps\&. +.RE +.SH "USAGE AND EXAMPLES" +.PP +You can use the SSL Debugging Tool to intercept any connection information\&. Although you can run the tool at its most basic by issuing the ssltap command with no options other than hostname:port, the information you get in this way is not very useful\&. For example, assume your development machine is called intercept\&. The simplest way to use the debugging tool is to execute the following command from a command shell: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ ssltap www\&.netscape\&.com +.fi +.if n \{\ +.RE +.\} +.PP +The program waits for an incoming connection on the default port 1924\&. In your browser window, enter the URL http://intercept:1924\&. The browser retrieves the requested page from the server at www\&.netscape\&.com, but the page is intercepted and passed on to the browser by the debugging tool on intercept\&. On its way to the browser, the data is printed to the command shell from which you issued the command\&. Data sent from the client to the server is surrounded by the following symbols: \-\-> [ data ] Data sent from the server to the client is surrounded by the following symbols: "left arrow"\-\- [ data ] The raw data stream is sent to standard output and is not interpreted in any way\&. This can result in peculiar effects, such as sounds, flashes, and even crashes of the command shell window\&. To output a basic, printable interpretation of the data, use the \-h option, or, if you are looking at an SSL connection, the \-s option\&. You will notice that the page you retrieved looks incomplete in the browser\&. This is because, by default, the tool closes down after the first connection is complete, so the browser is not able to load images\&. To make the tool continue to accept connections, switch on looping mode with the \-l option\&. The following examples show the output from commonly used combinations of options\&. +.PP +Example 1 +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ ssltap\&.exe \-sx \-p 444 interzone\&.mcom\&.com:443 > sx\&.txt +.fi +.if n \{\ +.RE +.\} +.PP +Output +.sp +.if n \{\ +.RS 4 +.\} +.nf +Connected to interzone\&.mcom\&.com:443 +\-\->; [ +alloclen = 66 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher\-specs\-length = 39 (0x27) + sid\-length = 0 (0x00) + challenge\-length = 16 (0x10) + cipher\-suites = { + + (0x010080) SSL2/RSA/RC4\-128/MD5 + (0x020080) SSL2/RSA/RC4\-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x040080) SSL2/RSA/RC2CBC40/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE\-CBC/MD5 + (0x000004) SSL3/RSA/RC4\-128/MD5 + (0x00ffe0) SSL3/RSA\-FIPS/3DES192EDE\-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE\-CBC/SHA + (0x00ffe1) SSL3/RSA\-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4\-40/MD5 + (0x000006) SSL3/RSA/RC2CBC40/MD5 + } + session\-id = { } + challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 + +0x2592 } +} +] +<\-\- [ +SSLRecord { + 0: 16 03 00 03 e5 |\&.\&.\&.\&.\&. + type = 22 (handshake) + version = { 3,0 } + length = 997 (0x3e5) + handshake { + 0: 02 00 00 46 |\&.\&.\&.F + type = 2 (server_hello) + length = 70 (0x000046) + ServerHello { + server_version = {3, 0} + random = {\&.\&.\&.} + 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 | +wn&l\&.\(`i\&.\&.XOG\&.\-\&.E + 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f | + +\e\&.uC\(scL\&.\(,C\&.d<PAHO\&. + session ID = { + length = 32 + + contents = {\&.\&.} + 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 | \&.\&.\&.\(ad*1\&.)\&.\&.@7W\&.\(sc2 + 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 | VoRb\(Tp=\(S3e\(+-\&.\&.\&.R\(Po\(`E\&. + } + cipher_suite = (0x0003) SSL3/RSA/RC4\-40/MD5 + } + 0: 0b 00 02 c5 |\&.\&.\&.\(oA + type = 11 (certificate) + length = 709 (0x0002c5) + CertificateChain { + chainlength = 706 (0x02c2) + Certificate { + size = 703 (0x02bf) + data = { saved in file \*(Aqcert\&.001\*(Aq } + } + } + 0: 0c 00 00 ca |\&.\&.\&.\&. + type = 12 (server_key_exchange) + length = 202 (0x0000ca) + 0: 0e 00 00 00 |\&.\&.\&.\&. + type = 14 (server_hello_done) + length = 0 (0x000000) + } +} +] +\-\-> [ +SSLRecord { + 0: 16 03 00 00 44 |\&.\&.\&.\&.D + type = 22 (handshake) + version = { 3,0 } + length = 68 (0x44) + handshake { + 0: 10 00 00 40 |\&.\&.\&.@ + type = 16 (client_key_exchange) + length = 64 (0x000040) + ClientKeyExchange { + message = {\&.\&.\&.} + } + } +} +] +\-\-> [ +SSLRecord { + 0: 14 03 00 00 01 |\&.\&.\&.\&.\&. + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + 0: 01 |\&. +} +SSLRecord { + 0: 16 03 00 00 38 |\&.\&.\&.\&.8 + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + +} +] +<\-\- [ +SSLRecord { + 0: 14 03 00 00 01 |\&.\&.\&.\&.\&. + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + 0: 01 |\&. +} +] +<\-\- [ +SSLRecord { + 0: 16 03 00 00 38 |\&.\&.\&.\&.8 + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + +} +] +\-\-> [ +SSLRecord { + 0: 17 03 00 01 1f |\&.\&.\&.\&.\&. + type = 23 (application_data) + version = { 3,0 } + length = 287 (0x11f) + < encrypted > +} +] +<\-\- [ +SSLRecord { + 0: 17 03 00 00 a0 |\&.\&.\&.\&. + type = 23 (application_data) + version = { 3,0 } + length = 160 (0xa0) + < encrypted > + +} +] +<\-\- [ +SSLRecord { +0: 17 03 00 00 df |\&.\&.\&.\&.\(ss + type = 23 (application_data) + version = { 3,0 } + length = 223 (0xdf) + < encrypted > + +} +SSLRecord { + 0: 15 03 00 00 12 |\&.\&.\&.\&.\&. + type = 21 (alert) + version = { 3,0 } + length = 18 (0x12) + < encrypted > +} +] +Server socket closed\&. +.fi +.if n \{\ +.RE +.\} +.PP +Example 2 +.PP +The \-s option turns on SSL parsing\&. Because the \-x option is not used in this example, undecoded values are output as raw data\&. The output is routed to a text file\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ ssltap \-s \-p 444 interzone\&.mcom\&.com:443 > s\&.txt +.fi +.if n \{\ +.RE +.\} +.PP +Output +.sp +.if n \{\ +.RS 4 +.\} +.nf +Connected to interzone\&.mcom\&.com:443 +\-\-> [ +alloclen = 63 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher\-specs\-length = 36 (0x24) + sid\-length = 0 (0x00) + challenge\-length = 16 (0x10) + cipher\-suites = { + (0x010080) SSL2/RSA/RC4\-128/MD5 + (0x020080) SSL2/RSA/RC4\-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE\-CBC/MD5 + (0x000004) SSL3/RSA/RC4\-128/MD5 + (0x00ffe0) SSL3/RSA\-FIPS/3DES192EDE\-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE\-CBC/SHA + (0x00ffe1) SSL3/RSA\-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4\-40/MD5 + } + session\-id = { } + challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c +0x3fd0 } +] +>\-\- [ +SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 997 (0x3e5) + handshake { + type = 2 (server_hello) + length = 70 (0x000046) + ServerHello { + server_version = {3, 0} + random = {\&.\&.\&.} + session ID = { + length = 32 + contents = {\&.\&.} + } + cipher_suite = (0x0003) SSL3/RSA/RC4\-40/MD5 + } + type = 11 (certificate) + length = 709 (0x0002c5) + CertificateChain { + chainlength = 706 (0x02c2) + Certificate { + size = 703 (0x02bf) + data = { saved in file \*(Aqcert\&.001\*(Aq } + } + } + type = 12 (server_key_exchange) + length = 202 (0x0000ca) + type = 14 (server_hello_done) + length = 0 (0x000000) + } +} +] +\-\-> [ +SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 68 (0x44) + handshake { + type = 16 (client_key_exchange) + length = 64 (0x000040) + ClientKeyExchange { + message = {\&.\&.\&.} + } + } +} +] +\-\-> [ +SSLRecord { + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) +} +SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + > encrypted > +} +] +>\-\- [ +SSLRecord { + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) +} +] +>\-\- [ +SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + > encrypted > +} +] +\-\-> [ +SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 287 (0x11f) + > encrypted > +} +] +[ +SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 160 (0xa0) + > encrypted > +} +] +>\-\- [ +SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 223 (0xdf) + > encrypted > +} +SSLRecord { + type = 21 (alert) + version = { 3,0 } + length = 18 (0x12) + > encrypted > +} +] +Server socket closed\&. +.fi +.if n \{\ +.RE +.\} +.PP +Example 3 +.PP +In this example, the \-h option turns hex/ASCII format\&. There is no SSL parsing or decoding\&. The output is routed to a text file\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ ssltap \-h \-p 444 interzone\&.mcom\&.com:443 > h\&.txt +.fi +.if n \{\ +.RE +.\} +.PP +Output +.sp +.if n \{\ +.RS 4 +.\} +.nf +Connected to interzone\&.mcom\&.com:443 +\-\-> [ + 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 | \&.@\&.\&.\&.\&.\*(Aq\&.\&.\&.\&.\&.\&.\&.\&.\&. + 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | \&.\&.\&.\&.\&.\&.\&.\&.\&.@\&.\&.\&.\&.\&.\&. + 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 | \&.\&.\&.\&.\&.\&.\&.\&.\('a\&.\&.\&.\&.\&.\&.\&. + 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 | \&.\&.\(Tp[V\&.I\&.\exd9 \&.\&.\&.\(Om\(S1R + 40: 6f 2d |o\- +] +<\-\- [ + 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d | \&.\&.\&.\&.\&.\&.\&.\&.F\&.\&.\&.\&.\&.\&.\&. + 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b | h\&.:y`\&.\&.<\&.\&.\(S3\&.\(`Oi; + 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 | x\&.K\&.\(bbR\&.KF\(`e\&. \&.\&.\&. + 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 | MR\&.\('y\&.\&.QH\&.\&.\&.\&.\&.\(psvw + 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b | *\(^o\&.\&.\(r!\&.a\(ctd\&.\&.\&.\&.\&.\&. + 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 | \&.\&.\(oA\&.\&.\&.\&.\&.\&.0\&.\&.\&.0\&.\&. + 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 | $ \&.\&.\&.\&.\&.\&.\&.60\&.\&.\&.*\&. + 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 | H\&.\(di\&.\&.\&.\&.\&.\&.0w1\&.0\&.\&. + 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 | \&.U\&.\&.\&.\&.US1,0*\&.\&.U\&. + 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d | \&.\&.#Netscape Comm + a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f | unications Corpo + b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 | ration1\&.0\&.\&.\&.U\&.\&.\&. + c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 | \&.Hardcore1\*(Aq0%\&.\&.U + d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 | \&.\&.\&.\&.Hardcore Cer + e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 | tificate Server + f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 | II0\&.\&.\&.9805160103 +<additional data lines> +] +<additional records in same format> +Server socket closed\&. +.fi +.if n \{\ +.RE +.\} +.PP +Example 4 +.PP +In this example, the \-s option turns on SSL parsing, and the \-h option turns on hex/ASCII format\&. Both formats are shown for each record\&. The output is routed to a text file\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ ssltap \-hs \-p 444 interzone\&.mcom\&.com:443 > hs\&.txt +.fi +.if n \{\ +.RE +.\} +.PP +Output +.sp +.if n \{\ +.RS 4 +.\} +.nf +Connected to interzone\&.mcom\&.com:443 +\-\-> [ + 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 | \&.=\&.\&.\&.\&.$\&.\&.\&.\&.\&.\&.\&.\&.\&. + 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | \&.\&.\&.\&.\&.\&.\&.\&.\&.@\&.\&.\&.\&.\&.\&. + 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 | \&.\&.\&.\&.\&.\&.\&.\&.\('a\&.\&.\&.\&.\&.\&.\&. + 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 |U\&.\&.y\(,C\exb0 ,\&.x\&.]\(mc\(:I\('e +alloclen = 63 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher\-specs\-length = 36 (0x24) + sid\-length = 0 (0x00) + challenge\-length = 16 (0x10) + cipher\-suites = { + (0x010080) SSL2/RSA/RC4\-128/MD5 + (0x020080) SSL2/RSA/RC4\-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x040080) SSL2/RSA/RC2CBC40/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE\-CBC/MD5 + (0x000004) SSL3/RSA/RC4\-128/MD5 + (0x00ffe0) SSL3/RSA\-FIPS/3DES192EDE\-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE\-CBC/SHA + (0x00ffe1) SSL3/RSA\-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4\-40/MD5 + } + session\-id = { } + challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db + +0xcfe9 } +} +] +<additional records in same formats> +Server socket closed\&. +.fi +.if n \{\ +.RE +.\} +.SH "USAGE TIPS" +.PP +When SSL restarts a previous session, it makes use of cached information to do a partial handshake\&. If you wish to capture a full SSL handshake, restart the browser to clear the session id cache\&. +.PP +If you run the tool on a machine other than the SSL server to which you are trying to connect, the browser will complain that the host name you are trying to connect to is different from the certificate\&. If you are using the default BadCert callback, you can still connect through a dialog\&. If you are not using the default BadCert callback, the one you supply must allow for this possibility\&. +.SH "SEE ALSO" +.PP +The NSS Security Tools are also documented at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE +.IP " 2." 4 +http://www.mozilla.org/projects/security/pki/nss/ +.RS 4 +\%http://www.mozilla.org/projects/security/pki/nss/tools +.RE diff --git a/security/nss/doc/rst/legacy/nroff/vfychain.1 b/security/nss/doc/rst/legacy/nroff/vfychain.1 new file mode 100644 index 0000000000..4beba750d5 --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/vfychain.1 @@ -0,0 +1,169 @@ +'\" t +.\" Title: VFYCHAIN +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "VFYCHAIN" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +vfychain_ \- vfychain [options] [revocation options] certfile [[options] certfile] \&.\&.\&. +.SH "SYNOPSIS" +.HP \w'\fBvfychain\fR\ 'u +\fBvfychain\fR +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The verification Tool, +\fBvfychain\fR, verifies certificate chains\&. +\fBmodutil\fR +can add and delete PKCS #11 modules, change passwords on security databases, set defaults, list module contents, enable or disable slots, enable or disable FIPS 140\-2 compliance, and assign default providers for cryptographic operations\&. This tool can also create certificate, key, and module security database files\&. +.PP +The tasks associated with security module database management are part of a process that typically also involves managing key databases and certificate databases\&. +.SH "OPTIONS" +.PP +\fB\-a\fR +.RS 4 +the following certfile is base64 encoded +.RE +.PP +\fB\-b \fR \fIYYMMDDHHMMZ\fR +.RS 4 +Validate date (default: now) +.RE +.PP +\fB\-d \fR \fIdirectory\fR +.RS 4 +database directory +.RE +.PP +\fB\-f \fR +.RS 4 +Enable cert fetching from AIA URL +.RE +.PP +\fB\-o \fR \fIoid\fR +.RS 4 +Set policy OID for cert validation(Format OID\&.1\&.2\&.3) +.RE +.PP +\fB\-p \fR +.RS 4 +Use PKIX Library to validate certificate by calling: +.sp +* CERT_VerifyCertificate if specified once, +.sp +* CERT_PKIXVerifyCert if specified twice and more\&. +.RE +.PP +\fB\-r \fR +.RS 4 +Following certfile is raw binary DER (default) +.RE +.PP +\fB\-t\fR +.RS 4 +Following cert is explicitly trusted (overrides db trust) +.RE +.PP +\fB\-u \fR \fIusage\fR +.RS 4 +0=SSL client, 1=SSL server, 2=SSL StepUp, 3=SSL CA, 4=Email signer, 5=Email recipient, 6=Object signer, 9=ProtectedObjectSigner, 10=OCSP responder, 11=Any CA +.RE +.PP +\fB\-T \fR +.RS 4 +Trust both explicit trust anchors (\-t) and the database\&. (Without this option, the default is to only trust certificates marked \-t, if there are any, or to trust the database if there are certificates marked \-t\&.) +.RE +.PP +\fB\-v \fR +.RS 4 +Verbose mode\&. Prints root cert subject(double the argument for whole root cert info) +.RE +.PP +\fB\-w \fR \fIpassword\fR +.RS 4 +Database password +.RE +.PP +\fB\-W \fR \fIpwfile\fR +.RS 4 +Password file +.RE +.PP +.RS 4 +Revocation options for PKIX API (invoked with \-pp options) is a collection of the following flags: [\-g type [\-h flags] [\-m type [\-s flags]] \&.\&.\&.] \&.\&.\&. +.sp +Where: +.RE +.PP +\fB\-g \fR \fItest\-type\fR +.RS 4 +Sets status checking test type\&. Possible values are "leaf" or "chain" +.RE +.PP +\fB\-g \fR \fItest type\fR +.RS 4 +Sets status checking test type\&. Possible values are "leaf" or "chain"\&. +.RE +.PP +\fB\-h \fR \fItest flags\fR +.RS 4 +Sets revocation flags for the test type it follows\&. Possible flags: "testLocalInfoFirst" and "requireFreshInfo"\&. +.RE +.PP +\fB\-m \fR \fImethod type\fR +.RS 4 +Sets method type for the test type it follows\&. Possible types are "crl" and "ocsp"\&. +.RE +.PP +\fB\-s \fR \fImethod flags\fR +.RS 4 +Sets revocation flags for the method it follows\&. Possible types are "doNotUse", "forbidFetching", "ignoreDefaultSrc", "requireInfo" and "failIfNoInfo"\&. +.RE +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nroff/vfyserv.1 b/security/nss/doc/rst/legacy/nroff/vfyserv.1 new file mode 100644 index 0000000000..2983bc477c --- /dev/null +++ b/security/nss/doc/rst/legacy/nroff/vfyserv.1 @@ -0,0 +1,70 @@ +'\" t +.\" Title: VFYSERV +.\" Author: [see the "Authors" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 19 May 2021 +.\" Manual: NSS Security Tools +.\" Source: nss-tools +.\" Language: English +.\" +.TH "VFYSERV" "1" "19 May 2021" "nss-tools" "NSS Security Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +vfyserv_ \- TBD +.SH "SYNOPSIS" +.HP \w'\fBvfyserv\fR\ 'u +\fBvfyserv\fR +.SH "STATUS" +.PP +This documentation is still work in progress\&. Please contribute to the initial review in +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "DESCRIPTION" +.PP +The +\fBvfyserv \fR +tool verifies a certificate chain +.SH "OPTIONS" +.PP +.RS 4 +.sp +.RE +.SH "ADDITIONAL RESOURCES" +.PP +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&. +.PP +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto +.PP +IRC: Freenode at #dogtag\-pki +.SH "AUTHORS" +.PP +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&. +.PP +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&. +.SH "LICENSE" +.PP +Licensed under the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. +.SH "NOTES" +.IP " 1." 4 +Mozilla NSS bug 836477 +.RS 4 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477 +.RE diff --git a/security/nss/doc/rst/legacy/nss_3.11.10_release_notes.html/index.rst b/security/nss/doc/rst/legacy/nss_3.11.10_release_notes.html/index.rst new file mode 100644 index 0000000000..d31cce2ac5 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_3.11.10_release_notes.html/index.rst @@ -0,0 +1,174 @@ +.. _mozilla_projects_nss_nss_3_11_10_release_notes_html: + +NSS_3.11.10_release_notes.html +============================== + +.. _nss_3.11.10_release_notes: + +`NSS 3.11.10 Release Notes <#nss_3.11.10_release_notes>`__ +---------------------------------------------------------- + +.. container:: + +.. _2008-12-10: + +`2008-12-10 <#2008-12-10>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Newsgroup: <ahref="news: mozilla.dev.tech.crypto"="" + news.mozilla.org="">mozilla.dev.tech.crypto</ahref="news:> + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Introduction <#introduction>`__ + - `Distribution Information <#distribution>`__ + - `Bugs Fixed <#bugsfixed>`__ + - `Documentation <#docs>`__ + - `Compatibility <#compatibility>`__ + - `Feedback <#feedback>`__ + + -------------- + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services (NSS) 3.11.10 is a patch release for NSS 3.11. The bug fixes in NSS + 3.11.10 are described in the "`Bugs Fixed <#bugsfixed>`__" section below. + + -------------- + + + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The CVS tag for the NSS 3.11.10 release is NSS_3_11_10_RTM. NSS 3.11.10 requires `NSPR + 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/nspr471.html>`__. + See the `Documentation <#docs>`__ section for the build instructions. + NSS 3.11.10 source and binary distributions are also available on ftp.mozilla.org for secure + HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_11_10_RTM/src/. + - Binary distributions: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_11_10_RTM/. Both debug and + optimized builds are provided. Go to the subdirectory for your platform, DBG (debug) or OPT + (optimized), to get the tar.gz or zip file. The tar.gz or zip file expands to an nss-3.11.10 + directory containing three subdirectories: + + - include - NSS header files + - lib - NSS shared libraries + - bin - `NSS Tools <https://www.mozilla.org/projects/security/pki/nss/tools/>`__ and test + programs + + You also need to download the NSPR 4.7.1 binary distributions to get the NSPR 4.7.1 header files + and shared libraries, which NSS 3.11.10 requires. NSPR 4.7.1 binary distributions are in + https://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.7.1/. + + -------------- + +.. _bugs_fixed: + +`Bugs Fixed <#bugs_fixed>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following bugs have been fixed in NSS 3.11.10. + + - `Bug 291384 <https://bugzilla.mozilla.org/show_bug.cgi?id=291384>`__: certutil -K behavior + doesn't match usage + - `Bug 374247 <https://bugzilla.mozilla.org/show_bug.cgi?id=374247>`__: modutil -disable command + not disabling modules' slots + - `Bug 384459 <https://bugzilla.mozilla.org/show_bug.cgi?id=384459>`__: Certification path + validation fails when Authority Key Identifier extension contains key identifier + - `Bug 385946 <https://bugzilla.mozilla.org/show_bug.cgi?id=385946>`__: Can't import certificate + into cert database in FIPS mode (certutil). + - `Bug 387892 <https://bugzilla.mozilla.org/show_bug.cgi?id=387892>`__: Add Entrust root CA + certificate(s) to NSS + - `Bug 396999 <https://bugzilla.mozilla.org/show_bug.cgi?id=396999>`__: PK11_Authenticate + - `Bug 397478 <https://bugzilla.mozilla.org/show_bug.cgi?id=397478>`__: Lock from + ssl_InitSymWrapKeysLock not freed on selfserv shutdown. + - `Bug 397486 <https://bugzilla.mozilla.org/show_bug.cgi?id=397486>`__: Session cache locks not + freed on strsclnt shutdown. + - `Bug 398680 <https://bugzilla.mozilla.org/show_bug.cgi?id=398680>`__: assertion botch in + ssl3_RegisterServerHelloExtensionSender doing second handshake with SSL_ForceHandshake + - `Bug 403240 <https://bugzilla.mozilla.org/show_bug.cgi?id=403240>`__: threads hanging in + nss_InitLock + - `Bug 403888 <https://bugzilla.mozilla.org/show_bug.cgi?id=403888>`__: memory leak in + trustdomain.c + - `Bug 416067 <https://bugzilla.mozilla.org/show_bug.cgi?id=416067>`__: certutil -L -h token + doesn't report token authentication failure + - `Bug 417637 <https://bugzilla.mozilla.org/show_bug.cgi?id=417637>`__: tstclnt crashes if -p + option is not specified + - `Bug 421634 <https://bugzilla.mozilla.org/show_bug.cgi?id=421634>`__: Don't send an SNI Client + Hello extension bearing an IPv6 address + - `Bug 422918 <https://bugzilla.mozilla.org/show_bug.cgi?id=422918>`__: Add VeriSign Class 3 + Public Primary CA - G5 to NSS + - `Bug 424152 <https://bugzilla.mozilla.org/show_bug.cgi?id=424152>`__: Add thawte Primary Root + CA to NSS + - `Bug 424169 <https://bugzilla.mozilla.org/show_bug.cgi?id=424169>`__: Add GeoTrust Primary + Certification Authority root to NSS + - `Bug 425469 <https://bugzilla.mozilla.org/show_bug.cgi?id=425469>`__: Add multiple new roots: + Geotrust + - `Bug 426568 <https://bugzilla.mozilla.org/show_bug.cgi?id=426568>`__: Add COMODO Certification + Authority certificate to NSS + - `Bug 431381 <https://bugzilla.mozilla.org/show_bug.cgi?id=431381>`__: Add Network Solutions + Certificate Authority root to NSS + - `Bug 431621 <https://bugzilla.mozilla.org/show_bug.cgi?id=431621>`__: Add DigiNotar Root CA + root to NSS + - `Bug 431772 <https://bugzilla.mozilla.org/show_bug.cgi?id=431772>`__: add network solutions + and diginotar root certs to NSS + - `Bug 442912 <https://bugzilla.mozilla.org/show_bug.cgi?id=442912>`__: fix nssckbi version + number on 3.11 branch + - `Bug 443045 <https://bugzilla.mozilla.org/show_bug.cgi?id=443045>`__: Fix PK11_GenerateKeyPair + for ECC keys on the 3.11 branch + - `Bug 444850 <https://bugzilla.mozilla.org/show_bug.cgi?id=444850>`__: NSS misbehaves badly in + the presence of a disabled PKCS#11 slot + - `Bug 462948 <https://bugzilla.mozilla.org/show_bug.cgi?id=462948>`__: lint warnings for source + files that include keythi.h + + -------------- + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For a list of the primary NSS documentation pages on mozilla.org, see `NSS + Documentation <../index.html#Documentation>`__. New and revised documents available since the + release of NSS 3.9 include the following: + + - `Build Instructions for NSS 3.11.4 and above <../nss-3.11.4/nss-3.11.4-build.html>`__ + + -------------- + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS 3.11.10 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.11.10 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in `NSS Public Functions <../ref/nssfunctions.html>`__ will remain + compatible with future versions of the NSS shared libraries. + + -------------- + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_3.12.1_release_notes.html/index.rst b/security/nss/doc/rst/legacy/nss_3.12.1_release_notes.html/index.rst new file mode 100644 index 0000000000..b66767fb36 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_3.12.1_release_notes.html/index.rst @@ -0,0 +1,255 @@ +.. _mozilla_projects_nss_nss_3_12_1_release_notes_html: + +NSS_3.12.1_release_notes.html +============================= + +.. _nss_3.12.1_release_notes: + +`NSS 3.12.1 Release Notes <#nss_3.12.1_release_notes>`__ +-------------------------------------------------------- + +.. container:: + +.. _2008-09-05: + +`2008-09-05 <#2008-09-05>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Introduction <#introduction>`__ + - `Distribution Information <#distribution_information>`__ + - `New in NSS 3.12.1 <#new_in_nss_3.12.1>`__ + - `Bugs Fixed <#bugs_fixed>`__ + - `Documentation <#documentation>`__ + - `Compatibility <#compatibility>`__ + - `Feedback <#feedback>`__ + + -------------- + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services (NSS) 3.12.1 is a patch release for NSS 3.12. The bug fixes in NSS + 3.12.1 are described in the "`Bugs Fixed <#bugsfixed>`__" section below. + NSS 3.12.1 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + + -------------- + + + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The CVS tag for the NSS 3.12.1 release is NSS_3_12_1_RTM. NSS 3.12.1 requires `NSPR + 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/nspr471.html>`__. + See the `Documentation <#docs>`__ section for the build instructions. + NSS 3.12.1 source and binary distributions are also available on ftp.mozilla.org for secure HTTPS + download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_1_RTM/src/. + - Binary distributions: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_1_RTM/. Both debug and + optimized builds are provided. Go to the subdirectory for your platform, DBG (debug) or OPT + (optimized), to get the tar.gz or zip file. The tar.gz or zip file expands to an nss-3.12.1 + directory containing three subdirectories: + + - include - NSS header files + - lib - NSS shared libraries + - bin - `NSS Tools <https://www.mozilla.org/projects/security/pki/nss/tools/>`__ and test + programs + + You also need to download the NSPR 4.7.1 binary distributions to get the NSPR 4.7.1 header files + and shared libraries, which NSS 3.12.1 requires. NSPR 4.7.1 binary distributions are in + https://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.7.1/. + + -------------- + +.. _new_in_nss_3.12.1: + +`New in NSS 3.12.1 <#new_in_nss_3.12.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - New functions in the nss shared library: + + CERT_NameToAsciiInvertible (see cert.h) + Convert an CERTName into its RFC1485 encoded equivalent. + Returns a string that must be freed with PORT_Free(). + Caller chooses encoding rules. + CERT_EncodeSubjectKeyID (see cert.h) + Encode Certificate SKID (Subject Key ID) extension. + PK11_GetAllSlotsForCert (see pk11pub.h) + PK11_GetAllSlotsForCert returns all the slots that a given certificate + exists on, since it's possible for a cert to exist on more than one + PKCS#11 token. + + - Levels of standards conformance strictness for CERT_NameToAsciiInvertible (see certt.h) + + CERT_N2A_READABLE + (maximum human readability) + CERT_N2A_STRICT + (strict RFC compliance) + CERT_N2A_INVERTIBLE + (maximum invertibility) + + -------------- + +.. _bugs_fixed: + +`Bugs Fixed <#bugs_fixed>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following bugs have been fixed in NSS 3.12.1. + + - `Bug 67890 <https://bugzilla.mozilla.org/show_bug.cgi?id=67890>`__: create self-signed cert + with existing key that signed CSR + - `Bug 129303 <https://bugzilla.mozilla.org/show_bug.cgi?id=129303>`__: NSS needs to expose + interfaces to deal with multiple token sources of certs. + - `Bug 311432 <https://bugzilla.mozilla.org/show_bug.cgi?id=311432>`__: ECC's ECL_USE_FP code + (for Linux x86) fails pairwise consistency test + - `Bug 330622 <https://bugzilla.mozilla.org/show_bug.cgi?id=330622>`__: certutil's usage + messages incorrectly document certain options + - `Bug 330628 <https://bugzilla.mozilla.org/show_bug.cgi?id=330628>`__: coreconf/Linux.mk should + \_not\_ default to x86 but result in an error if host is not recognized + - `Bug 359302 <https://bugzilla.mozilla.org/show_bug.cgi?id=359302>`__: Remove the sslsample + code from NSS source tree + - `Bug 372241 <https://bugzilla.mozilla.org/show_bug.cgi?id=372241>`__: Need more versatile form + of CERT_NameToAscii + - `Bug 390296 <https://bugzilla.mozilla.org/show_bug.cgi?id=390296>`__: NSS ignores subject CN + even when SAN contains no dNSName + - `Bug 401928 <https://bugzilla.mozilla.org/show_bug.cgi?id=401928>`__: Support generalized + PKCS#5 v2 PBEs + - `Bug 403543 <https://bugzilla.mozilla.org/show_bug.cgi?id=403543>`__: pkix: need a way to + enable/disable AIA cert fetching + - `Bug 408847 <https://bugzilla.mozilla.org/show_bug.cgi?id=408847>`__: pkix_OcspChecker_Check + does not support specified responder (and given signercert) + - `Bug 414003 <https://bugzilla.mozilla.org/show_bug.cgi?id=414003>`__: Crash [[@ + CERT_DecodeCertPackage] sometimes with this testcase + - `Bug 415167 <https://bugzilla.mozilla.org/show_bug.cgi?id=415167>`__: Memory leak in certutil + - `Bug 417399 <https://bugzilla.mozilla.org/show_bug.cgi?id=417399>`__: Arena Allocation results + are not checked in pkix_pl_InfoAccess_ParseLocation + - `Bug 420644 <https://bugzilla.mozilla.org/show_bug.cgi?id=420644>`__: Improve SSL tracing of + key derivation + - `Bug 426886 <https://bugzilla.mozilla.org/show_bug.cgi?id=426886>`__: Use const char\* in + PK11_ImportCertForKey + - `Bug 428103 <https://bugzilla.mozilla.org/show_bug.cgi?id=428103>`__: CERT_EncodeSubjectKeyID + is not defined in any public header file + - `Bug 429716 <https://bugzilla.mozilla.org/show_bug.cgi?id=429716>`__: debug builds of libPKIX + unconditionally dump socket traffic to stdout + - `Bug 430368 <https://bugzilla.mozilla.org/show_bug.cgi?id=430368>`__: vfychain -t option is + undocumented + - `Bug 430369 <https://bugzilla.mozilla.org/show_bug.cgi?id=430369>`__: vfychain -o succeeds + even if -pp is not specified + - `Bug 430399 <https://bugzilla.mozilla.org/show_bug.cgi?id=430399>`__: vfychain -pp crashes + - `Bug 430405 <https://bugzilla.mozilla.org/show_bug.cgi?id=430405>`__: Error log is not + produced by CERT_PKIXVerifyCert + - `Bug 430743 <https://bugzilla.mozilla.org/show_bug.cgi?id=430743>`__: Update ssltap to + understand the TLS session ticket extension + - `Bug 430859 <https://bugzilla.mozilla.org/show_bug.cgi?id=430859>`__: PKIX: Policy mapping + fails verification with error invalid arguments + - `Bug 430875 <https://bugzilla.mozilla.org/show_bug.cgi?id=430875>`__: Document the policy for + the order of cipher suites in SSL_ImplementedCiphers. + - `Bug 430916 <https://bugzilla.mozilla.org/show_bug.cgi?id=430916>`__: add sustaining asserts + - `Bug 431805 <https://bugzilla.mozilla.org/show_bug.cgi?id=431805>`__: leak in + NSSArena_Destroy() + - `Bug 431929 <https://bugzilla.mozilla.org/show_bug.cgi?id=431929>`__: Memory leaks on error + paths in devutil.c + - `Bug 432303 <https://bugzilla.mozilla.org/show_bug.cgi?id=432303>`__: Replace PKIX_PL_Memcpy + with memcpy + - `Bug 433177 <https://bugzilla.mozilla.org/show_bug.cgi?id=433177>`__: Fix the GCC compiler + warnings in lib/util and lib/freebl + - `Bug 433437 <https://bugzilla.mozilla.org/show_bug.cgi?id=433437>`__: vfychain ignores the -a + option + - `Bug 433594 <https://bugzilla.mozilla.org/show_bug.cgi?id=433594>`__: Crash destroying OCSP + Cert ID [[@ CERT_DestroyOCSPCertID ] + - `Bug 434099 <https://bugzilla.mozilla.org/show_bug.cgi?id=434099>`__: NSS relies on unchecked + PKCS#11 object attribute values + - `Bug 434187 <https://bugzilla.mozilla.org/show_bug.cgi?id=434187>`__: Fix the GCC compiler + warnings in nss/lib + - `Bug 434398 <https://bugzilla.mozilla.org/show_bug.cgi?id=434398>`__: libPKIX cannot find + issuer cert immediately after checking it with OCSP + - `Bug 434808 <https://bugzilla.mozilla.org/show_bug.cgi?id=434808>`__: certutil -B deadlock + when importing two or more roots + - `Bug 434860 <https://bugzilla.mozilla.org/show_bug.cgi?id=434860>`__: Coverity 1150 - dead + code in ocsp_CreateCertID + - `Bug 436428 <https://bugzilla.mozilla.org/show_bug.cgi?id=436428>`__: remove unneeded assert + from sec_PKCS7EncryptLength + - `Bug 436430 <https://bugzilla.mozilla.org/show_bug.cgi?id=436430>`__: Make NSS public headers + compilable with NO_NSPR_10_SUPPORT defined + - `Bug 436577 <https://bugzilla.mozilla.org/show_bug.cgi?id=436577>`__: uninitialized variable + in sec_pkcs5CreateAlgorithmID + - `Bug 438685 <https://bugzilla.mozilla.org/show_bug.cgi?id=438685>`__: libpkix doesn't try all + the issuers in a bridge with multiple certs + - `Bug 438876 <https://bugzilla.mozilla.org/show_bug.cgi?id=438876>`__: signtool is still using + static libraries. + - `Bug 439123 <https://bugzilla.mozilla.org/show_bug.cgi?id=439123>`__: Assertion failure in + libpkix at shutdown + - `Bug 440062 <https://bugzilla.mozilla.org/show_bug.cgi?id=440062>`__: incorrect list element + count in PKIX_List_AppendItem function + - `Bug 442618 <https://bugzilla.mozilla.org/show_bug.cgi?id=442618>`__: Eliminate dead function + CERT_CertPackageType + - `Bug 443755 <https://bugzilla.mozilla.org/show_bug.cgi?id=443755>`__: Extra semicolon in + PKM_TLSKeyAndMacDerive makes conditional code unconditional + - `Bug 443760 <https://bugzilla.mozilla.org/show_bug.cgi?id=443760>`__: Extra semicolon in + SeqDatabase makes static analysis tool suspicious + - `Bug 448323 <https://bugzilla.mozilla.org/show_bug.cgi?id=448323>`__: certutil -K doesn't + report the token and slot names for found keys + - `Bug 448324 <https://bugzilla.mozilla.org/show_bug.cgi?id=448324>`__: ocsp checker returns + incorrect error code on request with invalid signing cert + - `Bug 449146 <https://bugzilla.mozilla.org/show_bug.cgi?id=449146>`__: Remove dead libsec + function declarations + - `Bug 453227 <https://bugzilla.mozilla.org/show_bug.cgi?id=453227>`__: installation of + PEM-encoded certificate without trailing newline fails + + -------------- + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For a list of the primary NSS documentation pages on mozilla.org, see `NSS + Documentation <../index.html#Documentation>`__. New and revised documents available since the + release of NSS 3.11 include the following: + + - `Build Instructions for NSS 3.11.4 and above <../nss-3.11.4/nss-3.11.4-build.html>`__ + - `NSS Shared DB <http://wiki.mozilla.org/NSS_Shared_DB>`__ + + -------------- + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS 3.12.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.12.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in `NSS Public Functions <../ref/nssfunctions.html>`__ will remain + compatible with future versions of the NSS shared libraries. + + -------------- + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_3.12.2_release_notes.html/index.rst b/security/nss/doc/rst/legacy/nss_3.12.2_release_notes.html/index.rst new file mode 100644 index 0000000000..209bd2ef12 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_3.12.2_release_notes.html/index.rst @@ -0,0 +1,217 @@ +.. _mozilla_projects_nss_nss_3_12_2_release_notes_html: + +NSS_3.12.2_release_notes.html +============================= + +.. _nss_3.12.2_release_notes: + +`NSS 3.12.2 Release Notes <#nss_3.12.2_release_notes>`__ +-------------------------------------------------------- + +.. container:: + +.. _2008-10-20: + +`2008-10-20 <#2008-10-20>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Introduction <#introduction>`__ + - `Distribution Information <#distribution_information>`__ + - `New in NSS 3.12.2 <#new_in_nss_3.12.2>`__ + - `Bugs Fixed <#bugs_fixed>`__ + - `Documentation <#documentation>`__ + - `Compatibility <#compatibility>`__ + - `Feedback <#feedback>`__ + + -------------- + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services (NSS) 3.12.2 is a patch release for NSS 3.12. The bug fixes in NSS + 3.12.2 are described in the "`Bugs Fixed <#bugs_fixed>`__" section below. + NSS 3.12.2 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + + -------------- + + + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The CVS tag for the NSS 3.12.2 release is NSS_3_12_2_RTM. NSS 3.12.2 requires `NSPR + 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/nspr471.html>`__. + See the `Documentation <#documentation>`__ section for the build instructions. + NSS 3.12.2 source and binary distributions are also available on ftp.mozilla.org for secure HTTPS + download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_2_RTM/src/. + - Binary distributions: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_2_RTM/. Both debug and + optimized builds are provided. Go to the subdirectory for your platform, DBG (debug) or OPT + (optimized), to get the tar.gz or zip file. The tar.gz or zip file expands to an nss-3.12.2 + directory containing three subdirectories: + + - include - NSS header files + - lib - NSS shared libraries + - bin< - `NSS Tools <https://www.mozilla.org/projects/security/pki/nss/tools/>`__ and test + programs + + You also need to download the NSPR 4.7.1 binary distributions to get the NSPR 4.7.1 header files + and shared libraries, which NSS 3.12.2 requires. NSPR 4.7.1 binary distributions are in + https://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.7.1/. + + -------------- + +.. _new_in_nss_3.12.2: + +`New in NSS 3.12.2 <#new_in_nss_3.12.2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - New functions in the nss shared library: + + - SEC_PKCS12AddCertOrChainAndKey (see p12.h) + + - New PKCS11 errors (see secerr.h) + + - SEC_ERROR_PKCS11_GENERAL_ERROR + - SEC_ERROR_PKCS11_FUNCTION_FAILED + - SEC_ERROR_PKCS11_DEVICE_ERROR + + -------------- + +.. _bugs_fixed: + +`Bugs Fixed <#bugs_fixed>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following bugs have been fixed in NSS 3.12.2. + + - `Bug 200704 <https://bugzilla.mozilla.org/show_bug.cgi?id=200704>`__: PKCS11: invalid session + handle 0 + - `Bug 205434 <https://bugzilla.mozilla.org/show_bug.cgi?id=205434>`__: Fully implement new + libPKIX cert verification API from bug 294531 + - `Bug 302670 <https://bugzilla.mozilla.org/show_bug.cgi?id=302670>`__: Use the installed + libz.so where available + - `Bug 305693 <https://bugzilla.mozilla.org/show_bug.cgi?id=305693>`__: shlibsign generates PQG + for every run + - `Bug 311483 <https://bugzilla.mozilla.org/show_bug.cgi?id=311483>`__: exposing + includeCertChain as a parameter to SEC_PKCS12AddCertAndKey + - `Bug 390527 <https://bugzilla.mozilla.org/show_bug.cgi?id=390527>`__: get rid of pkixErrorMsg + variable in PKIX_Error + - `Bug 391560 <https://bugzilla.mozilla.org/show_bug.cgi?id=391560>`__: libpkix does not + consistently return PKIX_ValidateNode tree that truly represent failure reasons + - `Bug 408260 <https://bugzilla.mozilla.org/show_bug.cgi?id=408260>`__: certutil usage doesn't + give enough information about trust arguments + - `Bug 412311 <https://bugzilla.mozilla.org/show_bug.cgi?id=412311>`__: Replace + PR_INTERVAL_NO_WAIT with PR_INTERVAL_NO_TIMEOUT in client initialization calls + - `Bug 423839 <https://bugzilla.mozilla.org/show_bug.cgi?id=423839>`__: Add multiple PKCS#11 + token password command line option to NSS tools. + - `Bug 432260 <https://bugzilla.mozilla.org/show_bug.cgi?id=432260>`__: [[@ + pkix_pl_HttpDefaultClient_HdrCheckComplete - PKIX_PL_Memcpy] crashes when there is no + content-length header in the http response + - `Bug 436599 <https://bugzilla.mozilla.org/show_bug.cgi?id=436599>`__: PKIX: AIA extension is + not used in some Bridge CA / known certs configuration + - `Bug 437804 <https://bugzilla.mozilla.org/show_bug.cgi?id=437804>`__: certutil -R for cert + renewal should derive the subject from the cert if none is specified. + - `Bug 444974 <https://bugzilla.mozilla.org/show_bug.cgi?id=444974>`__: Crash upon reinsertion + of E-Identity smartcard + - `Bug 447563 <https://bugzilla.mozilla.org/show_bug.cgi?id=447563>`__: modutil -add prints no + error explanation on failure + - `Bug 448431 <https://bugzilla.mozilla.org/show_bug.cgi?id=448431>`__: PK11_CreateMergeLog() + declaration causes gcc warning when compiling with -Wstrict-prototypes + - `Bug 449334 <https://bugzilla.mozilla.org/show_bug.cgi?id=449334>`__: pk12util has duplicate + options letters + - `Bug 449725 <https://bugzilla.mozilla.org/show_bug.cgi?id=449725>`__: signver is still using + static libraries. + - `Bug 450427 <https://bugzilla.mozilla.org/show_bug.cgi?id=450427>`__: Add COMODO ECC + Certification Authority certificate to NSS + - `Bug 450536 <https://bugzilla.mozilla.org/show_bug.cgi?id=450536>`__: Remove obsolete XP_MAC + code + - `Bug 451024 <https://bugzilla.mozilla.org/show_bug.cgi?id=451024>`__: certutil.exe crashes + with Segmentation fault inside PR_Cleanup + - `Bug 451927 <https://bugzilla.mozilla.org/show_bug.cgi?id=451927>`__: + security/coreconf/WINNT6.0.mk has invalid defines + - `Bug 452751 <https://bugzilla.mozilla.org/show_bug.cgi?id=452751>`__: Slot leak in + PK11_FindSlotsByNames + - `Bug 452865 <https://bugzilla.mozilla.org/show_bug.cgi?id=452865>`__: Remove obsolete linker + flags needed when libnss3 was linked with libsoftokn3 + - `Bug 454961 <https://bugzilla.mozilla.org/show_bug.cgi?id=454961>`__: Fix the implementation + and use of pr_fgets in signtool + - `Bug 455348 <https://bugzilla.mozilla.org/show_bug.cgi?id=455348>`__: Change hyphens to + underscores in DEBUG_$(shell whoami). + - `Bug 455424 <https://bugzilla.mozilla.org/show_bug.cgi?id=455424>`__: nssilckt.h defines the + enumeration constant 'Lock' + - `Bug 456036 <https://bugzilla.mozilla.org/show_bug.cgi?id=456036>`__: Stubs for deprecated + functions in lib/certdb/stanpcertdb.c should set the PR_NOT_IMPLEMENTED_ERROR error. + - `Bug 456854 <https://bugzilla.mozilla.org/show_bug.cgi?id=456854>`__: CERT_DecodeCertPackage + does not set NSPR error code upon error + - `Bug 457980 <https://bugzilla.mozilla.org/show_bug.cgi?id=457980>`__: hundreds of kilobytes of + useless strings in libPKIX + - `Bug 457984 <https://bugzilla.mozilla.org/show_bug.cgi?id=457984>`__: Enable PKCS11 module + logging in optimized builds + - `Bug 458905 <https://bugzilla.mozilla.org/show_bug.cgi?id=458905>`__: Memory leaks in PKIX + bridge certificates. + - `Bug 459231 <https://bugzilla.mozilla.org/show_bug.cgi?id=459231>`__: Memory leak in cert + fetching - AIA extension. + - `Bug 459248 <https://bugzilla.mozilla.org/show_bug.cgi?id=459248>`__: Support Intel AES + extensions. + - `Bug 459359 <https://bugzilla.mozilla.org/show_bug.cgi?id=459359>`__: ForwardBuilderState + object is leaked when AIA path incorrect + - `Bug 459481 <https://bugzilla.mozilla.org/show_bug.cgi?id=459481>`__: NSS build problem with + GCC 3.4.6 on OS/2 + + -------------- + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For a list of the primary NSS documentation pages on mozilla.org, see `NSS + Documentation <../index.html#Documentation>`__. New and revised documents available since the + release of NSS 3.11 include the following: + + - `Build Instructions for NSS 3.11.4 and above <../nss-3.11.4/nss-3.11.4-build.html>`__ + - `NSS Shared DB <http://wiki.mozilla.org/NSS_Shared_DB>`__ + + -------------- + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS 3.12.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.12.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in `NSS Public Functions <../ref/nssfunctions.html>`__ will remain + compatible with future versions of the NSS shared libraries. + + -------------- + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_3.12_release_notes.html/index.rst b/security/nss/doc/rst/legacy/nss_3.12_release_notes.html/index.rst new file mode 100644 index 0000000000..6b01e17a35 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_3.12_release_notes.html/index.rst @@ -0,0 +1,919 @@ +.. _mozilla_projects_nss_nss_3_12_release_notes_html: + +NSS_3.12_release_notes.html +=========================== + +.. _nss_3.12_release_notes: + +`NSS 3.12 Release Notes <#nss_3.12_release_notes>`__ +---------------------------------------------------- + +.. container:: + +.. _17_june_2008: + +`17 June 2008 <#17_june_2008>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Introduction <#introduction>`__ + - `Distribution Information <#distribution_information>`__ + - `New in NSS 3.12 <#new_in_nss_3.12>`__ + - `Bugs Fixed <#bugs_fixed>`__ + - `Documentation <#documentation>`__ + - `Compatibility <#compatibility>`__ + - `Feedback <#feedback>`__ + + -------------- + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services (NSS) 3.12 is a minor release with the following new features: + + - SQLite-Based Shareable Certificate and Key Databases + - libpkix: an RFC 3280 Compliant Certificate Path Validation Library + - Camellia cipher support + - TLS session ticket extension (RFC 5077) + + NSS 3.12 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + Note: Firefox 3 uses NSS 3.12, but not the new SQLite-based shareable certificate and key + databases. We missed the deadline to enable that feature in Firefox 3. + + -------------- + + + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The CVS tag for the NSS 3.12 release is NSS_3_12_RTM. NSS 3.12 requires `NSPR + 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/nspr471.html>`__. + See the `Documentation <#docs>`__ section for the build instructions. + NSS 3.12 source and binary distributions are also available on ftp.mozilla.org for secure HTTPS + download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_RTM/src/. + - Binary distributions: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_RTM/. Both debug and + optimized builds are provided. Go to the subdirectory for your platform, DBG (debug) or OPT + (optimized), to get the tar.gz or zip file. The tar.gz or zip file expands to an nss-3.12 + directory containing three subdirectories: + + - include - NSS header files + - lib - NSS shared libraries + - bin - `NSS Tools <https://www.mozilla.org/projects/security/pki/nss/tools/>`__ and test + programs + + You also need to download the NSPR 4.7.1 binary distributions to get the NSPR 4.7.1 header files + and shared libraries, which NSS 3.12 requires. NSPR 4.7.1 binary distributions are in + https://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.7.1/. + NSS 3.12 libraries have the following versions: + + - sqlite3: 3.3.17 + - nssckbi: 1.70 + - softokn3 and freebl3: 3.12.0.3 + - other NSS libraries: 3.12.0.3 + + -------------- + +.. _new_in_nss_3.12: + +`New in NSS 3.12 <#new_in_nss_3.12>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - 3 new shared library are shipped with NSS 3.12: + + - nssutil + - sqlite + - nssdbm + + - 1 new include file is shipped with NSS3.12: + + - utilrename.h + + - New functions in the nss shared library: + + - CERT_CheckNameSpace (see cert.h) + - CERT_EncodeCertPoliciesExtension (see cert.h) + - CERT_EncodeInfoAccessExtension (see cert.h) + - CERT_EncodeInhibitAnyExtension (see cert.h) + - CERT_EncodeNoticeReference (see cert.h) + - CERT_EncodePolicyConstraintsExtension (see cert.h) + - CERT_EncodePolicyMappingExtension (see cert.h) + - CERT_EncodeSubjectKeyID (see certdb/cert.h) + - CERT_EncodeUserNotice (see cert.h) + - CERT_FindCRLEntryReasonExten (see cert.h) + - CERT_FindCRLNumberExten (see cert.h) + - CERT_FindNameConstraintsExten (see cert.h) + - CERT_GetClassicOCSPDisabledPolicy (see cert.h) + - CERT_GetClassicOCSPEnabledHardFailurePolicy (see cert.h) + - CERT_GetClassicOCSPEnabledSoftFailurePolicy (see cert.h) + - CERT_GetPKIXVerifyNistRevocationPolicy (see cert.h) + - CERT_GetUsePKIXForValidation (see cert.h) + - CERT_GetValidDNSPatternsFromCert (see cert.h) + - CERT_NewTempCertificate (see cert.h) + - CERT_SetOCSPTimeout (see certhigh/ocsp.h) + - CERT_SetUsePKIXForValidation (see cert.h) + - CERT_PKIXVerifyCert (see cert.h) + - HASH_GetType (see sechash.h) + - NSS_InitWithMerge (see nss.h) + - PK11_CreateMergeLog (see pk11pub.h) + - PK11_CreateGenericObject (see pk11pub.h) + - PK11_CreatePBEV2AlgorithmID (see pk11pub.h) + - PK11_DestroyMergeLog (see pk11pub.h) + - PK11_GenerateKeyPairWithOpFlags (see pk11pub.h) + - PK11_GetPBECryptoMechanism (see pk11pub.h) + - PK11_IsRemovable (see pk11pub.h) + - PK11_MergeTokens (see pk11pub.h) + - PK11_WriteRawAttribute (see pk11pub.h) + - SECKEY_ECParamsToBasePointOrderLen (see keyhi.h) + - SECKEY_ECParamsToKeySize (see keyhi.h) + - SECMOD_DeleteModuleEx (see secmod.h) + - SEC_GetRegisteredHttpClient (see ocsp.h) + - SEC_PKCS5IsAlgorithmPBEAlgTag (see secpkcs5.h) + - VFY_CreateContextDirect (see cryptohi.h) + - VFY_CreateContextWithAlgorithmID (see cryptohi.h) + - VFY_VerifyDataDirect (see cryptohi.h) + - VFY_VerifyDataWithAlgorithmID (see cryptohi.h) + - VFY_VerifyDigestDirect (see cryptohi.h) + - VFY_VerifyDigestWithAlgorithmID (see cryptohi.h) + + - New macros for Camellia support (see blapit.h): + + - NSS_CAMELLIA + - NSS_CAMELLIA_CBC + - CAMELLIA_BLOCK_SIZE + + - New macros for RSA (see blapit.h): + + - RSA_MAX_MODULUS_BITS + - RSA_MAX_EXPONENT_BITS + + - New macros in certt.h: + + - X.509 v3 + + - KU_ENCIPHER_ONLY + - CERT_MAX_SERIAL_NUMBER_BYTES + - CERT_MAX_DN_BYTES + + - PKIX + + - CERT_REV_M_DO_NOT_TEST_USING_THIS_METHOD + - CERT_REV_M_TEST_USING_THIS_METHOD + - CERT_REV_M_ALLOW_NETWORK_FETCHING + - CERT_REV_M_FORBID_NETWORK_FETCHING + - CERT_REV_M_ALLOW_IMPLICIT_DEFAULT_SOURCE + - CERT_REV_M_IGNORE_IMPLICIT_DEFAULT_SOURCE + - CERT_REV_M_SKIP_TEST_ON_MISSING_SOURCE + - CERT_REV_M_REQUIRE_INFO_ON_MISSING_SOURCE + - CERT_REV_M_IGNORE_MISSING_FRESH_INFO + - CERT_REV_M_FAIL_ON_MISSING_FRESH_INFO + - CERT_REV_M_STOP_TESTING_ON_FRESH_INFO + - CERT_REV_M_CONTINUE_TESTING_ON_FRESH_INFO + - CERT_REV_MI_TEST_EACH_METHOD_SEPARATELY + - CERT_REV_MI_TEST_ALL_LOCAL_INFORMATION_FIRST + - CERT_REV_MI_NO_OVERALL_INFO_REQUIREMENT + - CERT_REV_MI_REQUIRE_SOME_FRESH_INFO_AVAILABLE + - CERT_POLICY_FLAG_NO_MAPPING + - CERT_POLICY_FLAG_EXPLICIT + - CERT_POLICY_FLAG_NO_ANY + - CERT_ENABLE_LDAP_FETCH + - CERT_ENABLE_HTTP_FETCH + + - New macro in utilrename.h: + + - SMIME_AES_CBC_128 + + - The nssckbi PKCS #11 module's version changed to 1.70. + - In pkcs11n.h, all the \_NETSCAPE\_ macros are renamed with \_NSS\_ + + - For example, CKO_NETSCAPE_CRL becomes CKO_NSS_CRL. + + - New for PKCS #11 (see pkcs11t.h for details): + + - CKK: Keys + + - CKK_CAMELLIA + + - CKM: Mechanisms + + - CKM_SHA224_RSA_PKCS + - CKM_SHA224_RSA_PKCS_PSS + - CKM_SHA224 + - CKM_SHA224_HMAC + - CKM_SHA224_HMAC_GENERAL + - CKM_SHA224_KEY_DERIVATION + - CKM_CAMELLIA_KEY_GEN + - CKM_CAMELLIA_ECB + - CKM_CAMELLIA_CBC + - CKM_CAMELLIA_MAC + - CKM_CAMELLIA_MAC_GENERAL + - CKM_CAMELLIA_CBC_PAD + - CKM_CAMELLIA_ECB_ENCRYPT_DATA + - CKM_CAMELLIA_CBC_ENCRYPT_DATA + + - CKG: MFGs + + - CKG_MGF1_SHA224 + + - New error codes (see secerr.h): + + - SEC_ERROR_NOT_INITIALIZED + - SEC_ERROR_TOKEN_NOT_LOGGED_IN + - SEC_ERROR_OCSP_RESPONDER_CERT_INVALID + - SEC_ERROR_OCSP_BAD_SIGNATURE + - SEC_ERROR_OUT_OF_SEARCH_LIMITS + - SEC_ERROR_INVALID_POLICY_MAPPING + - SEC_ERROR_POLICY_VALIDATION_FAILED + - SEC_ERROR_UNKNOWN_AIA_LOCATION_TYPE + - SEC_ERROR_BAD_HTTP_RESPONSE + - SEC_ERROR_BAD_LDAP_RESPONSE + - SEC_ERROR_FAILED_TO_ENCODE_DATA + - SEC_ERROR_BAD_INFO_ACCESS_LOCATION + - SEC_ERROR_LIBPKIX_INTERNAL + + - New mechanism flags (see secmod.h) + + - PUBLIC_MECH_AES_FLAG + - PUBLIC_MECH_SHA256_FLAG + - PUBLIC_MECH_SHA512_FLAG + - PUBLIC_MECH_CAMELLIA_FLAG + + - New OIDs (see secoidt.h) + + - new EC Signature oids + + - SEC_OID_ANSIX962_ECDSA_SIGNATURE_RECOMMENDED_DIGEST + - SEC_OID_ANSIX962_ECDSA_SIGNATURE_SPECIFIED_DIGEST + - SEC_OID_ANSIX962_ECDSA_SHA224_SIGNATURE + - SEC_OID_ANSIX962_ECDSA_SHA256_SIGNATURE + - SEC_OID_ANSIX962_ECDSA_SHA384_SIGNATURE + - SEC_OID_ANSIX962_ECDSA_SHA512_SIGNATURE + + - More id-ce and id-pe OIDs from RFC 3280 + + - SEC_OID_X509_HOLD_INSTRUCTION_CODE + - SEC_OID_X509_DELTA_CRL_INDICATOR + - SEC_OID_X509_ISSUING_DISTRIBUTION_POINT + - SEC_OID_X509_CERT_ISSUER + - SEC_OID_X509_FRESHEST_CRL + - SEC_OID_X509_INHIBIT_ANY_POLICY + - SEC_OID_X509_SUBJECT_INFO_ACCESS + + - Camellia OIDs (RFC3657) + + - SEC_OID_CAMELLIA_128_CBC + - SEC_OID_CAMELLIA_192_CBC + - SEC_OID_CAMELLIA_256_CBC + + - PKCS 5 V2 OIDS + + - SEC_OID_PKCS5_PBKDF2 + - SEC_OID_PKCS5_PBES2 + - SEC_OID_PKCS5_PBMAC1 + - SEC_OID_HMAC_SHA1 + - SEC_OID_HMAC_SHA224 + - SEC_OID_HMAC_SHA256 + - SEC_OID_HMAC_SHA384 + - SEC_OID_HMAC_SHA512 + - SEC_OID_PKIX_TIMESTAMPING + - SEC_OID_PKIX_CA_REPOSITORY + - SEC_OID_ISO_SHA1_WITH_RSA_SIGNATURE + + - Changed OIDs (see secoidt.h) + + - SEC_OID_PKCS12_KEY_USAGE changed to SEC_OID_BOGUS_KEY_USAGE + - SEC_OID_ANSIX962_ECDSA_SIGNATURE_WITH_SHA1_DIGEST changed to + SEC_OID_ANSIX962_ECDSA_SHA1_SIGNATURE + - Note: SEC_OID_ANSIX962_ECDSA_SIGNATURE_WITH_SHA1_DIGEST is also kept for compatibility + reasons. + + - TLS Session ticket extension (off by default) + + - See SSL_ENABLE_SESSION_TICKETS in ssl.h + + - New SSL error codes (see sslerr.h) + + - SSL_ERROR_UNSUPPORTED_EXTENSION_ALERT + - SSL_ERROR_CERTIFICATE_UNOBTAINABLE_ALERT + - SSL_ERROR_UNRECOGNIZED_NAME_ALERT + - SSL_ERROR_BAD_CERT_STATUS_RESPONSE_ALERT + - SSL_ERROR_BAD_CERT_HASH_VALUE_ALERT + - SSL_ERROR_RX_UNEXPECTED_NEW_SESSION_TICKET + - SSL_ERROR_RX_MALFORMED_NEW_SESSION_TICKET + + - New TLS cipher suites (see sslproto.h): + + - TLS_RSA_WITH_CAMELLIA_128_CBC_SHA + - TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA + - TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA + - TLS_RSA_WITH_CAMELLIA_256_CBC_SHA + - TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA + - TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA + + - Note: the following TLS cipher suites are declared but are not yet implemented: + + - TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA + - TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA + - TLS_DH_ANON_WITH_CAMELLIA_128_CBC_SHA + - TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA + - TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA + - TLS_DH_ANON_WITH_CAMELLIA_256_CBC_SHA + - TLS_ECDH_anon_WITH_NULL_SHA + - TLS_ECDH_anon_WITH_RC4_128_SHA + - TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA + - TLS_ECDH_anon_WITH_AES_128_CBC_SHA + - TLS_ECDH_anon_WITH_AES_256_CBC_SHA + + -------------- + +.. _bugs_fixed: + +`Bugs Fixed <#bugs_fixed>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following bugs have been fixed in NSS 3.12. + + - `Bug 354403 <https://bugzilla.mozilla.org/show_bug.cgi?id=354403>`__: nssList_CreateIterator + returns pointer to a freed memory if the function fails to allocate a lock + - `Bug 399236 <https://bugzilla.mozilla.org/show_bug.cgi?id=399236>`__: pkix wrapper must print + debug output into stderr + - `Bug 399300 <https://bugzilla.mozilla.org/show_bug.cgi?id=399300>`__: PKIX error results not + freed after use. + - `Bug 414985 <https://bugzilla.mozilla.org/show_bug.cgi?id=414985>`__: Crash in + pkix_pl_OcspRequest_Destroy + - `Bug 421870 <https://bugzilla.mozilla.org/show_bug.cgi?id=421870>`__: Strsclnt crashed in PKIX + tests. + - `Bug 429388 <https://bugzilla.mozilla.org/show_bug.cgi?id=429388>`__: vfychain.main leaks + memory + - `Bug 396044 <https://bugzilla.mozilla.org/show_bug.cgi?id=396044>`__: Warning: usage of + uninitialized variable in ckfw/object.c(174) + - `Bug 396045 <https://bugzilla.mozilla.org/show_bug.cgi?id=396045>`__: Warning: usage of + uninitialized variable in ckfw/mechanism.c(719) + - `Bug 401986 <https://bugzilla.mozilla.org/show_bug.cgi?id=401986>`__: Mac OS X leopard build + failure in legacydb + - `Bug 325805 <https://bugzilla.mozilla.org/show_bug.cgi?id=325805>`__: diff considers + mozilla/security/nss/cmd/pk11util/scripts/pkey a binary file + - `Bug 385151 <https://bugzilla.mozilla.org/show_bug.cgi?id=385151>`__: Remove the link time + dependency from NSS to Softoken + - `Bug 387892 <https://bugzilla.mozilla.org/show_bug.cgi?id=387892>`__: Add Entrust root CA + certificate(s) to NSS + - `Bug 433386 <https://bugzilla.mozilla.org/show_bug.cgi?id=433386>`__: when system clock is off + by more than two days, OSCP check fails, can result in crash if user tries to view certificate + [[@ SECITEM_CompareItem_Util] [[@ memcmp] + - `Bug 396256 <https://bugzilla.mozilla.org/show_bug.cgi?id=396256>`__: certutil and pp do not + print all the GeneralNames in a CRLDP extension + - `Bug 398019 <https://bugzilla.mozilla.org/show_bug.cgi?id=398019>`__: correct confusing and + erroneous comments in DER_AsciiToTime + - `Bug 422866 <https://bugzilla.mozilla.org/show_bug.cgi?id=422866>`__: vfychain -pp command + crashes in NSS_shutdown + - `Bug 345779 <https://bugzilla.mozilla.org/show_bug.cgi?id=345779>`__: Useless assignment + statements in ec_GF2m_pt_mul_mont + - `Bug 349011 <https://bugzilla.mozilla.org/show_bug.cgi?id=349011>`__: please stop exporting + these crmf\_ symbols + - `Bug 397178 <https://bugzilla.mozilla.org/show_bug.cgi?id=397178>`__: Crash when entering + chrome://pippki/content/resetpassword.xul in URL bar + - `Bug 403822 <https://bugzilla.mozilla.org/show_bug.cgi?id=403822>`__: + pkix_pl_OcspRequest_Create can leave some members uninitialized + - `Bug 403910 <https://bugzilla.mozilla.org/show_bug.cgi?id=403910>`__: + CERT_FindUserCertByUsage() returns wrong certificate if multiple certs with same subject + available + - `Bug 404919 <https://bugzilla.mozilla.org/show_bug.cgi?id=404919>`__: memory leak in + sftkdb_ReadSecmodDB() (sftkmod.c) + - `Bug 406120 <https://bugzilla.mozilla.org/show_bug.cgi?id=406120>`__: Allow application to + specify OCSP timeout + - `Bug 361025 <https://bugzilla.mozilla.org/show_bug.cgi?id=361025>`__: Support for Camellia + Cipher Suites to TLS RFC4132 + - `Bug 376417 <https://bugzilla.mozilla.org/show_bug.cgi?id=376417>`__: PK11_GenerateKeyPair + needs to get the key usage from the caller. + - `Bug 391291 <https://bugzilla.mozilla.org/show_bug.cgi?id=391291>`__: Shared Database + Integrity checks not yet implemented. + - `Bug 391292 <https://bugzilla.mozilla.org/show_bug.cgi?id=391292>`__: Shared Database + implementation slow + - `Bug 391294 <https://bugzilla.mozilla.org/show_bug.cgi?id=391294>`__: Shared Database + implementation really slow on network file systems + - `Bug 392521 <https://bugzilla.mozilla.org/show_bug.cgi?id=392521>`__: Automatic shared db + update fails if user opens database R/W but never supplies a password + - `Bug 392522 <https://bugzilla.mozilla.org/show_bug.cgi?id=392522>`__: Integrity hashes must be + updated when passwords are changed. + - `Bug 401610 <https://bugzilla.mozilla.org/show_bug.cgi?id=401610>`__: Shared DB fails on IOPR + tests + - `Bug 388120 <https://bugzilla.mozilla.org/show_bug.cgi?id=388120>`__: build error due to + SEC_BEGIN_PROTOS / SEC_END_PROTOS are undefined + - `Bug 415264 <https://bugzilla.mozilla.org/show_bug.cgi?id=415264>`__: Make Security use of new + NSPR rotate macros + - `Bug 317052 <https://bugzilla.mozilla.org/show_bug.cgi?id=317052>`__: lib/base/whatnspr.c is + obsolete + - `Bug 317323 <https://bugzilla.mozilla.org/show_bug.cgi?id=317323>`__: Set NSPR31_LIB_PREFIX to + empty explicitly for WIN95 and WINCE builds + - `Bug 320336 <https://bugzilla.mozilla.org/show_bug.cgi?id=320336>`__: SECITEM_AllocItem + returns a non-NULL pointer if the allocation of its 'data' buffer fails + - `Bug 327529 <https://bugzilla.mozilla.org/show_bug.cgi?id=327529>`__: Can't pass 0 as an + unnamed null pointer argument to CERT_CreateRDN + - `Bug 334683 <https://bugzilla.mozilla.org/show_bug.cgi?id=334683>`__: Extraneous semicolons + cause Empty declaration compiler warnings + - `Bug 335275 <https://bugzilla.mozilla.org/show_bug.cgi?id=335275>`__: Compile with the GCC + flag -Werror-implicit-function-declaration + - `Bug 354565 <https://bugzilla.mozilla.org/show_bug.cgi?id=354565>`__: fipstest sha_test needs + to detect SHA tests that are incorrectly configured for BIT oriented implementations + - `Bug 356595 <https://bugzilla.mozilla.org/show_bug.cgi?id=356595>`__: On Windows, + RNG_SystemInfoForRNG calls GetCurrentProcess, which returns the constant (HANDLE)-1. + - `Bug 357015 <https://bugzilla.mozilla.org/show_bug.cgi?id=357015>`__: On Windows, + ReadSystemFiles reads 21 files as opposed to 10 files in C:\WINDOWS\system32. + - `Bug 361076 <https://bugzilla.mozilla.org/show_bug.cgi?id=361076>`__: Clean up the + USE_PTHREADS related code in coreconf/SunOS5.mk. + - `Bug 361077 <https://bugzilla.mozilla.org/show_bug.cgi?id=361077>`__: Clean up the + USE_PTHREADS related code in coreconf/HP-UX*.mk. + - `Bug 402114 <https://bugzilla.mozilla.org/show_bug.cgi?id=402114>`__: Fix the incorrect + function prototypes of SSL handshake callbacks + - `Bug 402308 <https://bugzilla.mozilla.org/show_bug.cgi?id=402308>`__: Fix miscellaneous + compiler warnings in nss/cmd + - `Bug 402777 <https://bugzilla.mozilla.org/show_bug.cgi?id=402777>`__: lib/util can't be built + stand-alone. + - `Bug 407866 <https://bugzilla.mozilla.org/show_bug.cgi?id=407866>`__: Contributed improvement + to security/nss/lib/freebl/mpi/mp_comba.c + - `Bug 410587 <https://bugzilla.mozilla.org/show_bug.cgi?id=410587>`__: SSL_GetChannelInfo + returns SECSuccess on invalid arguments + - `Bug 416508 <https://bugzilla.mozilla.org/show_bug.cgi?id=416508>`__: Fix a \_MSC_VER typo in + sha512.c, and use SEC_BEGIN_PROTOS/SEC_END_PROTOS in secport.h + - `Bug 419242 <https://bugzilla.mozilla.org/show_bug.cgi?id=419242>`__: 'all' is not the default + makefile target in lib/softoken and lib/softoken/legacydb + - `Bug 419523 <https://bugzilla.mozilla.org/show_bug.cgi?id=419523>`__: Export + Cert_NewTempCertificate. + - `Bug 287061 <https://bugzilla.mozilla.org/show_bug.cgi?id=287061>`__: CRL number should be a + big integer, not ulong + - `Bug 301213 <https://bugzilla.mozilla.org/show_bug.cgi?id=301213>`__: Combine internal libpkix + function tests into a single statically linked program + - `Bug 324740 <https://bugzilla.mozilla.org/show_bug.cgi?id=324740>`__: add generation of SIA + and AIA extensions to certutil + - `Bug 339737 <https://bugzilla.mozilla.org/show_bug.cgi?id=339737>`__: LIBPKIX OCSP checking + calls CERT_VerifyCert + - `Bug 358785 <https://bugzilla.mozilla.org/show_bug.cgi?id=358785>`__: Merge NSS_LIBPKIX_BRANCH + back to trunk + - `Bug 365966 <https://bugzilla.mozilla.org/show_bug.cgi?id=365966>`__: infinite recursive call + in VFY_VerifyDigestDirect + - `Bug 382078 <https://bugzilla.mozilla.org/show_bug.cgi?id=382078>`__: pkix default http client + returns error when try to get an ocsp response. + - `Bug 384926 <https://bugzilla.mozilla.org/show_bug.cgi?id=384926>`__: libpkix build problems + - `Bug 389411 <https://bugzilla.mozilla.org/show_bug.cgi?id=389411>`__: Mingw build error - + undefined reference to \`_imp__PKIX_ERRORNAMES' + - `Bug 389904 <https://bugzilla.mozilla.org/show_bug.cgi?id=389904>`__: avoid multiple + decoding/encoding while creating and using PKIX_PL_X500Name + - `Bug 390209 <https://bugzilla.mozilla.org/show_bug.cgi?id=390209>`__: pkix AIA manager tries + to get certs using AIA url with OCSP access method + - `Bug 390233 <https://bugzilla.mozilla.org/show_bug.cgi?id=390233>`__: umbrella bug for libPKIX + cert validation failures discovered from running vfyserv + - `Bug 390499 <https://bugzilla.mozilla.org/show_bug.cgi?id=390499>`__: libpkix does not check + cached cert chain for revocation + - `Bug 390502 <https://bugzilla.mozilla.org/show_bug.cgi?id=390502>`__: libpkix fails cert + validation when no valid CRL (NIST validation policy is always enforced) + - `Bug 390530 <https://bugzilla.mozilla.org/show_bug.cgi?id=390530>`__: libpkix does not support + time override + - `Bug 390536 <https://bugzilla.mozilla.org/show_bug.cgi?id=390536>`__: Cert validation + functions must validate leaf cert themselves + - `Bug 390554 <https://bugzilla.mozilla.org/show_bug.cgi?id=390554>`__: all PKIX_NULLCHECK\_ + errors are reported as PKIX ALLOC ERROR + - `Bug 390888 <https://bugzilla.mozilla.org/show_bug.cgi?id=390888>`__: CERT_Verify\* functions + should be able to use libPKIX + - `Bug 391457 <https://bugzilla.mozilla.org/show_bug.cgi?id=391457>`__: libpkix does not check + for object ref leak at shutdown + - `Bug 391774 <https://bugzilla.mozilla.org/show_bug.cgi?id=391774>`__: PKIX_Shutdown is not + called by nssinit.c + - `Bug 393174 <https://bugzilla.mozilla.org/show_bug.cgi?id=393174>`__: Memory leaks in + ocspclnt/PKIX. + - `Bug 395093 <https://bugzilla.mozilla.org/show_bug.cgi?id=395093>`__: + pkix_pl_HttpCertStore_ProcessCertResponse is unable to process certs in DER format + - `Bug 395224 <https://bugzilla.mozilla.org/show_bug.cgi?id=395224>`__: Don't reject certs with + critical NetscapeCertType extensions in libPKIX + - `Bug 395427 <https://bugzilla.mozilla.org/show_bug.cgi?id=395427>`__: PKIX_PL_Initialize must + not call NSS_Init + - `Bug 395850 <https://bugzilla.mozilla.org/show_bug.cgi?id=395850>`__: build of libpkix tests + creates links to nonexistant shared libraries and breaks windows build + - `Bug 398401 <https://bugzilla.mozilla.org/show_bug.cgi?id=398401>`__: Memory leak in PKIX + init. + - `Bug 399326 <https://bugzilla.mozilla.org/show_bug.cgi?id=399326>`__: libpkix is unable to + validate cert for certUsageStatusResponder + - `Bug 400947 <https://bugzilla.mozilla.org/show_bug.cgi?id=400947>`__: thread unsafe operation + in PKIX_PL_HashTable_Add cause selfserv to crash. + - `Bug 402773 <https://bugzilla.mozilla.org/show_bug.cgi?id=402773>`__: Verify the list of + public header files in NSS 3.12 + - `Bug 403470 <https://bugzilla.mozilla.org/show_bug.cgi?id=403470>`__: Strsclnt + tstclnt + crashes when PKIX enabled. + - `Bug 403685 <https://bugzilla.mozilla.org/show_bug.cgi?id=403685>`__: Application crashes + after having called CERT_PKIXVerifyCert + - `Bug 408434 <https://bugzilla.mozilla.org/show_bug.cgi?id=408434>`__: Crash with PKIX based + verify + - `Bug 411614 <https://bugzilla.mozilla.org/show_bug.cgi?id=411614>`__: Explicit Policy does not + seem to work. + - `Bug 417024 <https://bugzilla.mozilla.org/show_bug.cgi?id=417024>`__: Convert libpkix error + code into nss error code + - `Bug 422859 <https://bugzilla.mozilla.org/show_bug.cgi?id=422859>`__: libPKIX builds & + validates chain to root not in the caller-provided anchor list + - `Bug 425516 <https://bugzilla.mozilla.org/show_bug.cgi?id=425516>`__: need to destroy data + pointed by CERTValOutParam array in case of error + - `Bug 426450 <https://bugzilla.mozilla.org/show_bug.cgi?id=426450>`__: PKIX_PL_HashTable_Remove + leaks hashtable key object + - `Bug 429230 <https://bugzilla.mozilla.org/show_bug.cgi?id=429230>`__: memory leak in + pkix_CheckCert function + - `Bug 392696 <https://bugzilla.mozilla.org/show_bug.cgi?id=392696>`__: Fix copyright + boilerplate in all new PKIX code + - `Bug 300928 <https://bugzilla.mozilla.org/show_bug.cgi?id=300928>`__: Integrate libpkix to NSS + - `Bug 303457 <https://bugzilla.mozilla.org/show_bug.cgi?id=303457>`__: extensions newly + supported in libpkix must be marked supported + - `Bug 331096 <https://bugzilla.mozilla.org/show_bug.cgi?id=331096>`__: NSS Softoken must detect + forks on all unix-ish platforms + - `Bug 390710 <https://bugzilla.mozilla.org/show_bug.cgi?id=390710>`__: + CERTNameConstraintsTemplate is incorrect + - `Bug 416928 <https://bugzilla.mozilla.org/show_bug.cgi?id=416928>`__: DER decode error on this + policy extension + - `Bug 375019 <https://bugzilla.mozilla.org/show_bug.cgi?id=375019>`__: Cache-enable + pkix_OcspChecker_Check + - `Bug 391454 <https://bugzilla.mozilla.org/show_bug.cgi?id=391454>`__: libPKIX does not honor + NSS's override trust flags + - `Bug 403682 <https://bugzilla.mozilla.org/show_bug.cgi?id=403682>`__: CERT_PKIXVerifyCert + never succeeds + - `Bug 324744 <https://bugzilla.mozilla.org/show_bug.cgi?id=324744>`__: add generation of policy + extensions to certutil + - `Bug 390973 <https://bugzilla.mozilla.org/show_bug.cgi?id=390973>`__: Add long option names to + SECU_ParseCommandLine + - `Bug 161326 <https://bugzilla.mozilla.org/show_bug.cgi?id=161326>`__: need API to convert + dotted OID format to/from octet representation + - `Bug 376737 <https://bugzilla.mozilla.org/show_bug.cgi?id=376737>`__: CERT_ImportCerts + routinely sets VALID_PEER or VALID_CA OVERRIDE trust flags + - `Bug 390381 <https://bugzilla.mozilla.org/show_bug.cgi?id=390381>`__: libpkix rejects cert + chain when root CA cert has no basic constraints + - `Bug 391183 <https://bugzilla.mozilla.org/show_bug.cgi?id=391183>`__: rename libPKIX error + string number type to pkix error number types + - `Bug 397122 <https://bugzilla.mozilla.org/show_bug.cgi?id=397122>`__: NSS 3.12 alpha treats a + key3.db with no global salt as having no password + - `Bug 405966 <https://bugzilla.mozilla.org/show_bug.cgi?id=405966>`__: Unknown signature OID + 1.3.14.3.2.29 causes sec_error_bad_signature, 3.11 ignores it + - `Bug 413010 <https://bugzilla.mozilla.org/show_bug.cgi?id=413010>`__: CERT_CompareRDN may + return a false match + - `Bug 417664 <https://bugzilla.mozilla.org/show_bug.cgi?id=417664>`__: false positive crl + revocation test on ppc/ppc64 NSS_ENABLE_PKIX_VERIFY=1 + - `Bug 404526 <https://bugzilla.mozilla.org/show_bug.cgi?id=404526>`__: glibc detected free(): + invalid pointer + - `Bug 300929 <https://bugzilla.mozilla.org/show_bug.cgi?id=300929>`__: Certificate Policy + extensions not supported + - `Bug 129303 <https://bugzilla.mozilla.org/show_bug.cgi?id=129303>`__: NSS needs to expose + interfaces to deal with multiple token sources of certs. + - `Bug 217538 <https://bugzilla.mozilla.org/show_bug.cgi?id=217538>`__: softoken databases + cannot be shared between multiple processes + - `Bug 294531 <https://bugzilla.mozilla.org/show_bug.cgi?id=294531>`__: Design new interfaces + for certificate path building and verification for libPKIX + - `Bug 326482 <https://bugzilla.mozilla.org/show_bug.cgi?id=326482>`__: NSS ECC performance + problems (intel) + - `Bug 391296 <https://bugzilla.mozilla.org/show_bug.cgi?id=391296>`__: Need an update helper + for Shared Databases + - `Bug 395090 <https://bugzilla.mozilla.org/show_bug.cgi?id=395090>`__: remove duplication of + pkcs7 code from pkix_pl_httpcertstore.c + - `Bug 401026 <https://bugzilla.mozilla.org/show_bug.cgi?id=401026>`__: Need to provide a way to + modify and create new PKCS #11 objects. + - `Bug 403680 <https://bugzilla.mozilla.org/show_bug.cgi?id=403680>`__: CERT_PKIXVerifyCert + fails if CRLs are missing, implement cert_pi_revocationFlags + - `Bug 427706 <https://bugzilla.mozilla.org/show_bug.cgi?id=427706>`__: NSS_3_12_RC1 crashes in + passwordmgr tests + - `Bug 426245 <https://bugzilla.mozilla.org/show_bug.cgi?id=426245>`__: Assertion failure went + undetected by tinderbox + - `Bug 158242 <https://bugzilla.mozilla.org/show_bug.cgi?id=158242>`__: PK11_PutCRL is very + memory inefficient + - `Bug 287563 <https://bugzilla.mozilla.org/show_bug.cgi?id=287563>`__: Please make + cert_CompareNameWithConstraints a non-static function + - `Bug 301496 <https://bugzilla.mozilla.org/show_bug.cgi?id=301496>`__: NSS_Shutdown failure in + p7sign + - `Bug 324878 <https://bugzilla.mozilla.org/show_bug.cgi?id=324878>`__: crlutil -L outputs false + CRL names + - `Bug 337010 <https://bugzilla.mozilla.org/show_bug.cgi?id=337010>`__: OOM crash [[@ + NSC_DigestKey] Dereferencing possibly NULL att + - `Bug 343231 <https://bugzilla.mozilla.org/show_bug.cgi?id=343231>`__: certutil issues certs + for invalid requests + - `Bug 353371 <https://bugzilla.mozilla.org/show_bug.cgi?id=353371>`__: Klocwork 91117 - Null + Pointer Dereference in CERT_CertChainFromCert + - `Bug 353374 <https://bugzilla.mozilla.org/show_bug.cgi?id=353374>`__: Klocwork 76494 - Null + ptr derefs in CERT_FormatName + - `Bug 353375 <https://bugzilla.mozilla.org/show_bug.cgi?id=353375>`__: Klocwork 76513 - Null + ptr deref in nssCertificateList_DoCallback + - `Bug 353413 <https://bugzilla.mozilla.org/show_bug.cgi?id=353413>`__: Klocwork 76541 free + uninitialized pointer in CERT_FindCertURLExtension + - `Bug 353416 <https://bugzilla.mozilla.org/show_bug.cgi?id=353416>`__: Klocwork 76593 null ptr + deref in nssCryptokiPrivateKey_SetCertificate + - `Bug 353423 <https://bugzilla.mozilla.org/show_bug.cgi?id=353423>`__: Klocwork bugs in + nss/lib/pk11wrap/dev3hack.c + - `Bug 353739 <https://bugzilla.mozilla.org/show_bug.cgi?id=353739>`__: Klocwork Null ptr + dereferences in instance.c + - `Bug 353741 <https://bugzilla.mozilla.org/show_bug.cgi?id=353741>`__: klocwork cascading + memory leak in mpp_make_prime + - `Bug 353742 <https://bugzilla.mozilla.org/show_bug.cgi?id=353742>`__: klocwork null ptr + dereference in ocsp_DecodeResponseBytes + - `Bug 353748 <https://bugzilla.mozilla.org/show_bug.cgi?id=353748>`__: klocwork null ptr + dereferences in pki3hack.c + - `Bug 353760 <https://bugzilla.mozilla.org/show_bug.cgi?id=353760>`__: klocwork null pointer + dereference in p7decode.c + - `Bug 353763 <https://bugzilla.mozilla.org/show_bug.cgi?id=353763>`__: klocwork Null ptr + dereferences in pk11cert.c + - `Bug 353773 <https://bugzilla.mozilla.org/show_bug.cgi?id=353773>`__: klocwork Null ptr + dereferences in pk11nobj.c + - `Bug 353777 <https://bugzilla.mozilla.org/show_bug.cgi?id=353777>`__: Klocwork Null ptr + dereferences in pk11obj.c + - `Bug 353780 <https://bugzilla.mozilla.org/show_bug.cgi?id=353780>`__: Klocwork NULL ptr + dereferences in pkcs11.c + - `Bug 353865 <https://bugzilla.mozilla.org/show_bug.cgi?id=353865>`__: klocwork Null ptr deref + in softoken/pk11db.c + - `Bug 353888 <https://bugzilla.mozilla.org/show_bug.cgi?id=353888>`__: klockwork IDs for + ssl3con.c + - `Bug 353895 <https://bugzilla.mozilla.org/show_bug.cgi?id=353895>`__: klocwork Null ptr derefs + in pki/pkibase.c + - `Bug 353902 <https://bugzilla.mozilla.org/show_bug.cgi?id=353902>`__: klocwork bugs in + stanpcertdb.c + - `Bug 353903 <https://bugzilla.mozilla.org/show_bug.cgi?id=353903>`__: klocwork oom crash in + softoken/keydb.c + - `Bug 353908 <https://bugzilla.mozilla.org/show_bug.cgi?id=353908>`__: klocwork OOM crash in + tdcache.c + - `Bug 353909 <https://bugzilla.mozilla.org/show_bug.cgi?id=353909>`__: klocwork ptr dereference + before NULL check in devutil.c + - `Bug 353912 <https://bugzilla.mozilla.org/show_bug.cgi?id=353912>`__: Misc klocwork bugs in + lib/ckfw + - `Bug 354008 <https://bugzilla.mozilla.org/show_bug.cgi?id=354008>`__: klocwork bugs in freebl + - `Bug 359331 <https://bugzilla.mozilla.org/show_bug.cgi?id=359331>`__: modutil -changepw strict + shutdown failure + - `Bug 373367 <https://bugzilla.mozilla.org/show_bug.cgi?id=373367>`__: verify OCSP response + signature in libpkix without decoding and reencoding + - `Bug 390542 <https://bugzilla.mozilla.org/show_bug.cgi?id=390542>`__: libpkix fails to + validate a chain that consists only of one self issued, trusted cert + - `Bug 390728 <https://bugzilla.mozilla.org/show_bug.cgi?id=390728>`__: + pkix_pl_OcspRequest_Create throws an error if it was not able to get AIA location + - `Bug 397825 <https://bugzilla.mozilla.org/show_bug.cgi?id=397825>`__: libpkix: ifdef code that + uses user object types + - `Bug 397832 <https://bugzilla.mozilla.org/show_bug.cgi?id=397832>`__: libpkix leaks memory if + a macro calls a function that returns an error + - `Bug 402727 <https://bugzilla.mozilla.org/show_bug.cgi?id=402727>`__: functions responsible + for creating an object leak if subsequent function code produces an error + - `Bug 402731 <https://bugzilla.mozilla.org/show_bug.cgi?id=402731>`__: + pkix_pl_Pk11CertStore_CrlQuery will crash if fails to acquire DP cache. + - `Bug 406647 <https://bugzilla.mozilla.org/show_bug.cgi?id=406647>`__: libpkix does not use + user defined revocation checkers + - `Bug 407064 <https://bugzilla.mozilla.org/show_bug.cgi?id=407064>`__: + pkix_pl_LdapCertStore_BuildCrlList should not fail if a crl fails to be decoded + - `Bug 421216 <https://bugzilla.mozilla.org/show_bug.cgi?id=421216>`__: libpkix test nss_thread + leaks a test certificate + - `Bug 301259 <https://bugzilla.mozilla.org/show_bug.cgi?id=301259>`__: signtool Usage message + is unhelpful + - `Bug 389781 <https://bugzilla.mozilla.org/show_bug.cgi?id=389781>`__: NSS should be built + size-optimized in browser builds on Linux, Windows, and Mac + - `Bug 90426 <https://bugzilla.mozilla.org/show_bug.cgi?id=90426>`__: use of obsolete typedefs + in public NSS headers + - `Bug 113323 <https://bugzilla.mozilla.org/show_bug.cgi?id=113323>`__: The first argument to + PK11_FindCertFromNickname should be const. + - `Bug 132485 <https://bugzilla.mozilla.org/show_bug.cgi?id=132485>`__: built-in root certs slot + description is empty + - `Bug 177184 <https://bugzilla.mozilla.org/show_bug.cgi?id=177184>`__: NSS_CMSDecoder_Cancel + might have a leak + - `Bug 232392 <https://bugzilla.mozilla.org/show_bug.cgi?id=232392>`__: Erroneous root CA tests + in NSS Libraries + - `Bug 286642 <https://bugzilla.mozilla.org/show_bug.cgi?id=286642>`__: util should be in a + shared library + - `Bug 287052 <https://bugzilla.mozilla.org/show_bug.cgi?id=287052>`__: Function to get CRL + Entry reason code has incorrect prototype and implementation + - `Bug 299308 <https://bugzilla.mozilla.org/show_bug.cgi?id=299308>`__: Need additional APIs in + the CRL cache for libpkix + - `Bug 335039 <https://bugzilla.mozilla.org/show_bug.cgi?id=335039>`__: + nssCKFWCryptoOperation_UpdateCombo is not declared + - `Bug 340917 <https://bugzilla.mozilla.org/show_bug.cgi?id=340917>`__: crlutil should init NSS + read-only for some options + - `Bug 350948 <https://bugzilla.mozilla.org/show_bug.cgi?id=350948>`__: freebl macro change can + give 1% improvement in RSA performance on amd64 + - `Bug 352439 <https://bugzilla.mozilla.org/show_bug.cgi?id=352439>`__: Reference leaks in + modutil + - `Bug 369144 <https://bugzilla.mozilla.org/show_bug.cgi?id=369144>`__: certutil needs option to + generate SubjectKeyID extension + - `Bug 391771 <https://bugzilla.mozilla.org/show_bug.cgi?id=391771>`__: pk11_config_name and + pk11_config_strings leaked on shutdown + - `Bug 401194 <https://bugzilla.mozilla.org/show_bug.cgi?id=401194>`__: crash in lg_FindObjects + on win64 + - `Bug 405652 <https://bugzilla.mozilla.org/show_bug.cgi?id=405652>`__: In the TLS ClientHello + message the gmt_unix_time is incorrect + - `Bug 424917 <https://bugzilla.mozilla.org/show_bug.cgi?id=424917>`__: Performance regression + with studio 12 compiler + - `Bug 391770 <https://bugzilla.mozilla.org/show_bug.cgi?id=391770>`__: OCSP_Global.monitor is + leaked on shutdown + - `Bug 403687 <https://bugzilla.mozilla.org/show_bug.cgi?id=403687>`__: move pkix functions to + certvfypkix.c, turn off EV_TEST_HACK + - `Bug 428105 <https://bugzilla.mozilla.org/show_bug.cgi?id=428105>`__: CERT_SetOCSPTimeout is + not defined in any public header file + - `Bug 213359 <https://bugzilla.mozilla.org/show_bug.cgi?id=213359>`__: enhance PK12util to + extract certs from p12 file + - `Bug 329067 <https://bugzilla.mozilla.org/show_bug.cgi?id=329067>`__: NSS encodes cert + distinguished name attributes with wrong string type + - `Bug 339906 <https://bugzilla.mozilla.org/show_bug.cgi?id=339906>`__: sec_pkcs12_install_bags + passes uninitialized variables to functions + - `Bug 396484 <https://bugzilla.mozilla.org/show_bug.cgi?id=396484>`__: certutil doesn't + truncate existing temporary files when writing them + - `Bug 251594 <https://bugzilla.mozilla.org/show_bug.cgi?id=251594>`__: Certificate from PKCS#12 + file with colon in friendlyName not selectable for signing/encryption + - `Bug 321584 <https://bugzilla.mozilla.org/show_bug.cgi?id=321584>`__: NSS PKCS12 decoder fails + to import bags without nicknames + - `Bug 332633 <https://bugzilla.mozilla.org/show_bug.cgi?id=332633>`__: remove duplicate header + files in nss/cmd/sslsample + - `Bug 335019 <https://bugzilla.mozilla.org/show_bug.cgi?id=335019>`__: pk12util takes friendly + name from key, not cert + - `Bug 339173 <https://bugzilla.mozilla.org/show_bug.cgi?id=339173>`__: mem leak whenever + SECMOD_HANDLE_STRING_ARG called in loop + - `Bug 353904 <https://bugzilla.mozilla.org/show_bug.cgi?id=353904>`__: klocwork Null ptr deref + in secasn1d.c + - `Bug 366390 <https://bugzilla.mozilla.org/show_bug.cgi?id=366390>`__: correct misleading + function names in fipstest + - `Bug 370536 <https://bugzilla.mozilla.org/show_bug.cgi?id=370536>`__: Memory leaks in pointer + tracker code in DEBUG builds only + - `Bug 372242 <https://bugzilla.mozilla.org/show_bug.cgi?id=372242>`__: CERT_CompareRDN uses + incorrect algorithm + - `Bug 379753 <https://bugzilla.mozilla.org/show_bug.cgi?id=379753>`__: S/MIME should support + AES + - `Bug 381375 <https://bugzilla.mozilla.org/show_bug.cgi?id=381375>`__: ocspclnt doesn't work on + Windows + - `Bug 398693 <https://bugzilla.mozilla.org/show_bug.cgi?id=398693>`__: DER_AsciiToTime produces + incorrect output for dates 1950-1970 + - `Bug 420212 <https://bugzilla.mozilla.org/show_bug.cgi?id=420212>`__: Empty cert DNs handled + badly, display as !INVALID AVA! + - `Bug 420979 <https://bugzilla.mozilla.org/show_bug.cgi?id=420979>`__: vfychain ignores -b TIME + option when -p option is present + - `Bug 403563 <https://bugzilla.mozilla.org/show_bug.cgi?id=403563>`__: Implement the TLS + session ticket extension (STE) + - `Bug 400917 <https://bugzilla.mozilla.org/show_bug.cgi?id=400917>`__: Want exported function + that outputs all host names for DNS name matching + - `Bug 315643 <https://bugzilla.mozilla.org/show_bug.cgi?id=315643>`__: + test_buildchain_resourcelimits won't build + - `Bug 353745 <https://bugzilla.mozilla.org/show_bug.cgi?id=353745>`__: klocwork null ptr + dereference in PKCS12 decoder + - `Bug 338367 <https://bugzilla.mozilla.org/show_bug.cgi?id=338367>`__: The GF2M_POPULATE and + GFP_POPULATE should check the ecCurve_map array index bounds before use + - `Bug 201139 <https://bugzilla.mozilla.org/show_bug.cgi?id=201139>`__: SSLTap should display + plain text for NULL cipher suites + - `Bug 233806 <https://bugzilla.mozilla.org/show_bug.cgi?id=233806>`__: Support NIST CRL policy + - `Bug 279085 <https://bugzilla.mozilla.org/show_bug.cgi?id=279085>`__: NSS tools display public + exponent as negative number + - `Bug 363480 <https://bugzilla.mozilla.org/show_bug.cgi?id=363480>`__: ocspclnt needs option to + take cert from specified file + - `Bug 265715 <https://bugzilla.mozilla.org/show_bug.cgi?id=265715>`__: remove unused hsearch.c + DBM code + - `Bug 337361 <https://bugzilla.mozilla.org/show_bug.cgi?id=337361>`__: Leaks in jar_parse_any + (security/nss/lib/jar/jarver.c) + - `Bug 338453 <https://bugzilla.mozilla.org/show_bug.cgi?id=338453>`__: Leaks in + security/nss/lib/jar/jarfile.c + - `Bug 351408 <https://bugzilla.mozilla.org/show_bug.cgi?id=351408>`__: Leaks in + JAR_JAR_sign_archive (security/nss/lib/jar/jarjart.c) + - `Bug 351443 <https://bugzilla.mozilla.org/show_bug.cgi?id=351443>`__: Remove unused code from + mozilla/security/nss/lib/jar + - `Bug 351510 <https://bugzilla.mozilla.org/show_bug.cgi?id=351510>`__: Remove USE_MOZ_THREAD + code from mozilla/security/lib/jar + - `Bug 118830 <https://bugzilla.mozilla.org/show_bug.cgi?id=118830>`__: NSS public header files + should be C++ safe + - `Bug 123996 <https://bugzilla.mozilla.org/show_bug.cgi?id=123996>`__: certutil -H doesn't + document certutil -C -a + - `Bug 178894 <https://bugzilla.mozilla.org/show_bug.cgi?id=178894>`__: Quick decoder updates + for lib/certdb and lib/certhigh + - `Bug 220115 <https://bugzilla.mozilla.org/show_bug.cgi?id=220115>`__: CKM_INVALID_MECHANISM + should be an unsigned long constant. + - `Bug 330721 <https://bugzilla.mozilla.org/show_bug.cgi?id=330721>`__: Remove OS/2 VACPP + compiler support from NSS + - `Bug 408260 <https://bugzilla.mozilla.org/show_bug.cgi?id=408260>`__: certutil usage doesn't + give enough information about trust arguments + - `Bug 410226 <https://bugzilla.mozilla.org/show_bug.cgi?id=410226>`__: leak in + create_objects_from_handles + - `Bug 415007 <https://bugzilla.mozilla.org/show_bug.cgi?id=415007>`__: + PK11_FindCertFromDERSubjectAndNickname is dead code + - `Bug 416267 <https://bugzilla.mozilla.org/show_bug.cgi?id=416267>`__: compiler warnings on + solaris due to extra semicolon in SEC_ASN1_MKSUB + - `Bug 419763 <https://bugzilla.mozilla.org/show_bug.cgi?id=419763>`__: logger thread should be + joined on exit + - `Bug 424471 <https://bugzilla.mozilla.org/show_bug.cgi?id=424471>`__: counter overflow in + bltest + - `Bug 229335 <https://bugzilla.mozilla.org/show_bug.cgi?id=229335>`__: Remove certificates that + expired in August 2004 from tree + - `Bug 346551 <https://bugzilla.mozilla.org/show_bug.cgi?id=346551>`__: init SECItem derTemp in + crmf_encode_popoprivkey + - `Bug 395080 <https://bugzilla.mozilla.org/show_bug.cgi?id=395080>`__: Double backslash in + sysDir filenames causes problems on OS/2 + - `Bug 341371 <https://bugzilla.mozilla.org/show_bug.cgi?id=341371>`__: certutil lacks a way to + request a certificate with an existing key + - `Bug 382292 <https://bugzilla.mozilla.org/show_bug.cgi?id=382292>`__: add support for Camellia + to cmd/symkeyutil + - `Bug 385642 <https://bugzilla.mozilla.org/show_bug.cgi?id=385642>`__: Add additional cert + usage(s) for certutil's -V -u option + - `Bug 175741 <https://bugzilla.mozilla.org/show_bug.cgi?id=175741>`__: strict aliasing bugs in + mozilla/dbm + - `Bug 210584 <https://bugzilla.mozilla.org/show_bug.cgi?id=210584>`__: CERT_AsciiToName doesn't + accept all valid values + - `Bug 298540 <https://bugzilla.mozilla.org/show_bug.cgi?id=298540>`__: vfychain usage option + should be improved and documented + - `Bug 323570 <https://bugzilla.mozilla.org/show_bug.cgi?id=323570>`__: Make dbck Debug mode + work with Softoken + - `Bug 371470 <https://bugzilla.mozilla.org/show_bug.cgi?id=371470>`__: vfychain needs option to + verify for specific date + - `Bug 387621 <https://bugzilla.mozilla.org/show_bug.cgi?id=387621>`__: certutil's random noise + generator isn't very efficient + - `Bug 390185 <https://bugzilla.mozilla.org/show_bug.cgi?id=390185>`__: signtool error message + wrongly uses the term database + - `Bug 391651 <https://bugzilla.mozilla.org/show_bug.cgi?id=391651>`__: Need config.mk file for + Windows Vista + - `Bug 396322 <https://bugzilla.mozilla.org/show_bug.cgi?id=396322>`__: Fix secutil's code and + NSS tools that print public keys + - `Bug 417641 <https://bugzilla.mozilla.org/show_bug.cgi?id=417641>`__: miscellaneous minor NSS + bugs + - `Bug 334914 <https://bugzilla.mozilla.org/show_bug.cgi?id=334914>`__: hopefully useless null + check of out it in JAR_find_next + - `Bug 95323 <https://bugzilla.mozilla.org/show_bug.cgi?id=95323>`__: ckfw should support cipher + operations. + - `Bug 337088 <https://bugzilla.mozilla.org/show_bug.cgi?id=337088>`__: Coverity 405, + PK11_ParamToAlgid() in mozilla/security/nss/lib/pk11wrap/pk11mech.c + - `Bug 339907 <https://bugzilla.mozilla.org/show_bug.cgi?id=339907>`__: oaep_xor_with_h1 + allocates and leaks sha1cx + - `Bug 341122 <https://bugzilla.mozilla.org/show_bug.cgi?id=341122>`__: Coverity 633 + SFTK_DestroySlotData uses slot->slotLock then checks it for NULL + - `Bug 351140 <https://bugzilla.mozilla.org/show_bug.cgi?id=351140>`__: Coverity 995, potential + crash in ecgroup_fromNameAndHex + - `Bug 362278 <https://bugzilla.mozilla.org/show_bug.cgi?id=362278>`__: lib/util includes header + files from other NSS directories + - `Bug 228190 <https://bugzilla.mozilla.org/show_bug.cgi?id=228190>`__: Remove unnecessary + NSS_ENABLE_ECC defines from manifest.mn + - `Bug 412906 <https://bugzilla.mozilla.org/show_bug.cgi?id=412906>`__: remove sha.c and sha.h + from lib/freebl + - `Bug 353543 <https://bugzilla.mozilla.org/show_bug.cgi?id=353543>`__: valgrind uninitialized + memory read in nssPKIObjectCollection_AddInstances + - `Bug 377548 <https://bugzilla.mozilla.org/show_bug.cgi?id=377548>`__: NSS QA test program + certutil's default DSA prime is only 512 bits + - `Bug 333405 <https://bugzilla.mozilla.org/show_bug.cgi?id=333405>`__: item cleanup is unused + DEADCODE in SECITEM_AllocItem loser + - `Bug 288730 <https://bugzilla.mozilla.org/show_bug.cgi?id=288730>`__: compiler warnings in + certutil + - `Bug 337251 <https://bugzilla.mozilla.org/show_bug.cgi?id=337251>`__: warning: /\* within + comment + - `Bug 362967 <https://bugzilla.mozilla.org/show_bug.cgi?id=362967>`__: export + SECMOD_DeleteModuleEx + - `Bug 389248 <https://bugzilla.mozilla.org/show_bug.cgi?id=389248>`__: NSS build failure when + NSS_ENABLE_ECC is not defined + - `Bug 390451 <https://bugzilla.mozilla.org/show_bug.cgi?id=390451>`__: Remembered passwords + lost when changing Master Password + - `Bug 418546 <https://bugzilla.mozilla.org/show_bug.cgi?id=418546>`__: reference leak in + CERT_PKIXVerifyCert + - `Bug 390074 <https://bugzilla.mozilla.org/show_bug.cgi?id=390074>`__: OS/2 sign.cmd doesn't + find sqlite3.dll + - `Bug 417392 <https://bugzilla.mozilla.org/show_bug.cgi?id=417392>`__: certutil -L -n reports + bogus trust flags + + -------------- + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For a list of the primary NSS documentation pages on mozilla.org, see `NSS + Documentation <../index.html#Documentation>`__. New and revised documents available since the + release of NSS 3.11 include the following: + + - :ref:`mozilla_projects_nss_reference_building_and_installing_nss_build_instructions` + - `NSS Shared DB <http://wiki.mozilla.org/NSS_Shared_DB>`__ + - :ref:`mozilla_projects_nss_reference_nss_environment_variables` + + -------------- + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS 3.12 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.12 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in `NSS Public Functions <../ref/nssfunctions.html>`__ will remain + compatible with future versions of the NSS shared libraries. + + -------------- + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__\ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_3.37.3release_notes/index.rst b/security/nss/doc/rst/legacy/nss_3.37.3release_notes/index.rst new file mode 100644 index 0000000000..a51cbcb954 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_3.37.3release_notes/index.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_nss_3_37_3release_notes: + +NSS 3.37.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.37.3 is a patch release for NSS 3.37. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_37_3_RTM. NSS 3.37.3 requires NSPR 4.19 or newer. + + NSS 3.37.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_37_3_RTM/src/ + +.. _new_in_nss_3.37.3: + +`New in NSS 3.37.3 <#new_in_nss_3.37.3>`__ +------------------------------------------ + +.. container:: + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix regression + bugs. + +.. _bugs_fixed_in_nss_3.37.3: + +`Bugs fixed in NSS 3.37.3 <#bugs_fixed_in_nss_3.37.3>`__ +-------------------------------------------------------- + +.. container:: + + - Bug 1459739 - Fix build on armv6/armv7 and other platforms. + + - Bug 1461731 - Fix crash on macOS related to authentication tokens, e.g. PK11or WebAuthn. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.37.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.37.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_api_guidelines/index.rst b/security/nss/doc/rst/legacy/nss_api_guidelines/index.rst new file mode 100644 index 0000000000..05483bb248 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_api_guidelines/index.rst @@ -0,0 +1,882 @@ +.. _mozilla_projects_nss_nss_api_guidelines: + +NSS API Guidelines +================== + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + This document describes how the NSS code is organized, the libraries that get built from the NSS + sources, and guidelines for writing NSS code. These guidelines will familiarize you with some of + the ways things can be done in the NSS code. This will help you understand existing NSS code. It + should also help you understand how to write new code, and where to place it. + + Some of the guidelines in this document, are more forward-looking than documentary. These rules + are here to help us all immediately achieve more consistent and usable code, but some existing + code won't follow all these rules. + +.. _nss_api_structure: + +`NSS API Structure <#nss_api_structure>`__ +------------------------------------------ + +.. container:: + + This section explains the structure and relationships of the NSS libraries. The + `Layering <#layering>`__ section explains how the NSS code is layered, and how higher-level + functions wrap low-level functions. The `Libraries <#libraries>`__ section describes the NSS + libraries, the functionality each provides, and the layer in which the library (mostly) operates. + +`Layering <#layering>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Each separate component of the API should live in its own layer. The functions in these APIs + should never call API layers above them. In addition, some low-level APIs may be completely + opaque to higher level layers. That is, access to these functions should only be provided by the + API directly above them. The NSS APIs are layered, as shown in this diagram: + + .. image:: /en-US/docs/Mozilla/Projects/NSS/NSS_API_Guidelines/layer.gif + :alt: A diagram of the different layers that collectively make up "NSS". Dependencies are only + permitted between siblings and layers below them. + :width: 427px + :height: 507px + + The boxes in the gray section, towards the center, are exported only through PKCS #11. PKCS #11 + is only exported through the Wrappers. The areas which need the most work (both here and + throughout the code) is: + + #. The relationship of the Certificate library with just about every other component (most + noticeably PKCS #12, PKCS #7, and PKCS #11) + #. Splitting Low Key and High Key components more clearly + #. The Crypto wrappers (PKCS #11 Wrappers) and High Key + #. PKCS #12 and PKCS #5 + +`Libraries <#libraries>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS compiles into the libraries described below. The Layer indicates the main layer, seen in the + previous diagram, in which the library operates. The Directory is the location of the library + code in the NSS source tree. The Public Headers is a list of header files that contain types, and + functions, that are publicly available to higer-level APIs. + + +----------+---------------------+---------------------+---------------+---------------------+ + | Library | Description | Layer | Directory | Public Headers | + +----------+---------------------+---------------------+---------------+---------------------+ + | certdb | Provides all | Low Cert | lib/certdb | cdbhdl.h, certdb.h, | + | | certificate | | | cert.h, certt.h | + | | handling functions | | | | + | | and types. The | | | | + | | certdb library | | | | + | | manipulates the | | | | + | | certificate | | | | + | | database (add, | | | | + | | create, delete | | | | + | | certificates and | | | | + | | CRLs). It also | | | | + | | provides general | | | | + | | c | | | | + | | ertificate-handling | | | | + | | routines (create a | | | | + | | certificate, | | | | + | | verify, add/check | | | | + | | certificate | | | | + | | extensions). | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | certhi | Provides high-level | High Cert | lib/certhigh | ocsp.h, ocspt.h | + | | certificate-related | | | | + | | functions, that do | | | | + | | not access the | | | | + | | certificate | | | | + | | database, nor | | | | + | | individual | | | | + | | certificate data | | | | + | | directly. | | | | + | | Currently, OCSP | | | | + | | checking settings | | | | + | | are exported | | | | + | | through certhi. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | crmf | Provides functions, | Same Level as SSL | lib/crmf | cmmf.h, crmf.h, | + | | and data types, to | | | crmft.h, cmmft.h, | + | | handle Certificate | | | crmffut.h | + | | Management Message | | | | + | | Format (CMMF) and | | | | + | | Certificate Request | | | | + | | Message Format | | | | + | | (CRMF, see `RFC | | | | + | | 2511 <https://data | | | | + | | tracker.ietf.org/do | | | | + | | c/html/rfc2511>`__) | | | | + | | data. CMMF no | | | | + | | longer exists as a | | | | + | | proposed standard; | | | | + | | CMMF functions have | | | | + | | been incorporated | | | | + | | into the proposal | | | | + | | for `Certificate | | | | + | | Management | | | | + | | Protocols | | | | + | | (CMP) <https://data | | | | + | | tracker.ietf.org/do | | | | + | | c/html/rfc2510>`__. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | cryptohi | Provides high-level | Sign/Verify | lib/cryptohi | cryptohi.h, | + | | cryptographic | | | cryptoht.h, | + | | support operations: | | | hasht.h, keyhi.h, | + | | such as signing, | | | keythi.h, key.h, | + | | verifying | | | keyt.h, sechash.h | + | | signatures, key | | | | + | | generation, key | | | | + | | manipulation, | | | | + | | hashing; and data | | | | + | | types. This code is | | | | + | | above the PKCS #11 | | | | + | | layer. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | fort | Provides a PKCS #11 | PKCS #11 | lib/fortcrypt | cryptint.h, | + | | interface, to | | | fmutex.h, | + | | Fortezza crypto | | | fortsock.h, | + | | services. Fortezza | | | fpkcs11.h, | + | | is a set of | | | fpkcs11f.h, | + | | security | | | fpkcs11t.h, | + | | algorithms, used by | | | fpkmem.h, | + | | the U.S. | | | fpkstrs.h, genci.h, | + | | government. There | | | maci.h | + | | is also a SWFT | | | | + | | library that | | | | + | | provides a | | | | + | | software-only | | | | + | | implementation of a | | | | + | | PKCS #11 Fortezza | | | | + | | token. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | freebl | Provides the API to | Within PKCS #11, | lib/freebl | blapi.h, blapit.h | + | | actual | wraps Crypto | | | + | | cryptographic | | | | + | | operations. The | | | | + | | freebl is a wrapper | | | | + | | API. You must | | | | + | | supply a library | | | | + | | that implements the | | | | + | | cryptographic | | | | + | | operations, such as | | | | + | | BSAFE from RSA | | | | + | | Security. This is | | | | + | | also known as the | | | | + | | "bottom layer" API, | | | | + | | or BLAPI. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | jar | Provides support | Port | lib/jar | jar-ds.h, jar.h, | + | | for reading and | | | jarfile.h | + | | writing data in | | | | + | | Java Archive (jar) | | | | + | | format, including | | | | + | | zlib compression. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | nss | Provides high-level | Above High Cert, | lib/nss | nss.h | + | | initialiazation and | High Key | | | + | | shutdown of | | | | + | | security services. | | | | + | | Specifically, this | | | | + | | library provides | | | | + | | NSS_Init() for | | | | + | | establishing | | | | + | | default | | | | + | | certificate, key, | | | | + | | module databases, | | | | + | | and initializing a | | | | + | | default random | | | | + | | number generator. | | | | + | | NSS_Shutdown() | | | | + | | closes these | | | | + | | databases, to | | | | + | | prevent further | | | | + | | access by an | | | | + | | application. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | pk11wrap | Provides access to | Crypto Wrapper | lib/pk11wrap | pk11func.h, | + | | PKCS #11 modules, | | | secmod.h, secmodt.h | + | | through a unified | | | | + | | interface. The | | | | + | | pkcs11wrap library | | | | + | | provides functions | | | | + | | for | | | | + | | selecting/finding | | | | + | | PKCS #11 modules | | | | + | | and slots. It also | | | | + | | provides functions | | | | + | | that invoke | | | | + | | operations in | | | | + | | selected modules | | | | + | | and slots, such as | | | | + | | key selection and | | | | + | | generation, | | | | + | | signing, encryption | | | | + | | and decryption, | | | | + | | etc. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | pkcs12 | Provides functions | PKCS #12 | lib/pkcs12 | pkcs12t.h, | + | | and types for | | | pkcs12.h, | + | | encoding and | | | p12plcy.h, p12.h, | + | | decoding PKCS #12 | | | p12t.h | + | | data. PKCS #12 can | | | | + | | be used to encode | | | | + | | keys, and | | | | + | | certificates, for | | | | + | | export or import | | | | + | | into other | | | | + | | applications. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | pkcs7 | Provides functions | PKCS #7 | lib/pkcs7 | secmime.h, | + | | and types for | | | secpkcs7.h, | + | | encoding and | | | pkcs7t.h | + | | decoding encrypted | | | | + | | data in PKCS #7 | | | | + | | format. For | | | | + | | example, PKCS #7 is | | | | + | | used to encrypt | | | | + | | certificate data to | | | | + | | exchange between | | | | + | | applications, or to | | | | + | | encrypt S/MIME | | | | + | | message data. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | softoken | Provides a software | PKCS #11: | lib/softoken | keydbt.h, keylow.h, | + | | implementation of a | implementation | | keytboth.h, | + | | PKCS #11 module. | | | keytlow.h, | + | | | | | secpkcs5.h, | + | | | | | pkcs11.h, | + | | | | | pkcs11f.h, | + | | | | | pkcs11p.h, | + | | | | | pkcs11t.h, | + | | | | | pkcs11u.h | + +----------+---------------------+---------------------+---------------+---------------------+ + | ssl | Provides an | SSL | lib/ssl | ssl.h, sslerr.h, | + | | implementation of | | | sslproto.h, | + | | the SSL protocol | | | preenc.h | + | | using NSS and NSPR. | | | | + +----------+---------------------+---------------------+---------------+---------------------+ + | secutil | Provides utility | Utility for any | lib/util | base64.h, | + | | functions and data | Layer | | ciferfam.h, | + | | types used by other | | | nssb64.h, | + | | libraries. The | | | nssb64t.h, | + | | library supports | | | nsslocks.h, | + | | base-64 | | | nssrwlk.h, | + | | encoding/decoding, | | | nssrwlkt.h, | + | | reader-writer | | | portreg.h, | + | | locks, the SECItem | | | pqgutil.h, | + | | data type, DER | | | secasn1.h, | + | | encoding/decoding, | | | secasn1t.h, | + | | error types and | | | seccomon.h, | + | | numbers, OID | | | secder.h, | + | | handling, and | | | secdert.h, | + | | secure random | | | secdig.h, | + | | number generation. | | | secdigt.h, | + | | | | | secitem.h, | + | | | | | secoid.h, | + | | | | | secoidt.h, | + | | | | | secport.h, | + | | | | | secrng.h, | + | | | | | secrngt.h, | + | | | | | secerr.h, | + | | | | | watcomfx.h | + +----------+---------------------+---------------------+---------------+---------------------+ + +.. _naming_conventions: + +`Naming Conventions <#naming_conventions>`__ +-------------------------------------------- + +.. container:: + + This section describes the rules that (ideally) should be followed for naming and identifying new + files, functions, and data types. + +.. _cvs_id: + +`CVS ID <#cvs_id>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Each file should include a CVS ID string for identification. The preferred format is: + + .. code:: + + "@(#) $RCSfile: nss-guidelines.html, + v $ $Revision: 48936 $ $Date: 2009-08-11 07:45:57 -0700 (Tue, 11 Aug 2009) $ $Name$" + + You can put the string in a comment or in a static char array. Use #ifdef DEBUG to include the + array in debug builds only. The advantage of using an array is that you can use strings(1) to + pull the ID tags out of a (debug) compiled library. You can even put them in header files; the + header files are protected from double inclusion. The only catch is that you have to determine + the name of the array. + + Here is an example from lib/base/baset.h: + + .. code:: + + #ifdef DEBUG + static const char BASET_CVS_ID[] = "@(#) $RCSfile: nss-guidelines.html, + v $ $Revision: 48936 $ $Date: 2009-08-11 07:45:57 -0700 (Tue, 11 Aug 2009) $ $Name$"; + #endif /* DEBUG */ + + The difference, between this and Id, is that Id has some useless information (*every* file is + "experimental"), and doesn't have Name. Name is the tag (if any) from which this file was pulled. + If you're good with tagging your releases, and then checking out (or exporting!) from the tag for + your build, this saves you from messing around with specific files revision numbers. + +.. _header_files: + +`Header Files <#header_files>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | We have a preferred naming system for include files. We had been moving towards one, for some + time, but for the NSS 3.0 project we finally wrote it down. + | + + ========================= =========== =================== + \ Data Types Function Prototypes + Public nss____t.h nss____.h + Friend (only if required) nss____tf.h nss____f.h + NSS-private \____t.h \____.h + Module-private \____tm.h \____m.h + ========================= =========== =================== + + The files on the right include the files to their left; the files in a row include the files + directly above them. Header files always include what they need; the files are protected against + double inclusion (and even double opening by the compiler). + + .. note:: + + Note: It's not necessary all eight files exist. Further, this is a simple ideal, and often + reality is more complex. + + We would like to keep names to 8.3, even if we no longer support win16. This usually gives us + four characters to identify a module of NSS. + + In short: + + #. Header files for consumption outside NSS start with "nss." + #. Header files with types have a trailing "t", header files with prototypes don't. + "extern" declarations of data also go in the prototypes files. + #. "Friend" headers are for things that we really wish weren't used by non-NSS code, but which + are. Those files have a trailing "f," and their use should be deprecated. + #. "Module" headers are for things used only within a specific subset of NSS; things which would + have been "static" if we had combined separate C source files together. These header files + have a trailing "m." + +.. _functions_and_types: + +`Functions and Types <#functions_and_types>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + There are a number of ways of doing things in our API, as well as naming decisions for functions + that can affect the usefulness of our library. If our library is self-consistent with how we + accomplish these tasks, it makes it easier for the developer to learn how to use our functions. + This section of the document should grow as we develop our API. + + First some general rules. These rules are derived from existing coding practices inside the + security library, since consistency is more important than debates about what might look nice. + + #. **Public functions** should have the form LAYER_Body(), where LAYER is an all caps prefix for + what layer the function lives in, and Body is concatenated English words, where the beginning + letter of each word is capitalized (also known as + `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`__). For Example: + LAYER_CapitalizedEnglishWords() or CERT_DestroyCertificate(). + #. **Data types** and typdefs should have the Form LAYERBody, with the same definitions for LAYER + as public functions, and Body in camel case English words. For example: + LAYERCapitalizedEnglishWords or SECKEYPrivateKey. + #. **Structures** should have the same name as their typedefs, with the string Str added to the + end. For example LAYERCapitalizedEnglishWordsStr or SECKEYPrivateKeyStr. + #. **Private functions** should have the form layer_Body(), where layer is the all lower case + prefix for what layer the function lives in, and Body is camel case English words. Private + functions include functions that may be "public" in a C sense, but are not exported out of the + layer. For example: layer_CapitalizedEnglishWords() or pk11_GenerateKeyID(). + #. **Public macros** should have the form LAYER_BODY(), where LAYER is an all caps prefix for + what layer the macro lives in, and BODY is English words, all in upper case, separated by + underscores. For example: LAYER_UPPER_CASE_ENGLISH_WORDS() or DER_CONVERT_BIT_STRING(). + #. **Structure members** for exposed data structures should have the form capitalizedEnglishWords + (the first letter uncapitalized). For example: PK11RSAGenParamsStr.\ **keySizeInBits** + #. For **members of enums**, our current API has no standard (typedefs for enums should follow + the Data types standard). There seem to be three reasonable options: + + #. Enum members have the same standard as exposed data structure members. + #. Enum members have the same standard as data types. + #. Enum members have the same standard as public macros (minus the '()' of course). + + Options 2 and 3 are the more preferred options. Option 1, currently the most common used for + enums, actually creates namespace pollution. + #. **Callback functions**, and functions used in function tables, should have a typedef used to + define the complete signature of the given function. Function typedefs should have the + following format: LAYERBody(), with the same definitions for LAYER as public functions, and + Body is camel case English words. For example: LAYERCapitalizedEnglishWords or + SECKEYPrivateKey. + +.. _opaque_data_structures: + +`Opaque Data Structures <#opaque_data_structures>`__ +---------------------------------------------------- + +.. container:: + + There are many data structures in the security library whose definition is effectively private, + to the portion of the security library that defines and operates on those data structures. + External code does not have access to these definitions. The goal here is to increase the + opaqueness of these structures. This will allow us to modify the size, definition, and format of + these data structures in future releases, without interfering with the operation of existing + applications that use the security library. + + The first task is to ensure the data structure definition lives in a private header file, while + its declaration lives in the public. The current standard in the security library is to typedef + the data structure name, the easiest way to accomplish this would be to add the typedef to the + public header file. + + For example, for the structure SECMyOpaqueData you would add: + + .. code:: + + typedef struct SECMyOpaqueDataStr SECMyOpaqueData; + + and add the actual structure definition to the private header file. In this same example: + + .. code:: + + struct SECMyOpaqueDataStr { + unsigned long myPrivateData1; + unsigned long myPrivateData2; + char *myName; + }; + + the second task is to determine if individual data fields, within the data structure, are part of + the API. One example may be the peerCert field, in an SSL data structure. Accessor functions, for + these data elements, should be added to the API. + + There can be legitimate exceptions to this 'make everything opaque' rule. For example, in + container structures, such as SECItem, or maybe linked list data structures. These data + structures need to be examined on a case by case basis, to determine if + + #. They are truly stable and will not change in future release + #. It is necessary for the callers of the API to know the size of these structures, as they may + allocate new ones and pass them down. + +.. _memory_allocation_with_arenas: + +`Memory Allocation with Arenas <#memory_allocation_with_arenas>`__ +------------------------------------------------------------------ + +.. container:: + + This section discusses memory allocation using arenas. NSS code uses arenas, and this section + explains some of the improvements we are making. + + NSS makes use of traditional memory allocation functions, wrapping NSPR's PR_Alloc in a util + function called PORT_Alloc. Though NSS makes further use of an NSPR memory-allocation facility + which uses 'Arenas' and 'ArenaPools'. This was added via javascript; a fast, lightweight, + non-thread-safe (though 'free-threaded') implementation. + + Experience shows that users of the security library expect arenas to be threadsafe, so we added + locking, and other useful changes. + + - There has always been confusion as to the difference between Arenas and ArenaPools. We will + simplify down to one logical 'memory bucket' type. Consensus called this type NSSArena. + - We have lots of code which takes an optional arena pointer, using the arena if there is one, + or alternatively the heap if there isn't. Therefore, we wrap that logic into the allocators. + Knowing what to then free does takes discipline not to leak memory, but it simplifies things a + lot. Also, the implementation of free works (doesn't crash), no matter if from an arena, or + the heap, as long as from our allocators. Combined with purify, this also helps us catch cases + where things being allocated by one allocator are freed by another, which is a common Windows + pitfall. + - The security code often wants to be sure to zero memory, when it's being freed; we'll add it + to the primitives to deal with. + + The ARENA_THREADMARK preprocessor definition (default in debug builds), and code it encloses, + will add some checking for the following situation: + + #. Thread A marks the arena, and allocates some memory from it. + #. Thread B allocates some memory from the arena. + #. Thread A releases the arena back to the mark. + #. Thread B now finds itself with a pointer to released data. + #. Some thread -- doesn't matter which -- allocates some data from the arena; this may overlap + the chunk thread B has. + #. Boom! + + Threadmark code notes the thread ID, whenever an arena is marked, and disallows any allocations + or marks by any other thread. (Frees are allowed.) + + The ARENA_DESTRUCTOR_LIST preprocessor definition, and the code it encloses, are an effort to + make the following work together: + + #. Arenas, letting you allocate stuff and then removing them all at once + #. Lazy creation of pure-memory objects from ASN.1 blobs, for example use of NSSPKIXCertificate + doesn't drag all the code in for all constituent objects, unless they're actually being used + #. Our agressive pointer-tracking facility + + All these are useful, but they don't combine well. Now some of the pointer-tracking pressure has + eased off, we can drop its use when it becomes too difficult. + + Many routines are defined to take an NSSArena \*arenaOpt argument. This means if an arena is + specified (non-null), it is used, otherwise (null) the routine uses the heap. You can think of + the heap as a default arena you can't destroy. + +.. _error_handling: + +`Error Handling <#error_handling>`__ +------------------------------------ + +.. container:: + + NSS 3.0 introduces the concept of an error stack. When something goes wrong, the call stack + unwinds, with routines returning an error indication. Each level which flags a problem, adds its + own error number to the stack. At the bottom of the stack is the fundamental error, for example: + file not found, and on top is an error precisely relating to what you are doing. + + .. note:: + + Note: Error stacks are vertical, and never horizontal. If multiple things go wrong + simultaneously, and you want to report them all, use another mechanism. + + Errors, though not integers, are done as external constants, instead of preprocessor definitions. + This is so any additional error doesn't trigger the entire tree to rebuild. Likewise, the + external references to errors are made in the prototypes files, with the functions which can + return them. Error stacks are thread-private. + + The usual semantic is that public routines clear the stack first, private routines don't. + Usually, every public routine has a private counterpart, and the implementation of the public + routine looks like this: + + .. code:: + + NSSImplement rv * + NSSType_Method + ( + NSSType *t, + NSSFoo *arg1, + NSSBar *arg2 + ) + { + nss_ClearErrorStack(); + + #ifdef DEBUG + if( !nssFoo_verifyPointer(arg1) ) return (rv *)NULL; + if( !nssBar_verifyPointer(arg2) ) return (rv *)NULL; + #endif /* DEBUG */ + + return nssType_Method(t, arg1, arg2); + } + + Aside from error cases, all documented entry points should check pointers in a debug, wherever + possible. Pointers to user-supplied buffers, and templates, should be checked against NULL. + Pointers to context-style functions should be checked using special debug macros. These macros + only define code when DEBUG is turned on, providing a way for systems to register, deregister, + and check valid pointers. + + SECPORT_DECL_PTR_CLASS(*classname*, *size*) - declare a class of pointers (labelled *classname*) + this object file needs to check. This class is local only to this object file. *Size* is the + expected number of pointers of type *classname*. + + SECPORT_DECL_GLOBAL_PTR_CLASS(*classname*, *size*) - same as above except *classname* can be used + in other object files. + + SECPORT_ADD_POINTER(*classname*, *pointer*) - Add *pointer* as a valid pointer for + class\ *classname*. This is usually called by a Create function. + + SECPORT_VERIFY_POINTER(*classname*, *pointer*, *secError*, *returnValue*)- Check if a given + *pointer* really belongs to the requested class. If it doesn't set the error *secError* and + return the value *returnValue*. + + SECPORT_REMOVE_POINTER(*classname*, *pointer*) - Remove a pointer from the valid list. Usually + called by a destroy function. + + Finally, error logging should be added an documented when debug is turned on. Interfaces for + these are in NSPR. + +.. _thread_safety: + +`Thread Safety <#thread_safety>`__ +---------------------------------- + +.. container:: + + Code developed using the NSS APIs needs to make use of thread safety features. First to examine + is **object creation** and **deletion**. + + Object creation is usually not a problem. No other threads have access to allocated memory just + created. Exceptions to this include objects which are created on the fly, or as global objects. + + Deletion, on the other hand, may be trickier. Threads may be referencing the object at the same + time a another thread tries to delete it. The semantics depend on the way the application uses + the object, also how and when the application wants to destroy it. For some data structures, this + problem can be removed by protected reference counting. The object does not disappear until all + users have released it. + + Next we examine **global data**, including function local static structures. Just initialized, + and never to be changed global data, does not need to protection from mutexes. We should also + determine if global data should be moved to a session context (see `session + context <#sessioncontext>`__ and `global effects <#globaleffects>`__ below). + + .. note:: + + Note: Permanent objects, like data in files, databases, tokens, etc. should be treated as + global data. Global data which is changed rarely, should be protected by reader/writer locks. + + Aside from global data, **allocated data** that gets modified needs to be examined. Data that's + just been allocated, within a function, is safe to modify. No other code has access to that data + pointer. Once that data pointer is made visible to the 'outside', either by returning the + pointer, or attaching the pointer to an existing visible data structure, access to the data + should be protected. Data structures that are read only, like SECKEYPublicKeys or PK11SymKeys, + need not be protected. + + Many of the data structures in the security code contain some sort of **session state** or + **session context**. These data structures may be accessed without data protection as long as: + + #. This semantic is documented in the functions which use these data structures. + #. These data structures are used for single streams, and not reused. + + Examples of these data in structures may include things like the PKCS #7 ContentInfo structure. + Example code should be included in the documentation, to show how to safely use these data + objects. + + A major type of global and allocated data that should be examined is various **data on lists**. + Queued, linked, and hash table stored objects should be examined with special care. Make sure + adding, removing, accessing, and destroying these objects are all safe operations. + + There are a number of strategies, and entire books about how to safely access data on lists. Some + simple strategies and their issues: + + - **Use hash tables:** Hash table lookups are usually quite fast, limiting the contention on the + lock. This is best for large lists of objects. Be sure to calculate the hash value first, then + only lock over the hash table value itself. Be sure to increment the reference count, on the + returned object, before unlocking. Examples of hash tables can be found in + security/nss/lib/certdb/pcertdb.c + - **Lock over the entire search:** For small linked listed, queues, or arrays, you can lock over + the entire search. This strategy is best when lists are short, or even better if lists are + relatively read only (they don't change very often) and using reader/writer locks. + - **Copy the linked list:** Instead of operating on the global list, you can copy the list. This + also requires small lists. + - **Lock over single element with retry:** For medium sized lists, you can secure the reference + to each element, complete a test, then detect if the given element has been removed from the + list. In the case of removal, the search can either be either restarted, or terminated. This + method is a more complicated than the other methods: requiring the calling of search code + tolerant to often repeated element inspection. + - Examples of the previous strategies can be found in + `security/nss/lib/pk11wrap/pk11slot.c. <https://searchfox.org/mozilla-central/source/security/nss/lib/pk11wrap/pk11slot.c>`__ + + Where possible use the NSPR list primitives. From these you can even set up SECUtil style + thread-safe lists that use some combination of the above strategies. + + In order to be fully thread safe, your code must understand the semantics of the **service + functions** it calls, and whether they are thread safe. For now, we should internally document + which service functions we call, and how we expect them to behave in a threaded environment. + + Finally, from an API point of view, we should examine functions which have **global effects**. + Functions like XXX_SetDefaultYYY(); should not operate on global data, particularly if they may + be called multiple times, to provide different semantics for different operations. For example, + the following should be avoided : + + - SEC_SetKey(keyForOperation); + SEC_Encrypt(Data,Length); + + Instead, a context handle should be created, and the SEC_SetKey() function, above, made on that + handle. Fortunately most of the existing API has the correct semantics. + + The exception to this global effects rule may be functions which set global state for an + application at initialization time. + +.. _methodsfunctions_design: + +`Methods/Functions Design <#methodsfunctions_design>`__ +------------------------------------------------------- + +.. container:: + +.. _init_shutdown_functions: + +`Init, Shutdown Functions <#init_shutdown_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + If a layer has some global initialization tasks, which need to be completed before the layer can + be used, that layer should supply an initialization function of the form LAYER_Init(). If an + initialization function is supplied, a corresponding LAYER_Shutdown() function should also be + supplied. LAYER_INIT() should increment a count of the number of times it is called, and + LAYER_Shutdown() should decrement that count, and shutdown when the count reaches '0'. + +.. _open_close_functions: + +`Open, Close Functions <#open_close_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Open functions should have a corresponding close function. Open and close function are not + reference counted, like init and shutdown functions. + +.. _creation_functions: + +`Creation Functions <#creation_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + In general, data objects should all have functions which create them. These functions should have + the form LAYER_CreateDataType[FromDataType](). For instance generating a new key would change + from PK11_KeyGen() to PK11_CreateSymKey(). + +.. _destruction_functions: + +`Destruction Functions <#destruction_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + In the security library we have 3 different ways of saying 'get rid of this data object': Free, + Delete, and Destroy. + + It turns out there are several different semantics of getting rid of a data object too: + + #. decrement the reference count, and when the object goes to '0' free/delete/destroy it + #. destroy it right now, this very instance, not matter what + #. make any permanent objects associated with this data object go away + #. a combination of 1 and 3, or 2 and 3 + + Unfortunately, within the security library Free, Delete, and Destroy are all used + interchangeably, for all sorts of object destruction. For instance, CERT_DestroyCertificate() is + type 1, PK11_DestroySlot() is type 2, and PK11_DestroyTokenObject() is type 3. + + .. note:: + + Note: In non-reference counted functions, types 1 and 2 are the same. + + We are standardizing on the following definitions: + + Destroy - means #1 for reference counted objects, #2 for non reference counted objects. + + Delete - means #3. + + This has the advantage of *not* surfacing the reference countedness of a data object. If you own + a pointer to an object, you must always destroy it. There is no way to destroy an object by + bypassing it's reference count. Also, the signature of public destruction functions do not have + the 'freeit' PRBool, since the structures being freed are opaque. + +.. _dup_copy_and_reference_functions: + +`Dup, Copy, and Reference Functions <#dup_copy_and_reference_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Functions that return a new reference or copy of a given object should have the form + LAYER_DupDataType(). For instance, CERT_DupCertifiate() will remain the same, but + PK11_ReferenceSlot() will become PK11_DupSlot(), and PK11_CloneContext() will become + PK11_DupContext(). + +.. _search_functions: + +`Search Functions <#search_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + There are several different kinds of searches done via the security library. The first is a + search for exactly one object, meeting a given criteria. These types of searches include + CERT_FindCertByDERCert(), PK11_FindAnyCertFromDERCert(), PK11_FindKeyByCert(), + PK11_GetBestSlot(). These functions should all have the form LAYER_FindDataType[ByDataType](). + + The second kind of search, looks for all the objects that match a given criteria. These functions + operate on a variety of levels. Some return allocated arrays of data, some return linked lists of + data, others use callbacks to return data elements one at a time. Unfortunately, there are good + reasons to maintain all these types. So here are some guidelines to make them more manageable: + + All callback operating search functions should be in the low level of the API, if exposed at all. + Developers dealing with SSL and PKCS #7 layers should not have to see any of these functions. + These functions should have the form LAYER_TraverseStorageObjectOrList(). + + List and Array returning functions should be available at the higher layers of the API, most + wrapping LAYER_Traverse() functions. They should have the form + LAYER_LookupDataType{List|Array}[ByDataType](). + +.. _accesssor_functions: + +`Accesssor Functions <#accesssor_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Accessor Functions should take the following formats: + + | LAYER_DataTypeGetElement() -- Get a specific element of a data structure. + | LAYER_DataTypeSetElement() -- Set a specific element of a data structure. + | LAYER_DataTypeExtractDataType() -- Get a pointer to the second data type which was derived for + elements of the first data type. + + Examples: PK11_SlotGetSeries(), PK11_SymKeyGetSeries(), CERT_CertificateExtractPublicKey() + +.. _parameter_ordering: + +`Parameter ordering <#parameter_ordering>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Most functions will have a 'Natural' ordering for parameters. To keep consistency we should have + some minimal parameter consistency. For most functions, they can be seen as operating on a + particular object. This object, that the function is operating on, should come first. For + instance, in most SSL functions this is the NSPR Socket, or the SSL Socket structure: Update, + final, encrypt, decrypt type functions operating on their state contexts, etc. + + All encrypt and decrypt functions, which return data inline, should have a consistent signature: + + .. code:: + + SECStatus MY_FunctionName(MyContext *context, + unsigned char *outBuf, + SECBufferLen *outLen, + SECBufferLenmaxOutLength, + unsigned char *inBuf, + SECBufferLeninLen) + + Encrypt and decrypt like functions which have different properties, additional parameters, + callbacks, etc., should insert their additional parameters between the context (first parameter) + and the output buffer. + + All hashing update, MACing update, and encrypt/decrypt functions which act like filters should + have a consistent signature: + + .. code:: + + SECStatus PK11_DigestOp(PK11Context *context, + unsigned char *inBuf, + SECBufferLeninLen) + + Functions like these which have different properties, for example, additional parameters, + callbacks, etc., should insert their additional parameters between the context (first parameter) + and the input buffer. + + Within your layer, multiple similar functions should have consistent parameter order. + +.. _callback_functions: + +`Callback Functions <#callback_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Callback functions should all contain an opaque parameter (void \*) as their first argument, + passed by the original caller. Callbacks which are set, like SSL callbacks, should have defaults + which provide generally useful semantics.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_config_options/index.rst b/security/nss/doc/rst/legacy/nss_config_options/index.rst new file mode 100644 index 0000000000..7f62e36f90 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_config_options/index.rst @@ -0,0 +1,217 @@ +.. _mozilla_projects_nss_nss_config_options: + +NSS Config Options +================== + +.. _nss_config_options_format: + +` NSS Config Options Format <#nss_config_options_format>`__ +----------------------------------------------------------- + +.. container:: + + The specified ciphers will be allowed by policy, but an application may allow more by policy + explicitly: + + .. code:: + + config="allow=curve1:curve2:hash1:hash2:rsa-1024..." + + Only the specified hashes and curves will be allowed: + + .. code:: + + config="disallow=all allow=sha1:sha256:secp256r1:secp384r1" + + Only the specified hashes and curves will be allowed, and RSA keys of 2048 or more will be + accepted, and DH key exchange with 1024-bit primes or more: + + .. code:: + + config="disallow=all allow=sha1:sha256:secp256r1:secp384r1:min-rsa=2048:min-dh=1024" + + A policy that enables the AES ciphersuites and the SECP256/384 curves: + + .. code:: + + config="allow=aes128-cbc:aes128-gcm::HMAC-SHA1:SHA1:SHA256:SHA384:RSA:ECDHE-RSA:SECP256R1:SECP384R1" + + Turn off md5 + + .. code:: + + config="disallow=MD5" + + Turn off md5 and sha1 only for SSL + + .. code:: + + config="disallow=MD5(SSL):SHA1(SSL)" + + Disallow values are parsed first, and then allow values, independent of the order in which they + appear. + + .. code:: + + Future key words (not yet implemented): + enable: turn on ciphersuites by default. + disable: turn off ciphersuites by default without disallowing them by policy. + flags: turn on the following flags: + ssl-lock: turn off the ability for applications to change policy with + the SSL_SetCipherPolicy (or SSL_SetPolicy). + policy-lock: turn off the ability for applications to change policy with + the call NSS_SetAlgorithmPolicy. + ssl-default-lock: turn off the ability for applications to change cipher + suite states with SSL_EnableCipher, SSL_DisableCipher. + + .. rubric:: ECC Curves + :name: ecc_curves + + | + | PRIME192V1 + | PRIME192V2 + | PRIME192V3 + | PRIME239V1 + | PRIME239V2 + | PRIME239V3 + | PRIME256V1 + | SECP112R1 + | SECP112R2 + | SECP128R1 + | SECP128R2 + | SECP160K1 + | SECP160R1 + | SECP160R2 + | SECP192K1 + | SECP192R1 + | SECP224K1 + | SECP256K1 + | SECP256R1 + | SECP384R1 + | SECP521R1 + | C2PNB163V1 + | C2PNB163V2 + | C2PNB163V3 + | C2PNB176V1 + | C2TNB191V1 + | C2TNB191V2 + | C2TNB191V3 + | C2ONB191V4 + | C2ONB191V5 + | C2PNB208W1 + | C2TNB239V1 + | C2TNB239V2 + | C2TNB239V3 + | C2ONB239V4 + | C2ONB239V5 + | C2PNB272W1 + | C2PNB304W1 + | C2TNB359V1 + | C2PNB368W1 + | C2TNB431R1 + | SECT113R1 + | SECT131R1 + | SECT131R1 + | SECT131R2 + | SECT163K1 + | SECT163R1 + | SECT163R2 + | SECT193R1 + | SECT193R2 + | SECT233K1 + | SECT233R1 + | SECT239K1 + | SECT283K1 + | SECT283R1 + | SECT409K1 + | SECT409R1 + | SECT571K1 + | SECT571R1 + + .. rubric:: Hashes + :name: hashes + + | + | MD2 + | MD4 + | MD5 + | SHA1 + | SHA224 + | SHA256 + | SHA384 + | SHA512 + + .. rubric:: MACS + :name: macs + + | HMAC-SHA1 + | HMAC-SHA224 + | HMAC-SHA256 + | HMAC-SHA384 + | HMAC-SHA512 + | HMAC-MD5 + + .. rubric:: Ciphers + :name: ciphers + + | AES128-CBC + | AES192-CBC + | AES256-CBC + | AES128-GCM + | AES192-GCM + | AES256-GCM + | CAMELLIA128-CBC + | CAMELLIA192-CBC + | CAMELLIA256-CBC + | SEED-CBC + | DES-EDE3-CBC + | DES-40-CBC + | DES-CBC + | NULL-CIPHER + | RC2 + | RC4 + | IDEA + + .. rubric:: SSL Key exchanges + :name: ssl_key_exchanges + + | RSA + | RSA-EXPORT + | DHE-RSA + | DHE-DSS + | DH-RSA + | DH-DSS + | ECDHE-ECDSA + | ECDHE-RSA + | ECDH-ECDSA + | ECDH-RSA + + .. rubric:: Restrictions for asymmetric keys (integers) + :name: restrictions_for_asymmetric_keys_(integers) + + | RSA-MIN + | DH-MIN + | DSA-MIN + + .. rubric:: Constraints on SSL Protocols Versions (integers) + :name: constraints_on_ssl_protocols_versions_(integers) + + | TLS-VERSION-MIN + | TLS-VERSION-MAX + + .. rubric:: Constraints on DTLS Protocols Versions (integers) + :name: constraints_on_dtls_protocols_versions_(integers) + + | DTLS-VERSION-MIN + | DTLS-VERSION-MAX + + .. rubric:: Policy flags for algorithms + :name: policy_flags_for_algorithms + + | SSL + | SSL-KEY-EXCHANGE + | KEY-EXCHANGE + | CERT-SIGNATURE + | SIGNATURE + | ALL + | NONE
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_developer_tutorial/index.rst b/security/nss/doc/rst/legacy/nss_developer_tutorial/index.rst new file mode 100644 index 0000000000..3626909da2 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_developer_tutorial/index.rst @@ -0,0 +1,277 @@ +.. _mozilla_projects_nss_nss_developer_tutorial: + +NSS Developer Tutorial +====================== + +.. _nss_coding_style: + +`NSS Coding Style <#nss_coding_style>`__ +---------------------------------------- + +`Formatting <#formatting>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + **Line length** should not exceed 80 characters. + + **Indentation level** is 4. + + **Tabs** are used heavily in many NSS source files. Try to stay consistent when you modify + existing code. The proper use of tabs has often been confusing for new NSS developers, so in + ``nss/lib/ssl``, we're gradually removing the use of tabs. + + **Curly braces**: both of the following styles are allowed: + + .. code:: + + if (condition) { + action1(); + } else { + action2(); + } + + Or: + + .. code:: + + if (condition) + { + action1(); + } + else + { + action2(); + } + + The former style is more common. When modifying existing code, try to stay consistent. In new + code, prefer the former style, as it conserves vertical space. + + When a block of code consists of a single statement, NSS doesn’t require curly braces, so both of + these examples are fine: + + .. code:: + + if (condition) { + action(); + } + + Or: + + .. code:: + + if (condition) + action(); + + although the use of curly braces is more common. + + **Multiple-line comments** should be formatted as follows: + + .. code:: + + /* + * Line1 + * Line2 + */ + + or + + .. code:: + + /* + ** Line 1 + ** Line 2 + */ + + The following styles are also common, because they conserve vertical space: + + .. code:: + + /* Line1 + * Line2 + */ + + or + + .. code:: + + /* Line1 + ** Line2 + */ + + or + + .. code:: + + /* Line1 + * Line2 */ + +`Naming <#naming>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Public functions are named ``FOO_DoOneAction``. + + Global, but unexported functions, are usually named ``foo_DoOneAction``. + + Variable, and function parameter names, always start with a lowercase letter. The most common + style is ``fooBarBaz``, although ``foobarbaz`` and ``foo_bar_baz`` are also used. + +`Miscellaneous <#miscellaneous>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + **goto** can be used, to simplify resource deallocation, before returning from a function. + + A data buffer is usually represented as: + + .. code:: c + + unsigned char *data; + unsigned int len; + + The buffer pointer is ``unsigned char *``, as opposed to ``void *``, so we can perform pointer + arithmetic without casting. Use ``char *`` only if the data is interpreted as text characters. + + For historical reasons, the buffer length is ``unsigned int``, as opposed to ``size_t``. + Unfortunately, this can be a source of integer overflow bugs on 64-bit systems. + +.. _c_features: + +`C Features <#c_features>`__ +---------------------------- + +.. container:: + + NSS requires C99. However, not all features from C99 are equally available. + + - Variables can be declared, at the point they are first used. + - The ``inline`` keyword can be used. + - Variadic macro arguments are permitted, but their use should be limited to using + ``__VA_ARGS__``. + - The exact-width integer types in NSPR should be used, in preference to those declared in + ``<stdint.h>`` (which will be used by NSPR in the future). + - Universal character names are not permitted, as are wide character types (``char16_t`` and + ``char32_t``). NSS source should only include ASCII text. Escape non-printing characters + (with ``\x`` if there is no special escape such as \\r, \\n, and \\t) and avoid defining + string literals that use non-ASCII characters. + - One line comments starting with ``//`` are permitted. + + Check with nss-dev@ before using a language feature not already used, if you are uncertain. + Please update this list if you do. + + These restrictions are different for C++ unit tests, which can use most C++11 features. The + `Mozilla C++ language features + guide <https://developer.mozilla.org/en-US/docs/Using_CXX_in_Mozilla_code>`__, and the `Chromium + C++ usage guide <https://chromium-cpp.appspot.com/>`__, list C++ features that are known to be + widely available and compatible. You should limit features to those that appear in both guides. + Ask on nss-dev@ if you think this is restrictive, or if you wish to prohibit a specific feature. + +.. _nss_c_abi_backward_compatibility: + +`NSS C ABI backward compatibility <#nss_c_abi_backward_compatibility>`__ +------------------------------------------------------------------------ + +`Functions <#functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Exported functions cannot be removed. + + The function prototype of an exported function, cannot be changed, with these exceptions: + + - A ``Foo *`` parameter can be changed to ``const Foo *``. This change is always safe. + + - Sometimes an ``int`` parameter can be changed to ``unsigned int``, or an ``int *`` parameter + can be changed to ``unsigned int *``. Whether such a change is safe needs to be reviewed on a + case-by-case basis. + +`Types <#types>`__ +------------------ + +`Structs <#structs>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Members of an exported struct, cannot be reordered or removed. + + Under certain circumstances, it is safe to add new members to an exported struct at the end. + + Opaque structs give us complete freedom to change them, but require applications to call NSS + functions, to allocate and free them. + +`Enums <#enums>`__ +~~~~~~~~~~~~~~~~~~ + +.. container:: + + The numeric values of public enumerators cannot be changed. To stress this fact, we often + explicitly assign numeric values to enumerators, rather than relying on the values assigned by + the compiler. + +.. _symbol_export_lists: + +`Symbol export lists <#symbol_export_lists>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The ``manifest.mn`` file, in a directory in the NSS source tree, specifies which headers are + public, and which headers are private. + + Public headers are in the ``EXPORTS`` variable. + + Private headers,which may be included by files in other directories, are in the + ``PRIVATE_EXPORTS`` variable. + + Private headers, that are only included by files in the same directory, are not listed in either + variable. + + Only functions listed in the symbol export lists (``nss.def``, ``ssl.def``, ``smime.def``, etc.) + are truly public functions. Unfortunately, public headers may declare private functions, for + historical reasons. The symbol export lists are the authoritative source of public functions. + +.. _behavioral_changes: + +`Behavioral changes <#behavioral_changes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + **Bug/quirk compatible**: Occasionally we cannot fix a bug, because applications may depend on + the buggy behavior. We would need to add a new function to provide the desired behavior. + + Similarly, **new options** often need to be disabled by default. + +.. _nss_reviewfeature_approval_process: + +`NSS review/feature approval process <#nss_reviewfeature_approval_process>`__ +----------------------------------------------------------------------------- + +.. container:: + + NSS doesn’t have 'super reviewers'. We wish to increase the number of NSS developers, who have + broad understanding of NSS. + + One review is usually enough for the review to pass. For critical code reviews, such as a patch + release of a stable branch, two reviews may be more reasonable. + + For new features, especially those that appear controversial, try to find a reviewer from a + different company or organization than your own, to avoid any perceptions of bias. + +.. _update_nss_in_mozilla-inbound_and_mozilla-central: + +`Update NSS in mozilla-inbound and mozilla-central <#update_nss_in_mozilla-inbound_and_mozilla-central>`__ +---------------------------------------------------------------------------------------------------------- + +.. container:: + + The procedure is documented at + `https://developer.mozilla.org//en-US/docs/Mozilla/Developer_guide/Build_Instructions/Updating_NSPR_or_NSS_in_mozilla-central <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Updating_NSPR_or_NSS_in_mozilla-central>`__. + + If it is necessary to apply private patches, please document them in + ``<tree>/security/patches/README``.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_release_notes_template/index.rst b/security/nss/doc/rst/legacy/nss_release_notes_template/index.rst new file mode 100644 index 0000000000..7ae2cbd085 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_release_notes_template/index.rst @@ -0,0 +1,126 @@ +.. _mozilla_projects_nss_nss_release_notes_template: + +NSS release notes template +========================== + +.. _draft_(remove_line_when_document_is_finished): + +`DRAFT (remove line when document is finished) <#draft_(remove_line_when_document_is_finished)>`__ +-------------------------------------------------------------------------------------------------- + +.. container:: + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + | The NSS team has released Network Security Services (NSS) 3.XX, which is a minor release. + | or + | Network Security Services (NSS) 3.XX.y is a patch release for NSS 3.XX. The bug fixes in NSS + 3.XX.y are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_XX_RTM. NSS 3.XX requires NSPR 4.XX or newer. + + NSS 3.XX source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_XX_RTM/src/ (make a link) + +.. _new_in_nss_3.xx: + +`New in NSS 3.XX <#new_in_nss_3.xx>`__ +-------------------------------------- + +.. container:: + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + either: + + No new functionality is introduced in this release. This is a patch release to fix ... + + or: + + - ... + + .. rubric:: New Functions + :name: new_functions + + - *in \___.h* + + - **function** - description + + .. rubric:: New Types + :name: new_types + + - *in \___.h* + + - **type** - description. + + .. rubric:: New Macros + :name: new_macros + + - *in \___.h* + + - **macro** - description + +.. _notable_changes_in_nss_3.xx: + +`Notable Changes in NSS 3.XX <#notable_changes_in_nss_3.xx>`__ +-------------------------------------------------------------- + +.. container:: + + - ... + +.. _bugs_fixed_in_nss_3.xx: + +`Bugs fixed in NSS 3.XX <#bugs_fixed_in_nss_3.xx>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.XX: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.XX + (make a link) + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank ... for responsibly disclosing the issue by + providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.XX.y shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.XX.y shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/index.rst b/security/nss/doc/rst/legacy/nss_releases/index.rst new file mode 100644 index 0000000000..74858e969d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/index.rst @@ -0,0 +1,161 @@ +.. _mozilla_projects_nss_nss_releases: + +Release notes for recent versions of NSS +======================================== + +.. container:: + + The current **Stable** release of NSS is 3.64, which was released on **15 April 2021**. + (:ref:`mozilla_projects_nss_nss_3_64_release_notes`) + + The current **ESR** releases of NSS are 3.44.4 + (:ref:`mozilla_projects_nss_nss_3_44_4_release_notes`), intended for Firefox ESR 68, which was + released on **19 May 2020**, and 3.53.1 :ref:`mozilla_projects_nss_nss_3_53_1_release_notes`, + intended for Firefox ESR 78, which was released on **16 June 2020**. + +.. _past_releases: + +`Past releases <#past_releases>`__ +---------------------------------- + +.. container:: + + - :ref:`mozilla_projects_nss_nss_3_63_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_63_release_notes` + - :ref:`mozilla_projects_nss_nss_3_62_release_notes` + - :ref:`mozilla_projects_nss_nss_3_61_release_notes` + - :ref:`mozilla_projects_nss_nss_3_60_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_60_release_notes` + - :ref:`mozilla_projects_nss_nss_3_59_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_59_release_notes` + - :ref:`mozilla_projects_nss_nss_3_58_release_notes` + - :ref:`mozilla_projects_nss_nss_3_57_release_notes` + - :ref:`mozilla_projects_nss_nss_3_56_release_notes` + - :ref:`mozilla_projects_nss_nss_3_55_release_notes` + - :ref:`mozilla_projects_nss_nss_3_54_release_notes` + - :ref:`mozilla_projects_nss_nss_3_53_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_53_release_notes` + - :ref:`mozilla_projects_nss_nss_3_52_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_44_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_52_release_notes` + - :ref:`mozilla_projects_nss_nss_3_51_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_51_release_notes` + - :ref:`mozilla_projects_nss_nss_3_50_release_notes` + - :ref:`mozilla_projects_nss_nss_3_49_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_49_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_49_release_notes` + - :ref:`mozilla_projects_nss_nss_3_48_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_48_release_notes` + - :ref:`mozilla_projects_nss_nss_3_47_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_47_release_notes` + - :ref:`mozilla_projects_nss_nss_3_46_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_46_release_notes` + - :ref:`mozilla_projects_nss_nss_3_45_release_notes` + - :ref:`mozilla_projects_nss_nss_3_44_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_44_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_44_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_44_release_notes` + - :ref:`mozilla_projects_nss_nss_3_43_release_notes` + - :ref:`mozilla_projects_nss_nss_3_42_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_42_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_8_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_7_release_notes` + - :ref:`mozilla_projects_nss_nss_3_41_release_notes` + - :ref:`mozilla_projects_nss_nss_3_40_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_6_release_notes` + - :ref:`mozilla_projects_nss_nss_3_40_release_notes` + - :ref:`mozilla_projects_nss_nss_3_39_release_notes` + - :ref:`mozilla_projects_nss_nss_3_38_release_notes` + - :ref:`mozilla_projects_nss_nss_3_37_3release_notes` + - :ref:`mozilla_projects_nss_nss_3_37_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_37_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_5_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_36_release_notes` + - :ref:`mozilla_projects_nss_nss_3_35_release_notes` + - :ref:`mozilla_projects_nss_nss_3_34_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_34_release_notes` + - :ref:`mozilla_projects_nss_nss_3_33_release_notes` + - :ref:`mozilla_projects_nss_nss_3_32_release_notes` + - :ref:`mozilla_projects_nss_nss_3_31_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_31_release_notes` + - :ref:`mozilla_projects_nss_nss_3_30_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_30_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_30_release_notes` + - :ref:`mozilla_projects_nss_nss_3_29_5_release_notes` + - :ref:`mozilla_projects_nss_nss_3_29_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_29_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_29_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_29_release_notes` + - :ref:`mozilla_projects_nss_nss_3_28_5_release_notes` + - :ref:`mozilla_projects_nss_nss_3_28_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_28_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_28_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_28_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_28_release_notes` + - :ref:`mozilla_projects_nss_nss_3_27_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_27_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_27_release_notes` + - :ref:`mozilla_projects_nss_nss_3_26_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_26_release_notes` + - :ref:`mozilla_projects_nss_nss_3_25_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_25_release_notes` + - :ref:`mozilla_projects_nss_nss_3_24_release_notes` + - :ref:`mozilla_projects_nss_nss_3_23_release_notes` + - :ref:`mozilla_projects_nss_nss_3_22_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_22_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_22_release_notes` + - :ref:`mozilla_projects_nss_nss_3_21_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_21_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_21_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_21_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_21_release_notes` + - :ref:`mozilla_projects_nss_nss_3_20_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_20_release_notes` + - :ref:`mozilla_projects_nss_nss_3_19_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_19_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_19_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_19_release_notes` + - :ref:`mozilla_projects_nss_nss_3_18_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_18_release_notes` + - :ref:`mozilla_projects_nss_nss_3_17_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_17_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_17_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_17_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_17_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_6_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_5_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_2_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_2_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_2_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_16_release_notes` + - :ref:`mozilla_projects_nss_nss_3_15_5_release_notes` + - :ref:`mozilla_projects_nss_nss_3_15_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_15_3_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_15_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_15_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_15_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_15_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_5_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_4_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_release_notes` + - :ref:`mozilla_projects_nss_release_notes` + +.. _future_releases: + +`Future releases <#future_releases>`__ +-------------------------------------- + +.. container:: + + Release planning is done on the Mozilla wiki: `NSS:Release + Versions <https://wiki.mozilla.org/NSS:Release_Versions>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/jss_4.4.0_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/jss_4.4.0_release_notes/index.rst new file mode 100644 index 0000000000..77da7f7681 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/jss_4.4.0_release_notes/index.rst @@ -0,0 +1,109 @@ +.. _mozilla_projects_nss_jss_4_4_0_release_notes: + +JSS 4.4.0 Release Notes +======================= + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Java Security Services (JSS) team has released JSS 4.4.0, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is JSS_4_4\ **\_20170313**. JSS 4.4.0 requires Netswork Security Services (NSS) 3.29.1 + and Netscape Portable Runtime (NSPR) 4.13.1 or newer. + + JSS 4.4.0 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + `https://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_4_0_RTM/src/ <https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_30_RTM/src/>`__ + +.. _new_in_jss_4.40: + +`New in JSS 4.40 <#new_in_jss_4.40>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: New Functions + :name: new_functions + + New Macros + +.. _notable_changes_in_jss_4.40: + +`Notable Changes in JSS 4.40 <#notable_changes_in_jss_4.40>`__ +-------------------------------------------------------------- + +.. container:: + + - Picks up work done downstream for Fedora and RHEL and used by various Linux distributions with + includes:. + - Support for IPv6. + - Support for TLS v1.1 and TLS v1.2 via NSS though JSS. + +.. _bugs_fixed_in_jss_4.4.0: + +`Bugs fixed in JSS 4.4.0 <#bugs_fixed_in_jss_4.4.0>`__ +------------------------------------------------------ + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 4.4.0: + + https://bugzilla.mozilla.org/buglist.cgi?product=JSS&target_milestone=4.4&target_milestone=4.4&bug_status=RESOLVED&resolution=FIXED + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Build instructions for JSS at https://hg.mozilla.org/projects/jss/file/tip/README + +.. _platform_information: + +`Platform Information <#platform_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - You can check out the source from mercurial via hg clone -r 055aa3ce8a61 + https://hg.mozilla.org/projects/jss + + - JSS 4.4.0 works with OpenJDK versions 1.7 or higher we suggest the latest - OpenJDK 1.8. + - JSS 4.4.0 requires :ref:`mozilla_projects_nss_nss_3_12_5_release_notes` or higher though NSS + 3.28.3 is recommended. + - JSS 4.3.1 requires `NSPR 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/>`__ or + higher though NSPR 3.13 is recommended. + - JSS only supports the native threading model (no green threads). + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + JSS 3.30 shared libraries are not backward compatible with all older JSS 4.3.2 shared libraries. + A program linked with older jSS 4.3.2 shared libraries will not work with JSS 4.4.0 shared + libraries without recompiling or relinking. Furthermore, applications that restrict their use of + jSS APIs to the functions listed in JSS Public Functions will remain compatible with future + versions of the JSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product JSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.12.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.3_release_notes/index.rst new file mode 100644 index 0000000000..06d4a8b1b4 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.3_release_notes/index.rst @@ -0,0 +1,432 @@ +.. _mozilla_projects_nss_nss_3_12_3_release_notes: + +NSS_3.12.3_release_notes.html +============================= + +.. _nss_3.12.3_release_notes: + +`NSS 3.12.3 Release Notes <#nss_3.12.3_release_notes>`__ +-------------------------------------------------------- + +.. _2009-04-01: + +`2009-04-01 <#2009-04-01>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Introduction <#introduction>`__ + - `Distribution Information <#distribution_information>`__ + - `New in NSS 3.12.3 <#new_in_nss_3.12.3>`__ + - `Bugs Fixed <#bugs_fixed>`__ + - `Documentation <#documentation>`__ + - `Compatibility <#compatibility>`__ + - `Feedback <#feedback>`__ + + -------------- + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services (NSS) 3.12.3 is a patch release for NSS 3.12. The bug fixes in NSS + 3.12.3 are described in the "`Bugs Fixed <#bugs_fixed>`__" section below. + + NSS 3.12.3 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + + -------------- + + + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | The CVS tag for the NSS 3.12.3 release is NSS_3_12_3_RTM. NSS 3.12.3 requires `NSPR + 4.7.4 <https://www.mozilla.org/projects/nspr/release-notes/nspr474.html>`__. + | See the `Documentation <#documentation>`__ section for the build instructions. + + NSS 3.12.3 source and binary distributions are also available on ftp.mozilla.org for secure HTTPS + download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_3_RTM/src/. + - Binary distributions: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_3_RTM/. Both debug and + optimized builds are provided. Go to the subdirectory for your platform, DBG (debug) or OPT + (optimized), to get the tar.gz or zip file. The tar.gz or zip file expands to an nss-3.12.3 + directory containing three subdirectories: + + - include - NSS header files + - lib - NSS shared libraries + - bin - `NSS Tools <https://www.mozilla.org/projects/security/pki/nss/tools/>`__ and test + programs + + You also need to download the NSPR 4.7.4 binary distributions to get the NSPR 4.7.4 header files + and shared libraries, which NSS 3.12.3 requires. NSPR 4.7.4 binary distributions are in + https://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.7.4/. + + -------------- + +.. _new_in_nss_3.12.3: + +`New in NSS 3.12.3 <#new_in_nss_3.12.3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Changes in behavior: + - In the development of NSS 3.12.3, it became necessary to change some old library behaviors due + to the discovery of certain vulnerabilities in the old behaviors, and to correct some errors + that had limited NSS's ability to interoperate with cryptographic hardware and software from + other sources. + Most of these changes should cause NO problems for NSS users, but in some cases, some + customers' software, hardware and/or certificates may be dependent on the old behaviors, and + may have difficulty with the new behaviors. In anticipation of that, the NSS team has provided + ways to easily cause NSS to revert to its previous behavior through the use of environment + variables. + Here is a table of the new environment variables introduced in NSS 3.12.3 and information + about how they affect these new behaviors. The information in this table is excerpted from + :ref:`mozilla_projects_nss_reference_nss_environment_variables` + + +--------------------------------+--------------------------------+--------------------------------+ + | **Environment Variable** | **Value Type** | **Description** | + +--------------------------------+--------------------------------+--------------------------------+ + | NSRANDCOUNT | Integer | Sets the maximum number of | + | | (byte count) | bytes to read from the file | + | | | named in the environment | + | | | variable NSRANDFILE (see | + | | | below). Makes NSRANDFILE | + | | | usable with /dev/urandom. | + +--------------------------------+--------------------------------+--------------------------------+ + | NSS_ALLOW_WEAK_SIGNATURE_ALG | Boolean | Enables the use of MD2 and MD4 | + | | (any non-empty value to | hash algorithms inside | + | | enable) | signatures. This was allowed | + | | | by default before NSS 3.12.3. | + +--------------------------------+--------------------------------+--------------------------------+ + | NSS_HASH_ALG_SUPPORT | String | Specifies algorithms allowed | + | | | to be used in certain | + | | | applications, such as in | + | | | signatures on certificates and | + | | | CRLs. See documentation at | + | | | `this | + | | | link | + | | | <https://bugzilla.mozilla.org/ | + | | | show_bug.cgi?id=483113#c0>`__. | + +--------------------------------+--------------------------------+--------------------------------+ + | NSS_STRICT_NOFORK | String | It is an error to try to use a | + | | ("1", | PKCS#11 crypto module in a | + | | "DISABLED", | process before it has been | + | | or any other non-empty value) | initialized in that process, | + | | | even if the module was | + | | | initialized in the parent | + | | | process. Beginning in NSS | + | | | 3.12.3, Softoken will detect | + | | | this error. This environment | + | | | variable controls Softoken's | + | | | response to that error. | + | | | | + | | | - If set to "1" or unset, | + | | | Softoken will trigger an | + | | | assertion failure in debug | + | | | builds, and will report an | + | | | error in non-DEBUG builds. | + | | | - If set to "DISABLED", | + | | | Softoken will ignore forks, | + | | | and behave as it did in | + | | | older versions. | + | | | - If set to any other | + | | | non-empty value, Softoken | + | | | will report an error in | + | | | both DEBUG and non-DEBUG | + | | | builds. | + +--------------------------------+--------------------------------+--------------------------------+ + | NSS_USE_DECODED_CKA_EC_POINT | Boolean | Tells NSS to send EC key | + | | (any non-empty value to | points across the PKCS#11 | + | | enable) | interface in the non-standard | + | | | unencoded format that was used | + | | | by default before NSS 3.12.3. | + | | | The new key point format is a | + | | | DER encoded ASN.1 OCTET | + | | | STRING. | + +--------------------------------+--------------------------------+--------------------------------+ + | NSS_USE_SHEXP_IN_CERT_NAME | Boolean | Tells NSS to allow shell-style | + | | (any non-empty value to | wildcard patterns in | + | | enable) | certificates to match SSL | + | | | server host names. This | + | | | behavior was the default | + | | | before NSS 3.12.3. The new | + | | | behavior conforms to RFC 2818. | + +--------------------------------+--------------------------------+--------------------------------+ + + - New Korean SEED cipher: + + - New macros for SEED support: + + - *in blapit.h:* + NSS_SEED + NSS_SEED_CBC + SEED_BLOCK_SIZE + SEED_KEY_LENGTH + *in pkcs11t.h:* + CKK_SEED + CKM_SEED_KEY_GEN + CKM_SEED_ECB + CKM_SEED_CBC + CKM_SEED_MAC + CKM_SEED_MAC_GENERAL + CKM_SEED_CBC_PAD + CKM_SEED_ECB_ENCRYPT_DATA + CKM_SEED_CBC_ENCRYPT_DATA + *in secmod.h:* + PUBLIC_MECH_SEED_FLAG + *in secmodt.h:* + SECMOD_SEED_FLAG + *in secoidt.h:* + SEC_OID_SEED_CBC + *in sslproto.h:* + TLS_RSA_WITH_SEED_CBC_SHA + *in sslt.h:* + ssl_calg_seed + + - New structure for SEED support: + + - (see blapit.h) + SEEDContextStr + SEEDContext + + - New functions in the nss shared library: + + - CERT_RFC1485_EscapeAndQuote (see cert.h) + CERT_CompareCerts (see cert.h) + CERT_RegisterAlternateOCSPAIAInfoCallBack (see ocsp.h) + PK11_GetSymKeyHandle (see pk11pqg.h) + UTIL_SetForkState (see secoid.h) + NSS_GetAlgorithmPolicy (see secoid.h) + NSS_SetAlgorithmPolicy (see secoid.h) + + - For the 2 functions above see also (in secoidt.h): + NSS_USE_ALG_IN_CERT_SIGNATURE + NSS_USE_ALG_IN_CMS_SIGNATURE + NSS_USE_ALG_RESERVED + + - Support for the Watcom C compiler is removed + + - The file watcomfx.h is removed. + + -------------- + +.. _bugs_fixed: + +`Bugs Fixed <#bugs_fixed>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following bugs have been fixed in NSS 3.12.3. + + - `Bug 159483 <https://bugzilla.mozilla.org/show_bug.cgi?id=159483>`__: cert name matching: RFC + 2818 vs. backwards compatibility (wildcards) + - `Bug 334678 <https://bugzilla.mozilla.org/show_bug.cgi?id=334678>`__: prng_fips1861.c + redefines the macro BSIZE on HP-UX + - `Bug 335016 <https://bugzilla.mozilla.org/show_bug.cgi?id=335016>`__: mpp_pprime (Miller-Rabin + probabilistic primality test) may choose 0 or 1 as the random integer + - `Bug 347037 <https://bugzilla.mozilla.org/show_bug.cgi?id=347037>`__: Make shlibsign depend on + the softoken only + - `Bug 371522 <https://bugzilla.mozilla.org/show_bug.cgi?id=371522>`__: Auto-Update of CRLs + stops after first update + - `Bug 380784 <https://bugzilla.mozilla.org/show_bug.cgi?id=380784>`__: PK11MODE in non FIPS + mode failed. + - `Bug 394077 <https://bugzilla.mozilla.org/show_bug.cgi?id=394077>`__: libpkix need to return + revocation status of a cert + - `Bug 412468 <https://bugzilla.mozilla.org/show_bug.cgi?id=412468>`__: modify certutil + - `Bug 417092 <https://bugzilla.mozilla.org/show_bug.cgi?id=417092>`__: Modify pkix_CertSelector + API to return an error if cert was rejected. + - `Bug 426413 <https://bugzilla.mozilla.org/show_bug.cgi?id=426413>`__: Audit messages need + distinct types + - `Bug 438870 <https://bugzilla.mozilla.org/show_bug.cgi?id=438870>`__: Free Freebl hashing code + of dependencies on NSPR and libUtil + - `Bug 439115 <https://bugzilla.mozilla.org/show_bug.cgi?id=439115>`__: DB merge allows nickname + conflicts in merged DB + - `Bug 439199 <https://bugzilla.mozilla.org/show_bug.cgi?id=439199>`__: SSE2 instructions for + bignum are not implemented on Windows 32-bit + - `Bug 441321 <https://bugzilla.mozilla.org/show_bug.cgi?id=441321>`__: Tolerate incorrect + encoding of DSA signatures in SSL 3.0 handshakes + - `Bug 444404 <https://bugzilla.mozilla.org/show_bug.cgi?id=444404>`__: libpkix reports unknown + issuer for nearly all certificate errors + - `Bug 452391 <https://bugzilla.mozilla.org/show_bug.cgi?id=452391>`__: certutil -K incorrectly + reports ec private key as an orphan + - `Bug 453234 <https://bugzilla.mozilla.org/show_bug.cgi?id=453234>`__: Support for SEED Cipher + Suites to TLS RFC4010 + - `Bug 453364 <https://bugzilla.mozilla.org/show_bug.cgi?id=453364>`__: Improve PK11_CipherOp + error reporting (was: PK11_CreateContextBySymKey returns NULL + - `Bug 456406 <https://bugzilla.mozilla.org/show_bug.cgi?id=456406>`__: Slot list leaks in + symkeyutil + - `Bug 461085 <https://bugzilla.mozilla.org/show_bug.cgi?id=461085>`__: RFE: export function + CERT_CompareCerts + - `Bug 462293 <https://bugzilla.mozilla.org/show_bug.cgi?id=462293>`__: Crash on fork after + Softoken is dlClose'd on some Unix platforms in NSS 3.12 + - `Bug 463342 <https://bugzilla.mozilla.org/show_bug.cgi?id=463342>`__: move some headers to + freebl/softoken + - `Bug 463452 <https://bugzilla.mozilla.org/show_bug.cgi?id=463452>`__: SQL DB creation does not + set files protections to 0600 + - `Bug 463678 <https://bugzilla.mozilla.org/show_bug.cgi?id=463678>`__: Need to add RPATH to + 64-bit libraries on HP-UX + - `Bug 464088 <https://bugzilla.mozilla.org/show_bug.cgi?id=464088>`__: Option to build NSS + without dbm (handy for WinCE) + - `Bug 464223 <https://bugzilla.mozilla.org/show_bug.cgi?id=464223>`__: Certutil didn't accept + certificate request to sign. + - `Bug 464406 <https://bugzilla.mozilla.org/show_bug.cgi?id=464406>`__: Fix signtool regressions + - `Bug 465270 <https://bugzilla.mozilla.org/show_bug.cgi?id=465270>`__: uninitialised value in + devutil.c::create_object() + - `Bug 465273 <https://bugzilla.mozilla.org/show_bug.cgi?id=465273>`__: dead assignment in + devutil.c::nssSlotArray_Clone() + - `Bug 465926 <https://bugzilla.mozilla.org/show_bug.cgi?id=465926>`__: During import of PKCS + #12 files + - `Bug 466180 <https://bugzilla.mozilla.org/show_bug.cgi?id=466180>`__: + SSL_ConfigMPServerSIDCache with default parameters fails on {Net + - `Bug 466194 <https://bugzilla.mozilla.org/show_bug.cgi?id=466194>`__: CERT_DecodeTrustString + should take a const char \* input trusts string. + - `Bug 466736 <https://bugzilla.mozilla.org/show_bug.cgi?id=466736>`__: Incorrect use of + NSS_USE_64 in lib/libpkix/pkix_pl_nss/system/pkix_pl_object.c + - `Bug 466745 <https://bugzilla.mozilla.org/show_bug.cgi?id=466745>`__: random number generator + fails on windows ce + - `Bug 467298 <https://bugzilla.mozilla.org/show_bug.cgi?id=467298>`__: SQL DB code uses local + cache on local file system + - `Bug 468279 <https://bugzilla.mozilla.org/show_bug.cgi?id=468279>`__: softoken crash importing + email cert into newly upgraded DB + - `Bug 468532 <https://bugzilla.mozilla.org/show_bug.cgi?id=468532>`__: Trusted CA trust flags + not being honored in CERT_VerifyCert + - `Bug 469583 <https://bugzilla.mozilla.org/show_bug.cgi?id=469583>`__: Coverity: uninitialized + variable used in sec_pkcs5CreateAlgorithmID + - `Bug 469944 <https://bugzilla.mozilla.org/show_bug.cgi?id=469944>`__: when built with + Microsoft compilers + - `Bug 470351 <https://bugzilla.mozilla.org/show_bug.cgi?id=470351>`__: crlutil build fails on + Windows because it calls undeclared isatty + - `Bug 471539 <https://bugzilla.mozilla.org/show_bug.cgi?id=471539>`__: Stop honoring digital + signatures in certificates and CRLs based on weak hashes + - `Bug 471665 <https://bugzilla.mozilla.org/show_bug.cgi?id=471665>`__: NSS reports incorrect + sizes for (AES) symmetric keys + - `Bug 471715 <https://bugzilla.mozilla.org/show_bug.cgi?id=471715>`__: Add cert to nssckbi to + override rogue md5-collision CA cert + - `Bug 472291 <https://bugzilla.mozilla.org/show_bug.cgi?id=472291>`__: crash in libpkix object + leak tests due to null pointer dereferencing in pkix_build.c:3218. + - `Bug 472319 <https://bugzilla.mozilla.org/show_bug.cgi?id=472319>`__: Vfychain validates chain + even if revoked certificate. + - `Bug 472749 <https://bugzilla.mozilla.org/show_bug.cgi?id=472749>`__: Softoken permits AES + keys of ANY LENGTH to be created + - `Bug 473147 <https://bugzilla.mozilla.org/show_bug.cgi?id=473147>`__: pk11mode tests fails on + AIX when using shareable DBs. + - `Bug 473357 <https://bugzilla.mozilla.org/show_bug.cgi?id=473357>`__: ssltap incorrectly + parses handshake messages that span record boundaries + - `Bug 473365 <https://bugzilla.mozilla.org/show_bug.cgi?id=473365>`__: Incompatible argument in + pkix_validate.c. + - `Bug 473505 <https://bugzilla.mozilla.org/show_bug.cgi?id=473505>`__: softoken's C_Initialize + and C_Finalize should succeed after a fork in a child process + - `Bug 473944 <https://bugzilla.mozilla.org/show_bug.cgi?id=473944>`__: Trust anchor is not + trusted when requireFreshInfo flag is set. + - `Bug 474532 <https://bugzilla.mozilla.org/show_bug.cgi?id=474532>`__: Softoken cannot import + certs with empty subjects and non-empty nicknames + - `Bug 474777 <https://bugzilla.mozilla.org/show_bug.cgi?id=474777>`__: Wrong deallocation when + modifying CRL. + - `Bug 476126 <https://bugzilla.mozilla.org/show_bug.cgi?id=476126>`__: CERT_AsciiToName fails + when AVAs in an RDN are separated by '+' + - `Bug 477186 <https://bugzilla.mozilla.org/show_bug.cgi?id=477186>`__: Infinite loop in + CERT_GetCertChainFromCert + - `Bug 477777 <https://bugzilla.mozilla.org/show_bug.cgi?id=477777>`__: Selfserv crashed in + client/server tests. + - `Bug 478171 <https://bugzilla.mozilla.org/show_bug.cgi?id=478171>`__: Consolidate the + coreconf/XXX.mk files for Windows + - `Bug 478563 <https://bugzilla.mozilla.org/show_bug.cgi?id=478563>`__: Add \_MSC_VER (the cl + version) to coreconf. + - `Bug 478724 <https://bugzilla.mozilla.org/show_bug.cgi?id=478724>`__: NSS build fails on + Windows since 20090213.1 nightly build. + - `Bug 478931 <https://bugzilla.mozilla.org/show_bug.cgi?id=478931>`__: object leak in + pkix_List_MergeLists function + - `Bug 478994 <https://bugzilla.mozilla.org/show_bug.cgi?id=478994>`__: Allow Softoken's fork + check to be disabled + - `Bug 479029 <https://bugzilla.mozilla.org/show_bug.cgi?id=479029>`__: OCSP Response signature + cert found invalid if issuer is trusted only for SSL + - `Bug 479601 <https://bugzilla.mozilla.org/show_bug.cgi?id=479601>`__: Wrong type (UTF8 String) + for email addresses in subject by CERT_AsciiToName + - `Bug 480142 <https://bugzilla.mozilla.org/show_bug.cgi?id=480142>`__: Use sizeof on the + correct type of ckc_x509 in lib/ckfw + - `Bug 480257 <https://bugzilla.mozilla.org/show_bug.cgi?id=480257>`__: OCSP fails when response + > 1K Byte + - `Bug 480280 <https://bugzilla.mozilla.org/show_bug.cgi?id=480280>`__: The CKA_EC_POINT PKCS#11 + attribute is encoded in the wrong way: missing encapsulating octet string + - `Bug 480442 <https://bugzilla.mozilla.org/show_bug.cgi?id=480442>`__: Remove (empty) + watcomfx.h from nss + - `Bug 481216 <https://bugzilla.mozilla.org/show_bug.cgi?id=481216>`__: Fix specific spelling + errors in NSS + - `Bug 482702 <https://bugzilla.mozilla.org/show_bug.cgi?id=482702>`__: OCSP test with revoked + CA cert validated as good. + - `Bug 483113 <https://bugzilla.mozilla.org/show_bug.cgi?id=483113>`__: add environment variable + to disable/enable hash algorithms in cert/CRL signatures + - `Bug 483168 <https://bugzilla.mozilla.org/show_bug.cgi?id=483168>`__: NSS Callback API for + looking up a default OCSP Responder URL + - `Bug 483963 <https://bugzilla.mozilla.org/show_bug.cgi?id=483963>`__: Assertion failure in + OCSP tests. + - `Bug 484425 <https://bugzilla.mozilla.org/show_bug.cgi?id=484425>`__: Need accessor function + to retrieve SymKey handle + - `Bug 484466 <https://bugzilla.mozilla.org/show_bug.cgi?id=484466>`__: sec_error_invalid_args + with NSS_ENABLE_PKIX_VERIFY=1 + - `Bug 485127 <https://bugzilla.mozilla.org/show_bug.cgi?id=485127>`__: bltest crashes when + attempting rc5_cbc or rc5_ecb + - `Bug 485140 <https://bugzilla.mozilla.org/show_bug.cgi?id=485140>`__: Wrong command line flags + used to build intel-aes.s with Solaris gas for x86_64 + - `Bug 485370 <https://bugzilla.mozilla.org/show_bug.cgi?id=485370>`__: crash + - `Bug 485713 <https://bugzilla.mozilla.org/show_bug.cgi?id=485713>`__: Files added by Red Hat + recently have missing texts in license headers. + - `Bug 485729 <https://bugzilla.mozilla.org/show_bug.cgi?id=485729>`__: Remove + lib/freebl/mapfile.Solaris + - `Bug 485837 <https://bugzilla.mozilla.org/show_bug.cgi?id=485837>`__: vc90.pdb files are + output in source directory instead of OBJDIR + - `Bug 486060 <https://bugzilla.mozilla.org/show_bug.cgi?id=486060>`__: sec_asn1d_parse_leaf + uses argument uninitialized by caller pbe_PK11AlgidToParam + + -------------- + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For a list of the primary NSS documentation pages on mozilla.org, see `NSS + Documentation <../index.html#Documentation>`__. New and revised documents available since the + release of NSS 3.11 include the following: + + - `Build Instructions for NSS 3.11.4 and above <../nss-3.11.4/nss-3.11.4-build.html>`__ + - `NSS Shared DB <http://wiki.mozilla.org/NSS_Shared_DB>`__ + + -------------- + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS 3.12.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.12.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in `NSS Public Functions <../ref/nssfunctions.html>`__ will remain + compatible with future versions of the NSS shared libraries. + + -------------- + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.12.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.4_release_notes/index.rst new file mode 100644 index 0000000000..400ff005c9 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.4_release_notes/index.rst @@ -0,0 +1,327 @@ +.. _mozilla_projects_nss_nss_3_12_4_release_notes: + +NSS 3.12.4 release notes +======================== + +.. container:: + + .. code:: + + 2009-08-20 + + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + .. rubric:: Introduction + :name: Introduction + + Network Security Services (NSS) 3.12.4 is a patch release for NSS 3.12. The bug fixes in NSS + 3.12.4 are described in the "`Bugs Fixed <#bugsfixed>`__" section below. + + NSS 3.12.4 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + + .. rubric:: Distribution Information + :name: Distribution_Information + + This release is built from the source, at the CVS repository rooted at cvs.mozilla.org:/cvsroot, + with the CVS tag ``NSS_3_12_4_RTM``. + + NSS 3.12.4 requires `NSPR 4.8 <https://www.mozilla.org/projects/nspr/release-notes/>`__. This is + not a hard requirement. Our QA tested NSS 3.12.4 with NSPR 4.8, but it should work with NSPR + 4.7.1 or later. + + You can check out the source from CVS by + + .. note:: + + cvs co -r NSPR_4_8_RTM NSPR + cvs co -r NSS_3_12_4_RTM NSS + + See the `Documentation <#docs>`__ section for the build instructions. + + NSS 3.12.4 source is also available on ``ftp.mozilla.org`` for secure HTTPS download: + + - Source tarball: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_4_RTM/src/. + + .. rubric:: Major changes in NSS 3.12.4 + :name: Major_changes_in_NSS_3.12.4 + + - NSS 3.12.4 is the version that we submitted to NIST for FIPS 140-2 validation. + Currently NSS 3.12.4 is in the "Review Pending" state in the FIPS 140-2 pre-validation + list at http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140InProcess.pdf + - Added CRL Distribution Point support (see cert.h). + **CERT_DecodeCRLIssuingDistributionPoint** + **CERT_FindCRLIssuingDistPointExten** + - The old documentation of the expression matching syntax rules was + incorrect, and the new corrected documentation is as follows for + public nssutil functions (see portreq.h): + + - **PORT_RegExpValid** + - **PORT_RegExpSearch** + - **PORT_RegExpCaseSearch** + + - These functions will match a string with a shell expression. The expressions + accepted are based loosely on the expressions accepted by zsh. + Expected return values: + + - NON_SXP if exp is a standard string + - INVALID_SXP if exp is a shell expression, but invalid + - VALID_SXP if exp is a valid shell expression + + Expression matching rules: + + - \* matches anything + - ? matches one character + - \\ will escape a special character + - $ matches the end of the string + - Bracketed expressions: + [abc] matches one occurrence of a, b, or c. + [^abc] matches any character except a, b, or c. + To be matched between [ and ], these characters must be escaped: \\ ] + No other characters need be escaped between brackets. + Unnecessary escaping is permitted. + - [a-z] matches any character between a and z, inclusive. + The two range-definition characters must be alphanumeric ASCII. + If one is upper case and the other is lower case, then the ASCII + non-alphanumeric characters between Z and a will also be in range. + - [^a-z] matches any character except those between a and z, inclusive. + These forms cannot be combined, e.g [a-gp-z] does not work. + - Exclusions: + As a top level, outter-most expression only, the expression + foo~bar will match the expression foo, provided it does not also + match the expression bar. Either expression or both may be a union. + Except between brackets, any unescaped ~ is an exclusion. + At most one exclusion is permitted. + Exclusions cannot be nested (contain other exclusions). + example: \*~abc will match any string except abc + - Unions: + (foo|bar) will match either the expression foo, or the expression bar. + At least one '|' separator is required. More are permitted. + Expressions inside unions may not include unions or exclusions. + Inside a union, to be matched and not treated as a special character, + these characters must be escaped: \\ ( \| ) [ ~ except when they occur + inside a bracketed expression, where only \\ and ] require escaping. + + - New functions in the nss shared library: + + - PK11_IsInternalKeySlot (see pk11pub.h) + - SECMOD_OpenNewSlot (see pk11pub.h) + + - New error codes (see secerr.h): + + - SEC_ERROR_BAD_INFO_ACCESS_METHOD + - SEC_ERROR_CRL_IMPORT_FAILED + + - New OIDs (see secoidt.h) + + - SEC_OID_X509_ANY_POLICY + + - The nssckbi PKCS #11 module's version changed to 1.75. + - Obsolete code for Win16 has been removed. + - Support for OpenVMS has been removed. + + .. rubric:: Bugs Fixed + :name: Bugs_Fixed + + The following bugs have been fixed in NSS 3.12.4. + + - `Bug 321755 <https://bugzilla.mozilla.org/show_bug.cgi?id=321755>`__: implement + crlDistributionPoint extension in libPKIX + - `Bug 391434 <https://bugzilla.mozilla.org/show_bug.cgi?id=391434>`__: avoid multiple + encoding/decoding of PKIX_PL_OID to and from ascii string + - `Bug 405297 <https://bugzilla.mozilla.org/show_bug.cgi?id=405297>`__: Problems building + nss/lib/ckfw/capi/ with MingW GCC + - `Bug 420991 <https://bugzilla.mozilla.org/show_bug.cgi?id=420991>`__: libPKIX returns wrong + NSS error code + - `Bug 427135 <https://bugzilla.mozilla.org/show_bug.cgi?id=427135>`__: Add super-H (sh3,4) + architecture support + - `Bug 431958 <https://bugzilla.mozilla.org/show_bug.cgi?id=431958>`__: Improve DES and SHA512 + for x86_64 platform + - `Bug 433791 <https://bugzilla.mozilla.org/show_bug.cgi?id=433791>`__: Win16 support should be + deleted from NSS + - `Bug 449332 <https://bugzilla.mozilla.org/show_bug.cgi?id=449332>`__: SECU_ParseCommandLine + does not validate its inputs + - `Bug 453735 <https://bugzilla.mozilla.org/show_bug.cgi?id=453735>`__: When using cert9 + (SQLite3) DB, set or change master password fails + - `Bug 463544 <https://bugzilla.mozilla.org/show_bug.cgi?id=463544>`__: warning: passing enum\* + for an int\* argument in pkix_validate.c + - `Bug 469588 <https://bugzilla.mozilla.org/show_bug.cgi?id=469588>`__: Coverity errors reported + for softoken + - `Bug 470055 <https://bugzilla.mozilla.org/show_bug.cgi?id=470055>`__: + pkix_HttpCertStore_FindSocketConnection reuses closed socket + - `Bug 470070 <https://bugzilla.mozilla.org/show_bug.cgi?id=470070>`__: Multiple object leaks + reported by tinderbox + - `Bug 470479 <https://bugzilla.mozilla.org/show_bug.cgi?id=470479>`__: IO timeout during cert + fetching makes libpkix abort validation. + - `Bug 470500 <https://bugzilla.mozilla.org/show_bug.cgi?id=470500>`__: Firefox 3.1b2 Crash + Report [[@ nssutil3.dll@0x34c0 ] + - `Bug 482742 <https://bugzilla.mozilla.org/show_bug.cgi?id=482742>`__: Enable building util + independently of the rest of nss + - `Bug 483653 <https://bugzilla.mozilla.org/show_bug.cgi?id=483653>`__: unable to build + certutil.exe for fennec/wince + - `Bug 485145 <https://bugzilla.mozilla.org/show_bug.cgi?id=485145>`__: Miscellaneous crashes in + signtool on Windows + - `Bug 485155 <https://bugzilla.mozilla.org/show_bug.cgi?id=485155>`__: NSS_ENABLE_PKIX_VERIFY=1 + causes sec_error_unknown_issuer errors + - `Bug 485527 <https://bugzilla.mozilla.org/show_bug.cgi?id=485527>`__: Rename the \_X86\_ macro + in lib/freebl + - `Bug 485658 <https://bugzilla.mozilla.org/show_bug.cgi?id=485658>`__: vfychain -p reports + revoked cert + - `Bug 485745 <https://bugzilla.mozilla.org/show_bug.cgi?id=485745>`__: modify fipstest.c to + support CAVS 7.1 DRBG testing + - `Bug 486304 <https://bugzilla.mozilla.org/show_bug.cgi?id=486304>`__: cert7.db/cert8.db + corruption when importing a large certificate (>64K) + - `Bug 486405 <https://bugzilla.mozilla.org/show_bug.cgi?id=486405>`__: Allocator mismatches in + pk12util.c + - `Bug 486537 <https://bugzilla.mozilla.org/show_bug.cgi?id=486537>`__: Disable execstack in + freebl x86_64 builds on Linux + - `Bug 486698 <https://bugzilla.mozilla.org/show_bug.cgi?id=486698>`__: Facilitate the building + of major components independently and in a chain manner by downstream distributions + - `Bug 486999 <https://bugzilla.mozilla.org/show_bug.cgi?id=486999>`__: Calling + SSL_SetSockPeerID a second time leaks the previous value + - `Bug 487007 <https://bugzilla.mozilla.org/show_bug.cgi?id=487007>`__: Make lib/jar conform to + NSS coding style + - `Bug 487162 <https://bugzilla.mozilla.org/show_bug.cgi?id=487162>`__: ckfw/capi build failure + on windows + - `Bug 487239 <https://bugzilla.mozilla.org/show_bug.cgi?id=487239>`__: nssutil.rc doesn't + compile on WinCE + - `Bug 487254 <https://bugzilla.mozilla.org/show_bug.cgi?id=487254>`__: sftkmod.c uses POSIX + file IO Functions on WinCE + - `Bug 487255 <https://bugzilla.mozilla.org/show_bug.cgi?id=487255>`__: sdb.c uses POSIX file IO + Functions on WinCE + - `Bug 487487 <https://bugzilla.mozilla.org/show_bug.cgi?id=487487>`__: CERT_NameToAscii reports + !Invalid AVA! whenever value exceeds 384 bytes + - `Bug 487736 <https://bugzilla.mozilla.org/show_bug.cgi?id=487736>`__: libpkix passes wrong + argument to DER_DecodeTimeChoice and crashes + - `Bug 487858 <https://bugzilla.mozilla.org/show_bug.cgi?id=487858>`__: Remove obsolete build + options MOZILLA_SECURITY_BUILD and MOZILLA_BSAFE_BUILD + - `Bug 487884 <https://bugzilla.mozilla.org/show_bug.cgi?id=487884>`__: object leak in libpkix + library upon error + - `Bug 488067 <https://bugzilla.mozilla.org/show_bug.cgi?id=488067>`__: PK11_ImportCRL reports + SEC_ERROR_CRL_NOT_FOUND when it fails to import a CRL + - `Bug 488350 <https://bugzilla.mozilla.org/show_bug.cgi?id=488350>`__: NSPR-free freebl + interface need to do post tests only in fips mode. + - `Bug 488396 <https://bugzilla.mozilla.org/show_bug.cgi?id=488396>`__: DBM needs to be FIPS + certifiable. + - `Bug 488550 <https://bugzilla.mozilla.org/show_bug.cgi?id=488550>`__: crash in certutil or pp + when printing cert with empty subject name + - `Bug 488992 <https://bugzilla.mozilla.org/show_bug.cgi?id=488992>`__: Fix + lib/freebl/win_rand.c warnings + - `Bug 489010 <https://bugzilla.mozilla.org/show_bug.cgi?id=489010>`__: stop exporting mktemp + and dbopen (again) + - `Bug 489287 <https://bugzilla.mozilla.org/show_bug.cgi?id=489287>`__: Resolve a few remaining + issues with NSS's new revocation flags + - `Bug 489710 <https://bugzilla.mozilla.org/show_bug.cgi?id=489710>`__: byteswap optimize for + MSVC++ + - `Bug 490154 <https://bugzilla.mozilla.org/show_bug.cgi?id=490154>`__: Cryptokey framework + requires module to implement GenerateKey when they support KeyPairGeneration + - `Bug 491044 <https://bugzilla.mozilla.org/show_bug.cgi?id=491044>`__: Remove support for VMS + (a.k.a., OpenVMS) from NSS + - `Bug 491174 <https://bugzilla.mozilla.org/show_bug.cgi?id=491174>`__: CERT_PKIXVerifyCert + reports wrong error code when EE cert is expired + - `Bug 491919 <https://bugzilla.mozilla.org/show_bug.cgi?id=491919>`__: cert.h doesn't have + valid functions prototypes + - `Bug 492131 <https://bugzilla.mozilla.org/show_bug.cgi?id=492131>`__: A failure to import a + cert from a P12 file leaves error code set to zero + - `Bug 492385 <https://bugzilla.mozilla.org/show_bug.cgi?id=492385>`__: crash freeing named CRL + entry on shutdown + - `Bug 493135 <https://bugzilla.mozilla.org/show_bug.cgi?id=493135>`__: bltest crashes if it + can't open the input file + - `Bug 493364 <https://bugzilla.mozilla.org/show_bug.cgi?id=493364>`__: can't build with + --disable-dbm option when not cross-compiling + - `Bug 493693 <https://bugzilla.mozilla.org/show_bug.cgi?id=493693>`__: SSE2 instructions for + bignum are not implemented on OS/2 + - `Bug 493912 <https://bugzilla.mozilla.org/show_bug.cgi?id=493912>`__: sqlite3_reset should be + invoked in sdb_FindObjectsInit when error occurs + - `Bug 494073 <https://bugzilla.mozilla.org/show_bug.cgi?id=494073>`__: update RSA/DSA + powerupself tests to be compliant for 2011 + - `Bug 494087 <https://bugzilla.mozilla.org/show_bug.cgi?id=494087>`__: Passing NULL as the + value of cert_pi_trustAnchors causes a crash in cert_pkixSetParam + - `Bug 494107 <https://bugzilla.mozilla.org/show_bug.cgi?id=494107>`__: During NSS_NoDB_Init(), + softoken tries but fails to load libsqlite3.so crash [@ @0x0 ] + - `Bug 495097 <https://bugzilla.mozilla.org/show_bug.cgi?id=495097>`__: sdb_mapSQLError returns + signed int + - `Bug 495103 <https://bugzilla.mozilla.org/show_bug.cgi?id=495103>`__: + NSS_InitReadWrite(sql:<dbdir>) causes NSS to look for sql:<dbdir>/libnssckbi.so + - `Bug 495365 <https://bugzilla.mozilla.org/show_bug.cgi?id=495365>`__: Add const to the + 'nickname' parameter of SEC_CertNicknameConflict + - `Bug 495656 <https://bugzilla.mozilla.org/show_bug.cgi?id=495656>`__: + NSS_InitReadWrite(sql:<configdir>) leaves behind a pkcs11.txu file if libnssckbi.so is in + <configdir>. + - `Bug 495717 <https://bugzilla.mozilla.org/show_bug.cgi?id=495717>`__: Unable to compile + nss/cmd/certutil/keystuff.c on WinCE + - `Bug 496961 <https://bugzilla.mozilla.org/show_bug.cgi?id=496961>`__: provide truncated HMAC + support for testing tool fipstest + - `Bug 497002 <https://bugzilla.mozilla.org/show_bug.cgi?id=497002>`__: Lab required nspr-free + freebl changes. + - `Bug 497217 <https://bugzilla.mozilla.org/show_bug.cgi?id=497217>`__: The first random value + ever generated by the RNG should be discarded + - `Bug 498163 <https://bugzilla.mozilla.org/show_bug.cgi?id=498163>`__: assert if profile path + contains cyrillic chars. [[@isspace - secmod_argIsBlank - secmod_argHasBlanks - + secmod_formatPair - secmod_mkNewModuleSpec] + - `Bug 498509 <https://bugzilla.mozilla.org/show_bug.cgi?id=498509>`__: Produce debuggable + optimized builds for Mozilla on MacOSX + - `Bug 498511 <https://bugzilla.mozilla.org/show_bug.cgi?id=498511>`__: Produce debuggable + optimized NSS builds for Mozilla on Linux + - `Bug 499385 <https://bugzilla.mozilla.org/show_bug.cgi?id=499385>`__: DRBG Reseed function + needs to be tested on POST + - `Bug 499825 <https://bugzilla.mozilla.org/show_bug.cgi?id=499825>`__: utilrename.h is missing + from Solaris packages + - `Bug 502961 <https://bugzilla.mozilla.org/show_bug.cgi?id=502961>`__: Allocator mismatch in + pk11mode + - `Bug 502965 <https://bugzilla.mozilla.org/show_bug.cgi?id=502965>`__: Allocator mismatch in + sdrtest + - `Bug 502972 <https://bugzilla.mozilla.org/show_bug.cgi?id=502972>`__: Another allocator + mismatch in sdrtest + - `Bug 504398 <https://bugzilla.mozilla.org/show_bug.cgi?id=504398>`__: + pkix_pl_AIAMgr_GetHTTPCerts could crash if SEC_GetRegisteredHttpClient fails + - `Bug 504405 <https://bugzilla.mozilla.org/show_bug.cgi?id=504405>`__: pkix_pl_CrlDp_Create + will fail on alloc success because of a missing ! + - `Bug 504408 <https://bugzilla.mozilla.org/show_bug.cgi?id=504408>`__: pkix_pl_CrlDp_Create + will always fail if dp->distPointType != generalName + - `Bug 504456 <https://bugzilla.mozilla.org/show_bug.cgi?id=504456>`__: Exploitable heap + overflow in NSS shell expression (filename globbing) parsing + - `Bug 505559 <https://bugzilla.mozilla.org/show_bug.cgi?id=505559>`__: Need function to + identify the one and only default internal private key slot. + - `Bug 505561 <https://bugzilla.mozilla.org/show_bug.cgi?id=505561>`__: Need a generic function + a la SECMOD_OpenUserDB() that can be used on non-softoken modules. + - `Bug 505858 <https://bugzilla.mozilla.org/show_bug.cgi?id=505858>`__: NSS_RegisterShutdown can + return without unlocking nssShutdownList.lock + - `Bug 507041 <https://bugzilla.mozilla.org/show_bug.cgi?id=507041>`__: Invalid build options + for VC6 + - `Bug 507228 <https://bugzilla.mozilla.org/show_bug.cgi?id=507228>`__: coreconf.dep doesn't + need to contain the NSS version number + - `Bug 507422 <https://bugzilla.mozilla.org/show_bug.cgi?id=507422>`__: crash [[@ PORT_FreeArena + - lg_mkSecretKeyRep] when PORT_NewArena fails + - `Bug 507482 <https://bugzilla.mozilla.org/show_bug.cgi?id=507482>`__: NSS 3.12.3 (and later) + doesn't build on AIX 5.1 + - `Bug 507937 <https://bugzilla.mozilla.org/show_bug.cgi?id=507937>`__: pwdecrypt program + problems + - `Bug 508259 <https://bugzilla.mozilla.org/show_bug.cgi?id=508259>`__: Pk11mode crashed on + Linux2.4 + - `Bug 508467 <https://bugzilla.mozilla.org/show_bug.cgi?id=508467>`__: libpkix ocsp checker + should use date argument to obtain the time for cert validity verification + - `Bug 510367 <https://bugzilla.mozilla.org/show_bug.cgi?id=510367>`__: Fix the UTF8 characters + in the nickname string for AC Raíz Certicamara S.A. + + .. rubric:: Documentation + :name: Documentation + + For a list of the primary NSS documentation pages on developer.mozilla.org, see NSS. New and + revised documents available since the release of NSS 3.12 include the following: + + - :ref:`mozilla_projects_nss_reference_building_and_installing_nss_build_instructions` + + .. rubric:: Compatibility + :name: Compatibility + + NSS 3.12.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.12.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in `NSS Public Functions </ref/nssfunctions.html>`__ will remain + compatible with future versions of the NSS shared libraries. + + .. rubric:: Feedback + :name: Feedback + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.12.5_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.5_release_notes/index.rst new file mode 100644 index 0000000000..b36b631e5d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.5_release_notes/index.rst @@ -0,0 +1,285 @@ +.. _mozilla_projects_nss_nss_3_12_5_release_notes: + +NSS 3.12.5 release_notes +======================== + +.. _nss_3.12.5_release_notes: + +`NSS 3.12.5 release notes <#nss_3.12.5_release_notes>`__ +-------------------------------------------------------- + +.. container:: + + .. container:: + + 2009-12-02 + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + -------------- + + .. container:: + :name: section_1 + + .. rubric:: Introduction + :name: Introduction + + Network Security Services (NSS) 3.12.5 is a patch release for NSS 3.12. The bug fixes in + NSS 3.12.5 are described in the "`Bugs + Fixed <https://dev.mozilla.jp/localmdc/localmdc_5125.html#bugsfixed>`__" section below. + + NSS 3.12.5 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + + .. container:: + :name: section_2 + + .. rubric:: Distribution Information + :name: Distribution_Information + + The CVS tag for the NSS 3.12.5 release is ``NSS_3_12_5_RTM``. + + NSS 3.12.5 requires `NSPR 4.8 <https://www.mozilla.org/projects/nspr/release-notes/>`__. + + You can check out the source from CVS by + + .. note:: + + cvs co -r NSPR_4_8_RTM NSPR + cvs co -r NSS_3_12_5_RTM NSS + + See the `Documentation <https://dev.mozilla.jp/localmdc/localmdc_5125.html#docs>`__ section + for the build instructions. + + NSS 3.12.5 source is also available on ``ftp.mozilla.org`` for secure HTTPS download: + + - Source tarball: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_5_RTM/src/. + + .. container:: + :name: section_3 + + .. rubric:: New in NSS 3.12.5 + :name: New_in_NSS_3.12.5 + + .. container:: + :name: section_4 + + .. rubric:: SSL3 & TLS Renegotiation Vulnerability + :name: SSL3_TLS_Renegotiation_Vulnerability + + See `CVE-2009-3555 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-3555>`__ and + `US-CERT VU#120541 <http://www.kb.cert.org/vuls/id/120541>`__ for more information about + this security vulnerability. + + All SSL/TLS renegotiation is disabled by default in NSS 3.12.5. This will cause programs + that attempt to perform renegotiation to experience failures where they formerly + experienced successes, and is necessary for them to not be vulnerable, until such time + as a new safe renegotiation scheme is standardized by the IETF. + + If an application depends on renegotiation feature, it can be enabled by setting the + environment variable NSS_SSL_ENABLE_RENEGOTIATION to 1. By setting this environmental + variable, the fix provided by these patches will have no effect and the application may + become vulnerable to the issue. + + This default setting can also be changed within the application by using the following + existing API functions: + + - + + - SECStatus SSL_OptionSet(PRFileDesc \*fd, PRInt32 option, PRBool on) + - SECStatus SSL_OptionSetDefault(PRInt32 option, PRBool on) + + - There is now a new value for "option", which is: + + - SSL_ENABLE_RENEGOTIATION + + The corresponding new values for SSL_ENABLE_RENEGOTIATION are: + + - SSL_RENEGOTIATE_NEVER: Never renegotiate at all (default). + - SSL_RENEGOTIATE_UNRESTRICTED: Renegotiate without restriction, whether or not the + peer's client hello bears the renegotiation info extension (as we always did in + the past). **UNSAFE**. + + .. container:: + :name: section_5 + + .. rubric:: TLS compression + :name: TLS_compression + + - Enable TLS compression with: + + - SSL_ENABLE_DEFLATE: Enable TLS compression with DEFLATE. Off by default. (See + ssl.h) + + Error codes: + + - SSL_ERROR_DECOMPRESSION_FAILURE (see sslerr.h) + - SSL_ERROR_RENEGOTIATION_NOT_ALLOWED (see sslerr.h) + + .. container:: + :name: section_6 + + .. rubric:: New context initialization and shutdown functions + :name: New_context_initialization_and_shutdown_functions + + - See nss.h for details. The 2 new functions are: + + - NSS_InitContext + - NSS_ShutdownContext + + Parameters for these functions are used to initialize softoken. These are mostly + strings used to internationalize softoken. Memory for the strings are owned by the + caller, who is free to free them once NSS_ContextInit returns. If the string + parameter is NULL (as opposed to empty, zero length), then the softoken default is + used. These are equivalent to the parameters for PK11_ConfigurePKCS11(). + + See the following struct in nss.h for details: + + - NSSInitParametersStr + + .. container:: + :name: section_7 + + .. rubric:: Other new functions + :name: Other_new_functions + + - *In secmod.h:* + + - SECMOD_GetSkipFirstFlag + - SECMOD_GetDefaultModDBFlag + + *In prlink.h* + + - NSS_SecureMemcmp + - PORT_LoadLibraryFromOrigin + + .. container:: + :name: section_8 + + .. rubric:: Modified functions + :name: Modified_functions + + - SGN_Update (see cryptohi.h) + + - The parameter "input" of this function is changed from *unsigned char \** to + *const unsigned char \**. + + - PK11_ConfigurePKCS11 (see nss.h) + + - The name of some parameters have been slightly changed ("des" became "desc"). + + .. container:: + :name: section_9 + + .. rubric:: Deprecated headers + :name: Deprecated_headers + + - The header file key.h is deprecated. Please use keyhi.h instead. + + .. container:: + :name: section_10 + + .. rubric:: Additional documentation + :name: Additional_documentation + + - *In pk11pub.h:* + + - The caller of PK11_DEREncodePublicKey should free the returned SECItem with a + SECITEM_FreeItem(..., PR_TRUE) call. + - PK11_ReadRawAttribute allocates the buffer for returning the attribute value. The + caller of PK11_ReadRawAttribute should free the data buffer pointed to by item + using a SECITEM_FreeItem(item, PR_FALSE) or PORT_Free(item->data) call. + + *In secasn1.h:* + + - If both pool and dest are NULL, the caller should free the returned SECItem with a + SECITEM_FreeItem(..., PR_TRUE) call. If pool is NULL but dest is not NULL, the + caller should free the data buffer pointed to by dest with a + SECITEM_FreeItem(dest, PR_FALSE) or PORT_Free(dest->data) call. + + .. container:: + :name: section_11 + + .. rubric:: Environment variables + :name: Environment_variables + + - NSS_FIPS + + - Will start NSS in FIPS mode. + + - NSS_SSL_ENABLE_RENEGOTIATION + - NSS_SSL_REQUIRE_SAFE_NEGOTIATION + + - See SSL3 & TLS Renegotiation Vulnerability. + + .. container:: + :name: section_12 + + .. rubric:: Bugs Fixed + :name: Bugs_Fixed + + The following bugs have been fixed in NSS 3.12.5. + + - `Bug 510435 <https://bugzilla.mozilla.org/show_bug.cgi?id=510435>`__: Remove unused make + variable DSO_LDFLAGS + - `Bug 510436 <https://bugzilla.mozilla.org/show_bug.cgi?id=510436>`__: Add macros for + build numbers (4th component of version number) to nssutil.h + - `Bug 511227 <https://bugzilla.mozilla.org/show_bug.cgi?id=511227>`__: Firefox 3.0.13 + fails to compile on FreeBSD/powerpc + - `Bug 511312 <https://bugzilla.mozilla.org/show_bug.cgi?id=511312>`__: NSS fails to load + softoken, looking for sqlite3.dll + - `Bug 511781 <https://bugzilla.mozilla.org/show_bug.cgi?id=511781>`__: Add new TLS 1.2 + cipher suites implemented in Windows 7 to ssltap + - `Bug 516101 <https://bugzilla.mozilla.org/show_bug.cgi?id=516101>`__: If PK11_ImportCert + fails, it leaves the certificate undiscoverable by CERT_PKIXVerifyCert + - `Bug 518443 <https://bugzilla.mozilla.org/show_bug.cgi?id=518443>`__: + PK11_ImportAndReturnPrivateKey leaks an arena + - `Bug 518446 <https://bugzilla.mozilla.org/show_bug.cgi?id=518446>`__: + PK11_DEREncodePublicKey leaks a CERTSubjectPublicKeyInfo + - `Bug 518457 <https://bugzilla.mozilla.org/show_bug.cgi?id=518457>`__: + SECKEY_EncodeDERSubjectPublicKeyInfo and PK11_DEREncodePublicKey are duplicate + - `Bug 522510 <https://bugzilla.mozilla.org/show_bug.cgi?id=522510>`__: Add deprecated + comments to key.h and pk11func.h + - `Bug 522580 <https://bugzilla.mozilla.org/show_bug.cgi?id=522580>`__: NSS uses + PORT_Memcmp for comparing secret data. + - `Bug 525056 <https://bugzilla.mozilla.org/show_bug.cgi?id=525056>`__: Timing attack + against ssl3ext.c:ssl3_ServerHandleSessionTicketXtn() + - `Bug 526689 <https://bugzilla.mozilla.org/show_bug.cgi?id=526689>`__: SSL3 & TLS + Renegotiation Vulnerability + + .. container:: + :name: section_13 + + .. rubric:: Documentation + :name: Documentation + + For a list of the primary NSS documentation pages on mozilla.org, see `NSS + Documentation <https://www.mozilla.org/projects/security/pki/nss/#documentation>`__. New + and revised documents available since the release of NSS 3.11 include the following: + + - `Build Instructions <https://dev.mozilla.jp/localmdc/localmdc_5142.html>`__ + - `NSS Shared DB <http://wiki.mozilla.org/NSS_Shared_DB>`__ + + .. container:: + :name: section_14 + + .. rubric:: Compatibility + :name: Compatibility + + NSS 3.12.5 shared libraries are backward compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with NSS 3.12.5 + shared libraries without recompiling or relinking. Furthermore, applications that restrict + their use of NSS APIs to the functions listed in `NSS Public + Functions <https://www.mozilla.org/projects/security/pki/nss/ref/nssfunctions.html>`__ will + remain compatible with future versions of the NSS shared libraries. + + .. container:: + :name: section_15 + + .. rubric:: Feedback + :name: Feedback + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS). + + This document was generated by *genma teruaki* on *November 28, 2010* using `texi2html + 1.82 <http://www.nongnu.org/texi2html/>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.12.6_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.6_release_notes/index.rst new file mode 100644 index 0000000000..19087bb9eb --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.6_release_notes/index.rst @@ -0,0 +1,318 @@ +.. _mozilla_projects_nss_nss_3_12_6_release_notes: + +NSS 3.12.6 release notes +======================== + +.. _nss_3.12.6_release_notes: + +`NSS 3.12.6 release notes <#nss_3.12.6_release_notes>`__ +-------------------------------------------------------- + +.. container:: + + .. container:: + + 2010-03-03 + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + .. container:: + :name: section_1 + + .. rubric:: Introduction + :name: Introduction + + Network Security Services (NSS) 3.12.6 is a patch release for NSS 3.12. The bug fixes in + NSS 3.12.6 are described in the "`Bugs + Fixed <http://mdn.beonex.com/en/NSS_3.12.6_release_notes.html#bugsfixed>`__" section below. + + NSS 3.12.6 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + + .. container:: + :name: section_2 + + .. rubric:: Distribution Information + :name: Distribution_Information + + | The CVS tag for the NSS 3.12.6 release is ``NSS_3_12_6_RTM``. NSS 3.12.6 requires `NSPR + 4.8.4 <https://www.mozilla.org/projects/nspr/release-notes/>`__. + | See the `Documentation <http://mdn.beonex.com/en/NSS_3.12.6_release_notes.html#docs>`__ + section for the build instructions. + + NSS 3.12.6 source and binary distributions are also available on ``ftp.mozilla.org`` for + secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_6_RTM/src/. + + | You also need to download the NSPR 4.8.4 binary distributions to get the NSPR 4.8.4 + header files and shared libraries, which NSS 3.12.6 requires. NSPR 4.8.4 binary + distributions are in https://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.8.4/. + | + + .. container:: + :name: section_3 + + .. rubric:: New in NSS 3.12.6 + :name: New_in_NSS_3.12.6 + + .. container:: + :name: section_4 + + .. rubric:: SSL3 & TLS Renegotiation Indication Extension (RFC 5746) + :name: SSL3_TLS_Renegotiation_Indication_Extension_(RFC_5746) + + - By default, NSS 3.12.6 uses the new TLS Renegotiation Indication Extension for TLS + renegotiation but allows simple SSL/TLS connections (without renegotiation) with + peers that don't support the TLS Renegotiation Indication Extension. + + The behavior of NSS for renegotiation can be changed through API function calls, or + with the following environment variables: + + - NSS_SSL_ENABLE_RENEGOTIATION + + - values: + + - [0|n|N]: SSL_RENEGOTIATE_NEVER + + - Never allow renegotiation - That was the default for 3.12.5 release. + + - [1|u|U]: SSL_RENEGOTIATE_UNRESTRICTED + + - Server and client are allowed to renegotiate without any restrictions. + This setting was the default prior 3.12.5 and makes products vulnerable. + + - [2|r|R]: SSL_RENEGOTIATE_REQUIRES_XTN (default) + + - Only allows renegotiation if the peer's hello bears the TLS + renegotiation_info extension. This is the safe renegotiation. + + - [3|t|T]: SSL_RENEGOTIATE_TRANSITIONAL + + - Disallows unsafe renegotiation in server sockets only, but allows clients + to continue to renegotiate with vulnerable servers. This value should + only be used during the transition period when few servers have been + upgraded. + + - NSS_SSL_REQUIRE_SAFE_NEGOTIATION + + - values: + + - 1: requireSafeNegotiation = TRUE + - unset: requireSafeNegotiation = FALSE + + Controls whether safe renegotiation indication is required for initial + handshake. If TRUE, a connection will be dropped at initial handshake if the + peer server or client does not support safe renegotiation. The default setting + for this option is FALSE. + + These options can also be set with the following SSL options: + + - sslOptions.enableRenegotiation + - sslOptions.requireSafeNegotiation + - New pseudo cipher suite value: TLS_EMPTY_RENEGOTIATION_INFO_SCSV (cannot be + negotiated) + + .. container:: + :name: section_5 + + .. rubric:: TLS Server Name Indication for servers + :name: TLS_Server_Name_Indication_for_servers + + - | TLS Server Name Indication (SNI) for servers is almost fully implemented in NSS + 3.12.6. + | See `bug 360421 <https://bugzilla.mozilla.org/show_bug.cgi?id=360421>`__ for + details. + + Note: The TLS Server Name Indication for clients is already fully implemented in NSS. + + - New functions for SNI *(see ssl.h for more information)*: + + - SSLSNISocketConfig + + - Return values: + + - SSL_SNI_CURRENT_CONFIG_IS_USED: libSSL must use the default cert and key. + - SSL_SNI_SEND_ALERT: libSSL must send the "unrecognized_name" alert. + + - SSL_SNISocketConfigHook + - SSL_ReconfigFD + - SSL_ConfigServerSessionIDCacheWithOpt + - SSL_SetTrustAnchors + - SSL_GetNegotiatedHostInfo + + - New enum for SNI: + + - SSLSniNameType *(see sslt.h)* + + .. container:: + :name: section_6 + + .. rubric:: New functions + :name: New_functions + + - *in cert.h* + + - CERTDistNames: Duplicate distinguished name array. + - CERT_DistNamesFromCertList: Generate an array of Distinguished names from a list + of certs. + + *in ocsp.h* + + - CERT_CacheOCSPResponseFromSideChannel: + + - This function is intended for use when OCSP responses are provided via a + side-channel, i.e. TLS OCSP stapling (a.k.a. the status_request extension). + + *in ssl.h* + + - SSL_GetImplementedCiphers + - SSL_GetNumImplementedCiphers + - SSL_HandshakeNegotiatedExtension + + .. container:: + :name: section_7 + + .. rubric:: New error codes + :name: New_error_codes + + - *in sslerr.h* + + - SSL_ERROR_UNSAFE_NEGOTIATION + - SSL_ERROR_RX_UNEXPECTED_UNCOMPRESSED_RECORD + + .. container:: + :name: section_8 + + .. rubric:: New types + :name: New_types + + - *in sslt.h* + + - SSLExtensionType + + .. container:: + :name: section_9 + + .. rubric:: New environment variables + :name: New_environment_variables + + - SQLITE_FORCE_PROXY_LOCKING + + - 1 means force always use proxy, 0 means never use proxy, NULL means use proxy for + non-local files only. + + - SSLKEYLOGFILE + + - Key log file. If set, NSS logs RSA pre-master secrets to this file. This allows + packet sniffers to decrypt TLS connections. + See `documentation <http://mdn.beonex.com/en/NSS_Key_Log_Format.html>`__. + Note: The code must be built with TRACE defined to use this functionality. + + .. container:: + :name: section_10 + + .. rubric:: Bugs Fixed + :name: Bugs_Fixed + + The following bugs have been fixed in NSS 3.12.6. + + - `Bug 275744 <https://bugzilla.mozilla.org/show_bug.cgi?id=275744>`__: Support for TLS + compression RFC 3749 + - `Bug 494603 <https://bugzilla.mozilla.org/show_bug.cgi?id=494603>`__: Update NSS's copy + of sqlite3 to 3.6.22 to get numerous bug fixes + - `Bug 496993 <https://bugzilla.mozilla.org/show_bug.cgi?id=496993>`__: Add accessor + functions for SSL_ImplementedCiphers + - `Bug 515279 <https://bugzilla.mozilla.org/show_bug.cgi?id=515279>`__: + CERT_PKIXVerifyCert considers a certificate revoked if cert_ProcessOCSPResponse fails + for any reason + - `Bug 515870 <https://bugzilla.mozilla.org/show_bug.cgi?id=515870>`__: GCC compiler + warnings in NSS 3.12.4 + - `Bug 518255 <https://bugzilla.mozilla.org/show_bug.cgi?id=518255>`__: The input buffer + for SGN_Update should be declared const + - `Bug 519550 <https://bugzilla.mozilla.org/show_bug.cgi?id=519550>`__: Allow the + specification of an alternate library for SQLite + - `Bug 524167 <https://bugzilla.mozilla.org/show_bug.cgi?id=524167>`__: Crash in [[@ + find_objects_by_template - nssToken_FindCertificateByIssuerAndSerialNumber] + - `Bug 526910 <https://bugzilla.mozilla.org/show_bug.cgi?id=526910>`__: maxResponseLength + (initialized to PKIX_DEFAULT_MAX_RESPONSE_LENGTH) is too small for downloading some + CRLs. + - `Bug 527759 <https://bugzilla.mozilla.org/show_bug.cgi?id=527759>`__: Add multiple roots + to NSS (single patch) + - `Bug 528741 <https://bugzilla.mozilla.org/show_bug.cgi?id=528741>`__: pkix_hash throws a + null-argument exception on empty strings + - `Bug 530907 <https://bugzilla.mozilla.org/show_bug.cgi?id=530907>`__: The peerID + argument to SSL_SetSockPeerID should be declared const + - `Bug 531188 <https://bugzilla.mozilla.org/show_bug.cgi?id=531188>`__: Decompression + failure with https://livechat.merlin.pl/ + - `Bug 532417 <https://bugzilla.mozilla.org/show_bug.cgi?id=532417>`__: Build problem with + spaces in path names + - `Bug 534943 <https://bugzilla.mozilla.org/show_bug.cgi?id=534943>`__: Clean up the + makefiles in lib/ckfw/builtins + - `Bug 534945 <https://bugzilla.mozilla.org/show_bug.cgi?id=534945>`__: lib/dev does not + need to include headers from lib/ckfw + - `Bug 535669 <https://bugzilla.mozilla.org/show_bug.cgi?id=535669>`__: Move common + makefile code in if and else to the outside + - `Bug 536023 <https://bugzilla.mozilla.org/show_bug.cgi?id=536023>`__: DER_UTCTimeToTime + and DER_GeneralizedTimeToTime ignore all bytes after an embedded null + - `Bug 536474 <https://bugzilla.mozilla.org/show_bug.cgi?id=536474>`__: Add support for + logging pre-master secrets + - `Bug 537356 <https://bugzilla.mozilla.org/show_bug.cgi?id=537356>`__: Implement new safe + SSL3 & TLS renegotiation + - `Bug 537795 <https://bugzilla.mozilla.org/show_bug.cgi?id=537795>`__: NSS_InitContext + does not work with NSS_RegisterShutdown + - `Bug 537829 <https://bugzilla.mozilla.org/show_bug.cgi?id=537829>`__: Allow NSS to build + for Android + - `Bug 540304 <https://bugzilla.mozilla.org/show_bug.cgi?id=540304>`__: Implement + SSL_HandshakeNegotiatedExtension + - `Bug 541228 <https://bugzilla.mozilla.org/show_bug.cgi?id=541228>`__: Remove an obsolete + NSPR version check in lib/util/secport.c + - `Bug 541231 <https://bugzilla.mozilla.org/show_bug.cgi?id=541231>`__: nssinit.c doesn't + need to include ssl.h and sslproto.h. + - `Bug 542538 <https://bugzilla.mozilla.org/show_bug.cgi?id=542538>`__: NSS: Add function + for recording OCSP stapled replies + - `Bug 544191 <https://bugzilla.mozilla.org/show_bug.cgi?id=544191>`__: Use system zlib on + Mac OS X + - `Bug 544584 <https://bugzilla.mozilla.org/show_bug.cgi?id=544584>`__: segmentation fault + when enumerating the nss database + - `Bug 544586 <https://bugzilla.mozilla.org/show_bug.cgi?id=544586>`__: Various + nss-sys-init patches from Fedora + - `Bug 545273 <https://bugzilla.mozilla.org/show_bug.cgi?id=545273>`__: Remove unused + function SEC_Init + - `Bug 546389 <https://bugzilla.mozilla.org/show_bug.cgi?id=546389>`__: nsssysinit binary + built inside source tree + + .. container:: + :name: section_11 + + .. rubric:: Documentation + :name: Documentation + + For a list of the primary NSS documentation pages on mozilla.org, see `NSS + Documentation <https://www.mozilla.org/projects/security/pki/nss/#documentation>`__. New + and revised documents available since the release of NSS 3.11 include the following: + + - `Build + Instructions <http://mdn.beonex.com/en/NSS_reference/Building_and_installing_NSS/Build_instructions.html>`__ + - `NSS Shared DB <http://wiki.mozilla.org/NSS_Shared_DB>`__ + + .. container:: + :name: section_12 + + .. rubric:: Compatibility + :name: Compatibility + + NSS 3.12.6 shared libraries are backward compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with NSS 3.12.6 + shared libraries without recompiling or relinking. Furthermore, applications that restrict + their use of NSS APIs to the functions listed in `NSS Public + Functions <https://www.mozilla.org/projects/security/pki/nss/ref/nssfunctions.html>`__ will + remain compatible with future versions of the NSS shared libraries. + + .. container:: + :name: section_13 + + .. rubric:: Feedback + :name: Feedback + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.12.9_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.9_release_notes/index.rst new file mode 100644 index 0000000000..2f534fd0ad --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.12.9_release_notes/index.rst @@ -0,0 +1,144 @@ +.. _: + +NSS 3.12.9 release notes +======================== + +.. _removed_functions: + +`Removed functions <#removed_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + 2010-09-23 + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + .. container:: + :name: section_1 + + .. rubric:: Introduction + :name: Introduction_2 + + Network Security Services (NSS) 3.12.9 is a patch release for NSS 3.12. The bug fixes in NSS + 3.12.9 are described in the "\ `Bugs Fixed <#bugsfixed>`__" section below. + + NSS 3.12.9 is tri-licensed under the MPL 1.1/GPL 2.0/LGPL 2.1. + + .. container:: + :name: section_2 + + .. rubric:: Distribution Information + :name: Distribution_Information + + | The CVS tag for the NSS 3.12.9 release is ``NSS_3.12.9_RTM``. NSS 3.12.9 requires `NSPR + 4.8.7 <https://www.mozilla.org/projects/nspr/release-notes/nspr486.html>`__. + | See the `Documentation <#docs>`__ section for the build instructions. + + NSS 3.12.9 source distribution is also available on ``ftp.mozilla.org`` for secure HTTPS + download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3.12.9_RTM/src/. + + You also need to download the NSPR 4.8.7 binary distributions to get the NSPR 4.8.7 header + files and shared libraries, which NSS 3.12.9 requires. NSPR 4.8.7 binary distributions are in + https://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.8.7/. + + .. container:: + :name: section_3 + + .. rubric:: New in NSS 3.12.9 + :name: New_in_NSS_3.12.9 + + .. container:: + :name: section_5 + + .. container:: + :name: section_6 + + .. rubric:: New SSL options + :name: New_SSL_options + + .. container:: + :name: section_7 + + .. rubric:: New error codes + :name: New_error_codes + + .. container:: + :name: section_8 + + .. rubric:: Bugs Fixed + :name: Bugs_Fixed + + The following bugs have been fixed in NSS 3.12.9. + + - `Bug 609068 <https://bugzilla.mozilla.org/show_bug.cgi?id=609068>`__: Implement J-PAKE in + FreeBL + - `Bug 607058 <https://bugzilla.mozilla.org/show_bug.cgi?id=607058>`__: crash [@ + nss_cms_decoder_work_data] + - `Bug 613394 <https://bugzilla.mozilla.org/show_bug.cgi?id=613394>`__: November/December + 2010 batch of NSS root CA changes + - `Bug 610843 <https://bugzilla.mozilla.org/show_bug.cgi?id=610843>`__: Need way to recover + softoken in child after fork() + - `Bug 617492 <https://bugzilla.mozilla.org/show_bug.cgi?id=617492>`__: Add + PK11_KeyGenWithTemplate function to pk11wrap (for Firefox Sync) + - `Bug 610162 <https://bugzilla.mozilla.org/show_bug.cgi?id=610162>`__: SHA-512 and SHA-384 + hashes are incorrect for inputs of 512MB or larger when running under Windows and other + 32-bit platforms (Fx 3.6.12 and 4.0b6) + - `Bug 518551 <https://bugzilla.mozilla.org/show_bug.cgi?id=518551>`__: Vfychain crashes in + PKITS tests. + - `Bug 536485 <https://bugzilla.mozilla.org/show_bug.cgi?id=536485>`__: crash during ssl + handshake in [@ intel_aes_decrypt_cbc_256] + - `Bug 444367 <https://bugzilla.mozilla.org/show_bug.cgi?id=444367>`__: NSS 3.12 softoken + returns the certificate type of a certificate object as CKC_X_509_ATTR_CERT. + - `Bug 620908 <https://bugzilla.mozilla.org/show_bug.cgi?id=620908>`__: certutil -T -d + "sql:." dumps core + - `Bug 584257 <https://bugzilla.mozilla.org/show_bug.cgi?id=584257>`__: Need a way to expand + partial private keys. + - `Bug 596798 <https://bugzilla.mozilla.org/show_bug.cgi?id=596798>`__: win_rand.c (among + others) uses unsafe \_snwprintf + - `Bug 597622 <https://bugzilla.mozilla.org/show_bug.cgi?id=597622>`__: Do not use the + SEC_ERROR_BAD_INFO_ACCESS_LOCATION error code for bad CRL distribution point URLs + - `Bug 619268 <https://bugzilla.mozilla.org/show_bug.cgi?id=619268>`__: Memory leaks in + CERT_ChangeCertTrust and CERT_SaveSMimeProfile + - `Bug 585518 <https://bugzilla.mozilla.org/show_bug.cgi?id=585518>`__: AddTrust Qualified CA + Root serial wrong in certdata.txt trust entry + - `Bug 337433 <https://bugzilla.mozilla.org/show_bug.cgi?id=337433>`__: Need + CERT_FindCertByNicknameOrEmailAddrByUsage + - `Bug 592939 <https://bugzilla.mozilla.org/show_bug.cgi?id=592939>`__: Expired CAs in + certdata.txt + + .. container:: + :name: section_9 + + .. rubric:: Documentation + :name: Documentation + + NSS Documentation. New and revised documents available since the release of NSS 3.11 include + the following: + + - `Build Instructions for NSS 3.11.4 and + above <https://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.4/nss-3.11.4-build>`__ + - `NSS Shared DB <http://wiki.mozilla.org/NSS_Shared_DB>`__ + + .. container:: + :name: section_10 + + .. rubric:: Compatibility + :name: Compatibility + + NSS 3.12.9 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.12.9 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS + APIs to the functions listed in `NSS Public Functions </en-US/ref/nssfunctions.html>`__ will + remain compatible with future versions of the NSS shared libraries. + + .. container:: + :name: section_11 + + .. rubric:: Feedback + :name: Feedback + + Bugs discovered should be reported by filing a bug report with `mozilla.org + Bugzilla <https://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.14.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.1_release_notes/index.rst new file mode 100644 index 0000000000..aac2861d17 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.1_release_notes/index.rst @@ -0,0 +1,127 @@ +.. _mozilla_projects_nss_nss_3_14_1_release_notes: + +NSS 3.14.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.14.1 is a patch release for NSS 3.14. The bug fixes in NSS + 3.14.1 are described in the "Bugs Fixed" section below. + + NSS 3.14.1 is licensed under the MPL 2.0. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The CVS tag is NSS_3_14_1_RTM. NSS 3.14.1 requires NSPR 4.9.4 or newer. + + NSS 3.14.1 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_14_1_RTM/src/ + +.. _new_in_nss_3.14.1: + +`New in NSS 3.14.1 <#new_in_nss_3.14.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS now has the ability to create signed OCSP responses. + + - The ability to create signed OCSP responses has been added in NSS 3.14.1. Note that this + code is used primarily for purposes of testing. + + .. rubric:: New Functions + :name: new_functions + + - *in ocspt.h* + + - CERT_CreateOCSPSingleResponseGood + - CERT_CreateOCSPSingleResponseUnknown + - CERT_CreateOCSPSingleResponseRevoked + - CERT_CreateEncodedOCSPSuccessResponse + - CERT_CreateEncodedOCSPErrorResponse + + .. rubric:: New Types + :name: new_types + + - *in ocspt.h* + + - CERTOCSPResponderIDType + +.. _notable_changes_in_nss_3.14.1: + +`Notable Changes in NSS 3.14.1 <#notable_changes_in_nss_3.14.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Windows CE support has been removed from the code base. + - `Bug 812399 <https://bugzilla.mozilla.org/show_bug.cgi?id=812399>`__ - In NSS 3.14, a + regression caused `Bug 641052 <https://bugzilla.mozilla.org/show_bug.cgi?id=641052>`__ / + CVE-2011-3640 to be re-introduced under certain situations. This regression only affected + applications that initialize NSS via the NSS_NoDB_Init function. NSS 3.14.1 includes the + complete fix for this issue. + - `Bug 357025 <https://bugzilla.mozilla.org/show_bug.cgi?id=357025>`__ - NSS 3.14 added support + for tokens that make use of CKA_ALWAYS_AUTHENTICATE. However, when authenticating with such + tokens, it was possible for an internal lock to be acquired twice, causing a hang. This hang + has been fixed in NSS 3.14.1. + - `Bug 802429 <https://bugzilla.mozilla.org/show_bug.cgi?id=802429>`__ - In previous versions of + NSS, the "cipherOrder" slot configuration flag was not respected, causing the most recently + added slot that supported the requested PKCS#11 mechanism to be used instead. NSS now + correctly respects the supplied cipherOrder. + Applications which use multiple PKCS#11 modules, which do not indicate which tokens should be + used by default for particular algorithms, and which do make use of cipherOrder may now find + that cryptographic operations occur on a different PKCS#11 token. + - `Bug 802429 <https://bugzilla.mozilla.org/show_bug.cgi?id=802429>`__ - The NSS softoken is now + the default token for SHA-256 and SHA-512. In previous versions of NSS, these algorithms would + be handled by the most recently added PKCS#11 token that supported them. + - `Bug 611451 <https://bugzilla.mozilla.org/show_bug.cgi?id=611451>`__ - When built with the + current version of Apple XCode on Mac OS X, the NSS shared libraries will now only export the + public NSS functions. + - `Bug 810582 <https://bugzilla.mozilla.org/show_bug.cgi?id=810582>`__ - TLS False Start is now + only used with servers that negotiate a cipher suite that supports forward secrecy. + **Note**: The criteria for False Start may change again in future NSS releases. + +.. _bugs_fixed_in_nss_3.14.1: + +`Bugs fixed in NSS 3.14.1 <#bugs_fixed_in_nss_3.14.1>`__ +-------------------------------------------------------- + +.. container:: + + The following Bugzilla query returns all of the bugs fixed in NSS 3.14.1: + + https://bugzilla.mozilla.org/buglist.cgi?list_id=5216669;resolution=FIXED;query_format=advanced;bug_status=RESOLVED;bug_status=VERIFIED;target_milestone=3.14.1;product=NSS + +`Compatability <#compatability>`__ +---------------------------------- + +.. container:: + + NSS 3.14.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.14.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered in this release should be reported by filing a bug report at + https://bugzilla.mozilla.org with the Product of NSS.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.14.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.2_release_notes/index.rst new file mode 100644 index 0000000000..b0b6420aab --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.2_release_notes/index.rst @@ -0,0 +1,103 @@ +.. _mozilla_projects_nss_nss_3_14_2_release_notes: + +NSS 3.14.2 release notes +======================== + +.. container:: + + Network Security Services (NSS) 3.14.2 is a patch release for NSS 3.14. The bug fixes in NSS + 3.14.2 are described in the "Bugs Fixed" section below. NSS 3.14.2 should be used with NSPR 4.9.5 + or newer. + + The release is available for download from + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_14_2_RTM/src/ + + For the primary NSS documentation pages please visit :ref:`mozilla_projects_nss` + +.. _new_in_nss_3.14.2: + +`New in NSS 3.14.2 <#new_in_nss_3.14.2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS will now make use of the Intel AES-NI and AVX instruction sets for hardware-accelerated + AES-GCM on 64-bit Linux systems. Note: the new assembly code requires GNU as version 2.19 or + newer. On Red Hat Enterprise Linux 5.x systems, install the binutils220 package and add + /usr/libexec/binutils220 to the beginning of your PATH environment variable. + - Initial manual pages for some NSS command line tools have been added. They are still under + review, and contributions are welcome. The documentation is in the docbook format and can be + rendered as HTML and UNIX-style manual pages using an optional build target. + + .. rubric:: New Types: + :name: new_types + + - in certt.h + + - ``cert_pi_useOnlyTrustAnchors`` + + - in secoidt.h + + - ``SEC_OID_MS_EXT_KEY_USAGE_CTL_SIGNING`` + +.. _notable_changes_in_nss_3.14.2: + +`Notable Changes in NSS 3.14.2 <#notable_changes_in_nss_3.14.2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Bug 805604 - Support for AES-NI and AVX accelerated AES-GCM was contributed by Shay Gueron of + Intel. If compiled on Linux systems in 64-bit mode, NSS will include runtime detection to + check if the platform supports AES-NI and PCLMULQDQ. If so, NSS uses the optimized code path, + reducing the CPU cycles per byte to 1/20 of what was required before the patch + (https://bugzilla.mozilla.org/show_bug.cgi?id=805604 and + https://crypto.stanford.edu/RealWorldCrypto/slides/gueron.pdf). Support for other platforms, + such as Windows, will follow in a future NSS release. + (https://bugzilla.mozilla.org/show_bug.cgi?id=540986) + - SQLite has been updated to 3.7.15. Note: please apply the patch in + https://bugzilla.mozilla.org/show_bug.cgi?id=837799 if you build NSS with the system SQLite + library and your system SQLite library is older than 3.7.15. + - Bug 816853 - When using libpkix for certificate validation, applications may now supply + additional application-defined trust anchors to be used in addition to those from loaded + security tokens, rather than as an alternative to. + (https://bugzilla.mozilla.org/show_bug.cgi?id=816853) + - Bug 772144 - Basic support for running NSS test suites on Android devices.This is currently + limited to running tests from a Linux host machine using an SSH connection. Only the SSHDroid + app has been tested. + - Bug 373108 - Fixed a bug where, under certain circumstances, when applications supplied + invalid/out-of-bounds parameters for AES encryption, a double free may occur. + - Bug 813857 - Modification of certificate trust flags from multiple threads is now a + thread-safe operation. + - Bug 618418 - C_Decrypt/C_DecryptFinal now correctly validate the PKCS #7 padding when present. + - Bug 807890 - Added support for Microsoft Trust List Signing EKU. + - Bug 822433 - Fixed a crash in dtls_FreeHandshakeMessages. + - Bug 823336 - Reject invalid LDAP AIA URIs sooner. + +.. _bugs_fixed_in_nss_3.14.2: + +`Bugs Fixed in NSS 3.14.2 <#bugs_fixed_in_nss_3.14.2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - https://bugzilla.mozilla.org/buglist.cgi?list_id=5502456;resolution=FIXED;classification=Components;query_format=advanced;target_milestone=3.14.2;product=NSS + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS 3.14.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.14.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <http://bugzilla.mozilla.org/>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.14.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.3_release_notes/index.rst new file mode 100644 index 0000000000..de7ca1d419 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.3_release_notes/index.rst @@ -0,0 +1,132 @@ +.. _mozilla_projects_nss_nss_3_14_3_release_notes: + +NSS 3.14.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.14.3 is a patch release for NSS 3.14. The bug fixes in NSS + 3.14.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The CVS tag is NSS_3_14_3_RTM. NSS 3.14.3 requires NSPR 4.9.5 or newer. + + NSS 3.14.3 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_14_3_RTM/src/ + +.. _new_in_nss_3.14.3: + +`New in NSS 3.14.3 <#new_in_nss_3.14.3>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - No new major functionality is introduced in this release. This release is a patch release to + address `CVE-2013-1620 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1620>`__. + + .. rubric:: New Functions + :name: new_functions + + - *in pk11pub.h* + + - **PK11_SignWithSymKey** - Similar to PK11_Sign, performs a signing operation in a single + operation. However, unlike PK11_Sign, which uses a *SECKEYPrivateKey*, PK11_SignWithSymKey + performs the signature using a symmetric key, such as commonly used for generating MACs. + + .. rubric:: New Types + :name: new_types + + - *CK_NSS_MAC_CONSTANT_TIME_PARAMS* - Parameters for use with *CKM_NSS_HMAC_CONSTANT_TIME* and + *CKM_NSS_SSL3_MAC_CONSTANT_TIME*. + + .. rubric:: New PKCS #11 Mechanisms + :name: new_pkcs_11_mechanisms + + - *CKM_NSS_HMAC_CONSTANT_TIME* - Constant-time HMAC operation for use when verifying a padded, + MAC-then-encrypted block of data. + - *CKM_NSS_SSL3_MAC_CONSTANT_TIME* - Constant-time MAC operation for use when verifying a + padded, MAC-then-encrypted block of data using the SSLv3 MAC. + +.. _notable_changes_in_nss_3.14.3: + +`Notable Changes in NSS 3.14.3 <#notable_changes_in_nss_3.14.3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `CVE-2013-1620 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1620>`__ + + Recent research by Nadhem AlFardan and Kenny Patterson has highlighted a weakness in the + handling of CBC padding as used in SSL, TLS, and DTLS that allows an attacker to exploit + timing differences in MAC processing. The details of their research and the attack can be + found at http://www.isg.rhul.ac.uk/tls/, and has been referred to as "Lucky Thirteen". + + NSS 3.14.3 includes changes to the *softoken* and *ssl* libraries to address and mitigate + these attacks, contributed by Adam Langley of Google. This attack is mitigated when using NSS + 3.14.3 with an NSS Cryptographic Module ("softoken") version 3.14.3 or later. However, this + attack is only partially mitigated if NSS 3.14.3 is used with the current FIPS validated `NSS + Cryptographic + Module <http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2012.htm#1837>`__, version + 3.12.9.1. + + - `Bug 840714 <https://bugzilla.mozilla.org/show_bug.cgi?id=840714>`__ - "certutil -a" was not + correctly producing ASCII output as requested. + + - `Bug 837799 <https://bugzilla.mozilla.org/show_bug.cgi?id=837799>`__ - NSS 3.14.2 broke + compilation with older versions of sqlite that lacked the SQLITE_FCNTL_TEMPFILENAME file + control. NSS 3.14.3 now properly compiles when used with older versions of sqlite. + +`Acknowledgements <#acknowledgements>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The NSS development team would like to thank Nadhem AlFardan and Kenny Patterson (Royal Holloway, + University of London) for responsibly disclosing the issue by providing advance copies of their + research. In addition, thanks to Adam Langley (Google) for the development of a mitigation for + the issues raised in the paper, along with Emilia Kasper and Bodo Möller (Google) for assisting + in the review and improvements to the initial patches. + +.. _bugs_fixed_in_nss_3.14.3: + +`Bugs fixed in NSS 3.14.3 <#bugs_fixed_in_nss_3.14.3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - https://bugzilla.mozilla.org/buglist.cgi?list_id=5689256;resolution=FIXED;classification=Components;query_format=advanced;target_milestone=3.14.3;product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.14.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.14.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.14.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.4_release_notes/index.rst new file mode 100644 index 0000000000..4ba26d3023 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.4_release_notes/index.rst @@ -0,0 +1,82 @@ +.. _mozilla_projects_nss_nss_3_14_4_release_notes: + +NSS 3.14.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.14.4 is a patch release for NSS 3.14. The bug fixes in NSS + 3.14.4 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The CVS tag is NSS_3_14_4_RTM. NSS 3.14.4 requires NSPR 4.9.5 or newer. + + NSS 3.14.4 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_14_4_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.14.4. Users are encouraged to + upgrade immediately. + + - `Bug 894370 <https://bugzilla.mozilla.org/show_bug.cgi?id=894370>`__ - (CVE-2013-1739) Avoid + uninitialized data read in the event of a decryption failure. + +.. _new_in_nss_3.14.4: + +`New in NSS 3.14.4 <#new_in_nss_3.14.4>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - No new major functionality is introduced in this release. This release is a patch release to + address `CVE-2013-1739 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1739>`__. + +.. _bugs_fixed_in_nss_3.14.4: + +`Bugs fixed in NSS 3.14.4 <#bugs_fixed_in_nss_3.14.4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - https://bugzilla.mozilla.org/buglist.cgi?bug_id=894370%2C832942%2C863947&bug_id_type=anyexact&list_id=8338081&resolution=FIXED&classification=Components&query_format=advanced&product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.14.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.14.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.14.5_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.5_release_notes/index.rst new file mode 100644 index 0000000000..0fcf607db8 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.14.5_release_notes/index.rst @@ -0,0 +1,82 @@ +.. _mozilla_projects_nss_nss_3_14_5_release_notes: + +NSS 3.14.5 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.14.5 is a patch release for NSS 3.14. The bug fixes in NSS + 3.14.5 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The CVS tag is NSS_3_14_5_RTM. NSS 3.14.5 requires NSPR 4.9.5 or newer. + + NSS 3.14.5 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_14_5_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.14.5. Users are encouraged to + upgrade immediately. + + - `Bug 934016 <https://bugzilla.mozilla.org/show_bug.cgi?id=934016>`__ - (CVE-2013-5605) Handle + invalid handshake packets + +.. _new_in_nss_3.14.5: + +`New in NSS 3.14.5 <#new_in_nss_3.14.5>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - No new major functionality is introduced in this release. This release is a patch release to + address `CVE-2013-5605 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-5605>`__. + +.. _bugs_fixed_in_nss_3.14.5: + +`Bugs fixed in NSS 3.14.5 <#bugs_fixed_in_nss_3.14.5>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - https://bugzilla.mozilla.org/buglist.cgi?bug_id=934016&bug_id_type=anyexact&resolution=FIXED&classification=Components&query_format=advanced&product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.14.5 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.14.5 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.14_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.14_release_notes/index.rst new file mode 100644 index 0000000000..a1974d1562 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.14_release_notes/index.rst @@ -0,0 +1,174 @@ +.. _mozilla_projects_nss_nss_3_14_release_notes: + +NSS 3.14 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.14, which is a minor release with the + following new features: + + - Support for TLS 1.1 (RFC 4346) + - Experimental support for DTLS 1.0 (RFC 4347) and DTLS-SRTP (RFC 5764) + - Support for AES-CTR, AES-CTS, and AES-GCM + - Support for Keying Material Exporters for TLS (RFC 5705) + + In addition to the above new features, the following major changes have been introduced: + + - Support for certificate signatures using the MD5 hash algorithm is now disabled by default. + - The NSS license has changed to MPL 2.0. Previous releases were released under a MPL 1.1/GPL + 2.0/LGPL 2.1 tri-license. For more information about MPL 2.0, please see + http://www.mozilla.org/MPL/2.0/FAQ.html. For an additional explantation on GPL/LGPL + compatibility, see security/nss/COPYING in the source code. + - Export and DES cipher suites are disabled by default. Non-ECC AES and Triple DES cipher suites + are enabled by default. + + NSS 3.14 source tarballs can be downloaded from + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_14_RTM/src/. The CVS tag is + NSS_3_14_RTM. + +.. _new_in_nss_3.14: + +`New in NSS 3.14 <#new_in_nss_3.14>`__ +-------------------------------------- + +.. container:: + + The sections that follow discuss specific changes in NSS 3.14 in more detail. + + - Support for TLS 1.1 (RFC 4346) has been added + (https://bugzilla.mozilla.org/show_bug.cgi?id=565047). + + .. container:: + + To better support TLS 1.1 and future versions of TLS, a new version range API was + introduced to allow applications to specify the desired minimum and maximum versions. These + functions are intended to replace the now-deprecated use of the SSL_ENABLE_SSL3 and + SSL_ENABLE_TLS socket options. The following functions have been added to the libssl + library included in NSS 3.14 + + - SSL_VersionRangeGet (in ssl.h) + - SSL_VersionRangeGetDefault (in ssl.h) + - SSL_VersionRangeGetSupported (in ssl.h) + - SSL_VersionRangeSet (in ssl.h) + - SSL_VersionRangeSetDefault (in ssl.h) + + - To better ensure interoperability with peers that support TLS 1.1, NSS has altered how it + handles certain SSL protocol layer events. Such changes may present interoperability concerns + when enabling TLS 1.1. + + .. container:: + + - When connecting to a server, the record layer version of the initial ClientHello will be + at most { 3, 1 } (TLS 1.0), even when attempting to negotiate TLS 1.1 + (https://bugzilla.mozilla.org/show_bug.cgi?id=774547) + - The choice of client_version sent during renegotiations has changed. See the + "`Changes <#changes>`__" section below. + + - Experimental Support for DTLS (RFC 4347) and DTLS-SRTP (RFC 5764) + + DTLS client and server support has been added in NSS 3.14. Because the test coverage and + interoperability testing is not yet at the same level as other NSS code, this feature should + be considered "experimental" and may contain bugs. + + The following functions have been added to the libssl library included in NSS 3.14: + + - DTLS_ImportFD (in ssl.h) + - DTLS_GetHandshakeTimeout (in ssl.h) + - SSL_GetSRTPCipher (in ssl.h) + - SSL_SetRTPCiphers (in ssl.h) + + - Support for AES-GCM + + .. container:: + + Support for AES-GCM has been added to the NSS PKCS #11 module (softoken), based upon the + draft 7 of PKCS #11 v2.30. + + **WARNING**: Because of ambiguity in the current draft text, applications should ONLY use + GCM in single-part mode (C_Encrypt/C_Decrypt). They should NOT use multi-part APIs + (C_EncryptUpdate/C_DecryptUpdate). + + - Support for application-defined certificate chain validation callback when using libpkix + + .. container:: + + To better support per-application security policies, a new callback has been added for + applications that use libpkix to verify certificates. Applications may use this callback to + inform libpkix whether or not candidate certificate chains meet application-specific + security policies, allowing libpkix to continue discovering certificate paths until it can + find a chain that satisfies the policies. + + The following types have been added in NSS 3.14 + + - CERTChainVerifyCallback (in certt.h) + - CERTChainVerifyCallbackFunc (in certt.h) + - cert_pi_chainVerifyCallback, a new option for CERTValParamInType (in certt.h) + - A new error code: SEC_ERROR_APPLICATION_CALLBACK_ERROR (in secerr.h) + + - New for PKCS #11 + + .. container:: + + PKCS #11 mechanisms: + + - CKM_AES_CTS + - CKM_AES_CTR + - CKM_AES_GCM (see warnings against using C_EncryptUpdate/C_DecryptUpdate above) + - CKM_SHA224_KEY_DERIVATION + - CKM_SHA256_KEY_DERIVATION + - CKM_SHA384_KEY_DERIVATION + - CKM_SHA512_KEY_DERIVATION + + Changes in NSS 3.14 + +.. _changes_in_nss_3.14: + +`Changes in NSS 3.14 <#changes_in_nss_3.14>`__ +---------------------------------------------- + +.. container:: + + - `Bug 333601 <https://bugzilla.mozilla.org/show_bug.cgi?id=333601>`__ - Performance + enhancements for Intel Macs + + When building for Intel Macs, NSS will now take advantage of optimized assembly code for + common operations. These changes have the observed effect of doubling RSA performance. + + - `Bug 792681 <https://bugzilla.mozilla.org/show_bug.cgi?id=792681>`__ - New default cipher + suites + + The default cipher suites in NSS 3.14 have been changed to better reflect the current security + landscape. The defaults now better match the set that most major Web browsers enable by + default. + + - `Bug 783448 <https://bugzilla.mozilla.org/show_bug.cgi?id=783448>`__ - When performing an SSL + renegotiation, the client_version that is sent in the renegotiation ClientHello will be set to + match the client_version that was sent in the initial ClientHello. This is needed for + compatibility with IIS. + + - Certificate signatures that make use of the MD5 hash algorithm will now be rejected by + default. Support for MD5 may be manually enabled (but is discouraged) by setting the + environment variable of "NSS_HASH_ALG_SUPPORT=+MD5" or by using the NSS_SetAlgorithmPolicy + function. Note that SSL cipher suites with "MD5" in their names are NOT disabled by this + change; those cipher suites use HMAC-MD5, not plain MD5, and are still considered safe. + + - Maximum key sizes for RSA and Diffie-Hellman keys have been increased to 16K bits. + + - Command line utilities tstclnt, strsclnt, and selfserv have changed. The old options to + disable SSL 2, SSL 3 and TLS 1.0 have been removed and replaced with a new -V option that + specifies the enabled range of protocol versions (see usage output of those tools). + +.. _bugs_fixed_in_nss_3.14: + +`Bugs fixed in NSS 3.14 <#bugs_fixed_in_nss_3.14>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.14: + + https://bugzilla.mozilla.org/buglist.cgi?list_id=4643675;resolution=FIXED;classification=Components;query_format=advanced;product=NSS;target_milestone=3.14
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.15.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.1_release_notes/index.rst new file mode 100644 index 0000000000..4ab5b7e1f2 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.1_release_notes/index.rst @@ -0,0 +1,131 @@ +.. _mozilla_projects_nss_nss_3_15_1_release_notes: + +NSS 3.15.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.15.1 is a patch release for NSS 3.15. The bug fixes in NSS + 3.15.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + NSS 3.15.1 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_15_1_RTM/src/ + +.. _new_in_nss_3.15.1: + +`New in NSS 3.15.1 <#new_in_nss_3.15.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - TLS 1.2: TLS 1.2 (`RFC 5246 <https://datatracker.ietf.org/doc/html/rfc5246>`__) is supported. + HMAC-SHA256 cipher suites (`RFC 5246 <https://datatracker.ietf.org/doc/html/rfc5246>`__ and + `RFC 5289 <https://datatracker.ietf.org/doc/html/rfc5289>`__) are supported, allowing TLS to + be used without MD5 and SHA-1. Note the following limitations. + + - The hash function used in the signature for TLS 1.2 client authentication must be the hash + function of the TLS 1.2 PRF, which is always SHA-256 in NSS 3.15.1. + - AES GCM cipher suites are not yet supported. + + .. rubric:: New Functions + :name: new_functions + + None. + + .. rubric:: New Types + :name: new_types + + - *in sslprot.h* + + - **SSL_LIBRARY_VERSION_TLS_1_2** - The protocol version of TLS 1.2 on the wire, value + 0x0303. + - **TLS_DHE_RSA_WITH_AES_256_CBC_SHA256**, **TLS_RSA_WITH_AES_256_CBC_SHA256**, + **TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256**, **TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256**, + **TLS_DHE_RSA_WITH_AES_128_CBC_SHA256**, **TLS_RSA_WITH_AES_128_CBC_SHA256**, + **TLS_RSA_WITH_NULL_SHA256** - New TLS 1.2 only HMAC-SHA256 cipher suites. + + - *in sslerr.h* + + - **SSL_ERROR_UNSUPPORTED_HASH_ALGORITHM**, **SSL_ERROR_DIGEST_FAILURE**, + **SSL_ERROR_INCORRECT_SIGNATURE_ALGORITHM** - New error codes for TLS 1.2. + + - *in sslt.h* + + - **ssl_hmac_sha256** - A new value in the SSLMACAlgorithm enum type. + - **ssl_signature_algorithms_xtn** - A new value in the SSLExtensionType enum type. + + .. rubric:: New PKCS #11 Mechanisms + :name: new_pkcs_11_mechanisms + + None. + +.. _notable_changes_in_nss_3.15.1: + +`Notable Changes in NSS 3.15.1 <#notable_changes_in_nss_3.15.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 856060 <https://bugzilla.mozilla.org/show_bug.cgi?id=856060>`__ - Enforce name + constraints on the common name in libpkix when no subjectAltName is present. + - `Bug 875156 <https://bugzilla.mozilla.org/show_bug.cgi?id=875156>`__ - Add const to the + function arguments of SEC_CertNicknameConflict. + - `Bug 877798 <https://bugzilla.mozilla.org/show_bug.cgi?id=877798>`__ - Fix ssltap to print the + certificate_status handshake message correctly. + - `Bug 882829 <https://bugzilla.mozilla.org/show_bug.cgi?id=882829>`__ - On Windows, NSS + initialization fails if NSS cannot call the RtlGenRandom function. + - `Bug 875601 <https://bugzilla.mozilla.org/show_bug.cgi?id=875601>`__ - + SECMOD_CloseUserDB/SECMOD_OpenUserDB fails to reset the token delay, leading to spurious + failures. + - `Bug 884072 <https://bugzilla.mozilla.org/show_bug.cgi?id=884072>`__ - Fix a typo in the + header include guard macro of secmod.h. + - `Bug 876352 <https://bugzilla.mozilla.org/show_bug.cgi?id=876352>`__ - certutil now warns if + importing a PEM file that contains a private key. + - `Bug 565296 <https://bugzilla.mozilla.org/show_bug.cgi?id=565296>`__ - Fix the bug that + shlibsign exited with status 0 even though it failed. + - The NSS_SURVIVE_DOUBLE_BYPASS_FAILURE build option is removed. + +.. _bugs_fixed_in_nss_3.15.1: + +`Bugs fixed in NSS 3.15.1 <#bugs_fixed_in_nss_3.15.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - https://bugzilla.mozilla.org/buglist.cgi?list_id=5689256;resolution=FIXED;classification=Components;query_format=advanced;target_milestone=3.15.1;product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.15.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.15.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.15.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.2_release_notes/index.rst new file mode 100644 index 0000000000..34fb238c5e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.2_release_notes/index.rst @@ -0,0 +1,126 @@ +.. _mozilla_projects_nss_nss_3_15_2_release_notes: + +NSS 3.15.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.15.2 is a patch release for NSS 3.15. The bug fixes in NSS + 3.15.2 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + NSS 3.15.2 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_15_2_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.15.2. Users are encouraged to + upgrade immediately. + + - `Bug 894370 <https://bugzilla.mozilla.org/show_bug.cgi?id=894370>`__ - (CVE-2013-1739) Avoid + uninitialized data read in the event of a decryption failure. + +.. _new_in_nss_3.15.2: + +`New in NSS 3.15.2 <#new_in_nss_3.15.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - AES-GCM Ciphersuites: AES-GCM cipher suite (RFC 5288 and RFC 5289) support has been added when + TLS 1.2 is negotiated. Specifically, the following cipher suites are now supported: + + - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 + - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_RSA_WITH_AES_128_GCM_SHA256 + + .. rubric:: New Functions + :name: new_functions + + PK11_CipherFinal has been introduced, which is a simple alias for PK11_DigestFinal. + + .. rubric:: New Types + :name: new_types + + No new types have been introduced. + + .. rubric:: New PKCS #11 Mechanisms + :name: new_pkcs_11_mechanisms + + No new PKCS#11 mechanisms have been introduced + +.. _notable_changes_in_nss_3.15.2: + +`Notable Changes in NSS 3.15.2 <#notable_changes_in_nss_3.15.2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 880543 <https://bugzilla.mozilla.org/show_bug.cgi?id=880543>`__ - Support for AES-GCM + ciphersuites that use the SHA-256 PRF + - `Bug 663313 <https://bugzilla.mozilla.org/show_bug.cgi?id=663313>`__ - MD2, MD4, and MD5 + signatures are no longer accepted for OCSP or CRLs, consistent with their handling for general + certificate signatures. + - `Bug 884178 <https://bugzilla.mozilla.org/show_bug.cgi?id=884178>`__ - Add PK11_CipherFinal + macro + +.. _bugs_fixed_in_nss_3.15.2: + +`Bugs fixed in NSS 3.15.2 <#bugs_fixed_in_nss_3.15.2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 734007 <https://bugzilla.mozilla.org/show_bug.cgi?id=734007>`__ - sizeof() used + incorrectly + - `Bug 900971 <https://bugzilla.mozilla.org/show_bug.cgi?id=900971>`__ - nssutil_ReadSecmodDB() + leaks memory + - `Bug 681839 <https://bugzilla.mozilla.org/show_bug.cgi?id=681839>`__ - Allow + SSL_HandshakeNegotiatedExtension to be called before the handshake is finished. + - `Bug 848384 <https://bugzilla.mozilla.org/show_bug.cgi?id=848384>`__ - Deprecate the SSL + cipher policy code, as it's no longer relevant. It is no longer necessary to call + NSS_SetDomesticPolicy because all cipher suites are now allowed by default. + + A complete list of all bugs resolved in this release can be obtained at + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&target_milestone=3.15.2&product=NSS&list_id=7982238 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.15.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.15.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.15.3.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.3.1_release_notes/index.rst new file mode 100644 index 0000000000..53484659ea --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.3.1_release_notes/index.rst @@ -0,0 +1,89 @@ +.. _mozilla_projects_nss_nss_3_15_3_1_release_notes: + +NSS 3.15.3.1 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.15.3.1 is a patch release for NSS 3.15. The bug fixes in NSS + 3.15.3.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_15_3_1_RTM. NSS 3.15.3.1 requires NSPR 4.10.2 or newer. + + NSS 3.15.3.1 source distributions are also available on ftp.mozilla.org for secure HTTPS + download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_15_3_1_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.15.3.1. Users are encouraged to + upgrade immediately. + + - `Bug 946351 <https://bugzilla.mozilla.org/show_bug.cgi?id=946351>`__ - Misissued Google + certificates from DCSSI + +.. _new_in_nss_3.15.3.1: + +`New in NSS 3.15.3.1 <#new_in_nss_3.15.3.1>`__ +---------------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new major functionality is introduced in this release. This is a patch release to `revoke + trust of a subordinate CA + certificate <https://blog.mozilla.org/security/2013/12/09/revoking-trust-in-one-anssi-certificate/>`__ + that was mis-used to generate a certificate used by a network appliance. + +.. _bugs_fixed_in_nss_3.15.3.1: + +`Bugs fixed in NSS 3.15.3.1 <#bugs_fixed_in_nss_3.15.3.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 946351 <https://bugzilla.mozilla.org/show_bug.cgi?id=946351>`__ - Misissued Google + certificates from DCSSI + + A complete list of all bugs resolved in this release can be obtained at + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&target_milestone=3.15.3.1&product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.15.3.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.15.3.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.15.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.3_release_notes/index.rst new file mode 100644 index 0000000000..ac1275460d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.3_release_notes/index.rst @@ -0,0 +1,94 @@ +.. _mozilla_projects_nss_nss_3_15_3_release_notes: + +NSS 3.15.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.15.3 is a patch release for NSS 3.15. The bug fixes in NSS + 3.15.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_15_3_RTM. NSS 3.15.3 requires NSPR 4.10.2 or newer. + + NSS 3.15.3 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_15_3_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.15.3. Users are encouraged to + upgrade immediately. + + - `Bug 925100 <https://bugzilla.mozilla.org/show_bug.cgi?id=925100>`__ - (CVE-2013-1741) Ensure + a size is <= half of the maximum PRUint32 value + - `Bug 934016 <https://bugzilla.mozilla.org/show_bug.cgi?id=934016>`__ - (CVE-2013-5605) Handle + invalid handshake packets + - `Bug 910438 <https://bugzilla.mozilla.org/show_bug.cgi?id=910438>`__ - (CVE-2013-5606) Return + the correct result in CERT_VerifyCert on failure, if a verifyLog isn't used + +.. _new_in_nss_3.15.3: + +`New in NSS 3.15.3 <#new_in_nss_3.15.3>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new major functionality is introduced in this release. This release is a patch release to + address `CVE-2013-1741 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1741>`__, + `CVE- <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-5605>`__\ `2013-5605 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-5605>`__ + and `CVE-2013-5606 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-5606>`__. + +.. _bugs_fixed_in_nss_3.15.3: + +`Bugs fixed in NSS 3.15.3 <#bugs_fixed_in_nss_3.15.3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 850478 <https://bugzilla.mozilla.org/show_bug.cgi?id=850478>`__ - List RC4_128 cipher + suites after AES_128 cipher suites + - `Bug 919677 <https://bugzilla.mozilla.org/show_bug.cgi?id=919677>`__ - Don't advertise TLS + 1.2-only ciphersuites in a TLS 1.1 ClientHello + + A complete list of all bugs resolved in this release can be obtained at + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&target_milestone=3.15.3&product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.15.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.15.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.15.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.4_release_notes/index.rst new file mode 100644 index 0000000000..1f01a93df9 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.4_release_notes/index.rst @@ -0,0 +1,137 @@ +.. _mozilla_projects_nss_nss_3_15_4_release_notes: + +NSS 3.15.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.15.4 is a patch release for NSS 3.15. The bug fixes in NSS + 3.15.4 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_15_4_RTM. NSS 3.15.4 requires NSPR 4.10.2 or newer. + + NSS 3.15.4 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_15_4_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.15.4. Users are encouraged to + upgrade immediately. + + - `Bug 919877 <https://bugzilla.mozilla.org/show_bug.cgi?id=919877>`__ - (CVE-2013-1740) When + false start is enabled, libssl will sometimes return unencrypted, unauthenticated data from + PR_Recv + +.. _new_in_nss_3.15.4: + +`New in NSS 3.15.4 <#new_in_nss_3.15.4>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Implemented OCSP querying using the HTTP GET method, which is the new default, and will fall + back to the HTTP POST method. + - Implemented OCSP server functionality for testing purposes (httpserv utility). + - Support SHA-1 signatures with TLS 1.2 client authentication. + - Added the --empty-password command-line option to certutil, to be used with -N: use an empty + password when creating a new database. + - Added the -w command-line option to pp: don't wrap long output lines. + +.. _new_functions: + +`New Functions <#new_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - CERT_ForcePostMethodForOCSP + - CERT_GetSubjectNameDigest + - CERT_GetSubjectPublicKeyDigest + - SSL_PeerCertificateChain + - SSL_RecommendedCanFalseStart + - SSL_SetCanFalseStartCallback + +.. _new_types: + +`New Types <#new_types>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - CERT_REV_M_FORCE_POST_METHOD_FOR_OCSP: When this flag is used, libpkix will never attempt to + use the HTTP GET method for OCSP requests; it will always use POST. + +.. _new_pkcs_11_mechanisms: + +`New PKCS #11 Mechanisms <#new_pkcs_11_mechanisms>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + None. + +.. _notable_changes_in_nss_3.15.4: + +`Notable Changes in NSS 3.15.4 <#notable_changes_in_nss_3.15.4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Reordered the cipher suites offered in SSL/TLS client hello messages to match modern best + practices. + - Updated the set of root CA certificates (version 1.96). + - Improved SSL/TLS false start. In addition to enabling the SSL_ENABLE_FALSE_START option, an + application must now register a callback using the SSL_SetCanFalseStartCallback function. + - When building on Windows, OS_TARGET now defaults to WIN95. To use the WINNT build + configuration, specify OS_TARGET=WINNT. + +.. _bugs_fixed_in_nss_3.15.4: + +`Bugs fixed in NSS 3.15.4 <#bugs_fixed_in_nss_3.15.4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A complete list of all bugs resolved in this release can be obtained at + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&target_milestone=3.15.4&product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.15.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.15.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.15.5_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.5_release_notes/index.rst new file mode 100644 index 0000000000..3a3a829f04 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.15.5_release_notes/index.rst @@ -0,0 +1,93 @@ +.. _mozilla_projects_nss_nss_3_15_5_release_notes: + +NSS 3.15.5 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.15.5 is a patch release for NSS 3.15. The bug fixes in NSS + 3.15.5 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_15_5_RTM. NSS 3.15.5 requires NSPR 4.10.2 or newer. + + NSS 3.15.5 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_15_5_RTM/src/ + +.. _new_in_nss_3.15.5: + +`New in NSS 3.15.5 <#new_in_nss_3.15.5>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Added support for the TLS `application layer protocol negotiation (ALPN) + extension <http://www.iana.org/go/draft-friedl-tls-applayerprotoneg>`__. Two SSL socket + options, ``SSL_ENABLE_NPN`` and ``SSL_ENABLE_ALPN``, can be used to control whether NPN or + ALPN (or both) should be used for application layer protocol negotiation. + - Added the TLS `padding + extension <https://datatracker.ietf.org/doc/html/draft-agl-tls-padding>`__. The extension type + value is 35655, which may change when an official extension type value is assigned by IANA. + NSS automatically adds the padding extension to ClientHello when necessary. + - Added a new macro ``CERT_LIST_TAIL``, defined in ``certt.h``, for getting the tail of a + ``CERTCertList``. + +.. _notable_changes_in_nss_3.15.5: + +`Notable Changes in NSS 3.15.5 <#notable_changes_in_nss_3.15.5>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 950129 <https://bugzilla.mozilla.org/show_bug.cgi?id=950129>`__: Improve the OCSP + fetching policy when verifying OCSP responses + - `Bug 949060 <https://bugzilla.mozilla.org/show_bug.cgi?id=949060>`__: Validate the ``iov`` + input argument (an array of ``PRIOVec`` structures) of ``ssl_WriteV`` (called via + ``PR_Writev``). Applications should still take care when converting ``struct iov`` to + ``PRIOVec`` because the ``iov_len`` members of the two structures have different types + (``size_t`` vs. ``int``). ``size_t`` is unsigned and may be larger than ``int``. + +.. _bugs_fixed_in_nss_3.15.5: + +`Bugs fixed in NSS 3.15.5 <#bugs_fixed_in_nss_3.15.5>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A complete list of all bugs resolved in this release can be obtained at + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&target_milestone=3.15.5&product=NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.15.5 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.15.5 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.15_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.15_release_notes/index.rst new file mode 100644 index 0000000000..afae48e33f --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.15_release_notes/index.rst @@ -0,0 +1,157 @@ +.. _mozilla_projects_nss_nss_3_15_release_notes: + +NSS 3.15 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.15, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_15_RTM. NSS 3.15 requires NSPR 4.10 or newer. + + NSS 3.15 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_15_RTM/src/ + +.. _new_in_nss_3.15: + +`New in NSS 3.15 <#new_in_nss_3.15>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Support for OCSP Stapling (`RFC 6066 <https://datatracker.ietf.org/doc/html/rfc6066>`__, + Certificate Status Request) has been added for both client and server sockets. TLS client + applications may enable this via a call to + ``SSL_OptionSetDefault(SSL_ENABLE_OCSP_STAPLING, PR_TRUE);`` + - Added function SECITEM_ReallocItemV2. It replaces function SECITEM_ReallocItem, which is now + declared as obsolete. + - Support for single-operation (eg: not multi-part) symmetric key encryption and decryption, via + *PK11_Encrypt* and *PK11_Decrypt*. + - certutil has been updated to support creating name constraints extensions. + + .. rubric:: New Functions + :name: new_functions + + - *in ssl.h* + + - **SSL_PeerStapledOCSPResponse** - Returns the server's stapled OCSP response, when used + with a TLS client socket that negotiated the *status_request* extension. + - **SSL_SetStapledOCSPResponses** - Set's a stapled OCSP response for a TLS server socket to + return when clients send the *status_request* extension. + + - *in ocsp.h* + + - **CERT_PostOCSPRequest** - Primarily intended for testing, permits the sending and + receiving of raw OCSP request/responses. + + - *in secpkcs7.h* + + - **SEC_PKCS7VerifyDetachedSignatureAtTime** - Verifies a PKCS#7 signature at a specific time + other than the present time. + + - *in xconst.h* + + - **CERT_EncodeNameConstraintsExtension** - Matching function for + CERT_DecodeNameConstraintsExtension, added in NSS 3.10. + + - *in secitem.h* + + - **SECITEM_AllocArray** + - **SECITEM_DupArray** + - **SECITEM_FreeArray** + - **SECITEM_ZfreeArray** - Utility functions to handle the allocation and deallocation of + *SECItemArray*\ s + - **SECITEM_ReallocItemV2** - Replaces *SECITEM_ReallocItem*, which is now obsolete. + *SECITEM_ReallocItemV2* better matches caller expectations, in that it updates + ``item->len`` on allocation. For more details of the issues with SECITEM_ReallocItem, see + `Bug 298649 <http://bugzil.la/298649>`__ and `Bug 298938 <http://bugzil.la/298938>`__. + + - *in pk11pub.h* + + - **PK11_Decrypt** - Performs decryption as a single PKCS#11 operation (eg: not multi-part). + This is necessary for AES-GCM. + - **PK11_Encrypt** - Performs encryption as a single PKCS#11 operation (eg: not multi-part). + This is necessary for AES-GCM. + + .. rubric:: New Types + :name: new_types + + - *in secitem.h* + + - **SECItemArray** - Represents a variable-length array of *SECItem*\ s. + + .. rubric:: New Macros + :name: new_macros + + - *in ssl.h* + + - **SSL_ENABLE_OCSP_STAPLING** - Used with *SSL_OptionSet* to configure TLS client sockets to + request the *certificate_status* extension (eg: OCSP stapling) when set to **PR_TRUE** + +.. _notable_changes_in_nss_3.15: + +`Notable Changes in NSS 3.15 <#notable_changes_in_nss_3.15>`__ +-------------------------------------------------------------- + +.. container:: + + - *SECITEM_ReallocItem* is now deprecated. Please consider using *SECITEM_ReallocItemV2* in all + future code. + + - NSS has migrated from CVS to the Mercurial source control management system. + + Updated build instructions are available at + :ref:`mozilla_projects_nss_reference_building_and_installing_nss_migration_to_hg` + + As part of this migration, the source code directory layout has been re-organized. + + - The list of root CA certificates in the *nssckbi* module has been updated. + + - The default implementation of SSL_AuthCertificate has been updated to add certificate status + responses stapled by the TLS server to the OCSP cache. + + Applications that use SSL_AuthCertificateHook to override the default handler should add + appropriate calls to *SSL_PeerStapledOCSPResponse* and + *CERT_CacheOCSPResponseFromSideChannel*. + + - `Bug 554369 <https://bugzilla.mozilla.org/show_bug.cgi?id=554369>`__: Fixed correctness of + CERT_CacheOCSPResponseFromSideChannel and other OCSP caching behaviour. + + - `Bug 853285 <https://bugzilla.mozilla.org/show_bug.cgi?id=853285>`__: Fixed bugs in AES GCM. + + - `Bug 341127 <https://bugzilla.mozilla.org/show_bug.cgi?id=341127>`__: Fix the invalid read in + rc4_wordconv. + + - `Faster NIST curve P-256 + implementation <https://bugzilla.mozilla.org/show_bug.cgi?id=831006>`__. + + - Dropped (32-bit) SPARC V8 processor support on Solaris. The shared library + ``libfreebl_32int_3.so`` is no longer produced. + +.. _bugs_fixed_in_nss_3.15: + +`Bugs fixed in NSS 3.15 <#bugs_fixed_in_nss_3.15>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.15: + + https://bugzilla.mozilla.org/buglist.cgi?list_id=6278317&resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.15
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.1_release_notes/index.rst new file mode 100644 index 0000000000..65602f5a8d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.1_release_notes/index.rst @@ -0,0 +1,97 @@ +.. _mozilla_projects_nss_nss_3_16_1_release_notes: + +NSS 3.16.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.1 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_1_RTM. NSS 3.16.1 requires NSPR 4.10.5 or newer. + + NSS 3.16.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_1_RTM/src/ + +.. _new_in_nss_3.16.1: + +`New in NSS 3.16.1 <#new_in_nss_3.16.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Added the "ECC" flag for modutil to select the module used for elliptic curve cryptography + (ECC) operations. + + .. rubric:: New Functions + :name: new_functions + + - *in pk11pub.h* + + - **PK11_ExportDERPrivateKeyInfo and PK11_ExportPrivKeyInfo** - exports a private key in a + DER-encoded ASN.1 PrivateKeyInfo type or a SECKEYPrivateKeyInfo structure. Only RSA private + keys are supported now. + + - *in secmod.h* + + - **SECMOD_InternalToPubMechFlags** - converts from NSS-internal to public representation of + mechanism flags. + + .. rubric:: New Types + :name: new_types + + - *in sslt.h* + + - **ssl_padding_xtn** - the value of this enum constant changed from the experimental value + 35655 to the IANA-assigned value 21. . + + .. rubric:: New Macros + :name: new_macros + + - *in secmod.h* + + - **PUBLIC_MECH_ECC_FLAG** - a public mechanism flag for elliptic curve cryptography (ECC) + operations. + + - *in utilmodt.h* + + - **SECMOD_ECC_FLAG** - an NSS-internal mechanism flag for elliptic curve cryptography (ECC) + operations. This macro has the same numeric value as **PUBLIC_MECH_ECC_FLAG.** + +.. _notable_changes_in_nss_3.16.1: + +`Notable Changes in NSS 3.16.1 <#notable_changes_in_nss_3.16.1>`__ +------------------------------------------------------------------ + +.. container:: + + - Imposed `name constraints <https://hg.mozilla.org/projects/nss/rev/742307da0792>`__ on the + French government root CA ANSSI (DCISS). + +.. _bugs_fixed_in_nss_3.16.1: + +`Bugs fixed in NSS 3.16.1 <#bugs_fixed_in_nss_3.16.1>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.16.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.16.1
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.1_release_notes/index.rst new file mode 100644 index 0000000000..6e768762a1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.1_release_notes/index.rst @@ -0,0 +1,99 @@ +.. _mozilla_projects_nss_nss_3_16_2_1_release_notes: + +NSS 3.16.2.1 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.2.1 is a patch release for NSS 3.16, based on the NSS 3.16.2 + release. The bug fixes in NSS 3.16.2.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_2_1_RTM. NSS 3.16.2.1 requires NSPR 4.10.6 or newer. + + NSS 3.16.2.1 source distributions are also available on ftp.mozilla.org for secure HTTPS + download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_2_1_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.16.2.1. Users are encouraged to + upgrade immediately. + + - `Bug 1064636 <https://bugzilla.mozilla.org/show_bug.cgi?id=1064636>`__ - (CVE-2014-1568) RSA + Signature Forgery in NSS. See also `MFSA + 2014-73 <https://www.mozilla.org/security/announce/2014/mfsa2014-73.html>`__ for details. + +.. _new_in_nss_3.16.2.1: + +`New in NSS 3.16.2.1 <#new_in_nss_3.16.2.1>`__ +---------------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix a bug that + caused NSS to accept forged RSA signatures. + + A new symbol, \_SGN_VerifyPKCS1DigestInfo is exported in this release. As with all exported NSS + symbols that have a leading underscore '_', this is an internal symbol for NSS use only. + Applications that use or depend on these symbols can and will break in future NSS releases. + +.. _bugs_fixed_in_nss_3.16.2.1: + +`Bugs fixed in NSS 3.16.2.1 <#bugs_fixed_in_nss_3.16.2.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 1064636 <https://bugzilla.mozilla.org/show_bug.cgi?id=1064636>`__ - (CVE-2014-1568) RSA + Signature Forgery in NSS + +`Acknowledgements <#acknowledgements>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The NSS development team would like to thank Antoine Delignat-Lavaud, security researcher at + Inria Paris in team Prosecco, and the Advanced Threat Research team at Intel Security, who both + independently discovered and reported this issue, for responsibly disclosing the issue by + providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.16.2.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.16.2.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.2_release_notes/index.rst new file mode 100644 index 0000000000..82894df0af --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.2_release_notes/index.rst @@ -0,0 +1,81 @@ +.. _mozilla_projects_nss_nss_3_16_2_2_release_notes: + +NSS 3.16.2.2 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.2.2 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.2.2 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_2_2_RTM. NSS 3.16.2.2 requires NSPR 4.10.6 or newer. + + NSS 3.16.2.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_2_2_RTM/src/ + +.. _new_in_nss_3.16.2.2: + +`New in NSS 3.16.2.2 <#new_in_nss_3.16.2.2>`__ +---------------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix a regression. + +.. _notable_changes_in_nss_3.16.2.2: + +`Notable Changes in NSS 3.16.2.2 <#notable_changes_in_nss_3.16.2.2>`__ +---------------------------------------------------------------------- + +.. container:: + + - `Bug 1049435 <https://bugzilla.mozilla.org/show_bug.cgi?id=1049435>`__: Change + RSA_PrivateKeyCheck to not require p > q. This fixes a regression introduced in NSS 3.16.2 + that prevented NSS from importing some RSA private keys (such as in PKCS #12 files) generated + by other crypto libraries. + +.. _bugs_fixed_in_nss_3.16.2.2: + +`Bugs fixed in NSS 3.16.2.2 <#bugs_fixed_in_nss_3.16.2.2>`__ +------------------------------------------------------------ + +.. container:: + + - `Bug 1049435 <https://bugzilla.mozilla.org/show_bug.cgi?id=1049435>`__ - Importing an RSA + private key fails if p < q + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.16.2.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.16.2.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.3_release_notes/index.rst new file mode 100644 index 0000000000..d2e7278d55 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2.3_release_notes/index.rst @@ -0,0 +1,110 @@ +.. _mozilla_projects_nss_nss_3_16_2_3_release_notes: + +NSS 3.16.2.3 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.2.3 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.2.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_2_3_RTM. NSS 3.16.2.3 requires NSPR 4.10.6 or newer. + + NSS 3.16.2.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_2_3_RTM/src/ + +.. _new_in_nss_3.16.2.3: + +`New in NSS 3.16.2.3 <#new_in_nss_3.16.2.3>`__ +---------------------------------------------- + +.. container:: + + This patch release fixes a bug and contains a backport of the TLS_FALLBACK_SCSV feature, which + was originally made available in NSS 3.17.1. + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `TLS_FALLBACK_SCSV <https://datatracker.ietf.org/doc/html/draft-ietf-tls-downgrade-scsv-00>`__ + is a signaling cipher suite value that indicates a handshake is the result of TLS version + fallback. + +.. _new_macros: + +`New Macros <#new_macros>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - *in ssl.h* + + - **SSL_ENABLE_FALLBACK_SCSV** - an SSL socket option that enables TLS_FALLBACK_SCSV. Off by + default. + + - *in sslerr.h* + + - **SSL_ERROR_INAPPROPRIATE_FALLBACK_ALERT** - a new SSL error code. + + - *in sslproto.h* + + - **TLS_FALLBACK_SCSV** - a signaling cipher suite value that indicates a handshake is the + result of TLS version fallback. + +.. _notable_changes_in_nss_3.16.2.3: + +`Notable Changes in NSS 3.16.2.3 <#notable_changes_in_nss_3.16.2.3>`__ +---------------------------------------------------------------------- + +.. container:: + + - `Bug 1057161 <https://bugzilla.mozilla.org/show_bug.cgi?id=1057161>`__: Check that an imported + elliptic curve public key is valid. Previously NSS would only validate the peer's public key + before performing ECDH key agreement. Now EC public keys are validated at import time. + +.. _bugs_fixed_in_nss_3.16.2.3: + +`Bugs fixed in NSS 3.16.2.3 <#bugs_fixed_in_nss_3.16.2.3>`__ +------------------------------------------------------------ + +.. container:: + + - `Bug 1057161 <https://bugzilla.mozilla.org/show_bug.cgi?id=1057161>`__ - NSS hangs with 100% + CPU on invalid EC key + - `Bug 1036735 <https://bugzilla.mozilla.org/show_bug.cgi?id=1036735>`__ - Add support for + draft-ietf-tls-downgrade-scsv to NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.16.2.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.16.2.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2_release_notes/index.rst new file mode 100644 index 0000000000..368680e3a1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.2_release_notes/index.rst @@ -0,0 +1,113 @@ +.. _mozilla_projects_nss_nss_3_16_2_release_notes: + +NSS 3.16.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.2 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.2 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_2_RTM. NSS 3.16.2 requires NSPR 4.10.6 or newer. + + NSS 3.16.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_2_RTM/src/ + +.. _new_in_nss_3.16.2: + +`New in NSS 3.16.2 <#new_in_nss_3.16.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - DTLS 1.2 is supported. + - The TLS application layer protocol negotiation (ALPN) extension is also supported on the + server side. + - RSA-OEAP is supported. Use the new PK11_PrivDecrypt and PK11_PubEncrypt functions with the + CKM_RSA_PKCS_OAEP mechanism. + - New Intel AES assembly code for 32-bit and 64-bit Windows, contributed by Shay Gueron and Vlad + Krasnov of Intel. + + .. rubric:: New Functions + :name: new_functions + + - *in cert.h* + + - **CERT_AddExtensionByOID** - adds an extension to a certificate. It is the same as + CERT_AddExtension except that the OID is represented by a SECItem instead of a SECOidTag. + + - *in pk11pub.h* + + - **PK11_PrivDecrypt** - decrypts with a private key. The algorithm is specified with a + CK_MECHANISM_TYPE. + - **PK11_PubEncrypt** - encrypts with a public key. The algorithm is specified with a + CK_MECHANISM_TYPE. + + .. rubric:: New Macros + :name: new_macros + + - *in sslerr.h* + + - **SSL_ERROR_NEXT_PROTOCOL_NO_CALLBACK** - An SSL error code that means the next protcol + negotiation extension was enabled, but the callback was cleared prior to being needed. + - **SSL_ERROR_NEXT_PROTOCOL_NO_PROTOCOL** - An SSL error code that means the server supports + no protocols that the client advertises in the ALPN extension. + +.. _notable_changes_in_nss_3.16.2: + +`Notable Changes in NSS 3.16.2 <#notable_changes_in_nss_3.16.2>`__ +------------------------------------------------------------------ + +.. container:: + + - The btoa command has a new command-line option -w *suffix*, which causes the output to be + wrapped in BEGIN/END lines with the given suffix. Use "c" as a shorthand for the suffix + CERTIFICATE. + - The certutil commands supports additionals types of subject alt name extensions: + + - --extSAN *type:name[,type:name]...* + + - The certutil commands supports generic certificate extensions, by loading binary data from + files, which have been prepared using external tools, or which have been extracted and dumped + to file from other existing certificates: + + - --dump-ext-val *OID* + - --extGeneric *OID:critical-flag:filename[,OID:critical-flag:filename]...* + + - The certutil command has three new certificate usage specifiers: + + - L: certificateUsageSSLCA + - A: certificateUsageAnyCA + - Y: certificateUsageVerifyCA + + - The pp command has a new command-line option -u, which means "use UTF-8". The default is to + show a non-ASCII character as ".". + - On Linux, NSS is built with the -ffunction-sections -fdata-sections compiler flags and the + --gc-sections linker flag to allow unused functions to be discarded. + +.. _bugs_fixed_in_nss_3.16.2: + +`Bugs fixed in NSS 3.16.2 <#bugs_fixed_in_nss_3.16.2>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.16.2: + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.16.2 diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.3_release_notes/index.rst new file mode 100644 index 0000000000..a2c04db1d0 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.3_release_notes/index.rst @@ -0,0 +1,171 @@ +.. _mozilla_projects_nss_nss_3_16_3_release_notes: + +NSS 3.16.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.3 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_3_RTM. NSS 3.16.3 requires NSPR 4.10.6 or newer. + + NSS 3.16.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_3_RTM/src/ + +.. _new_in_nss_3.16.3: + +`New in NSS 3.16.3 <#new_in_nss_3.16.3>`__ +------------------------------------------ + +.. container:: + + This release consists primarily of CA certificate changes as listed below, and fixes an issue + with a recently added utility function. + + .. rubric:: New Functions + :name: new_functions + + - *in cert.h* + + - **CERT_GetGeneralNameTypeFromString** - An utlity function to lookup a value of type + CERTGeneralNameType given a human readable string. This function was already added in NSS + 3.16.2, however, it wasn't declared in a public header file. + +.. _notable_changes_in_nss_3.16.3: + +`Notable Changes in NSS 3.16.3 <#notable_changes_in_nss_3.16.3>`__ +------------------------------------------------------------------ + +.. container:: + + - The following **1024-bit** CA certificates were **Removed** + + - CN = Entrust.net Secure Server Certification Authority + + - SHA1 Fingerprint: 99:A6:9B:E6:1A:FE:88:6B:4D:2B:82:00:7C:B8:54:FC:31:7E:15:39 + + - CN = GTE CyberTrust Global Root + + - SHA1 Fingerprint: 97:81:79:50:D8:1C:96:70:CC:34:D8:09:CF:79:44:31:36:7E:F4:74 + + - OU = ValiCert Class 1 Policy Validation Authority + + - SHA1 Fingerprint: E5:DF:74:3C:B6:01:C4:9B:98:43:DC:AB:8C:E8:6A:81:10:9F:E4:8E + + - OU = ValiCert Class 2 Policy Validation Authority + + - SHA1 Fingerprint: 31:7A:2A:D0:7F:2B:33:5E:F5:A1:C3:4E:4B:57:E8:B7:D8:F1:FC:A6 + + - OU = ValiCert Class 3 Policy Validation Authority + + - SHA1 Fingerprint: 69:BD:8C:F4:9C:D3:00:FB:59:2E:17:93:CA:55:6A:F3:EC:AA:35:FB + + - Additionally, the following CA certificate was **Removed** as requested by the CA + + - OU = TDC Internet Root CA + + - SHA1 Fingerprint: 21:FC:BD:8E:7F:6C:AF:05:1B:D1:B3:43:EC:A8:E7:61:47:F2:0F:8A + + - The following CA certificates were **Added** + + - CN = Certification Authority of WoSign + + - SHA1 Fingerprint: B9:42:94:BF:91:EA:8F:B6:4B:E6:10:97:C7:FB:00:13:59:B6:76:CB + + - CN = CA 沃通根证书 + + - SHA1 Fingerprint: 16:32:47:8D:89:F9:21:3A:92:00:85:63:F5:A4:A7:D3:12:40:8A:D6 + + - CN = DigiCert Assured ID Root G2 + + - SHA1 Fingerprint: A1:4B:48:D9:43:EE:0A:0E:40:90:4F:3C:E0:A4:C0:91:93:51:5D:3F + + - CN = DigiCert Assured ID Root G3 + + - SHA1 Fingerprint: F5:17:A2:4F:9A:48:C6:C9:F8:A2:00:26:9F:DC:0F:48:2C:AB:30:89 + + - CN = DigiCert Global Root G2 + + - SHA1 Fingerprint: DF:3C:24:F9:BF:D6:66:76:1B:26:80:73:FE:06:D1:CC:8D:4F:82:A4 + + - CN = DigiCert Global Root G3 + + - SHA1 Fingerprint: 7E:04:DE:89:6A:3E:66:6D:00:E6:87:D3:3F:FA:D9:3B:E8:3D:34:9E + + - CN = DigiCert Trusted Root G4 + + - SHA1 Fingerprint: DD:FB:16:CD:49:31:C9:73:A2:03:7D:3F:C8:3A:4D:7D:77:5D:05:E4 + + - CN = QuoVadis Root CA 1 G3 + + - SHA1 Fingerprint: 1B:8E:EA:57:96:29:1A:C9:39:EA:B8:0A:81:1A:73:73:C0:93:79:67 + + - CN = QuoVadis Root CA 2 G3 + + - SHA1 Fingerprint: 09:3C:61:F3:8B:8B:DC:7D:55:DF:75:38:02:05:00:E1:25:F5:C8:36 + + - CN = QuoVadis Root CA 3 G3 + + - SHA1 Fingerprint: 48:12:BD:92:3C:A8:C4:39:06:E7:30:6D:27:96:E6:A4:CF:22:2E:7D + + - The **Trust Bits were changed** for the following CA certificates + + - OU = Class 3 Public Primary Certification Authority + + - SHA1 Fingerprint: A1:DB:63:93:91:6F:17:E4:18:55:09:40:04:15:C7:02:40:B0:AE:6B + - Turned off websites and code signing trust bits (1024-bit root) + + - OU = Class 3 Public Primary Certification Authority + + - SHA1 Fingerprint: 74:2C:31:92:E6:07:E4:24:EB:45:49:54:2B:E1:BB:C5:3E:61:74:E2 + - Turned off websites and code signing trust bits (1024-bit root) + + - OU = Class 2 Public Primary Certification Authority - G2 + + - SHA1 Fingerprint: B3:EA:C4:47:76:C9:C8:1C:EA:F2:9D:95:B6:CC:A0:08:1B:67:EC:9D + - Turned off code signing trust bit (change requested by CA) + + - CN = VeriSign Class 2 Public Primary Certification Authority - G3 + + - SHA-1 Fingerprint: 61:EF:43:D7:7F:CA:D4:61:51:BC:98:E0:C3:59:12:AF:9F:EB:63:11 + - Turned off code signing trust bit (change requested by CA) + + - CN = AC Raíz Certicámara S.A. + + - SHA1 Fingerprint: CB:A1:C5:F8:B0:E3:5E:B8:B9:45:12:D3:F9:34:A2:E9:06:10:D3:36 + - Turned off websites trust bit (change requested by CA) + + - CN = NetLock Uzleti (Class B) Tanusitvanykiado + + - SHA1 Fingerprint: 87:9F:4B:EE:05:DF:98:58:3B:E3:60:D6:33:E7:0D:3F:FE:98:71:AF + - Turned off websites and code signing trust bits (1024-bit root) + + - CN = NetLock Expressz (Class C) Tanusitvanykiado + + - SHA1 Fingerprint: E3:92:51:2F:0A:CF:F5:05:DF:F6:DE:06:7F:75:37:E1:65:EA:57:4B + - Turned off websites and code signing trust bits (1024-bit root) + +.. _bugs_fixed_in_nss_3.16.3: + +`Bugs fixed in NSS 3.16.3 <#bugs_fixed_in_nss_3.16.3>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.16.3: + + | https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.16.3 + |
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.4_release_notes/index.rst new file mode 100644 index 0000000000..6d60b76d37 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.4_release_notes/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_nss_3_16_4_release_notes: + +NSS 3.16.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.4 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.4 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_4_RTM. NSS 3.16.4 requires NSPR 4.10.6 or newer. + + NSS 3.16.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_4_RTM/src/ + +.. _new_in_nss_3.16.4: + +`New in NSS 3.16.4 <#new_in_nss_3.16.4>`__ +------------------------------------------ + +.. container:: + + This release consists primarily of CA certificate changes as listed below, and includes a small + number of bug fixes. + +.. _notable_changes_in_nss_3.16.4: + +`Notable Changes in NSS 3.16.4 <#notable_changes_in_nss_3.16.4>`__ +------------------------------------------------------------------ + +.. container:: + + - The following **1024-bit** root CA certificate was **restored** to allow more time to develop + a better transition strategy for affected sites. It was removed in + :ref:`mozilla_projects_nss_nss_3_16_3_release_notes`, but discussion in the + mozilla.dev.security.policy forum led to the decision to keep this root included longer in + order to give website administrators more time to update their web servers. + + - CN = GTE CyberTrust Global Root + + - SHA1 Fingerprint: 97:81:79:50:D8:1C:96:70:CC:34:D8:09:CF:79:44:31:36:7E:F4:74 + + - In :ref:`mozilla_projects_nss_nss_3_16_3_release_notes`, the **1024-bit** "Entrust.net Secure + Server Certification Authority" root CA certificate (SHA1 Fingerprint: + 99:A6:9B:E6:1A:FE:88:6B:4D:2B:82:00:7C:B8:54:FC:31:7E:15:39) was removed. In NSS 3.16.4, a + **2048-bit** intermediate CA certificate has been included, without explicit trust. The + intention is to mitigate the effects of the previous removal of the 1024-bit Entrust.net root + certificate, because many public Internet sites still use the "USERTrust Legacy Secure Server + CA" intermediate certificate that is signed by the 1024-bit Entrust.net root certificate. The + inclusion of the intermediate certificate is a temporary measure to allow those sites to + function, by allowing them to find a trust path to another **2048-bit** root CA certificate. + The temporarily included intermediate certificate expires November 1, 2015. + +.. _bugs_fixed_in_nss_3.16.4: + +`Bugs fixed in NSS 3.16.4 <#bugs_fixed_in_nss_3.16.4>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.16.4: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.16.4
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.5_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.5_release_notes/index.rst new file mode 100644 index 0000000000..a16f2cddd7 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.5_release_notes/index.rst @@ -0,0 +1,98 @@ +.. _mozilla_projects_nss_nss_3_16_5_release_notes: + +NSS 3.16.5 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.5 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.5 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_5_RTM. NSS 3.16.5 requires NSPR 4.10.6 or newer. + + NSS 3.16.5 source distributions are also available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_5_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.16.5. Users are encouraged to + upgrade immediately. + + - `Bug 1064636 <https://bugzilla.mozilla.org/show_bug.cgi?id=1064636>`__ - (CVE-2014-1568) RSA + Signature Forgery in NSS. See also `MFSA + 2014-73 <https://www.mozilla.org/security/announce/2014/mfsa2014-73.html>`__ for details. + +.. _new_in_nss_3.16.5: + +`New in NSS 3.16.5 <#new_in_nss_3.16.5>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix a bug that + caused NSS to accept forged RSA signatures. + + A new symbol, \_SGN_VerifyPKCS1DigestInfo is exported in this release. As with all exported NSS + symbols that have a leading underscore '_', this is an internal symbol for NSS use only. + Applications that use or depend on these symbols can and will break in future NSS releases. + +.. _bugs_fixed_in_nss_3.16.5: + +`Bugs fixed in NSS 3.16.5 <#bugs_fixed_in_nss_3.16.5>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 1064636 <https://bugzilla.mozilla.org/show_bug.cgi?id=1064636>`__ - (CVE-2014-1568) RSA + Signature Forgery in NSS + +`Acknowledgements <#acknowledgements>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The NSS development team would like to thank Antoine Delignat-Lavaud, security researcher at + Inria Paris in team Prosecco, and the Advanced Threat Research team at Intel Security, who both + independently discovered and reported this issue, for responsibly disclosing the issue by + providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.16.5 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.16.5 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16.6_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.6_release_notes/index.rst new file mode 100644 index 0000000000..68cc205798 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16.6_release_notes/index.rst @@ -0,0 +1,81 @@ +.. _mozilla_projects_nss_nss_3_16_6_release_notes: + +NSS 3.16.6 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.16.6 is a patch release for NSS 3.16. The bug fixes in NSS + 3.16.6 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_6_RTM. NSS 3.16.6 requires NSPR 4.10.6 or newer. + + NSS 3.16.6 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_6_RTM/src/ + +.. _new_in_nss_3.16.6: + +`New in NSS 3.16.6 <#new_in_nss_3.16.6>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix a regression. + +.. _notable_changes_in_nss_3.16.6: + +`Notable Changes in NSS 3.16.6 <#notable_changes_in_nss_3.16.6>`__ +------------------------------------------------------------------ + +.. container:: + + - `Bug 1049435 <https://bugzilla.mozilla.org/show_bug.cgi?id=1049435>`__: Change + RSA_PrivateKeyCheck to not require p > q. This fixes a regression introduced in NSS 3.16.2 + that prevented NSS from importing some RSA private keys (such as in PKCS #12 files) generated + by other crypto libraries. + +.. _bugs_fixed_in_nss_3.16.6: + +`Bugs fixed in NSS 3.16.6 <#bugs_fixed_in_nss_3.16.6>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1049435 <https://bugzilla.mozilla.org/show_bug.cgi?id=1049435>`__ - Importing an RSA + private key fails if p < q + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.16.6 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.16.6 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.16_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.16_release_notes/index.rst new file mode 100644 index 0000000000..4431fe01be --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.16_release_notes/index.rst @@ -0,0 +1,98 @@ +.. _mozilla_projects_nss_nss_3_16_release_notes: + +NSS 3.16 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.16, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_16_RTM. NSS 3.16 requires NSPR 4.10.3 or newer. + + NSS 3.16 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_16_RTM/src/ + +.. _new_in_nss_3.16: + +`New in NSS 3.16 <#new_in_nss_3.16>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Supports the Linux x32 ABI. (This requires NSPR 4.10.4.) To build for the Linux x32 target, + set the environment variable USE_X32=1 when building NSS. + + .. rubric:: New Functions + :name: new_functions + + - *in cms.h* + + - **NSS_CMSSignerInfo_Verify** - verify the signature of a single SignerInfo. It just + verifies the signature, assuming that the certificate has been verified already. + + .. rubric:: New Macros + :name: new_macros + + - *in sslproto.h* + + - **TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, etc.** - cipher suites that were + first defined in SSL 3.0 can now be referred to with their official IANA names in TLS, with + the TLS\_ prefix. Previously, they had to be referred to with their names in SSL 3.0, with + the SSL\_ prefix. + +.. _notable_changes_in_nss_3.16: + +`Notable Changes in NSS 3.16 <#notable_changes_in_nss_3.16>`__ +-------------------------------------------------------------- + +.. container:: + + - ECC is enabled by default. It is no longer necessary to set the environment variable + NSS_ENABLE_ECC=1 when building NSS. To disable ECC, set the environment variable + NSS_DISABLE_ECC=1 when building NSS. + - `Bug 903885 <https://bugzilla.mozilla.org/show_bug.cgi?id=903885>`__: (CVE-2014-1492) In a + wildcard certificate, the wildcard character should not be embedded within the U-label of an + internationalized domain name. See the last bullet point in `RFC 6125, Section + 7.2 <https://datatracker.ietf.org/doc/html/rfc6125#section-7.2>`__. + - `Bug 962760 <https://bugzilla.mozilla.org/show_bug.cgi?id=962760>`__: libpkix should not + include the common name of CA as DNS names when evaluating name constraints. + - `Bug 981170 <https://bugzilla.mozilla.org/show_bug.cgi?id=981170>`__: AESKeyWrap_Decrypt + should not return SECSuccess for invalid keys. + - `Bug 974693 <https://bugzilla.mozilla.org/show_bug.cgi?id=974693>`__: Fix a memory corruption + in sec_pkcs12_new_asafe. + - `Bug 956082 <https://bugzilla.mozilla.org/show_bug.cgi?id=956082>`__: If the NSS_SDB_USE_CACHE + environment variable is set, skip the runtime test sdb_measureAccess. + - The built-in roots module has been updated to version 1.97, which adds, removes, and distrusts + several certificates. + - The atob utility has been improved to automatically ignore lines of text that aren't in base64 + format. + - The certutil utility has been improved to support creation of version 1 and version 2 + certificates, in addition to the existing version 3 support. + +.. _bugs_fixed_in_nss_3.16: + +`Bugs fixed in NSS 3.16 <#bugs_fixed_in_nss_3.16>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.16: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.16
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.17.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.1_release_notes/index.rst new file mode 100644 index 0000000000..46c30e6ad5 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.1_release_notes/index.rst @@ -0,0 +1,132 @@ +.. _mozilla_projects_nss_nss_3_17_1_release_notes: + +NSS 3.17.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.17.1 is a patch release for NSS 3.17. The bug fixes in NSS + 3.17.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_17_1_RTM. NSS 3.17.1 requires NSPR 4.10.7 or newer. + + NSS 3.17.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_17_1_RTM/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.17.1. Users are encouraged to + upgrade immediately. + + - `Bug 1064636 <https://bugzilla.mozilla.org/show_bug.cgi?id=1064636>`__ - (CVE-2014-1568) RSA + Signature Forgery in NSS. See also `MFSA + 2014-73 <https://www.mozilla.org/security/announce/2014/mfsa2014-73.html>`__ for details. + +.. _new_in_nss_3.17.1: + +`New in NSS 3.17.1 <#new_in_nss_3.17.1>`__ +------------------------------------------ + +.. container:: + + This patch release adds new functionality and fixes a bug that caused NSS to accept forged RSA + signatures. + + A new symbol, \_SGN_VerifyPKCS1DigestInfo is exported in this release. As with all exported NSS + symbols that have a leading underscore '_', this is an internal symbol for NSS use only. + Applications that use or depend on these symbols can and will break in future NSS releases. + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `TLS_FALLBACK_SCSV <https://datatracker.ietf.org/doc/html/draft-ietf-tls-downgrade-scsv-00>`__ + is a signaling cipher suite value that indicates a handshake is the result of TLS version + fallback. + + .. rubric:: New Macros + :name: new_macros + + - *in ssl.h* + + - **SSL_ENABLE_FALLBACK_SCSV** - an SSL socket option that enables TLS_FALLBACK_SCSV. Off by + default. + + - *in sslerr.h* + + - **SSL_ERROR_INAPPROPRIATE_FALLBACK_ALERT** - a new SSL error code. + + - *in sslproto.h* + + - **TLS_FALLBACK_SCSV** - a signaling cipher suite value that indicates a handshake is the + result of TLS version fallback. + +.. _notable_changes_in_nss_3.17.1: + +`Notable Changes in NSS 3.17.1 <#notable_changes_in_nss_3.17.1>`__ +------------------------------------------------------------------ + +.. container:: + + - `Signature algorithms now use SHA-256 instead of SHA-1 by + default <https://bugzilla.mozilla.org/show_bug.cgi?id=1058933>`__. + - Added support for Linux on little-endian powerpc64. + +.. _bugs_fixed_in_nss_3.17.1: + +`Bugs fixed in NSS 3.17.1 <#bugs_fixed_in_nss_3.17.1>`__ +-------------------------------------------------------- + +.. container:: + + | This Bugzilla query returns all the bugs fixed in NSS 3.17.1: + | https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.17.1 + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Antoine Delignat-Lavaud, security researcher at + Inria Paris in team Prosecco, and the Advanced Threat Research team at Intel Security, who both + independently discovered and reported this issue, for responsibly disclosing the issue by + providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.17.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.17.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.17.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.2_release_notes/index.rst new file mode 100644 index 0000000000..d059105691 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.2_release_notes/index.rst @@ -0,0 +1,88 @@ +.. _mozilla_projects_nss_nss_3_17_2_release_notes: + +NSS 3.17.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.17.2 is a patch release for NSS 3.17. The bug fixes in NSS + 3.17.2 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_17_2_RTM. NSS 3.17.2 requires NSPR 4.10.7 or newer. + + NSS 3.17.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_17_2_RTM/src/ + +.. _new_in_nss_3.17.2: + +`New in NSS 3.17.2 <#new_in_nss_3.17.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix a regression + and other bugs. + +.. _notable_changes_in_nss_3.17.2: + +`Notable Changes in NSS 3.17.2 <#notable_changes_in_nss_3.17.2>`__ +------------------------------------------------------------------ + +.. container:: + + - `Bug 1049435 <https://bugzilla.mozilla.org/show_bug.cgi?id=1049435>`__: Change + RSA_PrivateKeyCheck to not require p > q. This fixes a regression introduced in NSS 3.16.2 + that prevented NSS from importing some RSA private keys (such as in PKCS #12 files) generated + by other crypto libraries. + - `Bug 1057161 <https://bugzilla.mozilla.org/show_bug.cgi?id=1057161>`__: Check that an imported + elliptic curve public key is valid. Previously NSS would only validate the peer's public key + before performing ECDH key agreement. Now EC public keys are validated at import time. + - `Bug 1078669 <https://bugzilla.mozilla.org/show_bug.cgi?id=1078669>`__: certutil crashes when + an argument is passed to the --certVersion option. + +.. _bugs_fixed_in_nss_3.17.2: + +`Bugs fixed in NSS 3.17.2 <#bugs_fixed_in_nss_3.17.2>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.17.2: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.17.2 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.17.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.17.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.17.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.3_release_notes/index.rst new file mode 100644 index 0000000000..4cc11965a8 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.3_release_notes/index.rst @@ -0,0 +1,134 @@ +.. _mozilla_projects_nss_nss_3_17_3_release_notes: + +NSS 3.17.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.17.3 is a patch release for NSS 3.17. The bug fixes in NSS + 3.17.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_17_3_RTM. NSS 3.17.3 requires NSPR 4.10.7 or newer. + + NSS 3.17.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_17_3_RTM/src/ + +.. _new_in_nss_3.17.3: + +`New in NSS 3.17.3 <#new_in_nss_3.17.3>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Support for TLS_FALLBACK_SCSV has been added to the ssltap and tstclnt utilities. + +.. _notable_changes_in_nss_3.17.3: + +`Notable Changes in NSS 3.17.3 <#notable_changes_in_nss_3.17.3>`__ +------------------------------------------------------------------ + +.. container:: + + - The QuickDER decoder now decodes lengths robustly (CVE-2014-1569). + - The following CA certificates were **Removed** + + - CN = GTE CyberTrust Global Root + + - SHA1 Fingerprint: 97:81:79:50:D8:1C:96:70:CC:34:D8:09:CF:79:44:31:36:7E:F4:74 + + - CN = Thawte Server CA + + - SHA1 Fingerprint: 23:E5:94:94:51:95:F2:41:48:03:B4:D5:64:D2:A3:A3:F5:D8:8B:8C + + - CN = Thawte Premium Server CA + + - SHA1 Fingerprint: 62:7F:8D:78:27:65:63:99:D2:7D:7F:90:44:C9:FE:B3:F3:3E:FA:9A + + - CN = America Online Root Certification Authority 1 + + - SHA-1 Fingerprint: 39:21:C1:15:C1:5D:0E:CA:5C:CB:5B:C4:F0:7D:21:D8:05:0B:56:6A + + - CN = America Online Root Certification Authority 2 + + - SHA-1 Fingerprint: 85:B5:FF:67:9B:0C:79:96:1F:C8:6E:44:22:00:46:13:DB:17:92:84 + + - The following CA certificates had the Websites and Code Signing **trust bits turned off** + + - OU = Class 3 Public Primary Certification Authority - G2 + + - SHA1 Fingerprint: 85:37:1C:A6:E5:50:14:3D:CE:28:03:47:1B:DE:3A:09:E8:F8:77:0F + + - CN = Equifax Secure eBusiness CA-1 + + - SHA1 Fingerprint: DA:40:18:8B:91:89:A3:ED:EE:AE:DA:97:FE:2F:9D:F5:B7:D1:8A:41 + + - The following CA certificates were **Added** + + - CN = COMODO RSA Certification Authority + + - SHA1 Fingerprint: AF:E5:D2:44:A8:D1:19:42:30:FF:47:9F:E2:F8:97:BB:CD:7A:8C:B4 + + - CN = USERTrust RSA Certification Authority + + - SHA1 Fingerprint: 2B:8F:1B:57:33:0D:BB:A2:D0:7A:6C:51:F7:0E:E9:0D:DA:B9:AD:8E + + - CN = USERTrust ECC Certification Authority + + - SHA1 Fingerprint: D1:CB:CA:5D:B2:D5:2A:7F:69:3B:67:4D:E5:F0:5A:1D:0C:95:7D:F0 + + - CN = GlobalSign ECC Root CA - R4 + + - SHA1 Fingerprint: 69:69:56:2E:40:80:F4:24:A1:E7:19:9F:14:BA:F3:EE:58:AB:6A:BB + + - CN = GlobalSign ECC Root CA - R5 + + - SHA1 Fingerprint: 1F:24:C6:30:CD:A4:18:EF:20:69:FF:AD:4F:DD:5F:46:3A:1B:69:AA + + - The version number of the updated root CA list has been set to 2.2 + +.. _bugs_fixed_in_nss_3.17.3: + +`Bugs fixed in NSS 3.17.3 <#bugs_fixed_in_nss_3.17.3>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.17.3: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.17.3 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.17.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.17.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.17.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.4_release_notes/index.rst new file mode 100644 index 0000000000..9483373d0b --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.17.4_release_notes/index.rst @@ -0,0 +1,90 @@ +.. _mozilla_projects_nss_nss_3_17_4_release_notes: + +NSS 3.17.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.17.4 is a patch release for NSS 3.17. The bug fixes in NSS + 3.17.4 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_17_4_RTM. NSS 3.17.4 requires NSPR 4.10.7 or newer. + + NSS 3.17.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_17_4_RTM/src/ + +.. _new_in_nss_3.17.4: + +`New in NSS 3.17.4 <#new_in_nss_3.17.4>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix multiple bugs. + +.. _notable_changes_in_nss_3.17.4: + +`Notable Changes in NSS 3.17.4 <#notable_changes_in_nss_3.17.4>`__ +------------------------------------------------------------------ + +.. container:: + + - `Bug 1084986 <https://bugzilla.mozilla.org/show_bug.cgi?id=1084986>`__: If an SSL/TLS + connection fails, because client and server don't have any common protocol version enabled, + NSS has been changed to report error code SSL_ERROR_UNSUPPORTED_VERSION (instead of reporting + SSL_ERROR_NO_CYPHER_OVERLAP). + - `Bug 1112461 <https://bugzilla.mozilla.org/show_bug.cgi?id=1112461>`__: libpkix was fixed to + prefer the newest certificate, if multiple certificates match. + - `Bug 1094492 <https://bugzilla.mozilla.org/show_bug.cgi?id=1094492>`__: fixed a memory + corruption issue during failure of keypair generation. + - `Bug 1113632 <https://bugzilla.mozilla.org/show_bug.cgi?id=1113632>`__: fixed a failure to + reload a PKCS#11 module in FIPS mode. + - `Bug 1119983 <https://bugzilla.mozilla.org/show_bug.cgi?id=1119983>`__: fixed interoperability + of NSS server code with a LibreSSL client. + +.. _bugs_fixed_in_nss_3.17.4: + +`Bugs fixed in NSS 3.17.4 <#bugs_fixed_in_nss_3.17.4>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.17.4: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.17.4 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.17.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.17.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.17_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.17_release_notes/index.rst new file mode 100644 index 0000000000..17d4936985 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.17_release_notes/index.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_nss_3_17_release_notes: + +NSS 3.17 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.17, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_17_RTM. NSS 3.17 requires NSPR 4.10.7 or newer. + + NSS 3.17 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_17_RTM/src/ + +.. _new_in_nss_3.17: + +`New in NSS 3.17 <#new_in_nss_3.17>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - When using ECDHE, the TLS server code may be configured to generate a fresh ephemeral ECDH key + for each handshake, by setting the SSL_REUSE_SERVER_ECDHE_KEY socket option to PR_FALSE. The + SSL_REUSE_SERVER_ECDHE_KEY option defaults to PR_TRUE, which means the server's ephemeral ECDH + key is reused for multiple handshakes. This option does not affect the TLS client code, which + always generates a fresh ephemeral ECDH key for each handshake. + + New Macros + + - *in ssl.h* + + - **SSL_REUSE_SERVER_ECDHE_KEY** + +.. _notable_changes_in_nss_3.17: + +`Notable Changes in NSS 3.17 <#notable_changes_in_nss_3.17>`__ +-------------------------------------------------------------- + +.. container:: + + - The manual pages for the certutil and pp tools have been updated to document the new + parameters that had been added in NSS 3.16.2. + - On Windows, the new build variable USE_STATIC_RTL can be used to specify the static C runtime + library should be used. By default the dynamic C runtime library is used. + +.. _bugs_fixed_in_nss_3.17: + +`Bugs fixed in NSS 3.17 <#bugs_fixed_in_nss_3.17>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.17: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.17
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.18.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.18.1_release_notes/index.rst new file mode 100644 index 0000000000..8a1a8fdeda --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.18.1_release_notes/index.rst @@ -0,0 +1,105 @@ +.. _mozilla_projects_nss_nss_3_18_1_release_notes: + +NSS 3.18.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.18.1 is a patch release for NSS 3.18. The bug fixes in NSS + 3.18.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_18_1_RTM. NSS 3.18.1 requires NSPR 4.10.8 or newer. + + NSS 3.18.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_18_1_RTM/src/ + +.. _new_in_nss_3.18.1: + +`New in NSS 3.18.1 <#new_in_nss_3.18.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to update the list of + root CA certificates. + +.. _notable_changes_in_nss_3.18.1: + +`Notable Changes in NSS 3.18.1 <#notable_changes_in_nss_3.18.1>`__ +------------------------------------------------------------------ + +.. container:: + + - The following CA certificate had the Websites and Code Signing trust **bits restored to their + original state** to allow more time to develop a better transition strategy for affected + sites. The Websites and Code Signing trust bits were turned off in + :ref:`mozilla_projects_nss_nss_3_18_release_notes`. But when Firefox 38 went into Beta, there + was a huge spike in the number of certificate verification errors attributed to this change. + So, to give website administrators more time to update their web servers, we reverted the + trust bits back to being enabled. + + - OU = Equifax Secure Certificate Authority + + - SHA1 Fingerprint: D2:32:09:AD:23:D3:14:23:21:74:E4:0D:7F:9D:62:13:97:86:63:3A + + - The following CA certificate was **removed** after `discussion about + it <https://groups.google.com/d/msg/mozilla.dev.security.policy/LKJO9W5dkSY/9VjSJhRfraIJ>`__ + in the mozilla.dev.security.policy forum\ **.** + + - CN = e-Guven Kok Elektronik Sertifika Hizmet Saglayicisi + + - SHA1 Fingerprint: DD:E1:D2:A9:01:80:2E:1D:87:5E:84:B3:80:7E:4B:B1:FD:99:41:34 + + - The following intermediate CA certificate has been added as `actively + distrusted <https://wiki.mozilla.org/CA:MaintenanceAndEnforcement#Actively_Distrusting_a_Certificate>`__ + because it was + `misused <https://blog.mozilla.org/security/2015/04/02/distrusting-new-cnnic-certificates/>`__ to + issue certificates for domain names the holder did not own or control. + + - CN=MCSHOLDING TEST, O=MCSHOLDING, C=EG + + - SHA1 Fingerprint: E1:F3:59:1E:76:98:65:C4:E4:47:AC:C3:7E:AF:C9:E2:BF:E4:C5:76 + + - The version number of the updated root CA list has been set to 2.4 + +.. _bugs_fixed_in_nss_3.18.1: + +`Bugs fixed in NSS 3.18.1 <#bugs_fixed_in_nss_3.18.1>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.18.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.18.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.18.1 shared libraries are backward compatible with all older NSS 3.18 shared libraries. A + program linked with older NSS 3.18 shared libraries will work with NSS 3.18.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.18_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.18_release_notes/index.rst new file mode 100644 index 0000000000..c26975ac8e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.18_release_notes/index.rst @@ -0,0 +1,169 @@ +.. _mozilla_projects_nss_nss_3_18_release_notes: + +NSS 3.18 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.18, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_18_RTM. NSS 3.18 requires NSPR 4.10.8 or newer. + + NSS 3.18 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_18_RTM/src/ + +.. _new_in_nss_3.18: + +`New in NSS 3.18 <#new_in_nss_3.18>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - When importing certificates and keys from a PKCS#12 source, it's now possible to override the + nicknames, prior to importing them into the NSS database, using new API + SEC_PKCS12DecoderRenameCertNicknames. + - The tstclnt test utility program has new command-line options -C, -D, -b and -R. + Use -C one, two or three times to print information about the certificates received from a + server, and information about the locally found and trusted issuer certificates, to diagnose + server side configuration issues. It is possible to run tstclnt without providing a database + (-D). A PKCS#11 library that contains root CA certificates can be loaded by tstclnt, which may + either be the nssckbi library provided by NSS (-b) or another compatible library (-R). + + .. rubric:: New Functions + :name: new_functions + + - *in certdb.h* + + - **SEC_CheckCrlTimes** - Check the validity of a CRL at the given time. + - **SEC_GetCrlTimes** - Extract the validity times from a CRL. + + - *in p12.h* + + - **SEC_PKCS12DecoderRenameCertNicknames** - call an application provided callback for each + certificate found in a SEC_PKCS12DecoderContext. + + - *in pk11pub.h* + + - **\__PK11_SetCertificateNickname** - this is an internal symbol for NSS use only, as with + all exported NSS symbols that have a leading underscore '_'. Applications that use or + depend on these symbols can and will break in future NSS releases. + + .. rubric:: New Types + :name: new_types + + - *in p12.h* + + - **SEC_PKCS12NicknameRenameCallback** - a function pointer definition. An application that + uses SEC_PKCS12DecoderRenameCertNicknames must implement a callback function that + implements this function interface. + +.. _notable_changes_in_nss_3.18: + +`Notable Changes in NSS 3.18 <#notable_changes_in_nss_3.18>`__ +-------------------------------------------------------------- + +.. container:: + + - The highest TLS protocol version enabled by default has been increased from TLS 1.0 to TLS + 1.2. Similarly, the highest DTLS protocol version enabled by default has been increased from + DTLS 1.0 to DTLS 1.2. + - The default key size used by certutil when creating an RSA key pair has been increased from + 1024 bits to 2048 bits. + - On Mac OS X, by default the softokn shared library will link with the sqlite library installed + by the operating system, if it is version 3.5 or newer. + - The following CA certificates had the Websites and Code Signing **trust bits turned off** + + - OU = Equifax Secure Certificate Authority + + - SHA1 Fingerprint: D2:32:09:AD:23:D3:14:23:21:74:E4:0D:7F:9D:62:13:97:86:63:3A + + - CN = Equifax Secure Global eBusiness CA-1 + + - SHA1 Fingerprint: 7E:78:4A:10:1C:82:65:CC:2D:E1:F1:6D:47:B4:40:CA:D9:0A:19:45 + + - CN = TC TrustCenter Class 3 CA II + + - SHA1 Fingerprint: 80:25:EF:F4:6E:70:C8:D4:72:24:65:84:FE:40:3B:8A:8D:6A:DB:F5 + + - The following CA certificates were **Added** + + - CN = Staat der Nederlanden Root CA - G3 + + - SHA1 Fingerprint: D8:EB:6B:41:51:92:59:E0:F3:E7:85:00:C0:3D:B6:88:97:C9:EE:FC + + - CN = Staat der Nederlanden EV Root CA + + - SHA1 Fingerprint: 76:E2:7E:C1:4F:DB:82:C1:C0:A6:75:B5:05:BE:3D:29:B4:ED:DB:BB + + - CN = IdenTrust Commercial Root CA 1 + + - SHA1 Fingerprint: DF:71:7E:AA:4A:D9:4E:C9:55:84:99:60:2D:48:DE:5F:BC:F0:3A:25 + + - CN = IdenTrust Public Sector Root CA 1 + + - SHA1 Fingerprint: BA:29:41:60:77:98:3F:F4:F3:EF:F2:31:05:3B:2E:EA:6D:4D:45:FD + + - CN = S-TRUST Universal Root CA + + - SHA1 Fingerprint: 1B:3D:11:14:EA:7A:0F:95:58:54:41:95:BF:6B:25:82:AB:40:CE:9A + + - CN = Entrust Root Certification Authority - G2 + + - SHA1 Fingerprint: 8C:F4:27:FD:79:0C:3A:D1:66:06:8D:E8:1E:57:EF:BB:93:22:72:D4 + + - CN = Entrust Root Certification Authority - EC1 + + - SHA1 Fingerprint: 20:D8:06:40:DF:9B:25:F5:12:25:3A:11:EA:F7:59:8A:EB:14:B5:47 + + - CN = CFCA EV ROOT + + - SHA1 Fingerprint: E2:B8:29:4B:55:84:AB:6B:58:C2:90:46:6C:AC:3F:B8:39:8F:84:83 + + - The version number of the updated root CA list has been set to 2.3 + +.. _bugs_fixed_in_nss_3.18: + +`Bugs fixed in NSS 3.18 <#bugs_fixed_in_nss_3.18>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.18: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.18 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.18 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.18 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.1_release_notes/index.rst new file mode 100644 index 0000000000..6fae657bc8 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.1_release_notes/index.rst @@ -0,0 +1,113 @@ +.. _mozilla_projects_nss_nss_3_19_1_release_notes: + +NSS 3.19.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.1 is a security release for NSS 3.19. The bug fixes in NSS + 3.19.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_1_RTM. NSS 3.19.1 requires NSPR 4.10.8 or newer. + + NSS 3.19.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_1_RTM/src/ + +.. _security_fixes_in_nss_3.19.1: + +`Security Fixes in NSS 3.19.1 <#security_fixes_in_nss_3.19.1>`__ +---------------------------------------------------------------- + +.. container:: + + - `Bug + 1138554 <https://bugzilla.mozilla.org/show_bug.cgi?id=1138554>`__ / `CVE-2015-4000 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-4000>`__ - + The minimum strength of keys that libssl will accept for finite field algorithms (RSA, + Diffie-Hellman, and DSA) have been increased to 1023 bits. + +.. _new_in_nss_3.19.1: + +`New in NSS 3.19.1 <#new_in_nss_3.19.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This patch release includes a fix for the + recently published `logjam attack <https://weakdh.org/>`__. + +.. _notable_changes_in_nss_3.19.1: + +`Notable Changes in NSS 3.19.1 <#notable_changes_in_nss_3.19.1>`__ +------------------------------------------------------------------ + +.. container:: + + - NSS reports the bit length of keys more accurately. Thus, the SECKEY_PublicKeyStrength and + SECKEY_PublicKeyStrengthInBits functions could report smaller values for values that have + leading zero values. This affects the key strength values that are reported by + SSL_GetChannelInfo. + - The minimum size of keys that NSS will generate, import, or use has been raised: + + - The minimum modulus size for RSA keys is now 512 bits + - The minimum modulus size for DSA keys is now 1023 bits + - The minimum modulus size for Diffie-Hellman keys is now 1023 bits + +.. _bugs_fixed_in_nss_3.19.1: + +`Bugs fixed in NSS 3.19.1 <#bugs_fixed_in_nss_3.19.1>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.19.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.19.1 + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Matthew Green and Karthikeyan Bhargavan for + responsibly disclosing the issue in `bug + 1138554 <https://bugzilla.mozilla.org/show_bug.cgi?id=1138554>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + + **Note:** NSS 3.19.1 increases the minimum size of keys it is willing to use. This has been shown + to break some applications. :ref:`mozilla_projects_nss_nss_3_19_2_release_notes` reverts the + behaviour to the NSS 3.19 and earlier limits. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.1_release_notes/index.rst new file mode 100644 index 0000000000..6e3e5b48c3 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.1_release_notes/index.rst @@ -0,0 +1,88 @@ +.. _mozilla_projects_nss_nss_3_19_2_1_release_notes: + +NSS 3.19.2.1 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.2.1 is a patch release for NSS 3.19.2. The bug fixes in NSS + 3.19.2.1 are described in the "Security Advisories" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_2_1_RTM. NSS 3.19.2.1 requires NSPR 4.10.10 or newer. + + NSS 3.19.2.1 and NSPR 4.10.10 source distributions are available on ftp.mozilla.org for secure + HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_2_1_RTM/src/ + https://ftp.mozilla.org/pub/nspr/releases/v4.10.10/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.19.2.1. Users are encouraged to + upgrade immediately. + + - `Bug 1192028 <https://bugzilla.mozilla.org/show_bug.cgi?id=1192028>`__ (CVE-2015-7181) and + `Bug 1202868 <https://bugzilla.mozilla.org/show_bug.cgi?id=1202868>`__ (CVE-2015-7182): + Several issues existed within the ASN.1 decoder used by NSS for handling streaming BER data. + While the majority of NSS uses a separate, unaffected DER decoder, several public routines + also accept BER data, and thus are affected. An attacker that successfully exploited these + issues can overflow the heap and may be able to obtain remote code execution. + + | The following security-relevant bugs have been resolved in NSPR 4.10.10, which affect NSS. + | Because NSS includes portions of the affected NSPR code at build time, it is necessary to use + NSPR 4.10.10 when building NSS. + + - `Bug 1205157 <https://bugzilla.mozilla.org/show_bug.cgi?id=1205157>`__ (NSPR, CVE-2015-7183): + A logic bug in the handling of large allocations would allow exceptionally large allocations + to be reported as successful, without actually allocating the requested memory. This may allow + attackers to bypass security checks and obtain control of arbitrary memory. + +.. _new_in_nss_3.19.2.1: + +`New in NSS 3.19.2.1 <#new_in_nss_3.19.2.1>`__ +---------------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix + security-relevant bugs. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.2.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19.2.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.2_release_notes/index.rst new file mode 100644 index 0000000000..15fdd9ab40 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.2_release_notes/index.rst @@ -0,0 +1,84 @@ +.. _mozilla_projects_nss_nss_3_19_2_2_release_notes: + +NSS 3.19.2.2 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.2.2 is a security patch release for NSS 3.19.2. The bug + fixes in NSS 3.19.2.2 are described in the "Security Fixes" section below. + + (Current users of NSS 3.19.3 or NSS 3.19.4 are advised to update to + :ref:`mozilla_projects_nss_nss_3_20_2_release_notes`, + :ref:`mozilla_projects_nss_nss_3_21_release_notes`, or a later release.) + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_2_2_RTM. NSS 3.19.2.2 requires NSPR 4.10.10 or newer. + + NSS 3.19.2.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_2_2_RTM/src/ + +.. _security_fixes_in_nss_3.19.2.2: + +`Security Fixes in NSS 3.19.2.2 <#security_fixes_in_nss_3.19.2.2>`__ +-------------------------------------------------------------------- + +.. container:: + + - `Bug 1158489 <https://bugzilla.mozilla.org/show_bug.cgi?id=1158489>`__ + ` <https://bugzilla.mozilla.org/show_bug.cgi?id=1138554>`__ / + `CVE-2015-7575 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-7575>`__ - Prevent + MD5 Downgrade in TLS 1.2 Signatures. + +.. _new_in_nss_3.19.2.2: + +`New in NSS 3.19.2.2 <#new_in_nss_3.19.2.2>`__ +---------------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Karthikeyan Bhargavan from + `INRIA <http://inria.fr/>`__ for responsibly disclosing the issue in `Bug + 1158489 <https://bugzilla.mozilla.org/show_bug.cgi?id=1158489>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.2.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19.2.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.3_release_notes/index.rst new file mode 100644 index 0000000000..2b38a2b897 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.3_release_notes/index.rst @@ -0,0 +1,84 @@ +.. _mozilla_projects_nss_nss_3_19_2_3_release_notes: + +NSS 3.19.2.3 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.2.3 is a security patch release for NSS 3.19.2. The bug + fixes in NSS 3.19.2.3 are described in the "Security Fixes" section below. + + (Current users of NSS 3.19.3, NSS 3.19.4 or NSS 3.20.x are advised to update to + :ref:`mozilla_projects_nss_nss_3_21_1_release_notes`, + :ref:`mozilla_projects_nss_nss_3_22_2_release_notes`, or a later release.) + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_2_3_RTM. NSS 3.19.2.3 requires NSPR 4.10.10 or newer. + + NSS 3.19.2.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_2_3_RTM/src/ + +.. _new_in_nss_3.19.2.3: + +`New in NSS 3.19.2.3 <#new_in_nss_3.19.2.3>`__ +---------------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _security_fixes_in_nss_3.19.2.3: + +`Security Fixes in NSS 3.19.2.3 <#security_fixes_in_nss_3.19.2.3>`__ +-------------------------------------------------------------------- + +.. container:: + + - `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__ / + `CVE-2016-1950 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1950>`__ - Fixed a + heap-based buffer overflow related to the parsing of certain ASN.1 structures. An attacker + could create a specially-crafted certificate which, when parsed by NSS, would cause a crash or + execution of arbitrary code with the permissions of the user. + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank security researcher Francis Gabriel for responsibly + disclosing the issue in `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.2.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19.2.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.4_release_notes/index.rst new file mode 100644 index 0000000000..ec09849c61 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2.4_release_notes/index.rst @@ -0,0 +1,82 @@ +.. _mozilla_projects_nss_nss_3_19_2_4_release_notes: + +NSS 3.19.2.4 release notes +========================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.2.4 is a security patch release for NSS 3.19.2. The bug + fixed in NSS 3.19.2.4 have been described in the "Security Fixes" section below. + + (Current users of NSS 3.19.3, NSS 3.19.4 or NSS 3.20.x are advised to update to + :ref:`mozilla_projects_nss_nss_3_21_1_release_notes`, + :ref:`mozilla_projects_nss_nss_3_22_2_release_notes` or a later release.) + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_2_4_RTM. NSS 3.19.2.4 requires NSPR 4.10.10 or newer. + + NSS 3.19.2.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_2_4_RTM/src/ + +.. _new_in_nss_3.19.2.4: + +`New in NSS 3.19.2.4 <#new_in_nss_3.19.2.4>`__ +---------------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality has been introduced in this release. + +.. _security_fixes_in_nss_3.19.2.4: + +`Security Fixes in NSS 3.19.2.4 <#security_fixes_in_nss_3.19.2.4>`__ +-------------------------------------------------------------------- + +.. container:: + + The following security fixes from NSS 3.21 have been backported to NSS 3.19.2.4: + + - `Bug 1185033 <https://bugzilla.mozilla.org/show_bug.cgi?id=1185033>`__ / + `CVE-2016-1979 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1979>`__ - + Use-after-free during processing of DER encoded keys in NSS + - `Bug 1209546 <https://bugzilla.mozilla.org/show_bug.cgi?id=1209546>`__ / + `CVE-2016-1978 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1978>`__ - + Use-after-free in NSS during SSL connections in low memory + - `Bug 1190248 <https://bugzilla.mozilla.org/show_bug.cgi?id=1190248>`__ / + `CVE-2016-1938 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1938>`__ - Errors in + mp_div and mp_exptmod cryptographic functions in NSS + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.2.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19.2.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict the use of NSS APIs to + the functions listed in NSS Public Functions will remain compatible with future versions of the + NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2_release_notes/index.rst new file mode 100644 index 0000000000..e9960d60ad --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.2_release_notes/index.rst @@ -0,0 +1,94 @@ +.. _mozilla_projects_nss_nss_3_19_2_release_notes: + +NSS 3.19.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.2 is a patch release for NSS 3.19 that addresses + compatibility issues in NSS 3.19.1. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_2_RTM. NSS 3.19.2 requires NSPR 4.10.8 or newer. + + NSS 3.19.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_2_RTM/src/ + +.. _new_in_nss_3.19.2: + +`New in NSS 3.19.2 <#new_in_nss_3.19.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _notable_changes_in_nss_3.19.2: + +`Notable Changes in NSS 3.19.2 <#notable_changes_in_nss_3.19.2>`__ +------------------------------------------------------------------ + +.. container:: + + - `Bug 1172128 <https://bugzilla.mozilla.org/show_bug.cgi?id=1172128>`__ - In NSS 3.19.1, the + minimum key sizes that the freebl cryptographic implementation (part of the softoken + cryptographic module used by default by NSS) was willing to generate or use was increased - + for RSA keys, to 512 bits, and for DH keys, 1023 bits. This was done as part of a security fix + for `Bug 1138554 <https://bugzilla.mozilla.org/show_bug.cgi?id=1138554>`__ / + `CVE-2015-4000 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-4000>`__. + Applications that requested or attempted to use keys smaller then the minimum size would fail. + However, this change in behaviour unintentionally broke existing NSS applications that need to + generate or use such keys, via APIs such as SECKEY_CreateRSAPrivateKey or + SECKEY_CreateDHPrivateKey. + In NSS 3.19.2, this change in freebl behaviour has been reverted. The fix for `Bug + 1138554 <https://bugzilla.mozilla.org/show_bug.cgi?id=1138554>`__ has been moved to libssl, + and will now only affect the minimum keystrengths used in SSL/TLS. + **Note:** Future versions of NSS *may* increase the minimum keysizes required by the freebl + module. Consumers of NSS are **strongly** encouraged to migrate to stronger cryptographic + strengths as soon as possible. + +.. _bugs_fixed_in_nss_3.19.2: + +`Bugs fixed in NSS 3.19.2 <#bugs_fixed_in_nss_3.19.2>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.19.2: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.19.2 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.3_release_notes/index.rst new file mode 100644 index 0000000000..85879d28e6 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.3_release_notes/index.rst @@ -0,0 +1,117 @@ +.. _mozilla_projects_nss_nss_3_19_3_release_notes: + +NSS 3.19.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.3 is a patch release for NSS 3.19. The bug fixes in NSS + 3.19.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_3_RTM. NSS 3.19.3 requires NSPR 4.10.8 or newer. + + NSS 3.19.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_3_RTM/src/ + +.. _new_in_nss_3.19.3: + +`New in NSS 3.19.3 <#new_in_nss_3.19.3>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to update the list of + root CA certificates. + +.. _notable_changes_in_nss_3.19.3: + +`Notable Changes in NSS 3.19.3 <#notable_changes_in_nss_3.19.3>`__ +------------------------------------------------------------------ + +.. container:: + + - The following CA certificates were **Removed** + + - CN = Buypass Class 3 CA 1 + + - SHA1 Fingerprint: 61:57:3A:11:DF:0E:D8:7E:D5:92:65:22:EA:D0:56:D7:44:B3:23:71 + + - CN = TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı + + - SHA1 Fingerprint: 79:98:A3:08:E1:4D:65:85:E6:C2:1E:15:3A:71:9F:BA:5A:D3:4A:D9 + + - CN = SG TRUST SERVICES RACINE + + - SHA1 Fingerprint: 0C:62:8F:5C:55:70:B1:C9:57:FA:FD:38:3F:B0:3D:7B:7D:D7:B9:C6 + + - CN = TC TrustCenter Universal CA I + + - SHA-1 Fingerprint: 6B:2F:34:AD:89:58:BE:62:FD:B0:6B:5C:CE:BB:9D:D9:4F:4E:39:F3 + + - CN = TC TrustCenter Class 2 CA II + + - SHA-1 Fingerprint: AE:50:83:ED:7C:F4:5C:BC:8F:61:C6:21:FE:68:5D:79:42:21:15:6E + + - The following CA certificate had the Websites **trust bit turned off** + + - CN = ComSign Secured CA + + - SHA1 Fingerprint: F9:CD:0E:2C:DA:76:24:C1:8F:BD:F0:F0:AB:B6:45:B8:F7:FE:D5:7A + + - The following CA certificates were **Added** + + - CN = TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 + + - SHA1 Fingerprint: C4:18:F6:4D:46:D1:DF:00:3D:27:30:13:72:43:A9:12:11:C6:75:FB + + - CN = TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H6 + + - SHA1 Fingerprint: 8A:5C:8C:EE:A5:03:E6:05:56:BA:D8:1B:D4:F6:C9:B0:ED:E5:2F:E0 + + - CN = Certinomis - Root CA + + - SHA1 Fingerprint: 9D:70:BB:01:A5:A4:A0:18:11:2E:F7:1C:01:B9:32:C5:34:E7:88:A8 + + - The version number of the updated root CA list has been set to 2.5 + +.. _bugs_fixed_in_nss_3.19.3: + +`Bugs fixed in NSS 3.19.3 <#bugs_fixed_in_nss_3.19.3>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.19.3: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.19.3 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.3 shared libraries are backward compatible with all older NSS 3.19 shared libraries. A + program linked with older NSS 3.19 shared libraries will work with NSS 3.19.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.4_release_notes/index.rst new file mode 100644 index 0000000000..f3b93d107e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19.4_release_notes/index.rst @@ -0,0 +1,88 @@ +.. _mozilla_projects_nss_nss_3_19_4_release_notes: + +NSS 3.19.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.19.4 is a patch release for NSS 3.19. The bug fixes in NSS + 3.19.4 are described in the "Security Advisories" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_4_RTM. NSS 3.19.4 requires NSPR 4.10.10 or newer. + + NSS 3.19.4 and NSPR 4.10.10 source distributions are available on ftp.mozilla.org for secure + HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_4_RTM/src/ + https://ftp.mozilla.org/pub/nspr/releases/v4.10.10/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.19.4. Users are encouraged to + upgrade immediately. + + - `Bug 1192028 <https://bugzilla.mozilla.org/show_bug.cgi?id=1192028>`__ (CVE-2015-7181) and + `Bug 1202868 <https://bugzilla.mozilla.org/show_bug.cgi?id=1202868>`__ (CVE-2015-7182): + Several issues existed within the ASN.1 decoder used by NSS for handling streaming BER data. + While the majority of NSS uses a separate, unaffected DER decoder, several public routines + also accept BER data, and thus are affected. An attacker that successfully exploited these + issues can overflow the heap and may be able to obtain remote code execution. + + | The following security-relevant bugs have been resolved in NSPR 4.10.10, which affect NSS. + | Because NSS includes portions of the affected NSPR code at build time, it is necessary to use + NSPR 4.10.10 when building NSS. + + - `Bug 1205157 <https://bugzilla.mozilla.org/show_bug.cgi?id=1205157>`__ (NSPR, CVE-2015-7183): + A logic bug in the handling of large allocations would allow exceptionally large allocations + to be reported as successful, without actually allocating the requested memory. This may allow + attackers to bypass security checks and obtain control of arbitrary memory. + +.. _new_in_nss_3.19.4: + +`New in NSS 3.19.4 <#new_in_nss_3.19.4>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix + security-relevant bugs. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.19_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.19_release_notes/index.rst new file mode 100644 index 0000000000..90c986a83e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.19_release_notes/index.rst @@ -0,0 +1,119 @@ +.. _mozilla_projects_nss_nss_3_19_release_notes: + +NSS 3.19 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.19, which is a minor + security release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_19_RTM. NSS 3.19 requires NSPR 4.10.8 or newer. + + NSS 3.19 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_19_RTM/src/ + +.. _security_fixes_in_nss_3.19: + +`Security Fixes in NSS 3.19 <#security_fixes_in_nss_3.19>`__ +------------------------------------------------------------ + +.. container:: + + - `Bug 1086145 <https://bugzilla.mozilla.org/show_bug.cgi?id=1086145>`__ / + `CVE-2015-2721 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-2721>`__ - Fixed a + bug related to the ordering of TLS handshake messages. This was also known + as `SMACK <https://www.smacktls.com/>`__. + +.. _new_in_nss_3.19: + +`New in NSS 3.19 <#new_in_nss_3.19>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - For some certificates, such as root CA certificates that don't embed any constraints, NSS + might impose additional constraints such as name constraints. A new API + (`CERT_GetImposedNameConstraints <http://mxr.mozilla.org/nss/ident?i=CERT_GetImposedNameConstraints>`__) has + been added that allows one to lookup imposed constraints. + - It is possible to override the directory + (`SQLITE_LIB_DIR <https://bugzilla.mozilla.org/show_bug.cgi?id=1138820>`__) in which the NSS + build system will look for the sqlite library. + + .. rubric:: New Functions + :name: new_functions + + - *in cert.h* + + - **CERT_GetImposedNameConstraints** - Check if any imposed constraints exist for the given + certificate, and if found, return the constraints as encoded certificate extensions. + +.. _notable_changes_in_nss_3.19: + +`Notable Changes in NSS 3.19 <#notable_changes_in_nss_3.19>`__ +-------------------------------------------------------------- + +.. container:: + + - The SSL 3 protocol has been disabled by default. + - NSS now more strictly validates TLS extensions and will fail a handshake that contains + malformed extensions (`bug 753136 <https://bugzilla.mozilla.org/show_bug.cgi?id=753136>`__). + - In TLS 1.2 handshakes, NSS advertises support for the SHA512 hash algorithm in order to be + compatible with TLS servers that use certificates with a SHA512 signature (`bug + 1155922 <https://bugzilla.mozilla.org/show_bug.cgi?id=1155922>`__). + +.. _bugs_fixed_in_nss_3.19: + +`Bugs fixed in NSS 3.19 <#bugs_fixed_in_nss_3.19>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.19: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.19 + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Karthikeyan Bhargavan from + `INRIA <http://inria.fr/>`__ for responsibly disclosing the issue in `bug + 1086145 <https://bugzilla.mozilla.org/show_bug.cgi?id=1086145>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.19 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.19 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.20.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.20.1_release_notes/index.rst new file mode 100644 index 0000000000..2a149c5634 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.20.1_release_notes/index.rst @@ -0,0 +1,88 @@ +.. _mozilla_projects_nss_nss_3_20_1_release_notes: + +NSS 3.20.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.20.1 is a patch release for NSS 3.20. The bug fixes in NSS + 3.20.1 are described in the "Security Advisories" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_20_1_RTM. NSS 3.20.1 requires NSPR 4.10.10 or newer. + + NSS 3.20.1 and NSPR 4.10.10 source distributions are available on ftp.mozilla.org for secure + HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_20_1_RTM/src/ + https://ftp.mozilla.org/pub/nspr/releases/v4.10.10/src/ + +.. _security_advisories: + +`Security Advisories <#security_advisories>`__ +---------------------------------------------- + +.. container:: + + The following security-relevant bugs have been resolved in NSS 3.20.1. Users are encouraged to + upgrade immediately. + + - `Bug 1192028 <https://bugzilla.mozilla.org/show_bug.cgi?id=1192028>`__ (CVE-2015-7181) and + `Bug 1202868 <https://bugzilla.mozilla.org/show_bug.cgi?id=1202868>`__ (CVE-2015-7182): + Several issues existed within the ASN.1 decoder used by NSS for handling streaming BER data. + While the majority of NSS uses a separate, unaffected DER decoder, several public routines + also accept BER data, and thus are affected. An attacker that successfully exploited these + issues can overflow the heap and may be able to obtain remote code execution. + + | The following security-relevant bugs have been resolved in NSPR 4.10.10, which affect NSS. + | Because NSS includes portions of the affected NSPR code at build time, it is necessary to use + NSPR 4.10.10 when building NSS. + + - `Bug 1205157 <https://bugzilla.mozilla.org/show_bug.cgi?id=1205157>`__ (NSPR, CVE-2015-7183): + A logic bug in the handling of large allocations would allow exceptionally large allocations + to be reported as successful, without actually allocating the requested memory. This may allow + attackers to bypass security checks and obtain control of arbitrary memory. + +.. _new_in_nss_3.20.1: + +`New in NSS 3.20.1 <#new_in_nss_3.20.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix + security-relevant bugs. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.20.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.20.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.20.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.20.2_release_notes/index.rst new file mode 100644 index 0000000000..197e3c8978 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.20.2_release_notes/index.rst @@ -0,0 +1,80 @@ +.. _mozilla_projects_nss_nss_3_20_2_release_notes: + +NSS 3.20.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.20.2 is a security patch release for NSS 3.20. The bug fixes in + NSS 3.20.2 are described in the "Security Fixes" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_20_2_RTM. NSS 3.20.2 requires NSPR 4.10.10 or newer. + + NSS 3.20.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_20_2_RTM/src/ + +.. _security_fixes_in_nss_3.20.2: + +`Security Fixes in NSS 3.20.2 <#security_fixes_in_nss_3.20.2>`__ +---------------------------------------------------------------- + +.. container:: + + - `Bug 1158489 <https://bugzilla.mozilla.org/show_bug.cgi?id=1158489>`__ + ` <https://bugzilla.mozilla.org/show_bug.cgi?id=1138554>`__ / + `CVE-2015-7575 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-7575>`__ - Prevent + MD5 Downgrade in TLS 1.2 Signatures. + +.. _new_in_nss_3.20.2: + +`New in NSS 3.20.2 <#new_in_nss_3.20.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Karthikeyan Bhargavan from + `INRIA <http://inria.fr/>`__ for responsibly disclosing the issue in `Bug + 1158489 <https://bugzilla.mozilla.org/show_bug.cgi?id=1158489>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.20.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.20.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.20_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.20_release_notes/index.rst new file mode 100644 index 0000000000..9260778ce3 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.20_release_notes/index.rst @@ -0,0 +1,140 @@ +.. _mozilla_projects_nss_nss_3_20_release_notes: + +NSS 3.20 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.20, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_20_RTM. NSS 3.20 requires NSPR 4.10.8 or newer. + + NSS 3.20 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_20_RTM/src/ + +.. _new_in_nss_3.20: + +`New in NSS 3.20 <#new_in_nss_3.20>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The TLS library has been extended to support DHE ciphersuites in server applications. + + .. rubric:: New Functions + :name: new_functions + + - *in ssl.h* + + - **SSL_DHEGroupPrefSet** - Configure the set of allowed/enabled DHE group parameters that + can be used by NSS for a server socket. + - **SSL_EnableWeakDHEPrimeGroup** - Enable the use of weak DHE group parameters that are + smaller than default minimum size of the library. + + .. rubric:: New Types + :name: new_types + + - *in sslt.h* + + - **SSLDHEGroupType** - Enumerates the set of DHE parameters embedded in NSS that can be used + with function SSL_DHEGroupPrefSet + + .. rubric:: New Macros + :name: new_macros + + - *in ssl.h* + + - **SSL_ENABLE_SERVER_DHE** - A socket option user to enable or disable DHE ciphersuites for + a server socket + +.. _notable_changes_in_nss_3.20: + +`Notable Changes in NSS 3.20 <#notable_changes_in_nss_3.20>`__ +-------------------------------------------------------------- + +.. container:: + + - The TLS library has been extended to support DHE ciphersuites in server applications. + - For backward compatibility reasons, the server side implementation of the TLS library keeps + all DHE ciphersuites disabled by default. They can be enabled with the new socket option + SSL_ENABLE_SERVER_DHE and the SSL_OptionSet or the SSL_OptionSetDefault API. + - The server side implementation of the TLS does not support session tickets while using a DHE + ciphersuite (see `bug 1174677 <https://bugzilla.mozilla.org/show_bug.cgi?id=1174677>`__). + - Support for the following ciphersuites has been added: + + - TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 + - TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 + - TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 + + - By default, the server side TLS implementation will use DHE parameters with a size of 2048 + bits when using DHE ciphersuites. + - NSS embeds fixed DHE parameters sized 2048, 3072, 4096, 6144 and 8192 bits, which were copied + from version 08 of the Internet-Draft `"Negotiated Finite Field Diffie-Hellman Ephemeral + Parameters for + TLS" <https://datatracker.ietf.org/doc/html/draft-ietf-tls-negotiated-ff-dhe-08>`__, Appendix + A. + - A new API SSL_DHEGroupPrefSet has been added to NSS, which allows a server application to + select one or multiple of the embedded DHE parameters as the preferred parameters. The current + implementation of NSS will always use the first entry in the array that is passed as a + parameter to the SSL_DHEGroupPrefSet API. In future versions of the TLS implementation, a TLS + client might show a preference for certain DHE parameters, and the NSS TLS server side + implementation might select a matching entry from the set of parameters that have been + configured as preferred on the server side. + - NSS optionally supports the use of weak DHE parameters with DHE ciphersuites in order to + support legacy clients. To enable this support, the new API SSL_EnableWeakDHEPrimeGroup must + be used. Each time this API is called for the first time in a process, a fresh set of weak DHE + parameters will be randomly created, which may take a long amount of time. Please refer to the + comments in the header file that declares the SSL_EnableWeakDHEPrimeGroup API for additional + details. + - The size of the default PQG parameters used by certutil when creating DSA keys has been + increased to use 2048 bit parameters. + - The selfserv utility has been enhanced to support the new DHE features. + - NSS no longer supports C compilers that predate the ANSI C standard (C89). + +.. _bugs_fixed_in_nss_3.20: + +`Bugs fixed in NSS 3.20 <#bugs_fixed_in_nss_3.20>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.20: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.20 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.20 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.20 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report + at ` bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product + NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.21.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.1_release_notes/index.rst new file mode 100644 index 0000000000..94c4ef23aa --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.1_release_notes/index.rst @@ -0,0 +1,80 @@ +.. _mozilla_projects_nss_nss_3_21_1_release_notes: + +NSS 3.21.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.21.1 is a security patch release for NSS 3.21. The bug fixes in + NSS 3.21.1 are described in the "Security Fixes" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_21_1_RTM. NSS 3.21.1 requires NSPR 4.10.10 or newer. + + NSS 3.21.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_21_1_RTM/src/ + +.. _new_in_nss_3.21.1: + +`New in NSS 3.21.1 <#new_in_nss_3.21.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _security_fixes_in_nss_3.21.1: + +`Security Fixes in NSS 3.21.1 <#security_fixes_in_nss_3.21.1>`__ +---------------------------------------------------------------- + +.. container:: + + - `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__ / + `CVE-2016-1950 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1950>`__ - Fixed a + heap-based buffer overflow related to the parsing of certain ASN.1 structures. An attacker + could create a specially-crafted certificate which, when parsed by NSS, would cause a crash or + execution of arbitrary code with the permissions of the user. + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank security researcher Francis Gabriel for responsibly + disclosing the issue in `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.21.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.21.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.21.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.2_release_notes/index.rst new file mode 100644 index 0000000000..4a06d5c263 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.2_release_notes/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_nss_3_21_2_release_notes: + +NSS 3.21.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.21.2 is a security patch release for NSS 3.21.1. The bug fixes + in NSS 3.21.2 are described in the "Security Fixes" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_21_2_RTM. NSS 3.21.2 requires NSPR 4.10.10 or newer. + + NSS 3.21.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_21_2_RTM/src/ + +.. _new_in_nss_3.21.2: + +`New in NSS 3.21.2 <#new_in_nss_3.21.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _security_fixes_in_nss_3.21.2: + +`Security Fixes in NSS 3.21.2 <#security_fixes_in_nss_3.21.2>`__ +---------------------------------------------------------------- + +.. container:: + + - `Bug 1293334 <https://bugzilla.mozilla.org/show_bug.cgi?id=1293334>`__ / + `CVE-2016-9074 <https://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-9074>`__ - Fixed + a timing side channel in the TLS CBC code. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.21.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.21.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.21.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.3_release_notes/index.rst new file mode 100644 index 0000000000..64c8a986fd --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.3_release_notes/index.rst @@ -0,0 +1,78 @@ +.. _mozilla_projects_nss_nss_3_21_3_release_notes: + +NSS 3.21.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.21.3 is a security patch release for NSS 3.21.2. The bug fixes + in NSS 3.21.3 are described in the "Security Fixes" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_21_3_RTM. NSS 3.21.3 requires NSPR 4.10.10 or newer. + + NSS 3.21.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_21_3_RTM/src/ + +.. _new_in_nss_3.21.3: + +`New in NSS 3.21.3 <#new_in_nss_3.21.3>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _security_fixes_in_nss_3.21.3: + +`Security Fixes in NSS 3.21.3 <#security_fixes_in_nss_3.21.3>`__ +---------------------------------------------------------------- + +.. container:: + + - `Bug 1306103 <https://bugzilla.mozilla.org/show_bug.cgi?id=1306103>`__ / + `CVE-2016-5285 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-5285>`__ - Fixed a + possible DOS on NSS servers due to a missing NULL check. + - `Bug 1221620 <https://bugzil.la/1221620>`__ - Fixed a possible left-shift of a negative + integer value when parsing DER. + - `Bug 1206283 <https://bugzilla.mozilla.org/show_bug.cgi?id=1206283>`__ - Fixed an out-of-bound + read when parsing invalid UTF-16. + - `Bug 1241034 <https://bugzilla.mozilla.org/show_bug.cgi?id=1241034>`__ - Fixed an + out-of-bounds write when parsing invalid UTF-16. + - `Bug 1241037 <https://bugzilla.mozilla.org/show_bug.cgi?id=1241037>`__ - Fixed bogus surrogate + detection when parsing invalid UTF-16. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.21.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.21.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.21.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.4_release_notes/index.rst new file mode 100644 index 0000000000..bdb4231833 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.21.4_release_notes/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_nss_3_21_4_release_notes: + +NSS 3.21.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.21.4 is a security patch release for NSS 3.21. The bug fixes in + NSS 3.21.4 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_21_4_RTM. NSS 3.21.4 requires NSPR 4.12 or newer. + + NSS 3.21.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_21_4_RTM/src/ + +.. _new_in_nss_3.21.4: + +`New in NSS 3.21.4 <#new_in_nss_3.21.4>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.21.4: + +`Bugs fixed in NSS 3.21.4 <#bugs_fixed_in_nss_3.21.4>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1344380 <https://bugzilla.mozilla.org/show_bug.cgi?id=1344380>`__ / Out-of-bounds write + in Base64 encoding in NSS + (`CVE-2017-5461 <https://www.mozilla.org/en-US/security/advisories/mfsa2017-10/#CVE-2017-5461>`__) + - `Bug 1345089 <https://bugzilla.mozilla.org/show_bug.cgi?id=1345089>`__ / DRBG flaw in NSS + (`CVE-2017-5462 <https://www.mozilla.org/en-US/security/advisories/mfsa2017-10/#CVE-2017-5462>`__) + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Ronald Crane and Vladimir Klebanov for responsibly + disclosing the issues by providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.21.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.21.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.21_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.21_release_notes/index.rst new file mode 100644 index 0000000000..3e1dab4dc7 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.21_release_notes/index.rst @@ -0,0 +1,277 @@ +.. _mozilla_projects_nss_nss_3_21_release_notes: + +NSS 3.21 release notes +====================== + +.. container:: + + 2016-01-07, this page has been updated to include additional information about the release. The + sections "Security Fixes" and "Acknowledgements" have been added. + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.21, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_21_RTM. NSS 3.21 requires NSPR 4.10.10 or newer. + + NSS 3.21 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_21_RTM/src/ + +.. _security_fixes_in_nss_3.21: + +`Security Fixes in NSS 3.21 <#security_fixes_in_nss_3.21>`__ +------------------------------------------------------------ + +.. container:: + + - `Bug 1158489 <https://bugzilla.mozilla.org/show_bug.cgi?id=1158489>`__ + ` <https://bugzilla.mozilla.org/show_bug.cgi?id=1138554>`__ / + `CVE-2015-7575 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-7575>`__ - Prevent + MD5 Downgrade in TLS 1.2 Signatures. + +.. _new_in_nss_3.21: + +`New in NSS 3.21 <#new_in_nss_3.21>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - ``certutil`` now supports a ``--rename`` option to change a nickname (`bug + 1142209 <https://bugzilla.mozilla.org/show_bug.cgi?id=1142209>`__) + - TLS extended master secret extension (`RFC + 7627 <https://datatracker.ietf.org/doc/html/rfc7627>`__) is supported (`bug + 1117022 <https://bugzilla.mozilla.org/show_bug.cgi?id=1117022>`__) + - New info functions added for use during mid-handshake callbacks (`bug + 1084669 <https://bugzilla.mozilla.org/show_bug.cgi?id=1084669>`__) + + .. rubric:: New Functions + :name: new_functions + + - *in nss.h* + + - **NSS_OptionSet** - sets NSS global options + - **NSS_OptionGet** - gets the current value of NSS global options + + - *in secmod.h* + + - **SECMOD_CreateModuleEx** - Create a new SECMODModule structure from module name string, + module parameters string, NSS specific parameters string, and NSS configuration parameter + string. The module represented by the module structure is not loaded. The difference with + **SECMOD_CreateModule** is the new function handles NSS configuration parameter strings. + + - *in ssl.h* + + - **SSL_GetPreliminaryChannelInfo** - obtains information about a TLS channel prior to the + handshake being completed, for use with the callbacks that are invoked during the handshake + - **SSL_SignaturePrefSet** - configures the enabled signature and hash algorithms for TLS + - **SSL_SignaturePrefGet** - retrieves the currently configured signature and hash algorithms + - **SSL_SignatureMaxCount** - obtains the maximum number signature algorithms that can be + configured with **SSL_SignaturePrefSet** + + - *in utilpars.h* + + - **NSSUTIL_ArgParseModuleSpecEx** - takes a module spec and breaks it into shared library + string, module name string, module parameters string, NSS specific parameters string, and + NSS configuration parameter strings. The returned strings must be freed by the caller. The + difference with **NSS_ArgParseModuleSpec** is the new function handles NSS configuration + parameter strings. + - **NSSUTIL_MkModuleSpecEx** - take a shared library string, module name string, module + parameters string, NSS specific parameters string, and NSS configuration parameter string + and returns a module string which the caller must free when it is done. The difference with + **NSS_MkModuleSpec** is the new function handles NSS configuration parameter strings. + + .. rubric:: New Types + :name: new_types + + - *in pkcs11t.h* + + - **CK_TLS12_MASTER_KEY_DERIVE_PARAMS{_PTR}** - parameters {or pointer} for + **CKM_TLS12_MASTER_KEY_DERIVE** + - **CK_TLS12_KEY_MAT_PARAMS{_PTR}** - parameters {or pointer} for + **CKM_TLS12_KEY_AND_MAC_DERIVE** + - **CK_TLS_KDF_PARAMS{_PTR}** - parameters {or pointer} for **CKM_TLS_KDF** + - **CK_TLS_MAC_PARAMS{_PTR}** - parameters {or pointer} for **CKM_TLS_MAC** + + - *in sslt.h* + + - **SSLHashType** - identifies a hash function + - **SSLSignatureAndHashAlg** - identifies a signature and hash function + - **SSLPreliminaryChannelInfo** - provides information about the session state prior to + handshake completion + + .. rubric:: New Macros + :name: new_macros + + - *in nss.h* + + - **NSS_RSA_MIN_KEY_SIZE** - used with NSS_OptionSet and NSS_OptionGet to set or get the + minimum RSA key size + - **NSS_DH_MIN_KEY_SIZE** - used with NSS_OptionSet and NSS_OptionGet to set or get the + minimum DH key size + - **NSS_DSA_MIN_KEY_SIZE** - used with NSS_OptionSet and NSS_OptionGet to set or get the + minimum DSA key size + + - *in pkcs11t.h* + + - **CKM_TLS12_MASTER_KEY_DERIVE** - derives TLS 1.2 master secret + - **CKM_TLS12_KEY_AND_MAC_DERIVE** - derives TLS 1.2 traffic key and IV + - **CKM_TLS12_MASTER_KEY_DERIVE_DH** - derives TLS 1.2 master secret for DH (and ECDH) cipher + suites + - **CKM_TLS12_KEY_SAFE_DERIVE** and **CKM_TLS_KDF** are identifiers for additional PKCS#12 + mechanisms for TLS 1.2 that are currently unused in NSS. + - **CKM_TLS_MAC** - computes TLS Finished MAC + + - *in secoidt.h* + + - **NSS_USE_ALG_IN_SSL_KX** - policy flag indicating that keys are used in TLS key exchange + + - *in sslerr.h* + + - **SSL_ERROR_RX_SHORT_DTLS_READ** - error code for failure to include a complete DTLS record + in a UDP packet + - **SSL_ERROR_NO_SUPPORTED_SIGNATURE_ALGORITHM** - error code for when no valid signature and + hash algorithm is available + - **SSL_ERROR_UNSUPPORTED_SIGNATURE_ALGORITHM** - error code for when an unsupported + signature and hash algorithm is configured + - **SSL_ERROR_MISSING_EXTENDED_MASTER_SECRET** - error code for when the extended master + secret is missing after having been negotiated + - **SSL_ERROR_UNEXPECTED_EXTENDED_MASTER_SECRET** - error code for receiving an extended + master secret when previously not negotiated + + - *in sslt.h* + + - **SSL_ENABLE_EXTENDED_MASTER_SECRET** - configuration to enable the TLS extended master + secret extension (`RFC 7627 <https://datatracker.ietf.org/doc/html/rfc7627>`__) + - **ssl_preinfo_version** - used with **SSLPreliminaryChannelInfo** to indicate that a TLS + version has been selected + - **ssl_preinfo_cipher_suite** - used with **SSLPreliminaryChannelInfo** to indicate that a + TLS cipher suite has been selected + - **ssl_preinfo_all** - used with **SSLPreliminaryChannelInfo** to indicate that all + preliminary information has been set + +.. _notable_changes_in_nss_3.21: + +`Notable Changes in NSS 3.21 <#notable_changes_in_nss_3.21>`__ +-------------------------------------------------------------- + +.. container:: + + - NSS now builds with elliptic curve ciphers enabled by default (`bug + 1205688 <https://bugzilla.mozilla.org/show_bug.cgi?id=1205688>`__) + - NSS now builds with warnings as errors (`bug + 1182667 <https://bugzilla.mozilla.org/show_bug.cgi?id=1182667>`__) + - The following CA certificates were **Removed** + + - CN = VeriSign Class 4 Public Primary Certification Authority - G3 + + - SHA1 Fingerprint: C8:EC:8C:87:92:69:CB:4B:AB:39:E9:8D:7E:57:67:F3:14:95:73:9D + + - CN = UTN-USERFirst-Network Applications + + - SHA1 Fingerprint: 5D:98:9C:DB:15:96:11:36:51:65:64:1B:56:0F:DB:EA:2A:C2:3E:F1 + + - CN = TC TrustCenter Universal CA III + + - SHA1 Fingerprint: 96:56:CD:7B:57:96:98:95:D0:E1:41:46:68:06:FB:B8:C6:11:06:87 + + - CN = A-Trust-nQual-03 + + - SHA-1 Fingerprint: D3:C0:63:F2:19:ED:07:3E:34:AD:5D:75:0B:32:76:29:FF:D5:9A:F2 + + - CN = USERTrust Legacy Secure Server CA + + - SHA-1 Fingerprint: 7C:2F:91:E2:BB:96:68:A9:C6:F6:BD:10:19:2C:6B:52:5A:1B:BA:48 + + - Friendly Name: Digital Signature Trust Co. Global CA 1 + + - SHA-1 Fingerprint: 81:96:8B:3A:EF:1C:DC:70:F5:FA:32:69:C2:92:A3:63:5B:D1:23:D3 + + - Friendly Name: Digital Signature Trust Co. Global CA 3 + + - SHA-1 Fingerprint: AB:48:F3:33:DB:04:AB:B9:C0:72:DA:5B:0C:C1:D0:57:F0:36:9B:46 + + - CN = UTN - DATACorp SGC + + - SHA-1 Fingerprint: 58:11:9F:0E:12:82:87:EA:50:FD:D9:87:45:6F:4F:78:DC:FA:D6:D4 + + - O = TÜRKTRUST Bilgi İletişim ve Bilişim Güvenliği Hizmetleri A.Ş. (c) Kasım 2005 + + - SHA-1 Fingerprint: B4:35:D4:E1:11:9D:1C:66:90:A7:49:EB:B3:94:BD:63:7B:A7:82:B7 + + - The following CA certificate had the Websites **trust bit turned off** + + - OU = Equifax Secure Certificate Authority + + - SHA1 Fingerprint: D2:32:09:AD:23:D3:14:23:21:74:E4:0D:7F:9D:62:13:97:86:63:3A + + - The following CA certificates were **Added** + + - CN = Certification Authority of WoSign G2 + + - SHA1 Fingerprint: FB:ED:DC:90:65:B7:27:20:37:BC:55:0C:9C:56:DE:BB:F2:78:94:E1 + + - CN = CA WoSign ECC Root + + - SHA1 Fingerprint: D2:7A:D2:BE:ED:94:C0:A1:3C:C7:25:21:EA:5D:71:BE:81:19:F3:2B + + - CN = OISTE WISeKey Global Root GB CA + + - SHA1 Fingerprint: 0F:F9:40:76:18:D3:D7:6A:4B:98:F0:A8:35:9E:0C:FD:27:AC:CC:ED + + - The version number of the updated root CA list has been set to 2.6 + +.. _bugs_fixed_in_nss_3.21: + +`Bugs fixed in NSS 3.21 <#bugs_fixed_in_nss_3.21>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.21: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.21 + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Karthikeyan Bhargavan from + `INRIA <http://inria.fr/>`__ for responsibly disclosing the issue in `Bug + 1158489 <https://bugzilla.mozilla.org/show_bug.cgi?id=1158489>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.21 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.21 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.22.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.22.1_release_notes/index.rst new file mode 100644 index 0000000000..e64b37f266 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.22.1_release_notes/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_nss_3_22_1_release_notes: + +NSS 3.22.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.22.1 is a patch release for NSS 3.22. The bug fixes in NSS + 3.22.1 are described in the "Notable Changes" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_22_1_RTM. NSS 3.22.1 requires NSPR 4.12 or newer. + + NSS 3.22.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_22_1_RTM/src/ + +.. _new_in_nss_3.22.1: + +`New in NSS 3.22.1 <#new_in_nss_3.22.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _notable_changes_in_nss_3.22.1: + +`Notable Changes in NSS 3.22.1 <#notable_changes_in_nss_3.22.1>`__ +------------------------------------------------------------------ + +.. container:: + + - `bug 1194680 <https://bugzilla.mozilla.org/show_bug.cgi?id=1194680>`__: NSS has been changed + to use the PR_GetEnvSecure function that was made available in NSPR 4.12 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.22.1 shared libraries are backward compatible with all older NSS 3.22 shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.22.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.22.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.22.2_release_notes/index.rst new file mode 100644 index 0000000000..8583d9c0e1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.22.2_release_notes/index.rst @@ -0,0 +1,90 @@ +.. _mozilla_projects_nss_nss_3_22_2_release_notes: + +NSS 3.22.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.22.2 is a security patch release for NSS 3.22. The bug fixes in + NSS 3.22.2 are described in the "Security Fixes" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_22_2_RTM. NSS 3.22.2 requires NSPR 4.12 or newer. + + NSS 3.22.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_22_2_RTM/src/ + +.. _new_in_nss_3.22.2: + +`New in NSS 3.22.2 <#new_in_nss_3.22.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _security_fixes_in_nss_3.22.2: + +`Security Fixes in NSS 3.22.2 <#security_fixes_in_nss_3.22.2>`__ +---------------------------------------------------------------- + +.. container:: + + - `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__ / + `CVE-2016-1950 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1950>`__ - Fixed a + heap-based buffer overflow related to the parsing of certain ASN.1 structures. An attacker + could create a specially-crafted certificate which, when parsed by NSS, would cause a crash or + execution of arbitrary code with the permissions of the user. + +.. _notable_changes_in_nss_3.22.2: + +`Notable Changes in NSS 3.22.2 <#notable_changes_in_nss_3.22.2>`__ +------------------------------------------------------------------ + +.. container:: + + - `Bug 1247990 <https://bugzilla.mozilla.org/show_bug.cgi?id=1247990>`__ - The root CA changes + from :ref:`mozilla_projects_nss_nss_3_23_release_notes` have been backported. + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank security researcher Francis Gabriel for responsibly + disclosing the issue in `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.22.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.22.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.22.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.22.3_release_notes/index.rst new file mode 100644 index 0000000000..1130ecf147 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.22.3_release_notes/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_nss_3_22_3_release_notes: + +NSS 3.22.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.22.3 is a patch release for NSS 3.22. The bug fixes in NSS + 3.22.3 are described in the "Bugs fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_22_3_RTM. NSS 3.22.3 requires NSPR 4.12 or newer. + + NSS 3.22.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_22_3_RTM/src/ + +.. _new_in_nss_3.22.3: + +`New in NSS 3.22.3 <#new_in_nss_3.22.3>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.22.3: + +`Bugs fixed in NSS 3.22.3 <#bugs_fixed_in_nss_3.22.3>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1243641 <https://bugzilla.mozilla.org/show_bug.cgi?id=1243641>`__ - Increase + compatibility of TLS extended master secret, don't send an empty TLS extension last in the + handshake + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.22.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.22.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.22_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.22_release_notes/index.rst new file mode 100644 index 0000000000..9b4aefd19f --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.22_release_notes/index.rst @@ -0,0 +1,194 @@ +.. _mozilla_projects_nss_nss_3_22_release_notes: + +NSS 3.22 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.22, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_22_RTM. NSS 3.22 requires NSPR 4.11 or newer. + + NSS 3.22 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_22_RTM/src/ + +.. _new_in_nss_3.22: + +`New in NSS 3.22 <#new_in_nss_3.22>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - RSA-PSS signatures are now supported (`bug + 1215295 <https://bugzilla.mozilla.org/show_bug.cgi?id=1215295>`__) + + - New functions ``PK11_SignWithMechanism()`` and ``PK11_SignWithMechanism()`` are provided to + allow RSA keys to be used with PSS. + + - Pseudorandom functions based on hashes other than SHA-1 are now supported with PBKDF (`bug + 554827 <https://bugzilla.mozilla.org/show_bug.cgi?id=554827>`__). + + - ``PK11_CreatePBEV2AlgorithmID()`` now supports ``SEC_OID_PKCS5_PBKDF2`` with + ``cipherAlgTag`` and ``prfAlgTag`` set to ``SEC_OID_HMAC_SHA256``, ``SEC_OID_HMAC_SHA224``, + ``SEC_OID_HMAC_SHA384``, or ``SEC_OID_HMAC_SHA512``. + + - Enforce an External Policy on NSS from a config file (`bug + 1009429 <https://bugzilla.mozilla.org/show_bug.cgi?id=1009429>`__) + + - you can now add a config= line to pkcs11.txt (assuming you are using sql databases), which + will force NSS to restrict the application to certain cryptographic algorithms and + protocols. A complete list can be found in :ref:`mozilla_projects_nss_nss_config_options`. + + .. rubric:: New Functions + :name: new_functions + + - *in pk11pub.h* + + - **PK11_SignWithMechanism** - This function is an extended version ``PK11_Sign()``. + - **PK11_VerifyWithMechanism** - This function is an extended version of ``PK11_Verify()``. + + - These functions take an explicit mechanism and parameters as arguments rather than + inferring it from the key type using ``PK11_MapSignKeyType()``. The mechanism type + CKM_RSA_PKCS_PSS is now supported for RSA in addition to CKM_RSA_PKCS. The + CK_RSA_PKCS_PSS mechanism takes a parameter of type CK_RSA_PKCS_PSS_PARAMS. + + - *in ssl.h* + + - **SSL_PeerSignedCertTimestamps** - Get signed_certificate_timestamp TLS extension data + - **SSL_SetSignedCertTimestamps** - Set signed_certificate_timestamp TLS extension data + + .. rubric:: New Types + :name: new_types + + - *in secoidt.h* + + - The following are added to SECOidTag: + + - SEC_OID_AES_128_GCM + - SEC_OID_AES_192_GCM + - SEC_OID_AES_256_GCM + - SEC_OID_IDEA_CBC + - SEC_OID_RC2_40_CBC + - SEC_OID_DES_40_CBC + - SEC_OID_RC4_40 + - SEC_OID_RC4_56 + - SEC_OID_NULL_CIPHER + - SEC_OID_HMAC_MD5 + - SEC_OID_TLS_RSA + - SEC_OID_TLS_DHE_RSA + - SEC_OID_TLS_DHE_DSS + - SEC_OID_TLS_DH_RSA + - SEC_OID_TLS_DH_DSS + - SEC_OID_TLS_DH_ANON + - SEC_OID_TLS_ECDHE_ECDSA + - SEC_OID_TLS_ECDHE_RSA + - SEC_OID_TLS_ECDH_ECDSA + - SEC_OID_TLS_ECDH_RSA + - SEC_OID_TLS_ECDH_ANON + - SEC_OID_TLS_RSA_EXPORT + - SEC_OID_TLS_DHE_RSA_EXPORT + - SEC_OID_TLS_DHE_DSS_EXPORT + - SEC_OID_TLS_DH_RSA_EXPORT + - SEC_OID_TLS_DH_DSS_EXPORT + - SEC_OID_TLS_DH_ANON_EXPORT + - SEC_OID_APPLY_SSL_POLICY + + - in sslt.h + + - **ssl_signed_cert_timestamp_xtn** is added to ``SSLExtensionType``. + + .. rubric:: New Macros + :name: new_macros + + - in nss.h + + - NSS_RSA_MIN_KEY_SIZE + - NSS_DH_MIN_KEY_SIZE + - NSS_DSA_MIN_KEY_SIZE + - NSS_TLS_VERSION_MIN_POLICY + - NSS_TLS_VERSION_MAX_POLICY + - NSS_DTLS_VERSION_MIN_POLICY + - NSS_DTLS_VERSION_MAX_POLICY + + - *in pkcs11t.h* + + - **CKP_PKCS5_PBKD2_HMAC_GOSTR3411** - PRF based on HMAC with GOSTR3411 for PBKDF (not + supported) + - **CKP_PKCS5_PBKD2_HMAC_SHA224** - PRF based on HMAC with SHA-224 for PBKDF + - **CKP_PKCS5_PBKD2_HMAC_SHA256** - PRF based on HMAC with SHA-256 for PBKDF + - **CKP_PKCS5_PBKD2_HMAC_SHA384** - PRF based on HMAC with SHA-256 for PBKDF + - **CKP_PKCS5_PBKD2_HMAC_SHA512** - PRF based on HMAC with SHA-256 for PBKDF + - **CKP_PKCS5_PBKD2_HMAC_SHA512_224** - PRF based on HMAC with SHA-512 truncated to 224 bits + for PBKDF (not supported) + - **CKP_PKCS5_PBKD2_HMAC_SHA512_256** - PRF based on HMAC with SHA-512 truncated to 256 bits + for PBKDF (not supported) + + - *in secoidt.h* + + - NSS_USE_ALG_IN_SSL + - NSS_USE_POLICY_IN_SSL + + - *in ssl.h* + + - **SSL_ENABLE_SIGNED_CERT_TIMESTAMPS** + + - *in sslt.h* + + - **SSL_MAX_EXTENSIONS** is updated to 13 + +.. _notable_changes_in_nss_3.22: + +`Notable Changes in NSS 3.22 <#notable_changes_in_nss_3.22>`__ +-------------------------------------------------------------- + +.. container:: + + - NSS C++ tests are built by default, requiring a C++11 compiler. Set the NSS_DISABLE_GTESTS + variable to 1 to disable building these tests. + +.. _bugs_fixed_in_nss_3.22: + +`Bugs fixed in NSS 3.22 <#bugs_fixed_in_nss_3.22>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.22: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.22 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.22 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.22 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.23_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.23_release_notes/index.rst new file mode 100644 index 0000000000..fe5277c32b --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.23_release_notes/index.rst @@ -0,0 +1,192 @@ +.. _mozilla_projects_nss_nss_3_23_release_notes: + +NSS 3.23 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.23, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_23_RTM. NSS 3.23 requires NSPR 4.12 or newer. + + NSS 3.23 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_23_RTM/src/ + +.. _new_in_nss_3.23: + +`New in NSS 3.23 <#new_in_nss_3.23>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - ChaCha20/Poly1305 cipher and TLS cipher suites now supported (`bug + 917571 <https://bugzilla.mozilla.org/show_bug.cgi?id=917571>`__, `bug + 1227905 <https://bugzilla.mozilla.org/show_bug.cgi?id=1227905>`__) + + - + + .. container:: + + Experimental-only support TLS 1.3 1-RTT mode (draft-11). This code is not ready for + production use. + + .. rubric:: New Functions + :name: new_functions + + - *in ssl.h* + + - **SSL_SetDowngradeCheckVersion** - Set maximum version for new ServerRandom anti-downgrade + mechanism. Clients that perform a version downgrade (which is a dangerous practice) call + this with the highest version number that they possibly support. This gives them access to + the `version downgrade protection from TLS + 1.3 <https://tlswg.github.io/tls13-spec/#client-hello>`__. + +.. _notable_changes_in_nss_3.23: + +`Notable Changes in NSS 3.23 <#notable_changes_in_nss_3.23>`__ +-------------------------------------------------------------- + +.. container:: + + - The copy of SQLite shipped with NSS has been updated to version 3.10.2 (`bug + 1234698 <https://bugzilla.mozilla.org/show_bug.cgi?id=1234698>`__) + - The list of TLS extensions sent in the TLS handshake has been reordered to increase + compatibility of the Extended Master Secret with servers (`bug + 1243641 <https://bugzilla.mozilla.org/show_bug.cgi?id=1243641>`__) + - The build time environment variable NSS_ENABLE_ZLIB has been renamed to NSS_SSL_ENABLE_ZLIB + (`Bug 1243872 <https://bugzilla.mozilla.org/show_bug.cgi?id=1243872>`__). + - The build time environment variable NSS_DISABLE_CHACHAPOLY was added, which can be used to + prevent compilation of the ChaCha20/Poly1305 code. + - The following CA certificates were **Removed** + + - CN = Staat der Nederlanden Root CA + + - SHA-256 Fingerprint: + D4:1D:82:9E:8C:16:59:82:2A:F9:3F:CE:62:BF:FC:DE:26:4F:C8:4E:8B:95:0C:5F:F2:75:D0:52:35:46:95:A3 + + - CN = NetLock Minositett Kozjegyzoi (Class QA) Tanusitvanykiado + + - SHA-256 Fingerprint: + E6:06:DD:EE:E2:EE:7F:5C:DE:F5:D9:05:8F:F8:B7:D0:A9:F0:42:87:7F:6A:17:1E:D8:FF:69:60:E4:CC:5E:A5 + + - CN = NetLock Kozjegyzoi (Class A) Tanusitvanykiado + + - SHA-256 Fingerprint: + 7F:12:CD:5F:7E:5E:29:0E:C7:D8:51:79:D5:B7:2C:20:A5:BE:75:08:FF:DB:5B:F8:1A:B9:68:4A:7F:C9:F6:67 + + - CN = NetLock Uzleti (Class B) Tanusitvanykiado + + - SHA-256 Fingerprint: + 39:DF:7B:68:2B:7B:93:8F:84:71:54:81:CC:DE:8D:60:D8:F2:2E:C5:98:87:7D:0A:AA:C1:2B:59:18:2B:03:12 + + - CN = NetLock Expressz (Class C) Tanusitvanykiado + + - SHA-256 Fingerprint: + 0B:5E:ED:4E:84:64:03:CF:55:E0:65:84:84:40:ED:2A:82:75:8B:F5:B9:AA:1F:25:3D:46:13:CF:A0:80:FF:3F + + - Friendly Name: VeriSign Class 1 Public PCA – G2 + + - SHA-256 Fingerprint: + 34:1D:E9:8B:13:92:AB:F7:F4:AB:90:A9:60:CF:25:D4:BD:6E:C6:5B:9A:51:CE:6E:D0:67:D0:0E:C7:CE:9B:7F + + - Friendly Name: VeriSign Class 3 Public PCA + + - SHA-256 Fingerprint: + A4:B6:B3:99:6F:C2:F3:06:B3:FD:86:81:BD:63:41:3D:8C:50:09:CC:4F:A3:29:C2:CC:F0:E2:FA:1B:14:03:05 + + - Friendly Name: VeriSign Class 3 Public PCA – G2 + + - SHA-256 Fingerprint: + 83:CE:3C:12:29:68:8A:59:3D:48:5F:81:97:3C:0F:91:95:43:1E:DA:37:CC:5E:36:43:0E:79:C7:A8:88:63:8B + + - CN = CA Disig + + - SHA-256 Fingerprint: + 92:BF:51:19:AB:EC:CA:D0:B1:33:2D:C4:E1:D0:5F:BA:75:B5:67:90:44:EE:0C:A2:6E:93:1F:74:4F:2F:33:CF + + - The following CA certificates were **Added** + + - CN = SZAFIR ROOT CA2 + + - SHA-256 Fingerprint: + A1:33:9D:33:28:1A:0B:56:E5:57:D3:D3:2B:1C:E7:F9:36:7E:B0:94:BD:5F:A7:2A:7E:50:04:C8:DE:D7:CA:FE + + - CN = Certum Trusted Network CA 2 + + - SHA-256 Fingerprint: + B6:76:F2:ED:DA:E8:77:5C:D3:6C:B0:F6:3C:D1:D4:60:39:61:F4:9E:62:65:BA:01:3A:2F:03:07:B6:D0:B8:04 + + - The following CA certificate had the Email **trust bit turned on** + + - CN = Actalis Authentication Root CA + + - SHA-256 Fingerprint: + 55:92:60:84:EC:96:3A:64:B9:6E:2A:BE:01:CE:0B:A8:6A:64:FB:FE:BC:C7:AA:B5:AF:C1:55:B3:7F:D7:60:66 + +.. _security_fixes_in_nss_3.23: + +`Security Fixes in NSS 3.23 <#security_fixes_in_nss_3.23>`__ +------------------------------------------------------------ + +.. container:: + + - `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__ / + `CVE-2016-1950 <http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-1950>`__ - Fixed a + heap-based buffer overflow related to the parsing of certain ASN.1 structures. An attacker + could create a specially-crafted certificate which, when parsed by NSS, would cause a crash or + execution of arbitrary code with the permissions of the user. + +.. _bugs_fixed_in_nss_3.23: + +`Bugs fixed in NSS 3.23 <#bugs_fixed_in_nss_3.23>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.23: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.23 + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank security researcher Francis Gabriel for responsibly + disclosing the issue in `Bug 1245528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1245528>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.23 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.23 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.24_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.24_release_notes/index.rst new file mode 100644 index 0000000000..e1fe240a47 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.24_release_notes/index.rst @@ -0,0 +1,201 @@ +.. _mozilla_projects_nss_nss_3_24_release_notes: + +NSS 3.24 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.24, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_24_RTM. NSS 3.24 requires Netscape Portable Runtime(NSPR) 4.12 or newer. + + NSS 3.24 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_24_RTM/src/ + +.. _new_in_nss_3.24: + +`New in NSS 3.24 <#new_in_nss_3.24>`__ +-------------------------------------- + +.. container:: + + NSS 3.24 includes two NSS softoken updates, a new function to configure SSL/TLS server sockets, + and two functions to improve the use of temporary arenas. + +.. _new_functionality: + +`New functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS softoken has been updated with the latest National Institute of Standards and Technology + (NIST) guidance (as of 2015): + + - Software integrity checks and POST functions are executed on shared library load. These + checks have been disabled by default, as they can cause a performance regression. To enable + these checks, you must define symbol NSS_FORCE_FIPS when building NSS. + - Counter mode and Galois/Counter Mode (GCM) have checks to prevent counter overflow. + - Additional CSPs are zeroed in the code. + - NSS softoken uses new guidance for how many Rabin-Miller tests are needed to verify a prime + based on prime size. + + - NSS softoken has also been updated to allow NSS to run in FIPS Level 1 (no password). This + mode is triggered by setting the database password to the empty string. In FIPS mode, you may + move from Level 1 to Level 2 (by setting an appropriate password), but not the reverse. + - A SSL_ConfigServerCert function has been added for configuring SSL/TLS server sockets with a + certificate and private key. Use this new function in place of SSL_ConfigSecureServer, + SSL_ConfigSecureServerWithCertChain, SSL_SetStapledOCSPResponses, and + SSL_SetSignedCertTimestamps. SSL_ConfigServerCert automatically determines the certificate + type from the certificate and private key. The caller is no longer required to use SSLKEAType + explicitly to select a "slot" into which the certificate is configured (which incorrectly + identifies a key agreement type rather than a certificate). Separate functions for configuring + Online Certificate Status Protocol (OCSP) responses or Signed Certificate Timestamps are not + needed, since these can be added to the optional SSLExtraServerCertData struct provided to + SSL_ConfigServerCert. Also, partial support for RSA Probabilistic Signature Scheme (RSA-PSS) + certificates has been added. Although these certificates can be configured, they will not be + used by NSS in this version. + - For functions that use temporary arenas, allocating a PORTCheapArena on the stack is more + performant than allocating a PLArenaPool on the heap. Rather than declaring a PLArenaPool + pointer and calling PORT_NewArena/PORT_FreeArena to allocate or free an instance on the heap, + declare a PORTCheapArenaPool on the stack and use PORT_InitCheapArena/PORT_DestroyCheapArena + to initialize and destroy it. Items allocated from the arena are still created on the heap, + only the arena itself is stack-allocated. Note: This approach is only useful when the arena + use is tightly bounded, for example, if it is only used in a single function. + +.. _new_elements: + +`New elements <#new_elements>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This section lists and briefly describes the new functions, types, and macros in NSS 3.24. + + .. rubric:: New functions + :name: new_functions + + - *In ssl.h* + + - SSL_ConfigServerCert - Configures an SSL/TLS socket with a certificate, private key, and + other information. + + - *In secport.h* + + - PORT_InitCheapArena - Initializes an arena that was created on the stack. (See + PORTCheapArenaPool.) + - PORT_DestroyCheapArena - Destroys an arena that was created on the stack. (See + PORTCheapArenaPool.) + + .. rubric:: New types + :name: new_types + + - *In sslt.h* + + - SSLExtraServerCertData - Optionally passed as an argument to SSL_ConfigServerCert. This + struct contains supplementary information about a certificate, such as the intended type of + the certificate, stapled OCSP responses, or Signed Certificate Timestamps (used for + `certificate transparency <https://datatracker.ietf.org/doc/html/rfc6962>`__). + + - *In secport.h* + + - PORTCheapArenaPool - A stack-allocated arena pool, to be used for temporary arena + allocations. + + .. rubric:: New macros + :name: new_macros + + - *In pkcs11t.h* + + - CKM_TLS12_MAC + + - *In secoidt.h* + + - SEC_OID_TLS_ECDHE_PSK - This OID governs the use of the + TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256 cipher suite, which is used only for session + resumption in TLS 1.3. + +.. _notable_changes_in_nss_3.24: + +`Notable changes in NSS 3.24 <#notable_changes_in_nss_3.24>`__ +-------------------------------------------------------------- + +.. container:: + + Additions, deprecations, and other changes in NSS 3.24 are listed below. + + - Deprecate the following functions. (Applications should instead use the new + SSL_ConfigServerCert function.) + + - SSL_SetStapledOCSPResponses + - SSL_SetSignedCertTimestamps + - SSL_ConfigSecureServer + - SSL_ConfigSecureServerWithCertChain + + - Deprecate the NSS_FindCertKEAType function, as it reports a misleading value for certificates + that might be used for signing rather than key exchange. + - Update SSLAuthType to define a larger number of authentication key types. + - Deprecate the member attribute **authAlgorithm** of type SSLCipherSuiteInfo. Instead, + applications should use the newly added attribute **authType**. + - Rename ssl_auth_rsa to ssl_auth_rsa_decrypt. + - Add a shared library (libfreeblpriv3) on Linux platforms that define FREEBL_LOWHASH. + - Remove most code related to SSL v2, including the ability to actively send a SSLv2-compatible + client hello. However, the server-side implementation of the SSL/TLS protocol still supports + processing of received v2-compatible client hello messages. + - Disable (by default) NSS support in optimized builds for logging SSL/TLS key material to a + logfile if the SSLKEYLOGFILE environment variable is set. To enable the functionality in + optimized builds, you must define the symbol NSS_ALLOW_SSLKEYLOGFILE when building NSS. + - Update NSS to protect it against the Cachebleed attack. + - Disable support for DTLS compression. + - Improve support for TLS 1.3. This includes support for DTLS 1.3. Note that TLS 1.3 support is + experimental and not suitable for production use. + +.. _bugs_fixed_in_nss_3.24: + +`Bugs fixed in NSS 3.24 <#bugs_fixed_in_nss_3.24>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.24: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.24 + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Yuval Yarom for responsibly disclosing the + Cachebleed attack by providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.24 shared libraries are backward-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.24 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.25.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.25.1_release_notes/index.rst new file mode 100644 index 0000000000..d1c9862c9e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.25.1_release_notes/index.rst @@ -0,0 +1,80 @@ +.. _mozilla_projects_nss_nss_3_25_1_release_notes: + +NSS 3.25.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.25.1 is a patch release for NSS 3.25. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_25_1_RTM. NSS 3.25.1 requires NSPR 4.12 or newer. + + NSS 3.25.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_25_1_RTM/src/ + +.. _new_in_nss_3.25.1: + +`New in NSS 3.25.1 <#new_in_nss_3.25.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to address a TLS + compatibility issue that some client applications experienced with NSS 3.25. + +.. _notable_changes_in_nss_3.25.1: + +`Notable Changes in NSS 3.25.1 <#notable_changes_in_nss_3.25.1>`__ +------------------------------------------------------------------ + +.. container:: + + MD5 signature algorithms sent by the server in CertificateRequest messages are now properly + ignored. Previously, with rare server configurations, an MD5 signature algorithm might have been + selected for client authentication and caused the client to abort the connection soon after. + +.. _bugs_fixed_in_nss_3.25.1: + +`Bugs fixed in NSS 3.25.1 <#bugs_fixed_in_nss_3.25.1>`__ +-------------------------------------------------------- + +.. container:: + + - The following bug has been fixed in NSS 3.25.1: `Ignore MD5 signature algorithms in + certificate requests <https://bugzilla.mozilla.org/show_bug.cgi?id=1304407>`__ + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.25.1 shared libraries are backwards compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.25.1 shared libraries + without recompiling or relinking. Applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future versions of the NSS + shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.25_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.25_release_notes/index.rst new file mode 100644 index 0000000000..168f4a77fa --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.25_release_notes/index.rst @@ -0,0 +1,140 @@ +.. _mozilla_projects_nss_nss_3_25_release_notes: + +NSS 3.25 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.25, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_25_RTM. NSS 3.25 requires Netscape Portable Runtime(NSPR) 4.12 or newer. + + NSS 3.25 source distributions are available on ftp.mozilla.org for secure HTTPS download at the + following location. + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_25_RTM/src/ + +.. _new_in_nss_3.25: + +`New in NSS 3.25 <#new_in_nss_3.25>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Implemented DHE key agreement for TLS 1.3. + - Added support for ChaCha with TLS 1.3. + - Added support for TLS 1.2 ciphersuites that use SHA384 as the PRF. + - Removed the limitation that allowed NSS to only support certificate_verify messages that used + the same signature hash algorithm as the PRF when using TLS 1.2 client authentication. + - Several functions have been added to the public API of the NSS Cryptoki Framework. + + .. rubric:: New Functions + :name: new_functions + + - *in nssckfw.h* + + - **NSSCKFWSlot_GetSlotID** + - **NSSCKFWSession_GetFWSlot** + - **NSSCKFWInstance_DestroySessionHandle** + - **NSSCKFWInstance_FindSessionHandle** + +.. _notable_changes_in_nss_3.25: + +`Notable Changes in NSS 3.25 <#notable_changes_in_nss_3.25>`__ +-------------------------------------------------------------- + +.. container:: + + - An SSL socket can no longer be configured to allow both TLS 1.3 and SSL v3. + - Regression fix: NSS no longer reports a failure if an application attempts to disable the SSL + v2 protocol. + - The trusted CA certificate list has been updated to version 2.8. + - The following CA certificate was **Removed** + + - CN = Sonera Class1 CA + + - SHA-256 Fingerprint: + CD:80:82:84:CF:74:6F:F2:FD:6E:B5:8A:A1:D5:9C:4A:D4:B3:CA:56:FD:C6:27:4A:89:26:A7:83:5F:32:31:3D + + - The following CA certificates were **Added** + + - CN = Hellenic Academic and Research Institutions RootCA 2015 + + - SHA-256 Fingerprint: + A0:40:92:9A:02:CE:53:B4:AC:F4:F2:FF:C6:98:1C:E4:49:6F:75:5E:6D:45:FE:0B:2A:69:2B:CD:52:52:3F:36 + + - CN = Hellenic Academic and Research Institutions ECC RootCA 2015 + + - SHA-256 Fingerprint: + 44:B5:45:AA:8A:25:E6:5A:73:CA:15:DC:27:FC:36:D2:4C:1C:B9:95:3A:06:65:39:B1:15:82:DC:48:7B:48:33 + + - CN = Certplus Root CA G1 + + - SHA-256 Fingerprint: + 15:2A:40:2B:FC:DF:2C:D5:48:05:4D:22:75:B3:9C:7F:CA:3E:C0:97:80:78:B0:F0:EA:76:E5:61:A6:C7:43:3E + + - CN = Certplus Root CA G2 + + - SHA-256 Fingerprint: + 6C:C0:50:41:E6:44:5E:74:69:6C:4C:FB:C9:F8:0F:54:3B:7E:AB:BB:44:B4:CE:6F:78:7C:6A:99:71:C4:2F:17 + + - CN = OpenTrust Root CA G1 + + - SHA-256 Fingerprint: + 56:C7:71:28:D9:8C:18:D9:1B:4C:FD:FF:BC:25:EE:91:03:D4:75:8E:A2:AB:AD:82:6A:90:F3:45:7D:46:0E:B4 + + - CN = OpenTrust Root CA G2 + + - SHA-256 Fingerprint: + 27:99:58:29:FE:6A:75:15:C1:BF:E8:48:F9:C4:76:1D:B1:6C:22:59:29:25:7B:F4:0D:08:94:F2:9E:A8:BA:F2 + + - CN = OpenTrust Root CA G3 + + - SHA-256 Fingerprint: + B7:C3:62:31:70:6E:81:07:8C:36:7C:B8:96:19:8F:1E:32:08:DD:92:69:49:DD:8F:57:09:A4:10:F7:5B:62:92 + +.. _bugs_fixed_in_nss_3.25: + +`Bugs fixed in NSS 3.25 <#bugs_fixed_in_nss_3.25>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.25: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.25 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.25 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.25 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.26.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.26.2_release_notes/index.rst new file mode 100644 index 0000000000..e38e9f934b --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.26.2_release_notes/index.rst @@ -0,0 +1,80 @@ +.. _mozilla_projects_nss_nss_3_26_2_release_notes: + +NSS 3.26.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.26.2 is a patch release for NSS 3.26. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_26_2_RTM. NSS 3.26.2 requires NSPR 4.12 or newer. + + NSS 3.26.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_26_2_RTM/src/ + +.. _new_in_nss_3.26.2: + +`New in NSS 3.26.2 <#new_in_nss_3.26.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to address a TLS + compatibility issue that some client applications experienced with NSS 3.26.1. + +.. _notable_changes_in_nss_3.26.2: + +`Notable Changes in NSS 3.26.2 <#notable_changes_in_nss_3.26.2>`__ +------------------------------------------------------------------ + +.. container:: + + MD5 signature algorithms sent by the server in CertificateRequest messages are now properly + ignored. Previously, with rare server configurations, an MD5 signature algorithm might have been + selected for client authentication and caused the client to abort the connection soon after. + +.. _bugs_fixed_in_nss_3.26.2: + +`Bugs fixed in NSS 3.26.2 <#bugs_fixed_in_nss_3.26.2>`__ +-------------------------------------------------------- + +.. container:: + + - The following bug has been fixed in NSS 3.26.2: `Ignore MD5 signature algorithms in + certificate requests <https://bugzilla.mozilla.org/show_bug.cgi?id=1304407>`__ + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.26.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.26.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.26_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.26_release_notes/index.rst new file mode 100644 index 0000000000..fcc4e69b52 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.26_release_notes/index.rst @@ -0,0 +1,91 @@ +.. _mozilla_projects_nss_nss_3_26_release_notes: + +NSS 3.26 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.26, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_26_RTM. NSS 3.26 requires Netscape Portable Runtime(NSPR) 4.12 or newer. + + NSS 3.26 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_26_RTM/src/ + +.. _new_in_nss_3.26: + +`New in NSS 3.26 <#new_in_nss_3.26>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - the selfserv test utility has been enhanced to support ALPN (HTTP/1.1) and 0-RTT + - added support for the System-wide crypto policy available on Fedora Linux, see + http://fedoraproject.org/wiki/Changes/CryptoPolicy + - introduced build flag NSS_DISABLE_LIBPKIX which allows compilation of NSS without the libpkix + library + +.. _notable_changes_in_nss_3.26: + +`Notable Changes in NSS 3.26 <#notable_changes_in_nss_3.26>`__ +-------------------------------------------------------------- + +.. container:: + + - The following CA certificate was **Added** + + - CN = ISRG Root X1 + + - SHA-256 Fingerprint: + 96:BC:EC:06:26:49:76:F3:74:60:77:9A:CF:28:C5:A7:CF:E8:A3:C0:AA:E1:1A:8F:FC:EE:05:C0:BD:DF:08:C6 + + - NPN is disabled, and ALPN is enabled by default + - the NSS test suite now completes with the experimental TLS 1.3 code enabled + - several test improvements and additions, including a NIST known answer test + +.. _bugs_fixed_in_nss_3.26: + +`Bugs fixed in NSS 3.26 <#bugs_fixed_in_nss_3.26>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.26: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.26 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.26 shared libraries are backwards compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.26 shared libraries + without recompiling or relinking. Applications that restrict their use of NSS APIs, to the + functions listed in NSS Public Functions, will remain compatible with future versions of the NSS + shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.27.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.27.1_release_notes/index.rst new file mode 100644 index 0000000000..85a0365097 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.27.1_release_notes/index.rst @@ -0,0 +1,92 @@ +.. _mozilla_projects_nss_nss_3_27_1_release_notes: + +NSS 3.27.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.27.1 is a patch release for NSS 3.27. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_27_1_RTM. NSS 3.27.1 requires NSPR 4.13 or newer. + + NSS 3.27.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_27_1_RTM/src/ + +.. _new_in_nss_3.27.1: + +`New in NSS 3.27.1 <#new_in_nss_3.27.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to address a TLS + compatibility issue which some applications experienced with NSS 3.27. + +.. _notable_changes_in_nss_3.27.1: + +`Notable Changes in NSS 3.27.1 <#notable_changes_in_nss_3.27.1>`__ +------------------------------------------------------------------ + +.. container:: + + Availability of the TLS 1.3 (draft) implementation has been re-disabled in the default build. + + Previous versions of NSS made TLS 1.3 (draft) available only when compiled with + NSS_ENABLE_TLS_1_3. NSS 3.27 set this value on by default, allowing TLS 1.3 (draft) to be + disabled using NSS_DISABLE_TLS_1_3, although the maximum version used by default remained TLS + 1.2. + + However, some applications query the list of protocol versions that are supported by the NSS + library, enabling all supported TLS protocol versions. Because NSS 3.27 enabled compilation of + TLS 1.3 (draft) by default, it caused those applications to enable TLS 1.3 (draft). This resulted + in connectivity failures, as some TLS servers are version 1.3 intolerant, and failed to negotiate + an earlier TLS version with NSS 3.27 clients. + + NSS 3.27.1 once again requires NSS_ENABLE_TLS_1_3 to be deliberately set to enable TLS 1.3 + (draft). + +.. _bugs_fixed_in_nss_3.27.1: + +`Bugs fixed in NSS 3.27.1 <#bugs_fixed_in_nss_3.27.1>`__ +-------------------------------------------------------- + +.. container:: + + - The following bug has been fixed in NSS 3.27.1: `Re-disable TLS 1.3 by + default <https://bugzilla.mozilla.org/show_bug.cgi?id=1306985>`__ + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.27.1 shared libraries are backwards compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.27.1 shared libraries + without recompiling or relinking. Applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future versions of the NSS + shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.27.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.27.2_release_notes/index.rst new file mode 100644 index 0000000000..b12805848d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.27.2_release_notes/index.rst @@ -0,0 +1,84 @@ +.. _mozilla_projects_nss_nss_3_27_2_release_notes: + +NSS 3.27.2 Release Notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.27.2 is a patch release for NSS 3.27. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_27_2_RTM. NSS 3.27.2 requires NSPR 4.13 or newer. + + NSS 3.27.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + `https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_27_2_RTM/src/ <https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_27_1_RTM/src/>`__ + +.. _new_in_nss_3.27.2: + +`New in NSS 3.27.2 <#new_in_nss_3.27.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to address a memory + leak in the ``SSL_SetTrustAnchors()`` function. + +.. _notable_changes_in_nss_3.27.2: + +`Notable Changes in NSS 3.27.2 <#notable_changes_in_nss_3.27.2>`__ +------------------------------------------------------------------ + +.. container:: + + The ``SSL_SetTrustAnchors()`` function is used to set the distinguished names that an NSS server + includes in its TLS CertificateRequest message. If this function is not used, NSS will include + the distinguished names for all trust anchors installed in the database. This can be a lengthy + list. + + Previous versions of NSS leaked the memory used to store distinguished names when + ``SSL_SetTrustAnchors()`` was used. This release fixes that error. + +.. _bugs_fixed_in_nss_3.27.2: + +`Bugs fixed in NSS 3.27.2 <#bugs_fixed_in_nss_3.27.2>`__ +-------------------------------------------------------- + +.. container:: + + - The following bug has been fixed in NSS 3.27.2: `Bug 1318561 - SSL_SetTrustAnchors + leaks <https://bugzilla.mozilla.org/show_bug.cgi?id=1318561>`__ + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.27.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.27.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.27_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.27_release_notes/index.rst new file mode 100644 index 0000000000..d3677068b3 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.27_release_notes/index.rst @@ -0,0 +1,149 @@ +.. _mozilla_projects_nss_nss_3_27_release_notes: + +NSS 3.27 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.27, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_27_RTM. NSS 3.27 requires Netscape Portable Runtime(NSPR) 4.13 or newer. + + NSS 3.27 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_27_RTM/src/ + +.. _new_in_nss_3.27: + +`New in NSS 3.27 <#new_in_nss_3.27>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Allow custom named group priorities for TLS key exchange handshake (SSL_NamedGroupConfig). + - Added support for RSA-PSS signatures in TLS 1.2 and TLS 1.3 + + .. rubric:: New Functions + :name: new_functions + + - in ssl.h + + - SSL_NamedGroupConfig + +.. _notable_changes_in_nss_3.27: + +`Notable Changes in NSS 3.27 <#notable_changes_in_nss_3.27>`__ +-------------------------------------------------------------- + +.. container:: + + - *UPDATE 2016-10-02:* + + - The maximum TLS version supported has been increased to TLS 1.3 (draft). + - Although the maximum TLS version enabled by default is still TLS 1.2, there are + applications that query the list of TLS protocol versions supported by NSS, and enable all + supported versions. For those applications, updating to NSS 3.27 may result in TLS 1.3 + (draft) to be enabled. + - The TLS 1.3 (draft) protocol can be disabled, by defining symbol NSS_DISABLE_TLS_1_3 when + building NSS. + + - NPN can not be enabled anymore. + - Hard limits on the maximum number of TLS records encrypted with the same key are enforced. + - Disabled renegotiation in DTLS. + - The following CA certificates were **Removed** + + - CN = IGC/A, O = PM/SGDN, OU = DCSSI + + - SHA256 Fingerprint: + B9:BE:A7:86:0A:96:2E:A3:61:1D:AB:97:AB:6D:A3:E2:1C:10:68:B9:7D:55:57:5E:D0:E1:12:79:C1:1C:89:32 + + - CN = Juur-SK, O = AS Sertifitseerimiskeskus + + - SHA256 Fingerprint: + EC:C3:E9:C3:40:75:03:BE:E0:91:AA:95:2F:41:34:8F:F8:8B:AA:86:3B:22:64:BE:FA:C8:07:90:15:74:E9:39 + + - CN = EBG Elektronik Sertifika Hizmet Sağlayıcısı + + - SHA-256 Fingerprint: + 35:AE:5B:DD:D8:F7:AE:63:5C:FF:BA:56:82:A8:F0:0B:95:F4:84:62:C7:10:8E:E9:A0:E5:29:2B:07:4A:AF:B2 + + - CN = S-TRUST Authentication and Encryption Root CA 2005:PN + + - SHA-256 Fingerprint: + 37:D8:DC:8A:F7:86:78:45:DA:33:44:A6:B1:BA:DE:44:8D:8A:80:E4:7B:55:79:F9:6B:F6:31:76:8F:9F:30:F6 + + - O = VeriSign, Inc., OU = Class 1 Public Primary Certification Authority + + - SHA-256 Fingerprint: + 51:84:7C:8C:BD:2E:9A:72:C9:1E:29:2D:2A:E2:47:D7:DE:1E:3F:D2:70:54:7A:20:EF:7D:61:0F:38:B8:84:2C + + - O = VeriSign, Inc., OU = Class 2 Public Primary Certification Authority - G2 + + - SHA-256 Fingerprint: + 3A:43:E2:20:FE:7F:3E:A9:65:3D:1E:21:74:2E:AC:2B:75:C2:0F:D8:98:03:05:BC:50:2C:AF:8C:2D:9B:41:A1 + + - O = VeriSign, Inc., OU = Class 3 Public Primary Certification Authority + + - SHA-256 Fingerprint: + E7:68:56:34:EF:AC:F6:9A:CE:93:9A:6B:25:5B:7B:4F:AB:EF:42:93:5B:50:A2:65:AC:B5:CB:60:27:E4:4E:70 + + - O = Equifax, OU = Equifax Secure Certificate Authority + + - SHA-256 Fingerprint: + 08:29:7A:40:47:DB:A2:36:80:C7:31:DB:6E:31:76:53:CA:78:48:E1:BE:BD:3A:0B:01:79:A7:07:F9:2C:F1:78 + + - CN = Equifax Secure eBusiness CA-1 + + - SHA-256 Fingerprint: + CF:56:FF:46:A4:A1:86:10:9D:D9:65:84:B5:EE:B5:8A:51:0C:42:75:B0:E5:F9:4F:40:BB:AE:86:5E:19:F6:73 + + - CN = Equifax Secure Global eBusiness CA-1 + + - SHA-256 Fingerprint: + 5F:0B:62:EA:B5:E3:53:EA:65:21:65:16:58:FB:B6:53:59:F4:43:28:0A:4A:FB:D1:04:D7:7D:10:F9:F0:4C:07 + +.. _bugs_fixed_in_nss_3.27: + +`Bugs fixed in NSS 3.27 <#bugs_fixed_in_nss_3.27>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.27: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.27 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.27 shared libraries are backwards compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.27 shared libraries + without recompiling or relinking. Applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future versions of the NSS + shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.28.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.1_release_notes/index.rst new file mode 100644 index 0000000000..b3cd04e8ac --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.1_release_notes/index.rst @@ -0,0 +1,148 @@ +.. _mozilla_projects_nss_nss_3_28_1_release_notes: + +NSS 3.28.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.28.1 is a patch release for NSS 3.28. The bug fixes in NSS + 3.28.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_28_1_RTM. NSS 3.28.1 requires NSPR 4.13.1 or newer. + + NSS 3.28.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_28_1_RTM/src/ + +.. _new_in_nss_3.28.1: + +`New in NSS 3.28.1 <#new_in_nss_3.28.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to update the list of + root CA certificates, and address a minor TLS compatibility issue, that some applications + experienced with NSS 3.28. + +.. _notable_changes_in_nss_3.28.1: + +`Notable Changes in NSS 3.28.1 <#notable_changes_in_nss_3.28.1>`__ +------------------------------------------------------------------ + +.. container:: + + - The following CA certificates were **Removed** + + - CN = Buypass Class 2 CA 1 + + - SHA-256 Fingerprint: + 0F:4E:9C:DD:26:4B:02:55:50:D1:70:80:63:40:21:4F:E9:44:34:C9:B0:2F:69:7E:C7:10:FC:5F:EA:FB:5E:38 + + - CN = Root CA Generalitat Valenciana + + - SHA-256 Fingerprint: + 8C:4E:DF:D0:43:48:F3:22:96:9E:7E:29:A4:CD:4D:CA:00:46:55:06:1C:16:E1:B0:76:42:2E:F3:42:AD:63:0E + + - OU = RSA Security 2048 V3 + + - SHA-256 Fingerprint: + AF:8B:67:62:A1:E5:28:22:81:61:A9:5D:5C:55:9E:E2:66:27:8F:75:D7:9E:83:01:89:A5:03:50:6A:BD:6B:4C + + - The following CA certificates were **Added** + + - OU = AC RAIZ FNMT-RCM + + - SHA-256 Fingerprint: + EB:C5:57:0C:29:01:8C:4D:67:B1:AA:12:7B:AF:12:F7:03:B4:61:1E:BC:17:B7:DA:B5:57:38:94:17:9B:93:FA + + - CN = Amazon Root CA 1 + + - SHA-256 Fingerprint: + 8E:CD:E6:88:4F:3D:87:B1:12:5B:A3:1A:C3:FC:B1:3D:70:16:DE:7F:57:CC:90:4F:E1:CB:97:C6:AE:98:19:6E + + - CN = Amazon Root CA 2 + + - SHA-256 Fingerprint: + 1B:A5:B2:AA:8C:65:40:1A:82:96:01:18:F8:0B:EC:4F:62:30:4D:83:CE:C4:71:3A:19:C3:9C:01:1E:A4:6D:B4 + + - CN = Amazon Root CA 3 + + - SHA-256 Fingerprint: + 18:CE:6C:FE:7B:F1:4E:60:B2:E3:47:B8:DF:E8:68:CB:31:D0:2E:BB:3A:DA:27:15:69:F5:03:43:B4:6D:B3:A4 + + - CN = Amazon Root CA 4 + + - SHA-256 Fingerprint: + E3:5D:28:41:9E:D0:20:25:CF:A6:90:38:CD:62:39:62:45:8D:A5:C6:95:FB:DE:A3:C2:2B:0B:FB:25:89:70:92 + + - CN = LuxTrust Global Root 2 + + - SHA-256 Fingerprint: + 54:45:5F:71:29:C2:0B:14:47:C4:18:F9:97:16:8F:24:C5:8F:C5:02:3B:F5:DA:5B:E2:EB:6E:1D:D8:90:2E:D5 + + - CN = Symantec Class 1 Public Primary Certification Authority - G4 + + - SHA-256 Fingerprint: + 36:3F:3C:84:9E:AB:03:B0:A2:A0:F6:36:D7:B8:6D:04:D3:AC:7F:CF:E2:6A:0A:91:21:AB:97:95:F6:E1:76:DF + + - CN = Symantec Class 1 Public Primary Certification Authority - G6 + + - SHA-256 Fingerprint: + 9D:19:0B:2E:31:45:66:68:5B:E8:A8:89:E2:7A:A8:C7:D7:AE:1D:8A:AD:DB:A3:C1:EC:F9:D2:48:63:CD:34:B9 + + - CN = Symantec Class 2 Public Primary Certification Authority - G4 + + - SHA-256 Fingerprint: + FE:86:3D:08:22:FE:7A:23:53:FA:48:4D:59:24:E8:75:65:6D:3D:C9:FB:58:77:1F:6F:61:6F:9D:57:1B:C5:92 + + - CN = Symantec Class 2 Public Primary Certification Authority - G6 + + - SHA-256 Fingerprint: + CB:62:7D:18:B5:8A:D5:6D:DE:33:1A:30:45:6B:C6:5C:60:1A:4E:9B:18:DE:DC:EA:08:E7:DA:AA:07:81:5F:F0 + + - The version number of the updated root CA list has been set to 2.11 + - A misleading assertion/alert has been removed, when NSS tries to flush data to the peer but + the connection was already reset. + +.. _bugs_fixed_in_nss_3.28.1: + +`Bugs fixed in NSS 3.28.1 <#bugs_fixed_in_nss_3.28.1>`__ +-------------------------------------------------------- + +.. container:: + + | `Bug 1296697 - December 2016 batch of root CA + changes <https://bugzilla.mozilla.org/show_bug.cgi?id=1296697>`__ + | `Bug 1322496 - Internal error assert when the other side closes connection before reading + EOED <https://bugzilla.mozilla.org/show_bug.cgi?id=1322496>`__ + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.28.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.28.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.28.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.2_release_notes/index.rst new file mode 100644 index 0000000000..b22eab0dc0 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.2_release_notes/index.rst @@ -0,0 +1,79 @@ +.. _mozilla_projects_nss_nss_3_28_2_release_notes: + +NSS 3.28.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.28.2 is a patch release for NSS 3.28. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_28_2_RTM. NSS 3.28.2 requires NSPR 4.13.1 or newer. + + NSS 3.28.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_28_2_RTM/src/ + +.. _incorrect_version_number: + +`Incorrect version number <#incorrect_version_number>`__ +-------------------------------------------------------- + +.. container:: + + - Note the version numbers embedded in the NSS 3.28.2 are wrong (it reports itself as version + 3.28.1). + +.. _new_in_nss_3.28.2: + +`New in NSS 3.28.2 <#new_in_nss_3.28.2>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. This is a patch release includes bug fixes + and addresses some compatibility issues with TLS. + +.. _bugs_fixed_in_nss_3.28.2: + +`Bugs fixed in NSS 3.28.2 <#bugs_fixed_in_nss_3.28.2>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1334114 - NSS 3.28 regression in signature scheme flexibility, causes connectivity issue + between iOS 8 clients and NSS servers with ECDSA + certificates <https://bugzilla.mozilla.org/show_bug.cgi?id=1334114>`__ + - `Bug 1330612 - X25519 is the default curve for ECDHE in + NSS <https://bugzilla.mozilla.org/show_bug.cgi?id=1330612>`__ + - `Bug 1323150 - Crash [@ ReadDBEntry + ] <https://bugzilla.mozilla.org/show_bug.cgi?id=1323150>`__ + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.28.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.28.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.28.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.3_release_notes/index.rst new file mode 100644 index 0000000000..fee81fd010 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.3_release_notes/index.rst @@ -0,0 +1,95 @@ +.. _mozilla_projects_nss_nss_3_28_3_release_notes: + +NSS 3.28.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.28.3 is a patch release for NSS 3.28. The bug fixes in NSS + 3.28.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_28_3_RTM. NSS 3.28.3 requires Netscape Portable Runtime(NSPR) 4.13.1 or + newer. + + NSS 3.28.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_28_3_RTM/src/ + +.. _new_in_nss_3.28.3: + +`New in NSS 3.28.3 <#new_in_nss_3.28.3>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix binary + compatibility issues. + +.. _bugs_fixed_in_nss_3.28.3: + +`Bugs fixed in NSS 3.28.3 <#bugs_fixed_in_nss_3.28.3>`__ +-------------------------------------------------------- + +.. container:: + + NSS version 3.28, 3.28.1 and 3.28.2 contained changes that were in violation with the NSS + compatibility promise. + + ECParams, which is part of the public API of the freebl/softokn parts of NSS, had been changed to + include an additional attribute. That size increase caused crashes or malfunctioning with + applications that use that data structure directly, or indirectly through ECPublicKey, + ECPrivateKey, NSSLOWKEYPublicKey, NSSLOWKEYPrivateKey, or potentially other data structures that + reference ECParams. The change has been reverted to the original state in `bug + 1334108 <https://bugzilla.mozilla.org/show_bug.cgi?id=1334108>`__. + + SECKEYECPublicKey had been extended with a new attribute, named "encoding". If an application + passed type SECKEYECPublicKey to NSS (as part of SECKEYPublicKey), the NSS library read the + uninitialized attribute. With this NSS release SECKEYECPublicKey.encoding is deprecated. NSS no + longer reads the attribute, and will always set it to ECPoint_Undefined. See `bug + 1340103 <https://bugzilla.mozilla.org/show_bug.cgi?id=1340103>`__. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.28.3 shared libraries are backward compatible with most older NSS 3.x shared libraries, but + depending on your application, may be incompatible, if you application has been compiled against + header files of versions 3.28, 3.28.1, or 3.28.2. + + A program linked with most older NSS 3.x shared libraries (excluding the exceptions mentioned + above), will work with NSS 3.28.3 shared libraries without recompiling or relinking. Furthermore, + applications that restrict their use of NSS APIs to the functions listed in NSS Public Functions + will remain compatible with future versions of the NSS shared libraries. + + If you had compiled your application against header files of NSS 3.28, NSS 3.28.1 or NSS 3.28.2, + it is recommended that you recompile your application against NSS 3.28.3, at the time you upgrade + to NSS 3.28.3. + + Please note that NSS 3.29 also contained the incorrect change. You should avoid using NSS 3.29, + and rather use NSS 3.29.1 or a newer version. See also the + :ref:`mozilla_projects_nss_nss_3_29_1_release_notes` + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.28.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.4_release_notes/index.rst new file mode 100644 index 0000000000..f3a58535ec --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.4_release_notes/index.rst @@ -0,0 +1,77 @@ +.. _mozilla_projects_nss_nss_3_28_4_release_notes: + +NSS 3.28.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.28.4 is a security patch release for NSS 3.28. The bug fixes in + NSS 3.28.4 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_28_4_RTM. NSS 3.28.4 requires NSPR 4.13.1 or newer. + + NSS 3.28.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_28_4_RTM/src/ + +.. _new_in_nss_3.28.4: + +`New in NSS 3.28.4 <#new_in_nss_3.28.4>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.28.4: + +`Bugs fixed in NSS 3.28.4 <#bugs_fixed_in_nss_3.28.4>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1344380 <https://bugzilla.mozilla.org/show_bug.cgi?id=1344380>`__ / Out-of-bounds write + in Base64 encoding in NSS + (`CVE-2017-5461 <https://www.mozilla.org/en-US/security/advisories/mfsa2017-10/#CVE-2017-5461>`__) + - `Bug 1345089 <https://bugzilla.mozilla.org/show_bug.cgi?id=1345089>`__ / DRBG flaw in NSS + (`CVE-2017-5462 <https://www.mozilla.org/en-US/security/advisories/mfsa2017-10/#CVE-2017-5462>`__) + - `Bug 1342358 - Crash in + tls13_DestroyKeyShares <https://bugzilla.mozilla.org/show_bug.cgi?id=1342358>`__ + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Ronald Crane and Vladimir Klebanov for responsibly + disclosing the issues by providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.28.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.28.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.28.5_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.5_release_notes/index.rst new file mode 100644 index 0000000000..6db7c169d7 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.28.5_release_notes/index.rst @@ -0,0 +1,116 @@ +.. _mozilla_projects_nss_nss_3_28_5_release_notes: + +NSS 3.28.5 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.28.5 is a patch release for NSS 3.28. The bug fixes in NSS + 3.28.5 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_28_5_RTM. NSS 3.28.5 requires NSPR 4.13.1 or newer. + + NSS 3.28.5 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_28_5_RTM/src/ + +.. _new_in_nss_3.28.5: + +`New in NSS 3.28.5 <#new_in_nss_3.28.5>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to update the list of + root CA certificates. It backports the changes that were initially released in + :ref:`mozilla_projects_nss_nss_3_30_2_release_notes`. + +.. _notable_changes_in_nss_3.28.5: + +`Notable Changes in NSS 3.28.5 <#notable_changes_in_nss_3.28.5>`__ +------------------------------------------------------------------ + +.. container:: + + - The following CA certificates were **Removed:** + + - O = Japanese Government, OU = ApplicationCA + + - SHA-256 Fingerprint: + 2D:47:43:7D:E1:79:51:21:5A:12:F3:C5:8E:51:C7:29:A5:80:26:EF:1F:CC:0A:5F:B3:D9:DC:01:2F:60:0D:19 + + - CN = WellsSecure Public Root Certificate Authority + + - SHA-256 Fingerprint: + A7:12:72:AE:AA:A3:CF:E8:72:7F:7F:B3:9F:0F:B3:D1:E5:42:6E:90:60:B0:6E:E6:F1:3E:9A:3C:58:33:CD:43 + + - CN=TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H6 + + - SHA-256 Fingerprint: + 8D:E7:86:55:E1:BE:7F:78:47:80:0B:93:F6:94:D2:1D:36:8C:C0:6E:03:3E:7F:AB:04:BB:5E:B9:9D:A6:B7:00 + + - CN=Microsec e-Szigno Root + + - SHA-256 Fingerprint: + 32:7A:3D:76:1A:BA:DE:A0:34:EB:99:84:06:27:5C:B1:A4:77:6E:FD:AE:2F:DF:6D:01:68:EA:1C:4F:55:67:D0 + + - The following CA certificates were **Added:** + + - CN = D-TRUST Root CA 3 2013 + + - SHA-256 Fingerprint: + A1:A8:6D:04:12:1E:B8:7F:02:7C:66:F5:33:03:C2:8E:57:39:F9:43:FC:84:B3:8A:D6:AF:00:90:35:DD:94:57 + - Trust Flags: Email + + - CN = TUBITAK Kamu SM SSL Kok Sertifikasi - Surum 1 + + - SHA-256 Fingerprint: + 46:ED:C3:68:90:46:D5:3A:45:3F:B3:10:4A:B8:0D:CA:EC:65:8B:26:60:EA:16:29:DD:7E:86:79:90:64:87:16 + - Trust Flags: Websites + - Technically constrained to: gov.tr, k12.tr, pol.tr, mil.tr, tsk.tr, kep.tr, bel.tr, + edu.tr, org.tr + + - The version number of the updated root CA list has been set to 2.14. + (The version numbers 2.12 and 2.13 for the root CA list have been skipped.) + +.. _bugs_fixed_in_nss_3.28.5: + +`Bugs fixed in NSS 3.28.5 <#bugs_fixed_in_nss_3.28.5>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1350859 <https://bugzilla.mozilla.org/show_bug.cgi?id=1350859>`__ - March 2017 batch of + root CA changes. + - `Bug 1349705 <https://bugzilla.mozilla.org/show_bug.cgi?id=1349705>`__ - Implemented domain + name constraints for CA: TUBITAK Kamu SM SSL Kok Sertifikasi - Surum 1. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.28.5 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.28.5 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.28_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.28_release_notes/index.rst new file mode 100644 index 0000000000..b1eb165d07 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.28_release_notes/index.rst @@ -0,0 +1,170 @@ +.. _mozilla_projects_nss_nss_3_28_release_notes: + +NSS 3.28 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.28, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_28_RTM. NSS 3.28 requires Netscape Portable Runtime(NSPR) 4.13.1 or newer. + + NSS 3.28 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_28_RTM/src/ + +.. _new_in_nss_3.28: + +`New in NSS 3.28 <#new_in_nss_3.28>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS includes support for `TLS 1.3 draft + -18 <https://datatracker.ietf.org/doc/html/draft-ietf-tls-tls13-18>`__. This includes a + number of improvements to TLS 1.3: + + - The signed certificate timestamp, used in certificate transparency, is supported in TLS 1.3 + (`bug 1252745 <https://bugzilla.mozilla.org/show_bug.cgi?id=1252745>`__). + - Key exporters for TLS 1.3 are supported (`bug + 1310610 <https://bugzilla.mozilla.org/show_bug.cgi?id=1310610>`__). This includes the + early key exporter, which can be used if 0-RTT is enabled. Note that there is a difference + between TLS 1.3 and key exporters in older versions of TLS. TLS 1.3 does not distinguish + between an empty context and no context. + - The TLS 1.3 (draft) protocol can be enabled, by defining NSS_ENABLE_TLS_1_3=1 when building + NSS. + + - NSS includes support for `the X25519 key exchange + algorithm <https://datatracker.ietf.org/doc/html/rfc7748>`__ (`bug + 957105 <https://bugzilla.mozilla.org/show_bug.cgi?id=957105>`__), which is supported and + enabled by default in all versions of TLS. + + .. rubric:: New Functions + :name: new_functions + + - in ssl.h + + - **SSL_ExportEarlyKeyingMaterial** implements a key exporter based on the TLS 1.3 early + exporter secret. This API is equivalent in function to SSL_ExportKeyingMaterial, but it + can only succeed if 0-RTT was attempted (on the client) or accepted (on the server). + + - **SSL_SendAdditionalKeyShares** configures a TLS 1.3 client so that it generates additional + key shares when sending a ClientHello. + + - **SSL_SignatureSchemePrefSet** allows an application to set which signature schemes should + be supported in TLS and to specify the preference order of those schemes. + + - **SSL_SignatureSchemePrefGet** allows an application to learn the currently supported and + enabled signature schemes for a socket. + +.. _request_to_test_and_prepare_for_tls_1.3: + +`Request to test and prepare for TLS 1.3 <#request_to_test_and_prepare_for_tls_1.3>`__ +-------------------------------------------------------------------------------------- + +.. container:: + + This release contains improved support for TLS 1.3, however, the code that supports TLS 1.3 is + still disabled by default (not built). + + For the future NSS 3.29 release, it is planned that standard builds of NSS will support the TLS + 1.3 protocol (although the maximum TLS protocol version enabled by default will remain at TLS + 1.2). + + We know that some applications which use NSS, query NSS for the supported range of SSL/TLS + protocols, and will enable the maximum enabled protocol version. In NSS 3.29, those applications + will therefore enable support for the TLS 1.3 protocol. + + In order to prepare for this future change, we'd like to encourage all users of NSS to override + the standard NSS 3.28 build configuration, by defining NSS_ENABLE_TLS_1_3=1 at build time. This + will enable support for TLS 1.3. Please give feedback to the NSS developers for any compatibility + issues that you encounter in your tests. + +.. _notable_changes_in_nss_3.28: + +`Notable Changes in NSS 3.28 <#notable_changes_in_nss_3.28>`__ +-------------------------------------------------------------- + +.. container:: + + - NSS can no longer be compiled with support for additional elliptic curves (the + NSS_ECC_MORE_THAN_SUITE_B option, `bug + 1253912 <https://bugzilla.mozilla.org/show_bug.cgi?id=1253912>`__). This was previously + possible by replacing certain NSS source files. + - NSS will now detect the presence of tokens that support additional elliptic curves and enable + those curves for use in TLS (`bug + 1303648 <https://bugzilla.mozilla.org/show_bug.cgi?id=1303648>`__). Note that this detection + has a one-off performance cost, which can be avoided by using the SSL_NamedGroupConfig + function, to limit supported groups to those that NSS provides. + - PKCS#11 bypass for TLS is no longer supported and has been removed (`bug + 1303224 <https://bugzilla.mozilla.org/show_bug.cgi?id=1303224>`__). + - Support for "export" grade SSL/TLS cipher suites has been removed (`bug + 1252849 <https://bugzilla.mozilla.org/show_bug.cgi?id=1252849>`__). + - NSS now uses the signature schemes definition in TLS 1.3 (`bug + 1309446 <https://bugzilla.mozilla.org/show_bug.cgi?id=1309446>`__). This also affects TLS + 1.2. NSS will now only generate signatures with the combinations of hash and signature scheme + that are defined in TLS 1.3, even when negotiating TLS 1.2. + + - This means that SHA-256 will only be used with P-256 ECDSA certificates, SHA-384 with P-384 + certificates, and SHA-512 with P-521 certificates. SHA-1 is permitted (in TLS 1.2 only) + with any certificate for backward compatibility reasons. + - New functions to configure signature schemes are provided: **SSL_SignatureSchemePrefSet, + SSL_SignatureSchemePrefGet**. The old SSL_SignaturePrefSet and SSL_SignaturePrefSet + functions are now deprecated. + - NSS will now no longer assume that default signature schemes are supported by a peer if + there was no commonly supported signature scheme. + + - NSS will now check if RSA-PSS signing is supported by the token that holds the private key + prior to using it for TLS (`bug + 1311950 <https://bugzilla.mozilla.org/show_bug.cgi?id=1311950>`__). + - The certificate validation code contains checks to no longer trust certificates that are + issued by old WoSign and StartCom CAs, after October 21, 2016. This is equivalent to the + behavior that Mozilla will release with Firefox 51. Background information can be found in + `Mozilla's blog + post <https://blog.mozilla.org/security/2016/10/24/distrusting-new-wosign-and-startcom-certificates/>`__. + +.. _bugs_fixed_in_nss_3.28: + +`Bugs fixed in NSS 3.28 <#bugs_fixed_in_nss_3.28>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.28: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.28 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.28 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.28 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.29.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.1_release_notes/index.rst new file mode 100644 index 0000000000..2f8696341d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.1_release_notes/index.rst @@ -0,0 +1,94 @@ +.. _mozilla_projects_nss_nss_3_29_1_release_notes: + +NSS 3.29.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.29.1 is a patch release for NSS 3.29. The bug fixes in NSS + 3.29.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_29_1_RTM. NSS 3.29.1 requires Netscape Portable Runtime(NSPR) 4.13.1 or + newer. + + NSS 3.29.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_29_1_RTM/src/ + +.. _new_in_nss_3.29.1: + +`New in NSS 3.29.1 <#new_in_nss_3.29.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix binary + compatibility issues. + +.. _bugs_fixed_in_nss_3.29.1: + +`Bugs fixed in NSS 3.29.1 <#bugs_fixed_in_nss_3.29.1>`__ +-------------------------------------------------------- + +.. container:: + + NSS version 3.28, 3.28.1, 3.28.2 and 3.29 contained changes that were in violation with the NSS + compatibility promise. + + ECParams, which is part of the public API of the freebl/softokn parts of NSS, had been changed to + include an additional attribute. That size increase caused crashes or malfunctioning with + applications that use that data structure directly, or indirectly through ECPublicKey, + ECPrivateKey, NSSLOWKEYPublicKey, NSSLOWKEYPrivateKey, or potentially other data structures that + reference ECParams. The change has been reverted to the original state in `bug + 1334108 <https://bugzilla.mozilla.org/show_bug.cgi?id=1334108>`__. + + SECKEYECPublicKey had been extended with a new attribute, named "encoding". If an application + passed type SECKEYECPublicKey to NSS (as part of SECKEYPublicKey), the NSS library read the + uninitialized attribute. With this NSS release SECKEYECPublicKey.encoding is deprecated. NSS no + longer reads the attribute, and will always set it to ECPoint_Undefined. See `bug + 1340103 <https://bugzilla.mozilla.org/show_bug.cgi?id=1340103>`__. + + Note that NSS 3.28.3 from the older NSS 3.28.x branch + :ref:`mozilla_projects_nss_nss_3_28_3_release_notes` with the identical fixes. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.29.1 shared libraries are backward compatible with most older NSS 3.x shared libraries, but + depending on your application, may be incompatible, if you application has been compiled against + header files of versions 3.28, 3.28.1, 3.28.2 NSS 3.29.1. + + A program linked with most older NSS 3.x shared libraries (excluding the exceptions mentioned + above), will work with NSS 3.29.1 shared libraries without recompiling or relinking. Furthermore, + applications that restrict their use of NSS APIs to the functions listed in NSS Public Functions + will remain compatible with future versions of the NSS shared libraries. + + If you had compiled your application against header files of NSS 3.28, NSS 3.28.1, NSS 3.28.2 or + NSS 3.29, it is recommended that you recompile your application against NSS 3.29.1 (or NSS + 3.28.3), at the time you upgrade to NSS 3.29.1 (or NSS 3.28.3). + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.29.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.2_release_notes/index.rst new file mode 100644 index 0000000000..c165b2d005 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.2_release_notes/index.rst @@ -0,0 +1,71 @@ +.. _mozilla_projects_nss_nss_3_29_2_release_notes: + +NSS 3.29.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.29.2 is a patch release for NSS 3.29. The bug fixes in NSS + 3.29.2 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_29_2_RTM. NSS 3.29.2 requires Netscape Portable Runtime(NSPR) 4.13.1 or + newer. + + NSS 3.29.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_29_2_RTM/src/ + +.. _new_in_nss_3.29.2: + +`New in NSS 3.29.2 <#new_in_nss_3.29.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.29.2: + +`Bugs fixed in NSS 3.29.2 <#bugs_fixed_in_nss_3.29.2>`__ +-------------------------------------------------------- + +.. container:: + + NSS 3.29 and 3.29.1 included a change that reduced the time that NSS considered a TLS session + ticket to be valid. This release restores the session ticket lifetime to the intended value. See + `Bug 1340841 <https://bugzilla.mozilla.org/show_bug.cgi?id=1340841>`__ for details. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.29.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.29.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.29.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.3_release_notes/index.rst new file mode 100644 index 0000000000..c51632d4b9 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.3_release_notes/index.rst @@ -0,0 +1,73 @@ +.. _mozilla_projects_nss_nss_3_29_3_release_notes: + +NSS 3.29.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.29.3 is a patch release for NSS 3.29. The bug fixes in NSS + 3.29.3 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_29_3_RTM. NSS 3.29.3 requires NSPR 4.13.1 or newer. + + NSS 3.29.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_29_3_RTM/src/ + +.. _new_in_nss_3.29.3: + +`New in NSS 3.29.3 <#new_in_nss_3.29.3>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _notable_changes_in_nss_3.29.3: + +`Notable Changes in NSS 3.29.3 <#notable_changes_in_nss_3.29.3>`__ +------------------------------------------------------------------ + +.. container:: + + - A rare crash when initializing an SSL socket fails has been fixed. + +.. _bugs_fixed_in_nss_3.29.3: + +`Bugs fixed in NSS 3.29.3 <#bugs_fixed_in_nss_3.29.3>`__ +-------------------------------------------------------- + +.. container:: + + `Bug 1342358 - Crash in + tls13_DestroyKeyShares <https://bugzilla.mozilla.org/show_bug.cgi?id=1342358>`__ + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.29.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.29.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.29.5_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.5_release_notes/index.rst new file mode 100644 index 0000000000..2da8baebd1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.29.5_release_notes/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_nss_3_29_5_release_notes: + +NSS 3.29.5 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.29.5 is a security patch release for NSS 3.29. The bug fixes in + NSS 3.29.5 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_29_5_RTM. NSS 3.29.5 requires NSPR 4.13.1 or newer. + + NSS 3.29.5 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_29_5_RTM/src/ + +.. _new_in_nss_3.29.5: + +`New in NSS 3.29.5 <#new_in_nss_3.29.5>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.29.5: + +`Bugs fixed in NSS 3.29.5 <#bugs_fixed_in_nss_3.29.5>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1344380 <https://bugzilla.mozilla.org/show_bug.cgi?id=1344380>`__ / Out-of-bounds write + in Base64 encoding in NSS + (`CVE-2017-5461 <https://www.mozilla.org/en-US/security/advisories/mfsa2017-10/#CVE-2017-5461>`__) + - `Bug 1345089 <https://bugzilla.mozilla.org/show_bug.cgi?id=1345089>`__ / DRBG flaw in NSS + (`CVE-2017-5462 <https://www.mozilla.org/en-US/security/advisories/mfsa2017-10/#CVE-2017-5462>`__) + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Ronald Crane and Vladimir Klebanov for responsibly + disclosing the issues by providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.29.5 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.29.5 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.29_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.29_release_notes/index.rst new file mode 100644 index 0000000000..79b4235d4f --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.29_release_notes/index.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_nss_3_29_release_notes: + +NSS 3.29 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.29, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_29_RTM. NSS 3.29 requires Netscape Portable Runtime(NSPR) 4.13.1 or newer. + + NSS 3.29 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_29_RTM/src/ + +.. _notable_changes_in_nss_3.29: + +`Notable Changes in NSS 3.29 <#notable_changes_in_nss_3.29>`__ +-------------------------------------------------------------- + +.. container:: + + - Fixed a NSS 3.28 regression in the signature scheme flexibility that causes connectivity + issues between iOS 8 clients and NSS servers with ECDSA certificates + (`bug1334114 <https://bugzilla.mozilla.org/show_bug.cgi?id=1334114>`__). + - TLS 1.3 is now enabled by default in + (`bug1311296 <https://bugzilla.mozilla.org/show_bug.cgi?id=1311296>`__). + +.. _bugs_fixed_in_nss_3.29: + +`Bugs fixed in NSS 3.29 <#bugs_fixed_in_nss_3.29>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.29: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.29 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.29 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.29 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.30.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.30.1_release_notes/index.rst new file mode 100644 index 0000000000..05d418b4ac --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.30.1_release_notes/index.rst @@ -0,0 +1,73 @@ +.. _mozilla_projects_nss_nss_3_30_1_release_notes: + +NSS 3.30.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.30.1 is a security patch release for NSS 3.30. The bug fixes in + NSS 3.30.1 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_30_1_RTM. NSS 3.30.1 requires NSPR 4.14 or newer. + + NSS 3.30.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_30_1_RTM/src/ + +.. _new_in_nss_3.30.1: + +`New in NSS 3.30.1 <#new_in_nss_3.30.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.30.1: + +`Bugs fixed in NSS 3.30.1 <#bugs_fixed_in_nss_3.30.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1344380 <https://bugzilla.mozilla.org/show_bug.cgi?id=1344380>`__ / Out-of-bounds write + in Base64 encoding in NSS + (`CVE-2017-5461 <https://www.mozilla.org/en-US/security/advisories/mfsa2017-10/#CVE-2017-5461>`__) + +`Acknowledgements <#acknowledgements>`__ +---------------------------------------- + +.. container:: + + The NSS development team would like to thank Ronald Crane for responsibly disclosing the issue by + providing advance copies of their research. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.30.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.30.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.30.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.30.2_release_notes/index.rst new file mode 100644 index 0000000000..5f7322f8bb --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.30.2_release_notes/index.rst @@ -0,0 +1,115 @@ +.. _mozilla_projects_nss_nss_3_30_2_release_notes: + +NSS 3.30.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.30.2 is a patch release for NSS 3.30. The bug fixes in NSS + 3.30.2 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_30_2_RTM. NSS 3.30.2 requires NSPR 4.14 or newer. + + NSS 3.30.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_30_2_RTM/src/ + +.. _new_in_nss_3.30.2: + +`New in NSS 3.30.2 <#new_in_nss_3.30.2>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to update the list of + root CA certificates. + +.. _notable_changes_in_nss_3.30.2: + +`Notable Changes in NSS 3.30.2 <#notable_changes_in_nss_3.30.2>`__ +------------------------------------------------------------------ + +.. container:: + + - The following CA certificates were **Removed**: + + - O = Japanese Government, OU = ApplicationCA + + - SHA-256 Fingerprint: + 2D:47:43:7D:E1:79:51:21:5A:12:F3:C5:8E:51:C7:29:A5:80:26:EF:1F:CC:0A:5F:B3:D9:DC:01:2F:60:0D:19 + + - CN = WellsSecure Public Root Certificate Authority + + - SHA-256 Fingerprint: + A7:12:72:AE:AA:A3:CF:E8:72:7F:7F:B3:9F:0F:B3:D1:E5:42:6E:90:60:B0:6E:E6:F1:3E:9A:3C:58:33:CD:43 + + - CN=TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H6 + + - SHA-256 Fingerprint: + 8D:E7:86:55:E1:BE:7F:78:47:80:0B:93:F6:94:D2:1D:36:8C:C0:6E:03:3E:7F:AB:04:BB:5E:B9:9D:A6:B7:00 + + - CN=Microsec e-Szigno Root + + - SHA-256 Fingerprint: + 32:7A:3D:76:1A:BA:DE:A0:34:EB:99:84:06:27:5C:B1:A4:77:6E:FD:AE:2F:DF:6D:01:68:EA:1C:4F:55:67:D0 + + - The following CA certificates were **Added**: + + - CN = D-TRUST Root CA 3 2013 + + - SHA-256 Fingerprint: + A1:A8:6D:04:12:1E:B8:7F:02:7C:66:F5:33:03:C2:8E:57:39:F9:43:FC:84:B3:8A:D6:AF:00:90:35:DD:94:57 + - Trust Flags: Email + + - CN = TUBITAK Kamu SM SSL Kok Sertifikasi - Surum 1 + + - SHA-256 Fingerprint: + 46:ED:C3:68:90:46:D5:3A:45:3F:B3:10:4A:B8:0D:CA:EC:65:8B:26:60:EA:16:29:DD:7E:86:79:90:64:87:16 + - Trust Flags: Websites + - Technically constrained to: gov.tr, k12.tr, pol.tr, mil.tr, tsk.tr, kep.tr, bel.tr, + edu.tr, org.tr + + - The version number of the updated root CA list has been set to 2.14 + (The version numbers 2.12 and 2.13 for the root CA list have been skipped.) + +.. _bugs_fixed_in_nss_3.30.2: + +`Bugs fixed in NSS 3.30.2 <#bugs_fixed_in_nss_3.30.2>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1350859 <https://bugzilla.mozilla.org/show_bug.cgi?id=1350859>`__ - March 2017 batch of + root CA changes + - `Bug 1349705 <https://bugzilla.mozilla.org/show_bug.cgi?id=1349705>`__ - Implemented domain + name constraints for CA: TUBITAK Kamu SM SSL Kok Sertifikasi - Surum 1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.30.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.30.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.30_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.30_release_notes/index.rst new file mode 100644 index 0000000000..acbd98d30a --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.30_release_notes/index.rst @@ -0,0 +1,125 @@ +.. _mozilla_projects_nss_nss_3_30_release_notes: + +NSS 3.30 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.30, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_30_RTM. NSS 3.30 requires Netscape Portable Runtime (NSPR); 4.13.1 or newer. + + NSS 3.30 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_30_RTM/src/ + +.. _new_in_nss_3.30: + +`New in NSS 3.30 <#new_in_nss_3.30>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - In the PKCS#11 root CA module (nssckbi), CAs with positive trust are marked with a new boolean + attribute, CKA_NSS_MOZILLA_CA_POLICY, set to true. Applications that need to distinguish them + from other root CAs, may use the exported function PK11_HasAttributeSet. + - Support for callback functions that can be used to monitor SSL/TLS alerts that are sent or + received. + + .. rubric:: New Functions + :name: new_functions + + - *in cert.h* + + - **CERT_CompareAVA** - performs a comparison of two CERTAVA structures, and returns a + SECComparison result. + + - *in pk11pub.h* + + - **PK11_HasAttributeSet** - allows to check if a PKCS#11 object in a given slot has a + specific boolean attribute set. + + - *in ssl.h* + + - **SSL_AlertReceivedCallback** - register a callback function, that will be called whenever + an SSL/TLS alert is received + - **SSL_AlertSentCallback** - register a callback function, that will be called whenever an + SSL/TLS alert is sent + - **SSL_SetSessionTicketKeyPair** - configures an asymmetric key pair, for use in wrapping + session ticket keys, used by the server. This function currently only accepts an RSA + public/private key pair. + + .. rubric:: New Macros + :name: new_macros + + - *in ciferfam.h* + + - **PKCS12_AES_CBC_128, PKCS12_AES_CBC_192, PKCS12_AES_CBC_256** - cipher family identifiers + corresponding to the PKCS#5 v2.1 AES based encryption schemes used in the PKCS#12 support + in NSS + + - *in pkcs11n.h* + + - **CKA_NSS_MOZILLA_CA_POLICY** - identifier for a boolean PKCS#11 attribute, that should be + set to true, if a CA is present because of it's acceptance according to the Mozilla CA + Policy + +.. _notable_changes_in_nss_3.30: + +`Notable Changes in NSS 3.30 <#notable_changes_in_nss_3.30>`__ +-------------------------------------------------------------- + +.. container:: + + - The TLS server code has been enhanced to support session tickets when no RSA certificate (e.g. + only an ECDSA certificate) is configured. + - RSA-PSS signatures produced by key pairs with a modulus bit length that is not a multiple of 8 + are now supported. + - The pk12util tool now supports importing and exporting data encrypted in the AES based schemes + defined in PKCS#5 v2.1. + +.. _bugs_fixed_in_nss_3.30: + +`Bugs fixed in NSS 3.30 <#bugs_fixed_in_nss_3.30>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.30: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.30 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.30 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.30 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.31.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.31.1_release_notes/index.rst new file mode 100644 index 0000000000..453ee75eff --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.31.1_release_notes/index.rst @@ -0,0 +1,71 @@ +.. _mozilla_projects_nss_nss_3_31_1_release_notes: + +NSS 3.31.1 release notes +======================== + +.. container:: + + .. note:: + + **This is a DRAFT document.** This notice will be removed when completed. + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.31.1, which is a patch release for + NSS 3.31. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_31_1_RTM. NSS 3.31.1 requires Netscape Portable Runtime (NSPR) 4.15, or + newer. + + NSS 3.31.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_31_1_RTM/src/ + +.. _new_in_nss_3.31.1: + +`New in NSS 3.31.1 <#new_in_nss_3.31.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.31.1: + +`Bugs fixed in NSS 3.31.1 <#bugs_fixed_in_nss_3.31.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1381784 <https://bugzilla.mozilla.org/show_bug.cgi?id=1381784>`__ - Potential deadlock + when using an external PKCS#11 token. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.31.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.31.1 shared libraries, + without recompiling, or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.31_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.31_release_notes/index.rst new file mode 100644 index 0000000000..7cd6080b55 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.31_release_notes/index.rst @@ -0,0 +1,129 @@ +.. _mozilla_projects_nss_nss_3_31_release_notes: + +NSS 3.31 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.31, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_31_RTM. NSS 3.31 requires Netscape Portable Runtime (NSPR) 4.15 or newer. + + NSS 3.31 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_31_RTM/src/ + +.. _new_in_nss_3.31: + +`New in NSS 3.31 <#new_in_nss_3.31>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Allow certificates to be specified by RFC7512 PKCS#11 URIs. + - Allow querying a certificate object for its temporary or permanent storage status in a thread + safe way. + + .. rubric:: New Functions + :name: new_functions + + - *in cert.h* + + - **CERT_GetCertIsPerm** - retrieve the permanent storage status attribute of a certificate + in a thread safe way. + - **CERT_GetCertIsTemp** - retrieve the temporary storage status attribute of a certificate + in a thread safe way. + + - *in pk11pub.h* + + - **PK11_FindCertFromURI** - find a certificate identified by the given URI. + - **PK11_FindCertsFromURI** - find a list of certificates identified by the given URI. + - **PK11_GetModuleURI** - retrieve the URI of the given module. + - **PK11_GetTokenURI** - retrieve the URI of a token based on the given slot information. + + - *in pkcs11uri.h* + + - **PK11URI_CreateURI** - create a new PK11URI object from a set of attributes. + - **PK11URI_DestroyURI** - destroy a PK11URI object. + - **PK11URI_FormatURI** - format a PK11URI object to a string. + - **PK11URI_GetPathAttribute** - retrieve a path attribute with the given name. + - **PK11URI_GetQueryAttribute** - retrieve a query attribute with the given name. + - **PK11URI_ParseURI** - parse PKCS#11 URI and return a new PK11URI object. + + .. rubric:: New Macros + :name: new_macros + + - *in pkcs11uri.h* + + - Several new macros that start with **PK11URI_PATTR\_** for path attributes defined in + RFC7512. + - Several new macros that start with **PK11URI_QATTR\_** for query attributes defined in + RFC7512. + +.. _notable_changes_in_nss_3.31: + +`Notable Changes in NSS 3.31 <#notable_changes_in_nss_3.31>`__ +-------------------------------------------------------------- + +.. container:: + + - The APIs that set a TLS version range have been changed to trim the requested range to the + overlap with a systemwide crypto policy, if configured. **SSL_VersionRangeGetSupported** can + be used to query the overlap between the library's supported range of TLS versions and the + systemwide policy. + - Previously, **SSL_VersionRangeSet** and **SSL_VersionRangeSetDefault** returned a failure if + the requested version range wasn't fully allowed by the systemwide crypto policy. They have + been changed to return success, if at least one TLS version overlaps between the requested + range and the systemwide policy. An application may call **SSL_VersionRangeGet** + and **SSL_VersionRangeGetDefault** to query the TLS version range that was effectively + activated. + - Corrected the encoding of Domain Name Constraints extensions created by certutil + - NSS supports a clean seeding mechanism for \*NIX systems now using only /dev/urandom. This is + used only when SEED_ONLY_DEV_URANDOM is set at compile time. + - CERT_AsciiToName can handle OIDs in dotted decimal form now. + +.. _bugs_fixed_in_nss_3.31: + +`Bugs fixed in NSS 3.31 <#bugs_fixed_in_nss_3.31>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.31: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.31 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.31 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.31 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.32_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.32_release_notes/index.rst new file mode 100644 index 0000000000..1e87e7b657 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.32_release_notes/index.rst @@ -0,0 +1,143 @@ +.. _mozilla_projects_nss_nss_3_32_release_notes: + +NSS 3.32 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.32, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_32_RTM. NSS 3.32 requires Netscape Portable Runtime (NSPR) 4.16, or newer. + + NSS 3.32 source distributions are available on ftp.mozilla.org, for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_32_RTM/src/ + +.. _notable_changes_in_nss_3.32: + +`Notable Changes in NSS 3.32 <#notable_changes_in_nss_3.32>`__ +-------------------------------------------------------------- + +.. container:: + + - Various minor improvements and correctness fixes. + - The Code Signing trust bit was **turned off** for all, included root certificates. + - The Websites (TLS/SSL) trust bit was **turned off** for the following root certificates. + + - CN = AddTrust Class 1 CA Root + + - SHA-256 Fingerprint: + 8C:72:09:27:9A:C0:4E:27:5E:16:D0:7F:D3:B7:75:E8:01:54:B5:96:80:46:E3:1F:52:DD:25:76:63:24:E9:A7 + + - CN = Swisscom Root CA 2 + + - SHA-256 Fingerprint: + F0:9B:12:2C:71:14:F4:A0:9B:D4:EA:4F:4A:99:D5:58:B4:6E:4C:25:CD:81:14:0D:29:C0:56:13:91:4C:38:41 + + - The following CA certificates were **Removed**: + + - CN = AddTrust Public CA Root + + - SHA-256 Fingerprint: + 07:91:CA:07:49:B2:07:82:AA:D3:C7:D7:BD:0C:DF:C9:48:58:35:84:3E:B2:D7:99:60:09:CE:43:AB:6C:69:27 + + - CN = AddTrust Qualified CA Root + + - SHA-256 Fingerprint: + 80:95:21:08:05:DB:4B:BC:35:5E:44:28:D8:FD:6E:C2:CD:E3:AB:5F:B9:7A:99:42:98:8E:B8:F4:DC:D0:60:16 + + - CN = China Internet Network Information Center EV Certificates Root + + - SHA-256 Fingerprint: + 1C:01:C6:F4:DB:B2:FE:FC:22:55:8B:2B:CA:32:56:3F:49:84:4A:CF:C3:2B:7B:E4:B0:FF:59:9F:9E:8C:7A:F7 + + - CN = CNNIC ROOT + + - SHA-256 Fingerprint: + E2:83:93:77:3D:A8:45:A6:79:F2:08:0C:C7:FB:44:A3:B7:A1:C3:79:2C:B7:EB:77:29:FD:CB:6A:8D:99:AE:A7 + + - CN = ComSign Secured CA + + - SHA-256 Fingerprint: + 50:79:41:C7:44:60:A0:B4:70:86:22:0D:4E:99:32:57:2A:B5:D1:B5:BB:CB:89:80:AB:1C:B1:76:51:A8:44:D2 + + - CN = GeoTrust Global CA 2 + + - SHA-256 Fingerprint: + CA:2D:82:A0:86:77:07:2F:8A:B6:76:4F:F0:35:67:6C:FE:3E:5E:32:5E:01:21:72:DF:3F:92:09:6D:B7:9B:85 + + - CN = Secure Certificate Services + + - SHA-256 Fingerprint: + BD:81:CE:3B:4F:65:91:D1:1A:67:B5:FC:7A:47:FD:EF:25:52:1B:F9:AA:4E:18:B9:E3:DF:2E:34:A7:80:3B:E8 + + - CN = Swisscom Root CA 1 + + - SHA-256 Fingerprint: + 21:DB:20:12:36:60:BB:2E:D4:18:20:5D:A1:1E:E7:A8:5A:65:E2:BC:6E:55:B5:AF:7E:78:99:C8:A2:66:D9:2E + + - CN = Swisscom Root EV CA 2 + + - SHA-256 Fingerprint: + D9:5F:EA:3C:A4:EE:DC:E7:4C:D7:6E:75:FC:6D:1F:F6:2C:44:1F:0F:A8:BC:77:F0:34:B1:9E:5D:B2:58:01:5D + + - CN = Trusted Certificate Services + + - SHA-256 Fingerprint: + 3F:06:E5:56:81:D4:96:F5:BE:16:9E:B5:38:9F:9F:2B:8F:F6:1E:17:08:DF:68:81:72:48:49:CD:5D:27:CB:69 + + - CN = UTN-USERFirst-Hardware + + - SHA-256 Fingerprint: + 6E:A5:47:41:D0:04:66:7E:ED:1B:48:16:63:4A:A3:A7:9E:6E:4B:96:95:0F:82:79:DA:FC:8D:9B:D8:81:21:37 + + - CN = UTN-USERFirst-Object + + - SHA-256 Fingerprint: + 6F:FF:78:E4:00:A7:0C:11:01:1C:D8:59:77:C4:59:FB:5A:F9:6A:3D:F0:54:08:20:D0:F4:B8:60:78:75:E5:8F + +.. _bugs_fixed_in_nss_3.32: + +`Bugs fixed in NSS 3.32 <#bugs_fixed_in_nss_3.32>`__ +---------------------------------------------------- + +.. container:: + + NSS versions 3.28.x, 3.29.x. 3.30.x and 3.31.x contained a bug in function CERT_CompareName, + which caused the first RDN to be ignored. NSS version 3.32 fixed this bug. (CVE-2018-5149, `Bug + 1361197 <https://bugzilla.mozilla.org/show_bug.cgi?id=1361197>`__) + + This Bugzilla query returns all the bugs fixed in NSS 3.32: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.32 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.32 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.32 shared libraries, + without recompiling, or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (select the + product 'NSS').
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.33_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.33_release_notes/index.rst new file mode 100644 index 0000000000..ecea918b65 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.33_release_notes/index.rst @@ -0,0 +1,115 @@ +.. _mozilla_projects_nss_nss_3_33_release_notes: + +NSS 3.33 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.33, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_33_RTM. NSS 3.33 requires Netscape Portable Runtime (NSPR) 4.17, or newer. + + NSS 3.33 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_33_RTM/src/ + +.. _notable_changes_in_nss_3.33: + +`Notable Changes in NSS 3.33 <#notable_changes_in_nss_3.33>`__ +-------------------------------------------------------------- + +.. container:: + + - TLS compression is no longer supported. API calls that attempt to enable compression are + accepted without failure. However, TLS compression will remain disabled. + - This version of NSS uses a `formally verified + implementation <https://blog.mozilla.org/security/2017/09/13/verified-cryptography-firefox-57/>`__ + of Curve25519 on 64-bit systems. + - The compile time flag DISABLE_ECC has been removed. + - When NSS is compiled without NSS_FORCE_FIPS=1 startup checks are no longer performed. + - Fixes CVE-2017-7805, a potential use-after-free in TLS 1.2 server, when verifying client + authentication. + - Various minor improvements and correctness fixes. + +.. _new_in_nss_3.33: + +`New in NSS 3.33 <#new_in_nss_3.33>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - When listing an NSS database, using certutil -L, and the database hasn't yet been initialized + with any non-empty or empty password, the text "Database needs user init" will be included in + the listing. + - When using certutil to set an inacceptable password in FIPS mode, a correct explanation of + acceptable passwords will be printed. + + .. rubric:: New Functions + :name: new_functions + + - *in cert.h* + + - **CERT_FindCertByIssuerAndSNCX** - a variation of existing function + CERT_FindCertByIssuerAndSN that accepts an additional password context parameter. + - **CERT_FindCertByNicknameOrEmailAddrCX** - a variation of existing function + CERT_FindCertByNicknameOrEmailAddr that accepts an additional password context parameter. + - **CERT_FindCertByNicknameOrEmailAddrForUsageCX** - a variation of existing function + CERT_FindCertByNicknameOrEmailAddrForUsage that accepts an additional password context + parameter. + + - *in secport.h* + + - **NSS_SecureMemcmpZero** - check if a memory region is all zero in constant time. + - **PORT_ZAllocAligned** - allocate aligned memory. + - **PORT_ZAllocAlignedOffset** - allocate aligned memory for structs. + + - *in ssl.h* + + - **SSL_GetExperimentalAPI** - access experimental APIs in libssl. + +.. _bugs_fixed_in_nss_3.33: + +`Bugs fixed in NSS 3.33 <#bugs_fixed_in_nss_3.33>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.33: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.33 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.33 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.33 shared libraries, + without recompiling, or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (select product + 'NSS').
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.34.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.34.1_release_notes/index.rst new file mode 100644 index 0000000000..3083c3ad45 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.34.1_release_notes/index.rst @@ -0,0 +1,94 @@ +.. _mozilla_projects_nss_nss_3_34_1_release_notes: + +NSS 3.34.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.34.1, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_34.1_RTM. NSS 3.34.1 requires Netscape Portable Runtime (NSPR) 4.17, or + newer. + + NSS 3.34.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_34_1_RTM/src/ + +.. _notable_changes_in_nss_3.34.1: + +`Notable Changes in NSS 3.34.1 <#notable_changes_in_nss_3.34.1>`__ +------------------------------------------------------------------ + +.. container:: + + - The following CA certificate was **Re-Added**. It was previously removed in NSS 3.34, but now + re-added with only the Email trust bit set. (`bug + 1418678 <https://bugzilla.mozilla.org/show_bug.cgi?id=1418678>`__) + + - CN = Certum CA, O=Unizeto Sp. z o.o. + + - SHA-256 Fingerprint: + D8:E0:FE:BC:1D:B2:E3:8D:00:94:0F:37:D2:7D:41:34:4D:99:3E:73:4B:99:D5:65:6D:97:78:D4:D8:14:36:24 + + - Removed entries from certdata.txt for actively distrusted certificates that have expired (`bug + 1409872 <https://bugzilla.mozilla.org/show_bug.cgi?id=1409872>`__). + - The version of the CA list was set to 2.20. + +.. _new_in_nss_3.34: + +`New in NSS 3.34 <#new_in_nss_3.34>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - None + + .. rubric:: New Functions + :name: new_functions + +.. _bugs_fixed_in_nss_3.34.1: + +`Bugs fixed in NSS 3.34.1 <#bugs_fixed_in_nss_3.34.1>`__ +-------------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.34.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.34.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.34.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.34 shared libraries, + without recompiling, or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (select product + 'NSS').
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.34_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.34_release_notes/index.rst new file mode 100644 index 0000000000..236127adc8 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.34_release_notes/index.rst @@ -0,0 +1,215 @@ +.. _mozilla_projects_nss_nss_3_34_release_notes: + +NSS 3.34 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The Network Security Services (NSS) team has released NSS 3.34, which is a minor release. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The hg tag is NSS_3_34_RTM. NSS 3.34 requires Netscape Portable Runtime (NSPR) 4.17, or newer. + + NSS 3.34 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_34_RTM/src/ + +.. _notable_changes_in_nss_3.34: + +`Notable Changes in NSS 3.34 <#notable_changes_in_nss_3.34>`__ +-------------------------------------------------------------- + +.. container:: + + - The following CA certificates were **Added**: + + - CN = GDCA TrustAUTH R5 ROOT + + - SHA-256 Fingerprint: + BF:FF:8F:D0:44:33:48:7D:6A:8A:A6:0C:1A:29:76:7A:9F:C2:BB:B0:5E:42:0F:71:3A:13:B9:92:89:1D:38:93 + - Trust Flags: Websites + + - CN = SSL.com Root Certification Authority RSA + + - SHA-256 Fingerprint: + 85:66:6A:56:2E:E0:BE:5C:E9:25:C1:D8:89:0A:6F:76:A8:7E:C1:6D:4D:7D:5F:29:EA:74:19:CF:20:12:3B:69 + - Trust Flags: Websites, Email + + - CN = SSL.com Root Certification Authority ECC + + - SHA-256 Fingerprint: + 34:17:BB:06:CC:60:07:DA:1B:96:1C:92:0B:8A:B4:CE:3F:AD:82:0E:4A:A3:0B:9A:CB:C4:A7:4E:BD:CE:BC:65 + - Trust Flags: Websites, Email + + - CN = SSL.com EV Root Certification Authority RSA R2 + + - SHA-256 Fingerprint: + 2E:7B:F1:6C:C2:24:85:A7:BB:E2:AA:86:96:75:07:61:B0:AE:39:BE:3B:2F:E9:D0:CC:6D:4E:F7:34:91:42:5C + - Trust Flags: Websites + + - CN = SSL.com EV Root Certification Authority ECC + + - SHA-256 Fingerprint: + 22:A2:C1:F7:BD:ED:70:4C:C1:E7:01:B5:F4:08:C3:10:88:0F:E9:56:B5:DE:2A:4A:44:F9:9C:87:3A:25:A7:C8 + - Trust Flags: Websites + + - CN = TrustCor RootCert CA-1 + + - SHA-256 Fingerprint: + D4:0E:9C:86:CD:8F:E4:68:C1:77:69:59:F4:9E:A7:74:FA:54:86:84:B6:C4:06:F3:90:92:61:F4:DC:E2:57:5C + - Trust Flags: Websites, Email + + - CN = TrustCor RootCert CA-2 + + - SHA-256 Fingerprint: + 07:53:E9:40:37:8C:1B:D5:E3:83:6E:39:5D:AE:A5:CB:83:9E:50:46:F1:BD:0E:AE:19:51:CF:10:FE:C7:C9:65 + - Trust Flags: Websites, Email + + - CN = TrustCor ECA-1 + + - SHA-256 Fingerprint: + 5A:88:5D:B1:9C:01:D9:12:C5:75:93:88:93:8C:AF:BB:DF:03:1A:B2:D4:8E:91:EE:15:58:9B:42:97:1D:03:9C + - Trust Flags: Websites, Email + + - The following CA certificates were **Removed**: + + - CN = Certum CA, O=Unizeto Sp. z o.o. + + - SHA-256 Fingerprint: + D8:E0:FE:BC:1D:B2:E3:8D:00:94:0F:37:D2:7D:41:34:4D:99:3E:73:4B:99:D5:65:6D:97:78:D4:D8:14:36:24 + + - CN = StartCom Certification Authority + + - SHA-256 Fingerprint: + C7:66:A9:BE:F2:D4:07:1C:86:3A:31:AA:49:20:E8:13:B2:D1:98:60:8C:B7:B7:CF:E2:11:43:B8:36:DF:09:EA + + - CN = StartCom Certification Authority + + - SHA-256 Fingerprint: + E1:78:90:EE:09:A3:FB:F4:F4:8B:9C:41:4A:17:D6:37:B7:A5:06:47:E9:BC:75:23:22:72:7F:CC:17:42:A9:11 + + - CN = StartCom Certification Authority G2 + + - SHA-256 Fingerprint: + C7:BA:65:67:DE:93:A7:98:AE:1F:AA:79:1E:71:2D:37:8F:AE:1F:93:C4:39:7F:EA:44:1B:B7:CB:E6:FD:59:95 + + - CN = TÜBİTAK UEKAE Kök Sertifika Hizmet Sağlayıcısı - Sürüm 3 + + - SHA-256 Fingerprint: + E4:C7:34:30:D7:A5:B5:09:25:DF:43:37:0A:0D:21:6E:9A:79:B9:D6:DB:83:73:A0:C6:9E:B1:CC:31:C7:C5:2A + + - CN = ACEDICOM Root + + - SHA-256 Fingerprint: + 03:95:0F:B4:9A:53:1F:3E:19:91:94:23:98:DF:A9:E0:EA:32:D7:BA:1C:DD:9B:C8:5D:B5:7E:D9:40:0B:43:4A + + - CN = Certinomis - Autorité Racine + + - SHA-256 Fingerprint: + FC:BF:E2:88:62:06:F7:2B:27:59:3C:8B:07:02:97:E1:2D:76:9E:D1:0E:D7:93:07:05:A8:09:8E:FF:C1:4D:17 + + - CN = TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı + + - SHA-256 Fingerprint: + 97:8C:D9:66:F2:FA:A0:7B:A7:AA:95:00:D9:C0:2E:9D:77:F2:CD:AD:A6:AD:6B:A7:4A:F4:B9:1C:66:59:3C:50 + + - CN = PSCProcert + + - SHA-256 Fingerprint: + 3C:FC:3C:14:D1:F6:84:FF:17:E3:8C:43:CA:44:0C:00:B9:67:EC:93:3E:8B:FE:06:4C:A1:D7:2C:90:F2:AD:B0 + + - CN = CA 沃通根证书, O=WoSign CA Limited + + - SHA-256 Fingerprint: + D6:F0:34:BD:94:AA:23:3F:02:97:EC:A4:24:5B:28:39:73:E4:47:AA:59:0F:31:0C:77:F4:8F:DF:83:11:22:54 + + - CN = Certification Authority of WoSign + + - SHA-256 Fingerprint: + 4B:22:D5:A6:AE:C9:9F:3C:DB:79:AA:5E:C0:68:38:47:9C:D5:EC:BA:71:64:F7:F2:2D:C1:D6:5F:63:D8:57:08 + + - CN = Certification Authority of WoSign G2 + + - SHA-256 Fingerprint: + D4:87:A5:6F:83:B0:74:82:E8:5E:96:33:94:C1:EC:C2:C9:E5:1D:09:03:EE:94:6B:02:C3:01:58:1E:D9:9E:16 + + - CN = CA WoSign ECC Root + + - SHA-256 Fingerprint: + 8B:45:DA:1C:06:F7:91:EB:0C:AB:F2:6B:E5:88:F5:FB:23:16:5C:2E:61:4B:F8:85:56:2D:0D:CE:50:B2:9B:02 + + - libfreebl no longer requires SSE2 instructions. + +.. _new_in_nss_3.34: + +`New in NSS 3.34 <#new_in_nss_3.34>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - When listing an NSS database. using ``certutil -L``, and the database hasn't yet been + initialized with any non-empty or empty password, the text "Database needs user init" will be + included in the listing. + - When using certutil, to set an inacceptable password in FIPS mode, a correct explanation of + acceptable passwords will be printed. + - SSLKEYLOGFILE is now supported with TLS 1.3, see `Bug + 1287711 <https://bugzilla.mozilla.org/show_bug.cgi?id=1287711>`__ for details. + - ``SSLChannelInfo`` has two new fields (Bug + `1396525 <https://bugzilla.mozilla.org/show_bug.cgi?id=1396525>`__) + + - ``SSLNamedGroup originalKeaGroup`` holds the key exchange group of the original handshake, + when the session was resumed. + - ``PRBool resumed`` is ``PR_TRUE`` when the session is resumed, and ``PR_FALSE`` otherwise. + + - RSA-PSS signatures are now supported on certificates. Certificates with RSA-PSS or + RSA-PKCS#1v1.5 keys can be used to create an RSA-PSS signature on a certificate, using the + ``--pss-sign`` argument to ``certutil``. + + .. rubric:: New Functions + :name: new_functions + +.. _bugs_fixed_in_nss_3.34: + +`Bugs fixed in NSS 3.34 <#bugs_fixed_in_nss_3.34>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.34: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.34 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.34 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.34 shared libraries, + without recompiling, or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (select product + 'NSS').
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.35_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.35_release_notes/index.rst new file mode 100644 index 0000000000..a8f53e1a2e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.35_release_notes/index.rst @@ -0,0 +1,273 @@ +.. _mozilla_projects_nss_nss_3_35_release_notes: + +NSS 3.35 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.35, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_35_RTM. NSS 3.35 requires NSPR 4.18, or newer. + + NSS 3.35 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_35_RTM/src/ + +.. _new_in_nss_3.35: + +`New in NSS 3.35 <#new_in_nss_3.35>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - TLS 1.3 support has been updated to draft -23. This includes a large number of changes since + 3.34, which supported only draft -18. See below for details. + + .. rubric:: New Types + :name: new_types + + - *in sslt.h* + + - **SSLHandshakeType** - The type of a TLS handshake message. + - For the **SSLSignatureScheme** enum, the enumerated values ssl_sig_rsa_pss_sha\* are + deprecated in response to a change in TLS 1.3. Please use the equivalent + ssl_sig_rsa_pss_rsae_sha\* for rsaEncryption keys, or ssl_sig_rsa_pss_pss_sha\* for PSS + keys. Note that this release does not include support for the latter. + +.. _notable_changes_in_nss_3.35: + +`Notable Changes in NSS 3.35 <#notable_changes_in_nss_3.35>`__ +-------------------------------------------------------------- + +.. container:: + + - Previously, NSS used the DBM file format by default. Starting with version 3.35, NSS uses the + SQL file format by default. Below, are explanations that could be helpful for environments + that need to adopt to the new default. + + - If NSS is initialized, in read-write mode with a database directory provided, it uses + database files to store certificates, key, trust, and other information. NSS supports two + different database file formats: + + - DBM: The legacy file format, based on Berkeley DB, using filenames cert8.db, key3.db and + secmod.db. Parallel database access, by multiple applications, is forbidden as it will + likely result in data corruption. + - SQL: The newer file format, based on SQLite, using filenames cert9.db, key4.db and + pkcs11.txt. Parallel database access, by multiple applications, is supported. + + - Applications using NSS may explicitly request to use a specific database format, by adding + a type prefix to the database directory, provided at NSS initialization time. Without a + prefix, the default database type will be used (DBM in versions prior to 3.35, and SQL in + version 3.35 and later.) + - When using the SQL type (either explicitly, or because of the new default), with a database + directory which already contains a DBM type database, NSS will automatically perform a one + time migration of the information contained in the DBM files to the newer SQL files. If a + master password was set on the DBM database, then the initial migration may be partial, and + migration of keys from DBM to SQL will be delayed, until this master password is provided + to NSS. (Conversely, NSS will never synchronize data from SQL to DBM format.) + - Additional information can be found on this Fedora Linux project page: + https://fedoraproject.org/wiki/Changes/NSSDefaultFileFormatSql + + - Added formally verified implementations of non-vectorized Chacha20 and non-vectorized Poly1305 + 64-bit. + - For stronger security, when creating encrypted PKCS#7 or PKCS#12 data, the iteration count for + the password based encryption algorithm has been increased to one million iterations. Note + that debug builds will use a lower count, for better performance in test environments. As a + reminder, debug builds should not be used for production purposes. + - NSS 3.30 had introduced a regression, preventing NSS from reading some AES encrypted data, + produced by older versions of NSS. NSS 3.35 fixes this regression and restores the ability to + read affected data. + - The following CA certificates were **Removed**: + + - OU = Security Communication EV RootCA1 + + - SHA-256 Fingerprint: + A2:2D:BA:68:1E:97:37:6E:2D:39:7D:72:8A:AE:3A:9B:62:96:B9:FD:BA:60:BC:2E:11:F6:47:F2:C6:75:FB:37 + + - CN = CA Disig Root R1 + + - SHA-256 Fingerprint: + F9:6F:23:F4:C3:E7:9C:07:7A:46:98:8D:5A:F5:90:06:76:A0:F0:39:CB:64:5D:D1:75:49:B2:16:C8:24:40:CE + + - CN = DST ACES CA X6 + + - SHA-256 Fingerprint: + 76:7C:95:5A:76:41:2C:89:AF:68:8E:90:A1:C7:0F:55:6C:FD:6B:60:25:DB:EA:10:41:6D:7E:B6:83:1F:8C:40 + + - Subject CN = VeriSign Class 3 Secure Server CA - G2 + + - SHA-256 Fingerprint: + 0A:41:51:D5:E5:8B:84:B8:AC:E5:3A:5C:12:12:2A:C9:59:CD:69:91:FB:B3:8E:99:B5:76:C0:AB:DA:C3:58:14 + - This intermediate cert had been directly included to help with transition from 1024-bit + roots per `Bug #1045189 <https://bugzilla.mozilla.org/show_bug.cgi?id=1045189>`__. + + - The Websites (TLS/SSL) trust bit was turned **off** for the following CA certificates: + + - CN = Chambers of Commerce Root + + - SHA-256 Fingerprint: + 0C:25:8A:12:A5:67:4A:EF:25:F2:8B:A7:DC:FA:EC:EE:A3:48:E5:41:E6:F5:CC:4E:E6:3B:71:B3:61:60:6A:C3 + + - CN = Global Chambersign Root + + - SHA-256 Fingerprint: + EF:3C:B4:17:FC:8E:BF:6F:97:87:6C:9E:4E:CE:39:DE:1E:A5:FE:64:91:41:D1:02:8B:7D:11:C0:B2:29:8C:ED + + - Significant changes to TLS 1.3 were made, along with the update from draft -18 to draft -23: + + - Support for KeyUpdate was added. KeyUpdate will be used automatically, if a cipher is used + for a sufficient number of records. + - SSL_KEYLOGFILE support was updated for TLS 1.3. + - An option to enable TLS 1.3 compatibility mode, SSL_ENABLE_TLS13_COMPAT_MODE, was added. + - Note: In this release, support for new rsa_pss_pss_shaX signature schemes have been + disabled; end-entity certificates with RSA-PSS keys will still be used to produce + signatures, but they will use the rsa_pss_rsae_shaX codepoints. + - Note: The value of ssl_tls13_key_share_xtn value, from the SSLExtensionType, has been + renumbered to match changes in TLS 1.3. This is not expected to cause problems; code + compiled against previous versions of TLS will now refer to an unsupported codepoint, if + this value was used. Recompilation should correct any mismatches. + - Note: DTLS support is promoted in draft -23, but this is currently not compliant with the + DTLS 1.3 draft -23 specification. + + - TLS servers are able to handle a ClientHello statelessly, if the client supports TLS 1.3. If + the server sends a HelloRetryRequest, it is possible to discard the server socket, and make a + new socket to handle any subsequent ClientHello. This better enables stateless server + operation. (This feature is added in support of QUIC, but it also has utility for DTLS 1.3 + servers.) + - The tstclnt utility now supports DTLS, using the -P option. Note that a DTLS server is also + provided in tstclnt. + - TLS compression is no longer possible with NSS. The option can be enabled, but NSS will no + longer negotiate compression. + - The signatures of functions SSL_OptionSet, SSL_OptionGet, SSL_OptionSetDefault and + SSL_OptionGetDefault have been modified, to take a PRIntn argument rather than PRBool. This + makes it clearer, that options can have values other than 0 or 1. Note this does not affect + ABI compatibility, because PRBool is a typedef for PRIntn. + +.. _experimental_apis_and_functionality: + +`Experimental APIs and Functionality <#experimental_apis_and_functionality>`__ +------------------------------------------------------------------------------ + +.. container:: + + The functionality and the APIs listed in this section are experimental. Any of these APIs may be + removed from future NSS versions. Applications *must not* rely on these APIs to be present. If an + application is linked at runtime to a later version of NSS, which no longer provides any of these + APIs, the application *must* handle the scenario gracefully. + + In order to ease transitions, experimental functions return SECFailure and set the + SSL_ERROR_UNSUPPORTED_EXPERIMENTAL_API code if the selected API is not available. Experimental + functions will always return this result if they are disabled or removed from a later NSS + release. If these experimental functions are made permanent in a later NSS release, no change to + code is necessary. + + (Only APIs exported in \*.def files are stable APIs.) + +.. _new_experimental_functionality_provided: + +`New experimental functionality provided <#new_experimental_functionality_provided>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Below are descriptions of experimental functionality, which might not be available in future + releases of NSS. + + - Users of TLS are now able to provide implementations of TLS extensions, through an + experimental custom extension API. See the documentation in sslexp.h for + SSL_InstallExtensionHooks for more information on this feature. + - Several experimental APIs were added in support of TLS 1.3 features: + + - TLS servers are able to send session tickets to clients on demand, using the experimental + SSL_SendSessionTicket function. This ticket can include arbitrary application-chosen + content. + - An anti-replay mechanism was added for 0-RTT, through the experimental SSL_SetupAntiReplay + function. *This mechanism must be enabled for 0-RTT to be accepted when NSS is being used + as a server.* + - KeyUpdate can be triggered by the experimental SSL_KeyUpdate() function. + - TLS servers can screen new TLS 1.3 connections, as they are made using the experimental + SSL_HelloRetryRequestCallback function. This function allows for callbacks to be + installed, which are called when a server receives a new TLS ClientHello. The application + is then able to examine application-chosen content from the session tickets, or + HelloRetryRequest cookie, and decide whether to proceed with the connection. For an + initial ClientHello, an application can control whether NSS sends a HelloRetryRequest, and + include application-chosen content in the cookie. + +.. _new_experimental_apis: + +`New experimental APIs <#new_experimental_apis>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Below is a list of experimental functions, which might not be available in future releases of + NSS. + + - *in sslexp.h* + + - *experimental:* **SSL_KeyUpdate** - prompt NSS to update traffic keys (TLS 1.3 only). + - *experimental:* **SSL_GetExtensionSupport** - query NSS support for a TLS extension. + - *experimental:* **SSL_InstallExtensionHooks** - install custom handlers for a TLS + extension. + - *experimental:* **SSL_SetupAntiReplay** - configure a TLS server for 0-RTT anti-replay (TLS + 1.3 server only). + - *experimental:* **SSL_SendSessionTicket** - send a session ticket (TLS 1.3 server only). + +.. _removed_experimental_apis: + +`Removed experimental APIs <#removed_experimental_apis>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Note that experimental APIs might get removed from NSS without announcing removals in the release + notes. This section might be incomplete. + + - The experimental API SSL_UseAltServerHelloType has been disabled. + +.. _bugs_fixed_in_nss_3.35: + +`Bugs fixed in NSS 3.35 <#bugs_fixed_in_nss_3.35>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.35: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.35 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.35 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.35 shared libraries, + without recompiling, or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (select product + 'NSS').
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.1_release_notes/index.rst new file mode 100644 index 0000000000..e5ecde527d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.1_release_notes/index.rst @@ -0,0 +1,84 @@ +.. _mozilla_projects_nss_nss_3_36_1_release_notes: + +NSS 3.36.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.36.1 is a patch release for NSS 3.36. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_1_RTM. NSS 3.36.1 requires NSPR 4.19 or newer. + + NSS 3.36.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_36_1_RTM/src/ + +.. _new_in_nss_3.xx: + +`New in NSS 3.XX <#new_in_nss_3.xx>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix regression + bugs. + +.. _notable_changes_in_nss_3.36.1: + +`Notable Changes in NSS 3.36.1 <#notable_changes_in_nss_3.36.1>`__ +------------------------------------------------------------------ + +.. container:: + + - In NSS version 3.35 the iteration count in optimized builds, which is used for password based + encryption algorithm related to encrypted PKCS#7 or PKCS#12 data, was increased to one million + iterations. That change had caused an interoperability regression with operating systems that + are limited to 600 K iterations. NSS 3.36.1 has been changed to use the same 600 K limit. + +.. _bugs_fixed_in_nss_3.36.1: + +`Bugs fixed in NSS 3.36.1 <#bugs_fixed_in_nss_3.36.1>`__ +-------------------------------------------------------- + +.. container:: + + - Certain smartcard operations could result in a deadlock. + + This Bugzilla query returns all the bugs fixed in NSS 3.36.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.36.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.2_release_notes/index.rst new file mode 100644 index 0000000000..b4328efcd9 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.2_release_notes/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_nss_3_36_2_release_notes: + +NSS 3.36.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.36.2 is a patch release for NSS 3.36. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_2_RTM. NSS 3.36.2 requires NSPR 4.19 or newer. + + NSS 3.36.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_36_2_RTM/src/ + +.. _new_in_nss_3.36.2: + +`New in NSS 3.36.2 <#new_in_nss_3.36.2>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix regression + bugs. + +.. _bugs_fixed_in_nss_3.36.2: + +`Bugs fixed in NSS 3.36.2 <#bugs_fixed_in_nss_3.36.2>`__ +-------------------------------------------------------- + +.. container:: + + - Bug 1462303 - Connecting to a server that was recently upgraded to TLS 1.3 would result in a + SSL_RX_MALFORMED_SERVER_HELLO error. + + - Bug 1460673 - Fix a rare bug with PKCS#12 files. + + This Bugzilla query returns all the bugs fixed in NSS 3.36.2: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.36.2 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.4_release_notes/index.rst new file mode 100644 index 0000000000..15610593e6 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.4_release_notes/index.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_nss_3_36_4_release_notes: + +NSS 3.36.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.36.4 is a patch release for NSS 3.36. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_4_RTM. NSS 3.36.4 requires NSPR 4.19 or newer. + + NSS 3.36.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_36_4_RTM/src/ + +.. _new_in_nss_3.36.4: + +`New in NSS 3.36.4 <#new_in_nss_3.36.4>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix regression + bugs. + +.. _bugs_fixed_in_nss_3.36.4: + +`Bugs fixed in NSS 3.36.4 <#bugs_fixed_in_nss_3.36.4>`__ +-------------------------------------------------------- + +.. container:: + + - Bug 1461731 - Fix crash on macOS related to authentication tokens, e.g. PK11or WebAuthn. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36.5_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.5_release_notes/index.rst new file mode 100644 index 0000000000..d7dea2ce3c --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.5_release_notes/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_nss_3_36_5_release_notes: + +NSS 3.36.5 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.36.5 is a patch release for NSS 3.36. The bug fixes in NSS + 3.36.5 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_5_RTM. NSS 3.36.5 requires NSPR 4.19 or newer. + + NSS 3.36.5 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_36_5_RTM/src/ + +.. _new_in_nss_3.36.5: + +`New in NSS 3.36.5 <#new_in_nss_3.36.5>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix CVE-2018-12384 + +.. _bugs_fixed_in_nss_3.36.5: + +`Bugs fixed in NSS 3.36.5 <#bugs_fixed_in_nss_3.36.5>`__ +-------------------------------------------------------- + +.. container:: + + `Bug 1483128 <https://bugzilla.mozilla.org/show_bug.cgi?id=1483128>`__ - NSS responded to an + SSLv2-compatible ClientHello with a ServerHello that had an all-zero random (CVE-2018-12384) + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36.5 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36.5 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36.6_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.6_release_notes/index.rst new file mode 100644 index 0000000000..55e3ac20a0 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.6_release_notes/index.rst @@ -0,0 +1,73 @@ +.. _mozilla_projects_nss_nss_3_36_6_release_notes: + +NSS 3.36.6 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.36.6 is a patch release for NSS 3.36. The bug fixes in NSS + 3.36.6 are described in the "Bugs Fixed" section below. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_6_RTM. NSS 3.36.6 requires NSPR 4.19 or newer. + + NSS 3.36.6 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_36_6_RTM/src/ + +.. _new_in_nss_3.36.6: + +`New in NSS 3.36.6 <#new_in_nss_3.36.6>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix CVE-2018-12404 + +.. _bugs_fixed_in_nss_3.36.6: + +`Bugs fixed in NSS 3.36.6 <#bugs_fixed_in_nss_3.36.6>`__ +-------------------------------------------------------- + +.. container:: + + `Bug 1485864 <https://bugzilla.mozilla.org/show_bug.cgi?id=1485864>`__ - Cache side-channel + variant of the Bleichenbacher attack (CVE-2018-12404) + + `Bug 1389967 <https://bugzilla.mozilla.org/show_bug.cgi?id=1389967>`__ and `Bug + 1448748 <https://bugzilla.mozilla.org/show_bug.cgi?id=1448748>`__ - Fixes for MinGW on x64 + platforms. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36.6 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36.6 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36.7_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.7_release_notes/index.rst new file mode 100644 index 0000000000..9b6c47157e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.7_release_notes/index.rst @@ -0,0 +1,74 @@ +.. _mozilla_projects_nss_nss_3_36_7_release_notes: + +NSS 3.36.7 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.36.7 is a patch release for NSS 3.36. The bug fixes in NSS + 3.36.7 are described in the "Bugs Fixed" section below. It was released on 19 January 2019. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_7_RTM. NSS 3.36.7 requires NSPR 4.19 or newer. + + NSS 3.36.7 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_36_7_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.36.7: + +`New in NSS 3.36.7 <#new_in_nss_3.36.7>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix bugs. + +.. _bugs_fixed_in_nss_3.36.7: + +`Bugs fixed in NSS 3.36.7 <#bugs_fixed_in_nss_3.36.7>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1507135 <https://bugzilla.mozilla.org/show_bug.cgi?id=1507135>`__ and `Bug + 1507174 <https://bugzilla.mozilla.org/show_bug.cgi?id=1507174>`__ - Add additional null checks + to several CMS functions to fix a rare CMS crash. Thanks to Hanno Böck and Damian Poddebniak + for the discovery and fixes. + (`CVE-2018-18508 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2018-18508>`__) + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36.7 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36.7 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36.8_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.8_release_notes/index.rst new file mode 100644 index 0000000000..7c9ef80440 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36.8_release_notes/index.rst @@ -0,0 +1,90 @@ +.. _mozilla_projects_nss_nss_3_36_8_release_notes: + +NSS 3.36.8 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.36.8 is a patch release for NSS 3.36. The bug fixes in NSS + 3.36.8 are described in the "Bugs Fixed" section below. It was released on 21 June 2019. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_8_RTM. NSS 3.36.8 requires NSPR 4.19 or newer. + + NSS 3.36.8 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_36_8_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.36.8: + +`New in NSS 3.36.8 <#new_in_nss_3.36.8>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix bugs. + +.. _bugs_fixed_in_nss_3.36.8: + +`Bugs fixed in NSS 3.36.8 <#bugs_fixed_in_nss_3.36.8>`__ +-------------------------------------------------------- + +.. container:: + + - + + .. container:: + + `1554336 <https://bugzilla.mozilla.org/show_bug.cgi?id=1554336>`__ - Optimize away unneeded + loop in mpi.c + + - + + .. container:: + + `1515342 <https://bugzilla.mozilla.org/show_bug.cgi?id=1515342>`__ - More thorough input + checking (`CVE-2019-11729) <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11729>`__ + + - + + .. container:: + + `1540541 <https://bugzilla.mozilla.org/show_bug.cgi?id=1540541>`__ - Don't unnecessarily + strip leading 0's from key material during PKCS11 import + (`CVE-2019-11719 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11719>`__) + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36.8 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36.8 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.36_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.36_release_notes/index.rst new file mode 100644 index 0000000000..9e4bca92ea --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.36_release_notes/index.rst @@ -0,0 +1,78 @@ +.. _mozilla_projects_nss_nss_3_36_release_notes: + +NSS 3.36 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.36, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_36_RTM. NSS 3.36 requires NSPR 4.19 or newer. + + NSS 3.36 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_36_RTM/src/ (make a link) + +.. _new_in_nss_3.36: + +`New in NSS 3.36 <#new_in_nss_3.36>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Experimental APIs for TLS session cache handling. + +.. _notable_changes_in_nss_3.36: + +`Notable Changes in NSS 3.36 <#notable_changes_in_nss_3.36>`__ +-------------------------------------------------------------- + +.. container:: + + - Replaced existing vectorized ChaCha20 code with verified HACL\* implementation. + +.. _bugs_fixed_in_nss_3.36: + +`Bugs fixed in NSS 3.36 <#bugs_fixed_in_nss_3.36>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.36: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.36 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.36 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.36 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.37.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.37.1_release_notes/index.rst new file mode 100644 index 0000000000..cffa1a8619 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.37.1_release_notes/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_nss_3_37_1_release_notes: + +NSS 3.37.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.37.1 is a patch release for NSS 3.37. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_37_1_RTM. NSS 3.37.1 requires NSPR 4.19 or newer. + + NSS 3.37.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/security/nss/releases/NSS_3_37_1_RTM/src/ + +.. _new_in_nss_3.37.1: + +`New in NSS 3.37.1 <#new_in_nss_3.37.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix regression + bugs. + +.. _bugs_fixed_in_nss_3.37.1: + +`Bugs fixed in NSS 3.37.1 <#bugs_fixed_in_nss_3.37.1>`__ +-------------------------------------------------------- + +.. container:: + + - Bug 1462303 - Connecting to a server that was recently upgraded to TLS 1.3 would result in a + SSL_RX_MALFORMED_SERVER_HELLO error. + + - Bug 1460673 - Fix a rare bug with PKCS#12 files. + + This Bugzilla query returns all the bugs fixed in NSS 3.37.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.37.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.37.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.37.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.37_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.37_release_notes/index.rst new file mode 100644 index 0000000000..cc787a2dbe --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.37_release_notes/index.rst @@ -0,0 +1,112 @@ +.. _mozilla_projects_nss_nss_3_37_release_notes: + +NSS 3.37 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.37, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_37_RTM. NSS 3.37 requires NSPR 4.19 or newer. + + NSS 3.37 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_37_RTM/src/ + +.. _notable_changes_in_nss_3.37: + +`Notable Changes in NSS 3.37 <#notable_changes_in_nss_3.37>`__ +-------------------------------------------------------------- + +.. container:: + + - The TLS 1.3 implementation was updated to Draft 28. + + - An issue where NSS erroneously accepted HRR requests was resolved. This issue was found by + `OSS fuzz <https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=7159>`__. + + - Added HACL\* Poly1305 32-bit + + - The code to support the NPN protocol, which had already been disabled in a previous release, + has been fully removed. + + - NSS allows servers now to register ALPN handling callbacks to select a protocol. + + - NSS supports opening SQL databases in read-only mode. NSS now requires the SQLite APIs of + version 3.5.0 or newer. + + - Starting with NSS version 3.31, an alternative implementation for RNG seeding on the + Linux/UNIX platform was available (bug 1346735), which performed seeding exclusively based on + /dev/urandom. This alternative implementation is selected at build time by defining the + SEED_ONLY_DEV_URANDOM symbol. + + (The classic implementation for RNG seeding on the Linux/Unix platform, which may use + additional sources for the default seeding, is still available and will be used if + SEED_ONLY_DEV_URANDOM is undefined.) + + With NSS 3.37, this alternative implementation for Linux/Unix can be selected in "make" builds + by defining the environment variable NSS_SEED_ONLY_DEV_URANDOM. + + With NSS 3.37, this alternative implementation for Linux has been enhanced to use the glibc + function getentropy(), instead of reading from /dev/urandom directly, if the build and runtime + Linux platform supports it. + + - The CA certificates list was updated to version 2.24. + + - The following CA certificates were **Removed**: + + - CN = S-TRUST Universal Root CA + + - SHA-256 Fingerprint: + D8:0F:EF:91:0A:E3:F1:04:72:3B:04:5C:EC:2D:01:9F:44:1C:E6:21:3A:DF:15:67:91:E7:0C:17:90:11:0A:31 + + - CN = TC TrustCenter Class 3 CA II + + - SHA-256 Fingerprint: + 8D:A0:84:FC:F9:9C:E0:77:22:F8:9B:32:05:93:98:06:FA:5C:B8:11:E1:C8:13:F6:A1:08:C7:D3:36:B3:40:8E + + - CN = TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5 + + - SHA-256 Fingerprint: + 49:35:1B:90:34:44:C1:85:CC:DC:5C:69:3D:24:D8:55:5C:B2:08:D6:A8:14:13:07:69:9F:4A:F0:63:19:9D:78 + +.. _bugs_fixed_in_nss_3.37: + +`Bugs fixed in NSS 3.37 <#bugs_fixed_in_nss_3.37>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.37: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.37 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.37 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.37 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.38_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.38_release_notes/index.rst new file mode 100644 index 0000000000..053be661a4 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.38_release_notes/index.rst @@ -0,0 +1,106 @@ +.. _mozilla_projects_nss_nss_3_38_release_notes: + +NSS 3.38 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.38, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_38_RTM. NSS 3.38 requires NSPR 4.19 or newer. + + NSS 3.38 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_38_RTM/src/ + +.. _new_in_nss_3.38: + +`New in NSS 3.38 <#new_in_nss_3.38>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Added support for the TLS Record Size Limit Extension. + - When creating a certificate request (CSR) using certutil -R, an existing orphan private key + can be reused. Parameter -k may be used to specify the ID of an existing orphan key. The + available orphan key IDs can be displayed using command certutil -K. + - When using certutil -O to print the chain for a given certificate nickname, the new parameter + --simple-self-signed may be provided, which can avoid ambiguous output in some scenarios. + + .. rubric:: New Functions + :name: new_functions + + - *in secitem.h* + + - **SECITEM_MakeItem** - Allocate and make an item with the requested contents + + .. rubric:: New Macros + :name: new_macros + + - *in ssl.h* + + - **SSL_RECORD_SIZE_LIMIT** - used to control the TLS Record Size Limit Extension + +.. _notable_changes_in_nss_3.38: + +`Notable Changes in NSS 3.38 <#notable_changes_in_nss_3.38>`__ +-------------------------------------------------------------- + +.. container:: + + - Fixed `CVE-2018-0495 <https://nvd.nist.gov/vuln/detail/CVE-2018-0495>`__ in `bug + 1464971 <https://bugzilla.mozilla.org/show_bug.cgi?id=1464971>`__. + + - Various security fixes in the ASN.1 code. + + - NSS automatically enables caching for SQL database storage on Linux, if it is located on a + network filesystem that's known to benefit from caching. + + - When repeatedly importing the same certificate into an SQL database, the existing nickname + will be kept. + +.. _bugs_fixed_in_nss_3.38: + +`Bugs fixed in NSS 3.38 <#bugs_fixed_in_nss_3.38>`__ +---------------------------------------------------- + +.. container:: + + This Bugzilla query returns all the bugs fixed in NSS 3.38: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.38 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.38 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.38 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.39_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.39_release_notes/index.rst new file mode 100644 index 0000000000..697dc88aae --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.39_release_notes/index.rst @@ -0,0 +1,149 @@ +.. _mozilla_projects_nss_nss_3_39_release_notes: + +NSS 3.39 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.39, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_39_RTM. NSS 3.39 requires NSPR 4.20 or newer. + + NSS 3.39 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_39_RTM/src/ + +.. _new_in_nss_3.39: + +`New in NSS 3.39 <#new_in_nss_3.39>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The ``tstclnt`` and ``selfserv`` utilities added support for configuring the enabled TLS + signature schemes using the ``-J`` parameter. + + - NSS will use RSA-PSS keys to authenticate in TLS. Support for these keys is disabled by + default but can be enabled using ``SSL_SignatureSchemePrefSet()``. + + - ``certutil`` added the ability to delete an orphan private key from an NSS key database. + + - Added the ``nss-policy-check`` utility, which can be used to check an NSS policy configuration + for problems. + + - A PKCS#11 URI can be used as an identifier for a PKCS#11 token. + + .. rubric:: New Functions + :name: new_functions + + - in cert.h + + - **CERT_GetCertKeyType** - Query the Key Type associated with the given certificate. + + - utilpars.h + + - **NSSUTIL_AddNSSFlagToModuleSpec** - A helper function for modifying the PKCS#11 module + configuration. It can be used to add a single flag to the Flags= section inside the spec's + NSS= section. + +.. _notable_changes_in_nss_3.39: + +`Notable Changes in NSS 3.39 <#notable_changes_in_nss_3.39>`__ +-------------------------------------------------------------- + +.. container:: + + - The TLS 1.3 implementation uses the final version number from `RFC + 8446 <https://datatracker.ietf.org/doc/html/rfc8446>`__. + - Previous versions of NSS accepted an RSA PKCS#1 v1.5 signature where the DigestInfo structure + was missing the NULL parameter. + Starting with version 3.39, NSS requires the encoding to contain the NULL parameter. + - The ``tstclnt`` and ``selfserv`` test utilities no longer accept the -z parameter, as support + for TLS compression was removed in a previous NSS version. + - The CA certificates list was updated to version 2.26. + - The following CA certificates were **Added**: + + - OU = GlobalSign Root CA - R6 + + - SHA-256 Fingerprint: 2CABEAFE37D06CA22ABA7391C0033D25982952C453647349763A3AB5AD6CCF69 + + - CN = OISTE WISeKey Global Root GC CA + + - SHA-256 Fingerprint: 8560F91C3624DABA9570B5FEA0DBE36FF11A8323BE9486854FB3F34A5571198D + + - The following CA certificate was **Removed**: + + - CN = ComSign + + - SHA-256 Fingerprint: AE4457B40D9EDA96677B0D3C92D57B5177ABD7AC1037958356D1E094518BE5F2 + + - The following CA certificates had the **Websites trust bit disabled**: + + - CN = Certplus Root CA G1 + + - SHA-256 Fingerprint: 152A402BFCDF2CD548054D2275B39C7FCA3EC0978078B0F0EA76E561A6C7433E + + - CN = Certplus Root CA G2 + + - SHA-256 Fingerprint: 6CC05041E6445E74696C4CFBC9F80F543B7EABBB44B4CE6F787C6A9971C42F17 + + - CN = OpenTrust Root CA G1 + + - SHA-256 Fingerprint: 56C77128D98C18D91B4CFDFFBC25EE9103D4758EA2ABAD826A90F3457D460EB4 + + - CN = OpenTrust Root CA G2 + + - SHA-256 Fingerprint: 27995829FE6A7515C1BFE848F9C4761DB16C225929257BF40D0894F29EA8BAF2 + + - CN = OpenTrust Root CA G3 + + - SHA-256 Fingerprint: B7C36231706E81078C367CB896198F1E3208DD926949DD8F5709A410F75B6292 + +.. _bugs_fixed_in_nss_3.39: + +`Bugs fixed in NSS 3.39 <#bugs_fixed_in_nss_3.39>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1483128 <https://bugzilla.mozilla.org/show_bug.cgi?id=1483128>`__ - NSS responded to an + SSLv2-compatible ClientHello with a ServerHello that had an all-zero random (CVE-2018-12384) + + This Bugzilla query returns all the bugs fixed in NSS 3.39: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.39 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.39 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.39 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.40.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.40.1_release_notes/index.rst new file mode 100644 index 0000000000..bfbab1da06 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.40.1_release_notes/index.rst @@ -0,0 +1,81 @@ +.. _mozilla_projects_nss_nss_3_40_1_release_notes: + +NSS 3.40.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.40.1, which is a patch release for + NSS 3.40 + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_40_1_RTM. NSS 3.40.1 requires NSPR 4.20 or newer. + + NSS 3.40 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_40_1_RTM/src/ + +.. _new_in_nss_3.40.1: + +`New in NSS 3.40.1 <#new_in_nss_3.40.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - No new functionality is introduced in this release. This is a patch release to fix + CVE-2018-12404 + + .. rubric:: New Functions + :name: new_functions + + - none + +.. _bugs_fixed_in_nss_3.40.1: + +`Bugs fixed in NSS 3.40.1 <#bugs_fixed_in_nss_3.40.1>`__ +-------------------------------------------------------- + +.. container:: + + - + + .. container:: field indent + + .. container:: + + `Bug 1485864 <https://bugzilla.mozilla.org/show_bug.cgi?id=1485864>`__ - Cache + side-channel variant of the Bleichenbacher attack (CVE-2018-12404) + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.40.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.40.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.40_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.40_release_notes/index.rst new file mode 100644 index 0000000000..94faaea909 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.40_release_notes/index.rst @@ -0,0 +1,102 @@ +.. _mozilla_projects_nss_nss_3_40_release_notes: + +NSS 3.40 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.40, which is a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_40_RTM. NSS 3.40 requires NSPR 4.20 or newer. + + NSS 3.40 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_40_RTM/src/ + +.. _new_in_nss_3.40: + +`New in NSS 3.40 <#new_in_nss_3.40>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The draft-00 version of encrypted SNI support is implemented + + - ``tstclnt`` now takes ``-N`` option to specify encrypted SNI key + + .. rubric:: New Functions + :name: new_functions + + - none + +.. _notable_changes_in_nss_3.40: + +`Notable Changes in NSS 3.40 <#notable_changes_in_nss_3.40>`__ +-------------------------------------------------------------- + +.. container:: + + - The mozilla::pkix library has been ported from Mozilla PSM to NSS. This is a C++ library for + building certification paths. mozilla::pkix APIs are not exposed in the libraries NSS builds. + - It is easier to build NSS on Windows in + `mozilla-build <https://wiki.mozilla.org/MozillaBuild>`__ environments. + - The following CA certificates were **Removed**: + + - CN = Visa eCommerce Root + + - SHA-256 Fingerprint: 69FAC9BD55FB0AC78D53BBEE5CF1D597989FD0AAAB20A25151BDF1733EE7D122 + +.. _bugs_fixed_in_nss_3.40: + +`Bugs fixed in NSS 3.40 <#bugs_fixed_in_nss_3.40>`__ +---------------------------------------------------- + +.. container:: + + - + + .. container:: field indent + + .. container:: + + `Bug 1478698 <https://bugzilla.mozilla.org/show_bug.cgi?id=1478698>`__ - FFDHE key + exchange sometimes fails with decryption failure + + This Bugzilla query returns all the bugs fixed in NSS 3.40: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.40 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.40 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.40 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.41.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.41.1_release_notes/index.rst new file mode 100644 index 0000000000..5041561697 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.41.1_release_notes/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_nss_3_41_1_release_notes: + +NSS 3.41.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.41.1 is a patch release for NSS 3.41. The bug fixes in NSS + 3.41.1 are described in the "Bugs Fixed" section below. It was released on 22 January 2019. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_41_1_RTM. NSS 3.41.1 requires NSPR 4.20 or newer. + + NSS 3.41.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_41_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.41.1: + +`New in NSS 3.41.1 <#new_in_nss_3.41.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + No new functionality is introduced in this release. This is a patch release to fix bugs. + +.. _bugs_fixed_in_nss_3.41.1: + +`Bugs fixed in NSS 3.41.1 <#bugs_fixed_in_nss_3.41.1>`__ +-------------------------------------------------------- + +.. container:: + + - Bug 1507135 and Bug 1507174 - Add additional null checks to several CMS functions to fix a + rare CMS crash. Thanks to Hanno Böck and Damian Poddebniak for the discovery and fixes. + (CVE-2018-18508) + + This bugzilla query returns all bugs fixed in 3.41.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.41.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.41.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.41.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.41_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.41_release_notes/index.rst new file mode 100644 index 0000000000..c44b7b4d0e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.41_release_notes/index.rst @@ -0,0 +1,163 @@ +.. _mozilla_projects_nss_nss_3_41_release_notes: + +NSS 3.41 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.41 on 7 December 2018, which is a + minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_41_RTM. NSS 3.41 requires NSPR 4.20 or newer. + + NSS 3.41 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_41_RTM/src/ + +.. _new_in_nss_3.41: + +`New in NSS 3.41 <#new_in_nss_3.41>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 1252891 <https://bugzilla.mozilla.org/show_bug.cgi?id=1252891>`__ - Implemented EKU + handling for IPsec IKE. + - `Bug 1423043 <https://bugzilla.mozilla.org/show_bug.cgi?id=1423043>`__ - Enable half-closed + states for TLS. + - `Bug 1493215 <https://bugzilla.mozilla.org/show_bug.cgi?id=1493215>`__ - Enabled the following + ciphersuites by default: + + - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 + - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + - TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 + - TLS_RSA_WITH_AES_256_GCM_SHA384 + + .. rubric:: New Functions + :name: new_functions + + - none + +.. _notable_changes_in_nss_3.41: + +`Notable Changes in NSS 3.41 <#notable_changes_in_nss_3.41>`__ +-------------------------------------------------------------- + +.. container:: + + - The following CA certificates were **Added**: + + - CN = Certigna Root CA + + - SHA-256 Fingerprint: D48D3D23EEDB50A459E55197601C27774B9D7B18C94D5A059511A10250B93168 + + - CN = GTS Root R1 + + - SHA-256 Fingerprint: 2A575471E31340BC21581CBD2CF13E158463203ECE94BCF9D3CC196BF09A5472 + + - CN = GTS Root R2 + + - SHA-256 Fingerprint: C45D7BB08E6D67E62E4235110B564E5F78FD92EF058C840AEA4E6455D7585C60 + + - CN = GTS Root R3 + + - SHA-256 Fingerprint: 15D5B8774619EA7D54CE1CA6D0B0C403E037A917F131E8A04E1E6B7A71BABCE5 + + - CN = GTS Root R4 + + - SHA-256 Fingerprint: 71CCA5391F9E794B04802530B363E121DA8A3043BB26662FEA4DCA7FC951A4BD + + - CN = UCA Global G2 Root + + - SHA-256 Fingerprint: 9BEA11C976FE014764C1BE56A6F914B5A560317ABD9988393382E5161AA0493C + + - CN = UCA Extended Validation Root + + - SHA-256 Fingerprint: D43AF9B35473755C9684FC06D7D8CB70EE5C28E773FB294EB41EE71722924D24 + + - The following CA certificates were **Removed**: + + - CN = AC Raíz Certicámara S.A. + + - SHA-256 Fingerprint: A6C51E0DA5CA0A9309D2E4C0E40C2AF9107AAE8203857FE198E3E769E343085C + + - CN = Certplus Root CA G1 + + - SHA-256 Fingerprint: 152A402BFCDF2CD548054D2275B39C7FCA3EC0978078B0F0EA76E561A6C7433E + + - CN = Certplus Root CA G2 + + - SHA-256 Fingerprint: 6CC05041E6445E74696C4CFBC9F80F543B7EABBB44B4CE6F787C6A9971C42F17 + + - CN = OpenTrust Root CA G1 + + - SHA-256 Fingerprint: 56C77128D98C18D91B4CFDFFBC25EE9103D4758EA2ABAD826A90F3457D460EB4 + + - CN = OpenTrust Root CA G2 + + - SHA-256 Fingerprint: 27995829FE6A7515C1BFE848F9C4761DB16C225929257BF40D0894F29EA8BAF2 + + - CN = OpenTrust Root CA G3 + + - SHA-256 Fingerprint: B7C36231706E81078C367CB896198F1E3208DD926949DD8F5709A410F75B6292 + +.. _bugs_fixed_in_nss_3.41: + +`Bugs fixed in NSS 3.41 <#bugs_fixed_in_nss_3.41>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1412829 <https://bugzilla.mozilla.org/show_bug.cgi?id=1412829>`__, Reject empty + supported_signature_algorithms in Certificate Request in TLS 1.2 + + - `Bug 1485864 <https://bugzilla.mozilla.org/show_bug.cgi?id=1485864>`__ - Cache side-channel + variant of the Bleichenbacher attack (CVE-2018-12404) + + - `Bug 1481271 <https://bugzilla.mozilla.org/show_bug.cgi?id=1481271>`__ - Resend the same + ticket in ClientHello after HelloRetryRequest + + - `Bug 1493769 <https://bugzilla.mozilla.org/show_bug.cgi?id=1493769>`__ - Set session_id for + external resumption tokens + + - `Bug 1507179 <https://bugzilla.mozilla.org/show_bug.cgi?id=1507179>`__ - Reject CCS after + handshake is complete in TLS 1.3 + + This Bugzilla query returns all the bugs fixed in NSS 3.41: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.41 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.41 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.41 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.42.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.42.1_release_notes/index.rst new file mode 100644 index 0000000000..a84391d84c --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.42.1_release_notes/index.rst @@ -0,0 +1,65 @@ +.. _mozilla_projects_nss_nss_3_42_1_release_notes: + +NSS 3.42.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.42.1 on 31 January 2019, which is a + patch release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_42_1_RTM. NSS 3.42.1 requires NSPR 4.20 or newer. + + NSS 3.42.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_42_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.42.1: + +`Bugs fixed in NSS 3.42.1 <#bugs_fixed_in_nss_3.42.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1507135 <https://bugzilla.mozilla.org/show_bug.cgi?id=1507135>`__ and `Bug + 1507174 <https://bugzilla.mozilla.org/show_bug.cgi?id=1507174>`__ - Add additional null checks + to several CMS functions to fix a rare CMS crash. Thanks to Hanno Böck and Damian Poddebniak + for the discovery and fixes. This was originally announced in + :ref:`mozilla_projects_nss_nss_3_42_release_notes`, but was mistakenly not included in the + release. (`CVE-2018-18508 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2018-18508>`__) + + This Bugzilla query returns all the bugs fixed in NSS 3.42.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.42.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.42.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.42.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.42_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.42_release_notes/index.rst new file mode 100644 index 0000000000..bd6f2e8135 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.42_release_notes/index.rst @@ -0,0 +1,143 @@ +.. _mozilla_projects_nss_nss_3_42_release_notes: + +NSS 3.42 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.42 on 25 January 2019, which is a + minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_42_RTM. NSS 3.42 requires NSPR 4.20 or newer. + + NSS 3.42 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_42_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.42: + +`New in NSS 3.42 <#new_in_nss_3.42>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Bug 818686 <https://bugzilla.mozilla.org/show_bug.cgi?id=818686>`__ - Support XDG basedir + specification + + .. rubric:: New Functions + :name: new_functions + + - none + +.. _notable_changes_in_nss_3.42: + +`Notable Changes in NSS 3.42 <#notable_changes_in_nss_3.42>`__ +-------------------------------------------------------------- + +.. container:: + + - The following CA certificates were **Added**: + + - None + + - The following CA certificates were **Removed**: + + - None + + - Added support for some of the test cases from the `Wycheproof + project <https://github.com/google/wycheproof>`__: + + - `Bug 1508666 <https://bugzilla.mozilla.org/show_bug.cgi?id=1508666>`__ - Added AES-GCM test + cases + + - + + .. container:: field indent + + .. container:: + + .. container:: + + `Bug 1508673 <https://bugzilla.mozilla.org/show_bug.cgi?id=1508673>`__ - Added + ChaCha20-Poly1305 test cases + + - + + .. container:: field indent + + .. container:: + + .. container:: + + `Bug 1514999 <https://bugzilla.mozilla.org/show_bug.cgi?id=1514999>`__ - Added the + Curve25519 test cases + + - Thanks to Jonas Allmann for adapting these tests. + +.. _bugs_fixed_in_nss_3.42: + +`Bugs fixed in NSS 3.42 <#bugs_fixed_in_nss_3.42>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1490006 <https://bugzilla.mozilla.org/show_bug.cgi?id=1490006>`__ - Reject invalid + CH.legacy_version in TLS 1.3 + + - `Bug 1507135 <https://bugzilla.mozilla.org/show_bug.cgi?id=1507135>`__\ [STRIKEOUT:and]\ `Bug + 1507174 <https://bugzilla.mozilla.org/show_bug.cgi?id=1507174>`__\ [STRIKEOUT:- Add additional + null checks to several CMS functions to fix a rare CMS crash. Thanks to Hanno Böck and Damian + Poddebniak for the discovery and fixes.] Note: This was mistakenly not in release 3.42, and is + instead in :ref:`mozilla_projects_nss_nss_3_42_1_release_notes`. + + - + + .. container:: field indent + + .. container:: + + .. container:: + + `Bug 1513913 <https://bugzilla.mozilla.org/show_bug.cgi?id=1513913>`__ - A fix for + Solaris where Firefox 60 core dumps during start when using profile from version 52 + + This Bugzilla query returns all the bugs fixed in NSS 3.42: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.42 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.42 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.42 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.43_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.43_release_notes/index.rst new file mode 100644 index 0000000000..2e3336c84d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.43_release_notes/index.rst @@ -0,0 +1,151 @@ +.. _mozilla_projects_nss_nss_3_43_release_notes: + +NSS 3.43 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.43 on 16 March 2019, which is a minor + release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_43_RTM. NSS 3.43 requires NSPR 4.21 or newer. + + NSS 3.43 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_43_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.43: + +`New in NSS 3.43 <#new_in_nss_3.43>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: New Functions + :name: new_functions + + - *in sechash.h* + + - **HASH_GetHashOidTagByHashType** - convert type HASH_HashType to type SECOidTag + + - *in sslexp.h* + + - **SSL_SendCertificateRequest** - allow server to request post-handshake client + authentication. To use this both peers need to enable the + **SSL_ENABLE_POST_HANDSHAKE_AUTH** option. Note that while the mechanism is present, + post-handshake authentication is currently not TLS 1.3 compliant due to `Bug + 1532312 <https://bugzilla.mozilla.org/show_bug.cgi?id=1532312>`__ + +.. _notable_changes_in_nss_3.43: + +`Notable Changes in NSS 3.43 <#notable_changes_in_nss_3.43>`__ +-------------------------------------------------------------- + +.. container:: + + - + + .. container:: field indent + + .. container:: + + .. container:: + + The following CA certificates were **Added**: + + - CN = emSign Root CA - G1 + + - SHA-256 Fingerprint: 40F6AF0346A99AA1CD1D555A4E9CCE62C7F9634603EE406615833DC8C8D00367 + + - CN = emSign ECC Root CA - G3 + + - SHA-256 Fingerprint: 86A1ECBA089C4A8D3BBE2734C612BA341D813E043CF9E8A862CD5C57A36BBE6B + + - CN = emSign Root CA - C1 + + - SHA-256 Fingerprint: 125609AA301DA0A249B97A8239CB6A34216F44DCAC9F3954B14292F2E8C8608F + + - CN = emSign ECC Root CA - C3 + + - SHA-256 Fingerprint: BC4D809B15189D78DB3E1D8CF4F9726A795DA1643CA5F1358E1DDB0EDC0D7EB3 + + - CN = Hongkong Post Root CA 3 + + - SHA-256 Fingerprint: 5A2FC03F0C83B090BBFA40604B0988446C7636183DF9846E17101A447FB8EFD6 + + - The following CA certificates were **Removed**: + + - None + +.. _bugs_fixed_in_nss_3.43: + +`Bugs fixed in NSS 3.43 <#bugs_fixed_in_nss_3.43>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1528669 <https://bugzilla.mozilla.org/show_bug.cgi?id=1528669>`__ and `Bug + 1529308 <https://bugzilla.mozilla.org/show_bug.cgi?id=1529308>`__ - Improve Gyp build system + handling + - `Bug 1529950 <https://bugzilla.mozilla.org/show_bug.cgi?id=1529950>`__ and `Bug + 1521174 <https://bugzilla.mozilla.org/show_bug.cgi?id=1521174>`__ - Improve NSS S/MIME tests + for Thunderbird + - `Bug 1530134 <https://bugzilla.mozilla.org/show_bug.cgi?id=1530134>`__ - If Docker isn't + installed, try running a local clang-format as a fallback + - `Bug 1531267 <https://bugzilla.mozilla.org/show_bug.cgi?id=1531267>`__ - Enable FIPS mode + automatically if the system FIPS mode flag is set + - `Bug 1528262 <https://bugzilla.mozilla.org/show_bug.cgi?id=1528262>`__ - Add a -J option to + the strsclnt command to specify sigschemes + - `Bug 1513909 <https://bugzilla.mozilla.org/show_bug.cgi?id=1513909>`__ - Add manual for + nss-policy-check + - `Bug 1531074 <https://bugzilla.mozilla.org/show_bug.cgi?id=1531074>`__ - Fix a deref after a + null check in SECKEY_SetPublicValue + - `Bug 1517714 <https://bugzilla.mozilla.org/show_bug.cgi?id=1517714>`__ - Properly handle ESNI + with HRR + - `Bug 1529813 <https://bugzilla.mozilla.org/show_bug.cgi?id=1529813>`__ - Expose + HKDF-Expand-Label with mechanism + - `Bug 1535122 <https://bugzilla.mozilla.org/show_bug.cgi?id=1535122>`__ - Align TLS 1.3 HKDF + trace levels + - `Bug 1530102 <https://bugzilla.mozilla.org/show_bug.cgi?id=1530102>`__ - Use getentropy on + compatible versions of FreeBSD. + + This Bugzilla query returns all the bugs fixed in NSS 3.43: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.43 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.43 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.43 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.44.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.1_release_notes/index.rst new file mode 100644 index 0000000000..b318c274f1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.1_release_notes/index.rst @@ -0,0 +1,140 @@ +.. _mozilla_projects_nss_nss_3_44_1_release_notes: + +NSS 3.44.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.44.1 is a patch release for NSS 3.44. The bug fixes in NSS + 3.44.1 are described in the "Bugs Fixed" section below. It was released on 21 June 2019. + + The NSS team would like to recognize first-time contributors: Greg Rubin + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_44_1_RTM. NSS 3.44.1 requires NSPR 4.21 or newer. + + NSS 3.44.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_44_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.44.1: + +`New in NSS 3.44.1 <#new_in_nss_3.44.1>`__ +------------------------------------------ + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - + + .. container:: + + `1546229 <https://bugzilla.mozilla.org/show_bug.cgi?id=1546229>`__ - Add IPSEC IKE support + to softoken + + - + + .. container:: + + Many new FIPS test cases (Note: This has increased the source archive by approximately 50 + megabytes for this release.) + +.. _bugs_fixed_in_nss_3.44.1: + +`Bugs fixed in NSS 3.44.1 <#bugs_fixed_in_nss_3.44.1>`__ +-------------------------------------------------------- + +.. container:: + + - + + .. container:: + + `1554336 <https://bugzilla.mozilla.org/show_bug.cgi?id=1554336>`__ - Optimize away unneeded + loop in mpi.c + + - + + .. container:: + + `1515342 <https://bugzilla.mozilla.org/show_bug.cgi?id=1515342>`__ - More thorough input + checking (`CVE-2019-11729) <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11729>`__ + + - + + .. container:: + + `1540541 <https://bugzilla.mozilla.org/show_bug.cgi?id=1540541>`__ - Don't unnecessarily + strip leading 0's from key material during PKCS11 import + (`CVE-2019-11719 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11719>`__) + + - + + .. container:: + + `1515236 <https://bugzilla.mozilla.org/show_bug.cgi?id=1515236>`__ - Add a SSLKEYLOGFILE + enable/disable flag at `build.sh <http://build.sh>`__ + + - + + .. container:: + + `1473806 <https://bugzilla.mozilla.org/show_bug.cgi?id=1473806>`__ - Fix + SECKEY_ConvertToPublicKey handling of non-RSA keys + + - + + .. container:: + + `1546477 <https://bugzilla.mozilla.org/show_bug.cgi?id=1546477>`__ - Updates to testing for + FIPS validation + + - + + .. container:: + + `1552208 <https://bugzilla.mozilla.org/show_bug.cgi?id=1552208>`__ - Prohibit use of + RSASSA-PKCS1-v1_5 algorithms in TLS 1.3 + (`CVE-2019-11727 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11727>`__) + + - + + .. container:: + + `1551041 <https://bugzilla.mozilla.org/show_bug.cgi?id=1551041>`__ - Unbreak build on GCC < + 4.3 big-endian + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.44.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.44.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.44.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.2_release_notes/index.rst new file mode 100644 index 0000000000..e5d0087114 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.2_release_notes/index.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_nss_3_44_2_release_notes: + +NSS 3.44.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.44.2 is a patch release for NSS 3.44. The bug fixes in NSS + 3.44.2 are described in the "Bugs Fixed" section below. It was released on 2 October 2019. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_44_2_RTM. NSS 3.44.2 requires NSPR 4.21 or newer. + + NSS 3.44.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_44_2_RTM/src/ + + Other releases are available in NSS Releases. + +.. _new_in_nss_3.44.2: + +`New in NSS 3.44.2 <#new_in_nss_3.44.2>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.44.2: + +`Bugs fixed in NSS 3.44.2 <#bugs_fixed_in_nss_3.44.2>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1582343 <https://bugzilla.mozilla.org/show_bug.cgi?id=1582343>`__\ - Soft token MAC + verification not constant time + - `Bug 1577953 <https://bugzilla.mozilla.org/show_bug.cgi?id=1577953>`__\ - Remove arbitrary + HKDF output limit by allocating space as needed + + This Bugzilla query returns all the bugs fixed in NSS 3.44.2: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.44.2 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.44.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.44.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__\ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.44.3_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.3_release_notes/index.rst new file mode 100644 index 0000000000..c9712ce436 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.3_release_notes/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_nss_3_44_3_release_notes: + +NSS 3.44.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.44.3 is a patch release for NSS 3.44. The bug fixes in NSS + 3.44.3 are described in the "Bugs Fixed" section below. It was released on 19 November 2019. + + The NSS team would like to recognize first-time contributors: + + - Craig Disselkoen + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_44_3_RTM. NSS 3.44.3 requires NSPR 4.21 or newer. + + NSS 3.44.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_44_3_RTM/src/ + + Other releases are available in NSS Releases. + +.. _new_in_nss_3.44.3: + +`New in NSS 3.44.3 <#new_in_nss_3.44.3>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.44.3: + +`Bugs fixed in NSS 3.44.3 <#bugs_fixed_in_nss_3.44.3>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1579060 <https://bugzilla.mozilla.org/show_bug.cgi?id=1579060>`__ - Don't set the + CONSTRUCTED bit for issuerUniqueID and subjectUniqueID in mozilla::pkix + - `CVE-2019-11745 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11745>`__ - + EncryptUpdate should use maxout, not block size + + This Bugzilla query returns all the bugs fixed in NSS 3.44: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.44 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.44.3 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.44.3 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.44.4_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.4_release_notes/index.rst new file mode 100644 index 0000000000..9e969f0a5c --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.44.4_release_notes/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_nss_3_44_4_release_notes: + +NSS 3.44.4 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.44.4 on **19 May 2020**. This is a + security patch release. + + Thank you to Cesar Pereida Garcia and the Network and Information Security Group (NISEC) at + Tampere University for reporting this issue. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_44_4_RTM. NSS 3.44.4 requires NSPR 4.21 or newer. + + NSS 3.44.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_44_4_RTM/src/ + + Other releases are available in :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.44.4: + +`New in NSS 3.44.4 <#new_in_nss_3.44.4>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.44.4: + +`Bugs fixed in NSS 3.44.4 <#bugs_fixed_in_nss_3.44.4>`__ +-------------------------------------------------------- + +.. container:: + + - `CVE-2020-12399 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2020-12399>`__ - Force a + fixed length for DSA exponentiation + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.44.4 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.44.4 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.44_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.44_release_notes/index.rst new file mode 100644 index 0000000000..c5146bc97a --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.44_release_notes/index.rst @@ -0,0 +1,146 @@ +.. _mozilla_projects_nss_nss_3_44_release_notes: + +NSS 3.44 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.44 on 10 May 2019, which is a minor + release. + + The NSS team would like to recognize first-time contributors: Kevin Jacobs, David Carlier, + Alexander Scheel, and Edouard Oger. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_44_RTM. NSS 3.44 requires NSPR 4.21 or newer. + + NSS 3.44 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_44_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.44: + +`New in NSS 3.44 <#new_in_nss_3.44>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: New Functions + :name: new_functions + + - *in lib/certdb/cert.h* + + - **CERT_GetCertificateDer** - Access the DER-encoded form of a CERTCertificate. + +.. _notable_changes_in_nss_3.44: + +`Notable Changes in NSS 3.44 <#notable_changes_in_nss_3.44>`__ +-------------------------------------------------------------- + +.. container:: + + - It is now possible to build NSS as a static library (Bug + `1543545 <https://bugzilla.mozilla.org/show_bug.cgi?id=1543545>`__) + - Initial support for building for iOS. + +.. _bugs_fixed_in_nss_3.44: + +`Bugs fixed in NSS 3.44 <#bugs_fixed_in_nss_3.44>`__ +---------------------------------------------------- + +.. container:: + + - `1501542 <https://bugzilla.mozilla.org/show_bug.cgi?id=1501542>`__ - Implement CheckARMSupport + for Android + - `1531244 <https://bugzilla.mozilla.org/show_bug.cgi?id=1531244>`__ - Use \__builtin_bswap64 in + crypto_primitives.h + - `1533216 <https://bugzilla.mozilla.org/show_bug.cgi?id=1533216>`__ - CERT_DecodeCertPackage() + crash with Netscape Certificate Sequences + - `1533616 <https://bugzilla.mozilla.org/show_bug.cgi?id=1533616>`__ - + sdb_GetAttributeValueNoLock should make at most one sql query, rather than one for each + attribute + - `1531236 <https://bugzilla.mozilla.org/show_bug.cgi?id=1531236>`__ - Provide accessor for + CERTCertificate.derCert + - `1536734 <https://bugzilla.mozilla.org/show_bug.cgi?id=1536734>`__ - + lib/freebl/crypto_primitives.c assumes a big endian machine + - `1532384 <https://bugzilla.mozilla.org/show_bug.cgi?id=1532384>`__ - In NSS test certificates, + use @example.com (not @bogus.com) + - `1538479 <https://bugzilla.mozilla.org/show_bug.cgi?id=1538479>`__ - Post-Handshake messages + after async server authentication break when using record layer separation + - `1521578 <https://bugzilla.mozilla.org/show_bug.cgi?id=1521578>`__ - x25519 support in + pk11pars.c + - `1540205 <https://bugzilla.mozilla.org/show_bug.cgi?id=1540205>`__ - freebl build fails with + -DNSS_DISABLE_CHACHAPOLY + - `1532312 <https://bugzilla.mozilla.org/show_bug.cgi?id=1532312>`__ - post-handshake auth + doesn't interoperate with OpenSSL + - `1542741 <https://bugzilla.mozilla.org/show_bug.cgi?id=1542741>`__ - certutil -F crashes with + segmentation fault + - `1546925 <https://bugzilla.mozilla.org/show_bug.cgi?id=1546925>`__ - Allow preceding text in + try comment + - `1534468 <https://bugzilla.mozilla.org/show_bug.cgi?id=1534468>`__ - Expose ChaCha20 primitive + - `1418944 <https://bugzilla.mozilla.org/show_bug.cgi?id=1418944>`__ - Quote CC/CXX variables + passed to nspr + - `1543545 <https://bugzilla.mozilla.org/show_bug.cgi?id=1543545>`__ - Allow to build NSS as a + static library + - `1487597 <https://bugzilla.mozilla.org/show_bug.cgi?id=1487597>`__ - Early data that arrives + before the handshake completes can be read afterwards + - `1548398 <https://bugzilla.mozilla.org/show_bug.cgi?id=1548398>`__ - freebl_gtest not building + on Linux/Mac + - `1548722 <https://bugzilla.mozilla.org/show_bug.cgi?id=1548722>`__ - Fix some Coverity + warnings + - `1540652 <https://bugzilla.mozilla.org/show_bug.cgi?id=1540652>`__ - softoken/sdb.c: Logically + dead code + - `1549413 <https://bugzilla.mozilla.org/show_bug.cgi?id=1549413>`__ - Android log lib is not + included in build + - `1537927 <https://bugzilla.mozilla.org/show_bug.cgi?id=1537927>`__ - IPsec usage is too + restrictive for existing deployments + - `1549608 <https://bugzilla.mozilla.org/show_bug.cgi?id=1549608>`__ - Signature fails with dbm + disabled + - `1549848 <https://bugzilla.mozilla.org/show_bug.cgi?id=1549848>`__ - Allow building NSS for + iOS using gyp + - `1549847 <https://bugzilla.mozilla.org/show_bug.cgi?id=1549847>`__ - NSS's SQLite compilation + warnings make the build fail on iOS + - `1550041 <https://bugzilla.mozilla.org/show_bug.cgi?id=1550041>`__ - freebl not building on + iOS simulator + - `1542950 <https://bugzilla.mozilla.org/show_bug.cgi?id=1542950>`__ - MacOS cipher test + timeouts + + This Bugzilla query returns all the bugs fixed in NSS 3.44: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.44 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.44 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.44 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.45_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.45_release_notes/index.rst new file mode 100644 index 0000000000..e158e8b1a4 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.45_release_notes/index.rst @@ -0,0 +1,224 @@ +.. _mozilla_projects_nss_nss_3_45_release_notes: + +NSS 3.45 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.45 on **5 July 2019**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Bastien Abadie + - Christopher Patton + - Jeremie Courreges-Anglas + - Marcus Burghardt + - Michael Shigorin + - Tomas Mraz + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_45_RTM. NSS 3.45 requires NSPR 4.21 or newer. + + NSS 3.45 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_45_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.45: + +`New in NSS 3.45 <#new_in_nss_3.45>`__ +-------------------------------------- + +.. _new_functionality: + +`New Functionality <#new_functionality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: New Functions + :name: new_functions + + - in *pk11pub.h*: + + - **PK11_FindRawCertsWithSubject** - Finds all certificates on the given slot with the given + subject distinguished name and returns them as DER bytes. If no such certificates can be + found, returns SECSuccess and sets ``*results`` to NULL. If a failure is encountered while + fetching any of the matching certificates, SECFailure is returned and ``*results`` will be + NULL. + +.. _notable_changes_in_nss_3.45: + +`Notable Changes in NSS 3.45 <#notable_changes_in_nss_3.45>`__ +-------------------------------------------------------------- + +.. container:: + + - `Bug 1540403 <https://bugzilla.mozilla.org/show_bug.cgi?id=1540403>`__ - Implement Delegated + Credentials + (`draft-ietf-tls-subcerts <https://datatracker.ietf.org/doc/draft-ietf-tls-subcerts/>`__) + + - This adds a new experimental function: **SSL_DelegateCredential** + - **Note**: In 3.45, ``selfserv`` does not yet support delegated credentials. See `Bug + 1548360 <https://bugzilla.mozilla.org/show_bug.cgi?id=1548360>`__. + - **Note**: In 3.45 the SSLChannelInfo is left unmodified, while an upcoming change in 3.46 + will set ``SSLChannelInfo.authKeyBits`` to that of the delegated credential for better + policy enforcement. See `Bug + 1563078 <https://bugzilla.mozilla.org/show_bug.cgi?id=1563078>`__. + + - `Bug 1550579 <https://bugzilla.mozilla.org/show_bug.cgi?id=1550579>`__ - Replace ARM32 + Curve25519 implementation with one from + `fiat-crypto <https://github.com/mit-plv/fiat-crypto>`__ + - `Bug 1551129 <https://bugzilla.mozilla.org/show_bug.cgi?id=1551129>`__ - Support static + linking on Windows + - `Bug 1552262 <https://bugzilla.mozilla.org/show_bug.cgi?id=1552262>`__ - Expose a function + **PK11_FindRawCertsWithSubject** for finding certificates with a given subject on a given slot + - `Bug 1546229 <https://bugzilla.mozilla.org/show_bug.cgi?id=1546229>`__ - Add IPSEC IKE support + to softoken + - `Bug 1554616 <https://bugzilla.mozilla.org/show_bug.cgi?id=1554616>`__ - Add support for the + Elbrus lcc compiler (<=1.23) + - `Bug 1543874 <https://bugzilla.mozilla.org/show_bug.cgi?id=1543874>`__ - Expose an external + clock for SSL + + - This adds new experimental functions: **SSL_SetTimeFunc**, **SSL_CreateAntiReplayContext**, + **SSL_SetAntiReplayContext**, and **SSL_ReleaseAntiReplayContext**. + - The experimental function **SSL_InitAntiReplay** is removed. + + - `Bug 1546477 <https://bugzilla.mozilla.org/show_bug.cgi?id=1546477>`__ - Various changes in + response to the ongoing FIPS review + + - Note: The source package size has increased substantially due to the new FIPS test vectors. + This will likely prompt follow-on work, but please accept our apologies in the meantime. + +.. _certificate_authority_changes: + +`Certificate Authority Changes <#certificate_authority_changes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The following CA certificates were **Removed**: + + - `Bug 1552374 <https://bugzilla.mozilla.org/show_bug.cgi?id=1552374>`__ - CN = Certinomis - + Root CA + + - SHA-256 Fingerprint: 2A99F5BC1174B73CBB1D620884E01C34E51CCB3978DA125F0E33268883BF4158 + +.. _bugs_fixed_in_nss_3.45: + +`Bugs fixed in NSS 3.45 <#bugs_fixed_in_nss_3.45>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1540541 <https://bugzilla.mozilla.org/show_bug.cgi?id=1540541>`__ - Don't unnecessarily + strip leading 0's from key material during PKCS11 import + (`CVE-2019-11719 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11719>`__) + + - `Bug 1515342 <https://bugzilla.mozilla.org/show_bug.cgi?id=1515342>`__ - More thorough input + checking (`CVE-2019-11729) <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11729>`__ + + - + + .. container:: + + `Bug 1552208 <https://bugzilla.mozilla.org/show_bug.cgi?id=1552208>`__ - Prohibit use of + RSASSA-PKCS1-v1_5 algorithms in TLS 1.3 + (`CVE-2019-11727 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11727>`__) + + - `Bug 1227090 <https://bugzilla.mozilla.org/show_bug.cgi?id=1227090>`__ - Fix a potential + divide-by-zero in makePfromQandSeed from lib/freebl/pqg.c (static analysis) + + - `Bug 1227096 <https://bugzilla.mozilla.org/show_bug.cgi?id=1227096>`__ - Fix a potential + divide-by-zero in PQG_VerifyParams from lib/freebl/pqg.c (static analysis) + + - `Bug 1509432 <https://bugzilla.mozilla.org/show_bug.cgi?id=1509432>`__ - De-duplicate code + between mp_set_long and mp_set_ulong + + - `Bug 1515011 <https://bugzilla.mozilla.org/show_bug.cgi?id=1515011>`__ - Fix a mistake with + ChaCha20-Poly1305 test code where tags could be faked. Only relevant for clients that might + have copied the unit test code verbatim + + - `Bug 1550022 <https://bugzilla.mozilla.org/show_bug.cgi?id=1550022>`__ - Ensure nssutil3 gets + built on Android + + - `Bug 1528174 <https://bugzilla.mozilla.org/show_bug.cgi?id=1528174>`__ - ChaCha20Poly1305 + should no longer modify output length on failure + + - `Bug 1549382 <https://bugzilla.mozilla.org/show_bug.cgi?id=1549382>`__ - Don't leak in PKCS#11 + modules if C_GetSlotInfo() returns error + + - `Bug 1551041 <https://bugzilla.mozilla.org/show_bug.cgi?id=1551041>`__ - Fix builds using GCC + < 4.3 on big-endian architectures + + - + + .. container:: + + `Bug 1554659 <https://bugzilla.mozilla.org/show_bug.cgi?id=1554659>`__ - Add versioning to + OpenBSD builds to fix link time errors using NSS + + - `Bug 1553443 <https://bugzilla.mozilla.org/show_bug.cgi?id=1553443>`__ - Send session ticket + only after handshake is marked as finished + + - `Bug 1550708 <https://bugzilla.mozilla.org/show_bug.cgi?id=1550708>`__ - Fix gyp scripts on + Solaris SPARC so that libfreebl_64fpu_3.so builds + + - `Bug 1554336 <https://bugzilla.mozilla.org/show_bug.cgi?id=1554336>`__ - Optimize away + unneeded loop in mpi.c + + - `Bug 1559906 <https://bugzilla.mozilla.org/show_bug.cgi?id=1559906>`__ - fipstest: use + CKM_TLS12_MASTER_KEY_DERIVE instead of vendor specific mechanism + + - `Bug 1558126 <https://bugzilla.mozilla.org/show_bug.cgi?id=1558126>`__ - + TLS_AES_256_GCM_SHA384 should be marked as FIPS compatible + + - `Bug 1555207 <https://bugzilla.mozilla.org/show_bug.cgi?id=1555207>`__ - + HelloRetryRequestCallback return code for rejecting 0-RTT + + - `Bug 1556591 <https://bugzilla.mozilla.org/show_bug.cgi?id=1556591>`__ - Eliminate races in + uses of PK11_SetWrapKey + + - `Bug 1558681 <https://bugzilla.mozilla.org/show_bug.cgi?id=1558681>`__ - Stop using a global + for anti-replay of TLS 1.3 early data + + - `Bug 1561510 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561510>`__ - Fix a bug where + removing -arch XXX args from CC didn't work + + - `Bug 1561523 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561523>`__ - Add a string for the + new-ish error SSL_ERROR_MISSING_POST_HANDSHAKE_AUTH_EXTENSION + + This Bugzilla query returns all the bugs fixed in NSS 3.45: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.45 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.45 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.45 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.46.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.46.1_release_notes/index.rst new file mode 100644 index 0000000000..a67b54f200 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.46.1_release_notes/index.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_nss_3_46_1_release_notes: + +NSS 3.46.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.46.1 is a patch release for NSS 3.46. The bug fixes in NSS + 3.46.1 are described in the "Bugs Fixed" section below. It was released on 2 October 2019. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_46_1_RTM. NSS 3.46.1 requires NSPR 4.22 or newer. + + NSS 3.46.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_46_1_RTM/src/ + + Other releases are available in NSS Releases. + +.. _new_in_nss_3.46.1: + +`New in NSS 3.46.1 <#new_in_nss_3.46.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.46.1: + +`Bugs fixed in NSS 3.46.1 <#bugs_fixed_in_nss_3.46.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1582343 <https://bugzilla.mozilla.org/show_bug.cgi?id=1582343>`__\ - Soft token MAC + verification not constant time + - `Bug 1577953 <https://bugzilla.mozilla.org/show_bug.cgi?id=1577953>`__\ - Remove arbitrary + HKDF output limit by allocating space as needed + + This Bugzilla query returns all the bugs fixed in NSS 3.46.1: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.46.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.46.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.46.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__\ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.46_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.46_release_notes/index.rst new file mode 100644 index 0000000000..cbfeec56aa --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.46_release_notes/index.rst @@ -0,0 +1,219 @@ +.. _mozilla_projects_nss_nss_3_46_release_notes: + +NSS 3.46 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.46 on **30 August 2019**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Giulio Benetti + - Louis Dassy + - Mike Kaganski + - xhimanshuz + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_46_RTM. NSS 3.46 requires NSPR 4.22 or newer. + + NSS 3.46 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_46_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.46: + +`New in NSS 3.46 <#new_in_nss_3.46>`__ +-------------------------------------- + +.. container:: + + This release contains no significant new functionality, but concentrates on providing improved + performance, stability, and security. Of particular note are significant improvements to AES-GCM + performance on ARM. + +.. _notable_changes_in_nss_3.46: + +`Notable Changes in NSS 3.46 <#notable_changes_in_nss_3.46>`__ +-------------------------------------------------------------- + +.. container:: + +.. _certificate_authority_changes: + +`Certificate Authority Changes <#certificate_authority_changes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The following CA certificates were **Removed**: + + - `Bug 1574670 <https://bugzilla.mozilla.org/show_bug.cgi?id=1574670>`__ - Remove expired + Class 2 Primary root certificate + + - SHA-256 Fingerprint: 0F993C8AEF97BAAF5687140ED59AD1821BB4AFACF0AA9A58B5D57A338A3AFBCB + + - `Bug 1574670 <https://bugzilla.mozilla.org/show_bug.cgi?id=1574670>`__ - Remove expired + UTN-USERFirst-Client root certificate + + - SHA-256 Fingerprint: 43F257412D440D627476974F877DA8F1FC2444565A367AE60EDDC27A412531AE + + - `Bug 1574670 <https://bugzilla.mozilla.org/show_bug.cgi?id=1574670>`__ - Remove expired + Deutsche Telekom Root CA 2 root certificate + + - SHA-256 Fingerprint: B6191A50D0C3977F7DA99BCDAAC86A227DAEB9679EC70BA3B0C9D92271C170D3 + + - `Bug 1566569 <https://bugzilla.mozilla.org/show_bug.cgi?id=1566569>`__ - Remove Swisscom + Root CA 2 root certificate + + - SHA-256 Fingerprint: F09B122C7114F4A09BD4EA4F4A99D558B46E4C25CD81140D29C05613914C3841 + +.. _upcoming_changes_to_default_tls_configuration: + +`Upcoming changes to default TLS configuration <#upcoming_changes_to_default_tls_configuration>`__ +-------------------------------------------------------------------------------------------------- + +.. container:: + + The next NSS team plans to make two changes to the default TLS configuration in NSS 3.47, which + will be released in October: + + - `TLS 1.3 <https://datatracker.ietf.org/doc/html/rfc8446>`__ will be the default maximum TLS + version. See `Bug 1573118 <https://bugzilla.mozilla.org/show_bug.cgi?id=1573118>`__ for + details. + - `TLS extended master secret <https://datatracker.ietf.org/doc/html/rfc7627>`__ will be enabled + by default, where possible. See `Bug + 1575411 <https://bugzilla.mozilla.org/show_bug.cgi?id=1575411>`__ for details. + +.. _bugs_fixed_in_nss_3.46: + +`Bugs fixed in NSS 3.46 <#bugs_fixed_in_nss_3.46>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1572164 <https://bugzilla.mozilla.org/show_bug.cgi?id=1572164>`__ - Don't unnecessarily + free session in NSC_WrapKey + - `Bug 1574220 <https://bugzilla.mozilla.org/show_bug.cgi?id=1574220>`__ - Improve controls + after errors in tstcln, selfserv and vfyserv cmds + - `Bug 1550636 <https://bugzilla.mozilla.org/show_bug.cgi?id=1550636>`__ - Upgrade SQLite in NSS + to a 2019 version + - `Bug 1572593 <https://bugzilla.mozilla.org/show_bug.cgi?id=1572593>`__ - Reset advertised + extensions in ssl_ConstructExtensions + - `Bug 1415118 <https://bugzilla.mozilla.org/show_bug.cgi?id=1415118>`__ - NSS build with + ./build.sh --enable-libpkix fails + - `Bug 1539788 <https://bugzilla.mozilla.org/show_bug.cgi?id=1539788>`__ - Add length checks for + cryptographic primitives + (`CVE-2019-17006 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-17006>`__) + - `Bug 1542077 <https://bugzilla.mozilla.org/show_bug.cgi?id=1542077>`__ - mp_set_ulong and + mp_set_int should return errors on bad values + - `Bug 1572791 <https://bugzilla.mozilla.org/show_bug.cgi?id=1572791>`__ - Read out-of-bounds in + DER_DecodeTimeChoice_Util from SSLExp_DelegateCredential + - `Bug 1560593 <https://bugzilla.mozilla.org/show_bug.cgi?id=1560593>`__ - Cleanup.sh script + does not set error exit code for tests that "Failed with core" + - `Bug 1566601 <https://bugzilla.mozilla.org/show_bug.cgi?id=1566601>`__ - Add Wycheproof test + vectors for AES-KW + - `Bug 1571316 <https://bugzilla.mozilla.org/show_bug.cgi?id=1571316>`__ - curve25519_32.c:280: + undefined reference to \`PR_Assert' when building NSS 3.45 on armhf-linux + - `Bug 1516593 <https://bugzilla.mozilla.org/show_bug.cgi?id=1516593>`__ - Client to generate + new random during renegotiation + - `Bug 1563258 <https://bugzilla.mozilla.org/show_bug.cgi?id=1563258>`__ - fips.sh fails due to + non-existent "resp" directories + - `Bug 1561598 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561598>`__ - Remove + -Wmaybe-uninitialized warning in pqg.c + - `Bug 1560806 <https://bugzilla.mozilla.org/show_bug.cgi?id=1560806>`__ - Increase softoken + password max size to 500 characters + - `Bug 1568776 <https://bugzilla.mozilla.org/show_bug.cgi?id=1568776>`__ - Output paths relative + to repository in NSS coverity + - `Bug 1453408 <https://bugzilla.mozilla.org/show_bug.cgi?id=1453408>`__ - modutil -changepw + fails in FIPS mode if password is an empty string + - `Bug 1564727 <https://bugzilla.mozilla.org/show_bug.cgi?id=1564727>`__ - Use a PSS SPKI when + possible for delegated credentials + - `Bug 1493916 <https://bugzilla.mozilla.org/show_bug.cgi?id=1493916>`__ - fix ppc64 inline + assembler for clang + - `Bug 1561588 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561588>`__ - Remove + -Wmaybe-uninitialized warning in p7env.c + - `Bug 1561548 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561548>`__ - Remove + -Wmaybe-uninitialized warning in pkix_pl_ldapdefaultclient.c + - `Bug 1512605 <https://bugzilla.mozilla.org/show_bug.cgi?id=1512605>`__ - Incorrect alert + description after unencrypted Finished msg + - `Bug 1564715 <https://bugzilla.mozilla.org/show_bug.cgi?id=1564715>`__ - Read /proc/cpuinfo + when AT_HWCAP2 returns 0 + - `Bug 1532194 <https://bugzilla.mozilla.org/show_bug.cgi?id=1532194>`__ - Remove or fix + -DDEBUG_$USER from make builds + - `Bug 1565577 <https://bugzilla.mozilla.org/show_bug.cgi?id=1565577>`__ - Visual Studio's + cl.exe -? hangs on Windows x64 when building nss since changeset + 9162c654d06915f0f15948fbf67d4103a229226f + - `Bug 1564875 <https://bugzilla.mozilla.org/show_bug.cgi?id=1564875>`__ - Improve rebuilding + with build.sh + - `Bug 1565243 <https://bugzilla.mozilla.org/show_bug.cgi?id=1565243>`__ - Support TC_OWNER + without email address in nss taskgraph + - `Bug 1563778 <https://bugzilla.mozilla.org/show_bug.cgi?id=1563778>`__ - Increase maxRunTime + on Mac taskcluster Tools, SSL tests + - `Bug 1561591 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561591>`__ - Remove + -Wmaybe-uninitialized warning in tstclnt.c + - `Bug 1561587 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561587>`__ - Remove + -Wmaybe-uninitialized warning in lgattr.c + - `Bug 1561558 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561558>`__ - Remove + -Wmaybe-uninitialized warning in httpserv.c + - `Bug 1561556 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561556>`__ - Remove + -Wmaybe-uninitialized warning in tls13esni.c + - `Bug 1561332 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561332>`__ - ec.c:28 warning: + comparison of integers of different signs: 'int' and 'unsigned long' + - `Bug 1564714 <https://bugzilla.mozilla.org/show_bug.cgi?id=1564714>`__ - Print certutil + commands during setup + - `Bug 1565013 <https://bugzilla.mozilla.org/show_bug.cgi?id=1565013>`__ - HACL image builder + times out while fetching gpg key + - `Bug 1563786 <https://bugzilla.mozilla.org/show_bug.cgi?id=1563786>`__ - Update hacl-star + docker image to pull specific commit + - `Bug 1559012 <https://bugzilla.mozilla.org/show_bug.cgi?id=1559012>`__ - Improve GCM + perfomance using PMULL2 + - `Bug 1528666 <https://bugzilla.mozilla.org/show_bug.cgi?id=1528666>`__ - Correct resumption + validation checks + - `Bug 1568803 <https://bugzilla.mozilla.org/show_bug.cgi?id=1568803>`__ - More tests for client + certificate authentication + - `Bug 1564284 <https://bugzilla.mozilla.org/show_bug.cgi?id=1564284>`__ - Support profile + mobility across Windows and Linux + - `Bug 1573942 <https://bugzilla.mozilla.org/show_bug.cgi?id=1573942>`__ - Gtest for pkcs11.txt + with different breaking line formats + - `Bug 1575968 <https://bugzilla.mozilla.org/show_bug.cgi?id=1575968>`__ - Add strsclnt option + to enforce the use of either IPv4 or IPv6 + - `Bug 1549847 <https://bugzilla.mozilla.org/show_bug.cgi?id=1549847>`__ - Fix NSS builds on iOS + - `Bug 1485533 <https://bugzilla.mozilla.org/show_bug.cgi?id=1485533>`__ - Enable NSS_SSL_TESTS + on taskcluster + + This Bugzilla query returns all the bugs fixed in NSS 3.46: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.46 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.46 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.46 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.47.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.47.1_release_notes/index.rst new file mode 100644 index 0000000000..ba4f08e0b8 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.47.1_release_notes/index.rst @@ -0,0 +1,78 @@ +.. _mozilla_projects_nss_nss_3_47_1_release_notes: + +NSS 3.47.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.47.1 is a patch release for NSS 3.47. The bug fixes in NSS + 3.47.1 are described in the "Bugs Fixed" section below. It was released on 19 November 2019. + + The NSS team would like to recognize first-time contributors: + + - Craig Disselkoen + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_47_1_RTM. NSS 3.47.1 requires NSPR 4.23 or newer. + + NSS 3.47.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_47_1_RTM/src/ + + Other releases are available in NSS Releases. + +.. _new_in_nss_3.47.1: + +`New in NSS 3.47.1 <#new_in_nss_3.47.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.47.1: + +`Bugs fixed in NSS 3.47.1 <#bugs_fixed_in_nss_3.47.1>`__ +-------------------------------------------------------- + +.. container:: + + - `CVE-2019-11745 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2019-11745>`__ - + EncryptUpdate should use maxout, not block size + - `Bug 1590495 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590495>`__ - Fix a crash that + could be caused by client certificates during startup + - `Bug 1589810 <https://bugzilla.mozilla.org/show_bug.cgi?id=1589810>`__ - Fix compile-time + warnings from uninitialized variables in a perl script + + This Bugzilla query returns all the bugs fixed in NSS 3.47: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.47 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.47.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.47.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.47_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.47_release_notes/index.rst new file mode 100644 index 0000000000..48175d1b17 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.47_release_notes/index.rst @@ -0,0 +1,179 @@ +.. _mozilla_projects_nss_nss_3_47_release_notes: + +NSS 3.47 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.47 on **18 October 2019**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Christian Weisgerber + - Deian Stefan + - Jenine + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_47_RTM. NSS 3.47 requires NSPR 4.23 or newer. + + NSS 3.47 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_47_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _upcoming_changes_to_default_tls_configuration: + +`Upcoming changes to default TLS configuration <#upcoming_changes_to_default_tls_configuration>`__ +-------------------------------------------------------------------------------------------------- + +.. container:: + + The next NSS team plans to make two changes to the default TLS configuration in NSS 3.48, which + will be released in early December: + + - `TLS 1.3 <https://datatracker.ietf.org/doc/html/rfc8446>`__ will be the default maximum TLS + version. See `Bug 1573118 <https://bugzilla.mozilla.org/show_bug.cgi?id=1573118>`__ for + details. + - `TLS extended master secret <https://datatracker.ietf.org/doc/html/rfc7627>`__ will be enabled + by default, where possible. See `Bug + 1575411 <https://bugzilla.mozilla.org/show_bug.cgi?id=1575411>`__ for details. + +.. _notable_changes_in_nss_3.47: + +`Notable Changes in NSS 3.47 <#notable_changes_in_nss_3.47>`__ +-------------------------------------------------------------- + +.. container:: + + - `Bug 1152625 <https://bugzilla.mozilla.org/show_bug.cgi?id=1152625>`__ - Support AES HW + acceleration on ARMv8 + - `Bug 1267894 <https://bugzilla.mozilla.org/show_bug.cgi?id=1267894>`__ - Allow per-socket + run-time ordering of the cipher suites presented in ClientHello + - `Bug 1570501 <https://bugzilla.mozilla.org/show_bug.cgi?id=1570501>`__ - Add CMAC to FreeBL + and PKCS #11 libraries + +.. _bugs_fixed_in_nss_3.47: + +`Bugs fixed in NSS 3.47 <#bugs_fixed_in_nss_3.47>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1459141 <https://bugzilla.mozilla.org/show_bug.cgi?id=1459141>`__ - Make softoken CBC + padding removal constant time + - `Bug 1589120 <https://bugzilla.mozilla.org/show_bug.cgi?id=1589120>`__ - More CBC padding + tests + - `Bug 1465613 <https://bugzilla.mozilla.org/show_bug.cgi?id=1465613>`__ - Add ability to + distrust certificates issued after a certain date for a specified root cert + - `Bug 1588557 <https://bugzilla.mozilla.org/show_bug.cgi?id=1588557>`__ - Bad debug statement + in tls13con.c + - `Bug 1579060 <https://bugzilla.mozilla.org/show_bug.cgi?id=1579060>`__ - mozilla::pkix tag + definitions for issuerUniqueID and subjectUniqueID shouldn't have the CONSTRUCTED bit set + - `Bug 1583068 <https://bugzilla.mozilla.org/show_bug.cgi?id=1583068>`__ - NSS 3.47 should pick + up fix from bug 1575821 (NSPR 4.23) + - `Bug 1152625 <https://bugzilla.mozilla.org/show_bug.cgi?id=1152625>`__ - Support AES HW + acceleration on ARMv8 + - `Bug 1549225 <https://bugzilla.mozilla.org/show_bug.cgi?id=1549225>`__ - Disable DSA signature + schemes for TLS 1.3 + - `Bug 1586947 <https://bugzilla.mozilla.org/show_bug.cgi?id=1586947>`__ - + PK11_ImportAndReturnPrivateKey does not store nickname for EC keys + - `Bug 1586456 <https://bugzilla.mozilla.org/show_bug.cgi?id=1586456>`__ - Unnecessary + conditional in pki3hack, pk11load and stanpcertdb + - `Bug 1576307 <https://bugzilla.mozilla.org/show_bug.cgi?id=1576307>`__ - Check mechanism param + and param length before casting to mechanism-specific structs + - `Bug 1577953 <https://bugzilla.mozilla.org/show_bug.cgi?id=1577953>`__ - Support longer (up to + RFC maximum) HKDF outputs + - `Bug 1508776 <https://bugzilla.mozilla.org/show_bug.cgi?id=1508776>`__ - Remove refcounting + from sftk_FreeSession (CVE-2019-11756) + - `Bug 1494063 <https://bugzilla.mozilla.org/show_bug.cgi?id=1494063>`__ - Support TLS Exporter + in tstclnt and selfserv + - `Bug 1581024 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581024>`__ - Heap overflow in NSS + utility "derdump" + - `Bug 1582343 <https://bugzilla.mozilla.org/show_bug.cgi?id=1582343>`__ - Soft token MAC + verification not constant time + - `Bug 1578238 <https://bugzilla.mozilla.org/show_bug.cgi?id=1578238>`__ - Handle invald tag + sizes for CKM_AES_GCM + - `Bug 1576295 <https://bugzilla.mozilla.org/show_bug.cgi?id=1576295>`__ - Check all bounds when + encrypting with SEED_CBC + - `Bug 1580286 <https://bugzilla.mozilla.org/show_bug.cgi?id=1580286>`__ - NSS rejects TLS 1.2 + records with large padding with SHA384 HMAC + - `Bug 1577448 <https://bugzilla.mozilla.org/show_bug.cgi?id=1577448>`__ - Create additional + nested S/MIME test messages for Thunderbird + - `Bug 1399095 <https://bugzilla.mozilla.org/show_bug.cgi?id=1399095>`__ - Allow nss-try to be + used to test NSPR changes + - `Bug 1267894 <https://bugzilla.mozilla.org/show_bug.cgi?id=1267894>`__ - libSSL should allow + selecting the order of cipher suites in ClientHello + - `Bug 1581507 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581507>`__ - Fix unportable grep + expression in test scripts + - `Bug 1234830 <https://bugzilla.mozilla.org/show_bug.cgi?id=1234830>`__ - [CID 1242894][CID + 1242852] unused values + - `Bug 1580126 <https://bugzilla.mozilla.org/show_bug.cgi?id=1580126>`__ - Fix build failure on + aarch64_be while building freebl/gcm + - `Bug 1385039 <https://bugzilla.mozilla.org/show_bug.cgi?id=1385039>`__ - Build NSPR tests as + part of NSS continuous integration + - `Bug 1581391 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581391>`__ - Fix build on + OpenBSD/arm64 after bug #1559012 + - `Bug 1581041 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581041>`__ - mach-commands -> + mach-completion + - `Bug 1558313 <https://bugzilla.mozilla.org/show_bug.cgi?id=1558313>`__ - Code bugs found by + clang scanners. + - `Bug 1542207 <https://bugzilla.mozilla.org/show_bug.cgi?id=1542207>`__ - Limit policy check on + signature algorithms to known algorithms + - `Bug 1560329 <https://bugzilla.mozilla.org/show_bug.cgi?id=1560329>`__ - drbg: add continuous + self-test on entropy source + - `Bug 1579290 <https://bugzilla.mozilla.org/show_bug.cgi?id=1579290>`__ - ASAN builds should + disable LSAN while building + - `Bug 1385061 <https://bugzilla.mozilla.org/show_bug.cgi?id=1385061>`__ - Build NSPR tests with + NSS make; Add gyp parameters to build/run NSPR tests + - `Bug 1577359 <https://bugzilla.mozilla.org/show_bug.cgi?id=1577359>`__ - Build atob and btoa + for Thunderbird + - `Bug 1579036 <https://bugzilla.mozilla.org/show_bug.cgi?id=1579036>`__ - Confusing error when + trying to export non-existent cert with pk12util + - `Bug 1578626 <https://bugzilla.mozilla.org/show_bug.cgi?id=1578626>`__ - [CID 1453375] UB: + decrement nullptr. + - `Bug 1578751 <https://bugzilla.mozilla.org/show_bug.cgi?id=1578751>`__ - Ensure a consistent + style for pk11_find_certs_unittest.cc + - `Bug 1570501 <https://bugzilla.mozilla.org/show_bug.cgi?id=1570501>`__ - Add CMAC to FreeBL + and PKCS #11 libraries + - `Bug 657379 <https://bugzilla.mozilla.org/show_bug.cgi?id=657379>`__ - NSS uses the wrong OID + for signatureAlgorithm field of signerInfo in CMS for DSA and ECDSA + - `Bug 1576664 <https://bugzilla.mozilla.org/show_bug.cgi?id=1576664>`__ - Remove -mms-bitfields + from mingw NSS build. + - `Bug 1577038 <https://bugzilla.mozilla.org/show_bug.cgi?id=1577038>`__ - add + PK11_GetCertsFromPrivateKey to return all certificates with public keys matching a particular + private key + + This Bugzilla query returns all the bugs fixed in NSS 3.47: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.47 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.47 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.47 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.48.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.48.1_release_notes/index.rst new file mode 100644 index 0000000000..63a7b6b0a2 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.48.1_release_notes/index.rst @@ -0,0 +1,71 @@ +.. _mozilla_projects_nss_nss_3_48_1_release_notes: + +NSS 3.48.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.48.1 is a patch release for NSS 3.48. The bug fixes in NSS + 3.48.1 are described in the "Bugs Fixed" section below. It was released on **13 January 2020**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_48_1_RTM. NSS 3.48.1 requires NSPR 4.23 or newer. + + NSS 3.48.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_48_1_RTM/src/ + + Other releases are available in :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.48.1: + +`New in NSS 3.48.1 <#new_in_nss_3.48.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.48.1: + +`Bugs fixed in NSS 3.48.1 <#bugs_fixed_in_nss_3.48.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1606992 <https://bugzilla.mozilla.org/show_bug.cgi?id=1606992>`__ - Cache the most recent + PBKDF2 password hash, to speed up repeated SDR operations, important with the increased KDF + iteration counts. + + This Bugzilla query returns all the bugs fixed in NSS 3.48: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.48 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.48.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.48.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.48_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.48_release_notes/index.rst new file mode 100644 index 0000000000..21ccc13580 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.48_release_notes/index.rst @@ -0,0 +1,178 @@ +.. _mozilla_projects_nss_nss_3_48_release_notes: + +NSS 3.48 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.48 on **5 December 2019**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Craig Disselkoen + - Giulio Benetti + - Lauri Kasanen + - Tom Prince + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_48_RTM. NSS 3.48 requires NSPR 4.24 or newer. + + NSS 3.48 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_48_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.48: + +`Notable Changes in NSS 3.48 <#notable_changes_in_nss_3.48>`__ +-------------------------------------------------------------- + +.. container:: + + - `TLS 1.3 <https://datatracker.ietf.org/doc/html/rfc8446>`__ is the default maximum TLS + version. See `Bug 1573118 <https://bugzilla.mozilla.org/show_bug.cgi?id=1573118>`__ for + details. + - `TLS extended master secret <https://datatracker.ietf.org/doc/html/rfc7627>`__ is enabled by + default, where possible. See `Bug + 1575411 <https://bugzilla.mozilla.org/show_bug.cgi?id=1575411>`__ for details. + - The master password PBE now uses 10,000 iterations by default when using the default sql + (key4.db) storage. Because using an iteration count higher than 1 with the legacy dbm + (key3.db) storage creates files that are incompatible with previous versions of NSS, + applications that wish to enable it for key3.db are required to set environment variable + NSS_ALLOW_LEGACY_DBM_ITERATION_COUNT=1. Applications may set environment variable + NSS_MIN_MP_PBE_ITERATION_COUNT to request a higher iteration count than the library's default, + or NSS_MAX_MP_PBE_ITERATION_COUNT to request a lower iteration count for test environments. + See `Bug 1562671 <https://bugzilla.mozilla.org/show_bug.cgi?id=1562671>`__ for details. + +.. _certificate_authority_changes: + +`Certificate Authority Changes <#certificate_authority_changes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The following CA certificates were Added: + + - `Bug 1591178 <https://bugzilla.mozilla.org/show_bug.cgi?id=1591178>`__ - Entrust Root + Certification Authority - G4 Cert + + - SHA-256 Fingerprint: DB3517D1F6732A2D5AB97C533EC70779EE3270A62FB4AC4238372460E6F01E88 + +.. _upcoming_changes_in_nss_3.49: + +`Upcoming Changes in NSS 3.49 <#upcoming_changes_in_nss_3.49>`__ +---------------------------------------------------------------- + +.. container:: + + - The legacy DBM database, **libnssdbm**, will no longer be built by default. See `Bug + 1594933 <https://bugzilla.mozilla.org/show_bug.cgi?id=1594933>`__ for details. + +.. _bugs_fixed_in_nss_3.48: + +`Bugs fixed in NSS 3.48 <#bugs_fixed_in_nss_3.48>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1600775 <https://bugzilla.mozilla.org/show_bug.cgi?id=1600775>`__ - Require NSPR 4.24 for + NSS 3.48 + - `Bug 1593401 <https://bugzilla.mozilla.org/show_bug.cgi?id=1593401>`__ - Fix race condition in + self-encrypt functions + - `Bug 1599545 <https://bugzilla.mozilla.org/show_bug.cgi?id=1599545>`__ - Fix assertion and add + test for early Key Update + - `Bug 1597799 <https://bugzilla.mozilla.org/show_bug.cgi?id=1597799>`__ - Fix a crash in + nssCKFWObject_GetAttributeSize + - `Bug 1591178 <https://bugzilla.mozilla.org/show_bug.cgi?id=1591178>`__ - Add Entrust Root + Certification Authority - G4 certificate to NSS + - `Bug 1590001 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590001>`__ - Prevent negotiation + of versions lower than 1.3 after HelloRetryRequest + - `Bug 1596450 <https://bugzilla.mozilla.org/show_bug.cgi?id=1596450>`__ - Added a simplified + and unified MAC implementation for HMAC and CMAC behind PKCS#11 + - `Bug 1522203 <https://bugzilla.mozilla.org/show_bug.cgi?id=1522203>`__ - Remove an old Pentium + Pro performance workaround + - `Bug 1592557 <https://bugzilla.mozilla.org/show_bug.cgi?id=1592557>`__ - Fix PRNG + known-answer-test scripts + - `Bug 1586176 <https://bugzilla.mozilla.org/show_bug.cgi?id=1586176>`__ - EncryptUpdate should + use maxout not block size (CVE-2019-11745) + - `Bug 1593141 <https://bugzilla.mozilla.org/show_bug.cgi?id=1593141>`__ - add \`notBefore\` or + similar "beginning-of-validity-period" parameter to + mozilla::pkix::TrustDomain::CheckRevocation + - `Bug 1591363 <https://bugzilla.mozilla.org/show_bug.cgi?id=1591363>`__ - Fix a PBKDF2 memory + leak in NSC_GenerateKey if key length > MAX_KEY_LEN (256) + - `Bug 1592869 <https://bugzilla.mozilla.org/show_bug.cgi?id=1592869>`__ - Use ARM NEON for + ctr_xor + - `Bug 1566131 <https://bugzilla.mozilla.org/show_bug.cgi?id=1566131>`__ - Ensure SHA-1 fallback + disabled in TLS 1.2 + - `Bug 1577803 <https://bugzilla.mozilla.org/show_bug.cgi?id=1577803>`__ - Mark PKCS#11 token as + friendly if it implements CKP_PUBLIC_CERTIFICATES_TOKEN + - `Bug 1566126 <https://bugzilla.mozilla.org/show_bug.cgi?id=1566126>`__ - POWER GHASH Vector + Acceleration + - `Bug 1589073 <https://bugzilla.mozilla.org/show_bug.cgi?id=1589073>`__ - Use of new + PR_ASSERT_ARG in certdb.c + - `Bug 1590495 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590495>`__ - Fix a crash in + PK11_MakeCertFromHandle + - `Bug 1591742 <https://bugzilla.mozilla.org/show_bug.cgi?id=1591742>`__ - Ensure DES IV length + is valid before usage from PKCS#11 + - `Bug 1588567 <https://bugzilla.mozilla.org/show_bug.cgi?id=1588567>`__ - Enable mozilla::pkix + gtests in NSS CI + - `Bug 1591315 <https://bugzilla.mozilla.org/show_bug.cgi?id=1591315>`__ - Update NSC_Decrypt + length in constant time + - `Bug 1562671 <https://bugzilla.mozilla.org/show_bug.cgi?id=1562671>`__ - Increase NSS MP KDF + default iteration count, by default for modern key4 storage, optionally for legacy key3.db + storage + - `Bug 1590972 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590972>`__ - Use -std=c99 rather + than -std=gnu99 + - `Bug 1590676 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590676>`__ - Fix build if ARM + doesn't support NEON + - `Bug 1575411 <https://bugzilla.mozilla.org/show_bug.cgi?id=1575411>`__ - Enable TLS extended + master secret by default + - `Bug 1590970 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590970>`__ - SSL_SetTimeFunc has + incomplete coverage + - `Bug 1590678 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590678>`__ - Remove + -Wmaybe-uninitialized warning in tls13esni.c + - `Bug 1588244 <https://bugzilla.mozilla.org/show_bug.cgi?id=1588244>`__ - NSS changes for + Delegated Credential key strength checks + - `Bug 1459141 <https://bugzilla.mozilla.org/show_bug.cgi?id=1459141>`__ - Add more CBC padding + tests that missed NSS 3.47 + - `Bug 1590339 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590339>`__ - Fix a memory leak in + btoa.c + - `Bug 1589810 <https://bugzilla.mozilla.org/show_bug.cgi?id=1589810>`__ - fix uninitialized + variable warnings from certdata.perl + - `Bug 1573118 <https://bugzilla.mozilla.org/show_bug.cgi?id=1573118>`__ - Enable TLS 1.3 by + default in NSS + + This Bugzilla query returns all the bugs fixed in NSS 3.48: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.48 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.48 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.48 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.49.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.49.1_release_notes/index.rst new file mode 100644 index 0000000000..72689db1b1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.49.1_release_notes/index.rst @@ -0,0 +1,71 @@ +.. _mozilla_projects_nss_nss_3_49_1_release_notes: + +NSS 3.49.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.49.1 is a patch release for NSS 3.49. The bug fixes in NSS + 3.49.1 are described in the "Bugs Fixed" section below. It was released on **13 January 2020**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_49_1_RTM. NSS 3.49.1 requires NSPR 4.24 or newer. + + NSS 3.49.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_49_1_RTM/src/ + + Other releases are available in :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.49.1: + +`New in NSS 3.49.1 <#new_in_nss_3.49.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.49.1: + +`Bugs fixed in NSS 3.49.1 <#bugs_fixed_in_nss_3.49.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1606992 <https://bugzilla.mozilla.org/show_bug.cgi?id=1606992>`__ - Cache the most recent + PBKDF2 password hash, to speed up repeated SDR operations, important with the increased KDF + iteration counts. + + This Bugzilla query returns all the bugs fixed in NSS 3.49: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.49 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.49.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.49.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.49.2_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.49.2_release_notes/index.rst new file mode 100644 index 0000000000..d9bfed62e2 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.49.2_release_notes/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_nss_3_49_2_release_notes: + +NSS 3.49.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.49.2 is a patch release for NSS 3.49. The bug fixes in NSS + 3.49.2 are described in the "Bugs Fixed" section below. It was released on **23 January 2020**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_49_2_RTM. NSS 3.49.2 requires NSPR 4.24 or newer. + + NSS 3.49.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_49_2_RTM/src/ + + Other releases are available in :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.49.2: + +`New in NSS 3.49.2 <#new_in_nss_3.49.2>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.49.2: + +`Bugs fixed in NSS 3.49.2 <#bugs_fixed_in_nss_3.49.2>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1606992 <https://bugzilla.mozilla.org/show_bug.cgi?id=1606992>`__ - Cache the most + recent PBKDF1 password hash, to speed up repeated SDR operations, important with the increased + KDF iteration counts. NSS 3.49.1 sped up PBKDF2 operations, though PBKDF1 operations are also + relevant for older NSS databases. + - `Bug 1608327 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608327>`__ - Fix compilation + problems with NEON-specific code in freebl + - `Bug 1608895 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608895>`__ - Fix a taskcluster + issue with Python 2 / Python 3 + + This Bugzilla query returns all the bugs fixed in NSS 3.49: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.49 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.49.2 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.49.2 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.49_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.49_release_notes/index.rst new file mode 100644 index 0000000000..9d34d0810f --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.49_release_notes/index.rst @@ -0,0 +1,103 @@ +.. _mozilla_projects_nss_nss_3_49_release_notes: + +NSS 3.49 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.49 on **3 January 2020**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Alex Henrie + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_49_RTM. NSS 3.49 requires NSPR 4.24 or newer. + + NSS 3.49 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_49_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.49: + +`Notable Changes in NSS 3.49 <#notable_changes_in_nss_3.49>`__ +-------------------------------------------------------------- + +.. container:: + + - The legacy DBM database, **libnssdbm**, is no longer built by default when using gyp builds. + See `Bug 1594933 <https://bugzilla.mozilla.org/show_bug.cgi?id=1594933>`__ for details. + +.. _bugs_fixed_in_nss_3.49: + +`Bugs fixed in NSS 3.49 <#bugs_fixed_in_nss_3.49>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1513586 <https://bugzilla.mozilla.org/show_bug.cgi?id=1513586>`__ - Set downgrade + sentinel for client TLS versions lower than 1.2. + - `Bug 1606025 <https://bugzilla.mozilla.org/show_bug.cgi?id=1606025>`__ - Remove + -Wmaybe-uninitialized warning in sslsnce.c + - `Bug 1606119 <https://bugzilla.mozilla.org/show_bug.cgi?id=1606119>`__ - Fix PPC HW Crypto + build failure + - `Bug 1605545 <https://bugzilla.mozilla.org/show_bug.cgi?id=1605545>`__ - Memory leak in + Pk11Install_Platform_Generate + - `Bug 1602288 <https://bugzilla.mozilla.org/show_bug.cgi?id=1602288>`__ - Fix build failure due + to missing posix signal.h + - `Bug 1588714 <https://bugzilla.mozilla.org/show_bug.cgi?id=1588714>`__ - Implement + CheckARMSupport for Win64/aarch64 + - `Bug 1585189 <https://bugzilla.mozilla.org/show_bug.cgi?id=1585189>`__ - NSS database uses + 3DES instead of AES to encrypt DB entries + - `Bug 1603257 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603257>`__ - Fix UBSAN issue in + softoken CKM_NSS_CHACHA20_CTR initialization + - `Bug 1590001 <https://bugzilla.mozilla.org/show_bug.cgi?id=1590001>`__ - Additional HRR Tests + (CVE-2019-17023) + - `Bug 1600144 <https://bugzilla.mozilla.org/show_bug.cgi?id=1600144>`__ - Treat ClientHello + with message_seq of 1 as a second ClientHello + - `Bug 1603027 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603027>`__ - Test that ESNI is + regenerated after HelloRetryRequest + - `Bug 1593167 <https://bugzilla.mozilla.org/show_bug.cgi?id=1593167>`__ - Intermittent + mis-reporting potential security risk SEC_ERROR_UNKNOWN_ISSUER + - `Bug 1535787 <https://bugzilla.mozilla.org/show_bug.cgi?id=1535787>`__ - Fix + automation/release/nss-release-helper.py on MacOS + - `Bug 1594933 <https://bugzilla.mozilla.org/show_bug.cgi?id=1594933>`__ - Disable building DBM + by default + - `Bug 1562548 <https://bugzilla.mozilla.org/show_bug.cgi?id=1562548>`__ - Improve GCM + perfomance on aarch32 + + This Bugzilla query returns all the bugs fixed in NSS 3.49: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.49 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.49 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.49 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.50_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.50_release_notes/index.rst new file mode 100644 index 0000000000..c22d70f70a --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.50_release_notes/index.rst @@ -0,0 +1,120 @@ +.. _mozilla_projects_nss_nss_3_50_release_notes: + +NSS 3.50 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.50 on **7 February 2020**, which is a + minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_50_RTM. NSS 3.50 requires NSPR 4.25 or newer. + + NSS 3.50 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_50_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.50: + +`Notable Changes in NSS 3.50 <#notable_changes_in_nss_3.50>`__ +-------------------------------------------------------------- + +.. container:: + + - Verified primitives from HACL\* were updated, bringing performance improvements for several + platforms. + + - Note that Intel processors with SSE4 but without AVX are currently unable to use the + improved ChaCha20/Poly1305 due to a build issue; such platforms will fall-back to less + optimized algorithms. See `Bug 1609569 for + details. <https://bugzilla.mozilla.org/show_bug.cgi?id=1609569>`__ + + - Updated DTLS 1.3 implementation to Draft-30. See `Bug 1599514 for + details. <https://bugzilla.mozilla.org/show_bug.cgi?id=1599514>`__ + - Added NIST SP800-108 KBKDF - PKCS#11 implementation. See `Bug 1599603 for + details. <https://bugzilla.mozilla.org/show_bug.cgi?id=1599603>`__ + +.. _bugs_fixed_in_nss_3.50: + +`Bugs fixed in NSS 3.50 <#bugs_fixed_in_nss_3.50>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1599514 <https://bugzilla.mozilla.org/show_bug.cgi?id=1599514>`__ - Update DTLS 1.3 + implementation to Draft-30 + - `Bug 1603438 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603438>`__ - Fix native tools + build failure due to lack of zlib include dir if external + - `Bug 1599603 <https://bugzilla.mozilla.org/show_bug.cgi?id=1599603>`__ - NIST SP800-108 KBKDF + - PKCS#11 implementation + - `Bug 1606992 <https://bugzilla.mozilla.org/show_bug.cgi?id=1606992>`__ - Cache the most + recent PBKDF1 password hash, to speed up repeated SDR operations, important with the increased + KDF iteration counts. NSS 3.49.1 sped up PBKDF2 operations, though PBKDF1 operations are also + relevant for older NSS databases (also included in NSS 3.49.2) + - `Bug 1608895 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608895>`__ - Gyp builds on + taskcluster broken by Setuptools v45.0.0 (for lacking Python3) + - `Bug 1574643 <https://bugzilla.mozilla.org/show_bug.cgi?id=1574643>`__ - Upgrade HACL\* + verified implementations of ChaCha20, Poly1305, and 64-bit Curve25519 + - `Bug 1608327 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608327>`__ - Two problems with + NEON-specific code in freebl + - `Bug 1575843 <https://bugzilla.mozilla.org/show_bug.cgi?id=1575843>`__ - Detect AArch64 CPU + features on FreeBSD + - `Bug 1607099 <https://bugzilla.mozilla.org/show_bug.cgi?id=1607099>`__ - Remove the buildbot + configuration + - `Bug 1585429 <https://bugzilla.mozilla.org/show_bug.cgi?id=1585429>`__ - Add more HKDF test + vectors + - `Bug 1573911 <https://bugzilla.mozilla.org/show_bug.cgi?id=1573911>`__ - Add more RSA test + vectors + - `Bug 1605314 <https://bugzilla.mozilla.org/show_bug.cgi?id=1605314>`__ - Compare all 8 bytes + of an mp_digit when clamping in Windows assembly/mp_comba + - `Bug 1604596 <https://bugzilla.mozilla.org/show_bug.cgi?id=1604596>`__ - Update Wycheproof + vectors and add support for CBC, P256-ECDH, and CMAC tests + - `Bug 1608493 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608493>`__ - Use AES-NI for + non-GCM AES ciphers on platforms with no assembly-optimized implementation, such as macOS. + - `Bug 1547639 <https://bugzilla.mozilla.org/show_bug.cgi?id=1547639>`__ - Update zlib in NSS to + 1.2.11 + - `Bug 1609181 <https://bugzilla.mozilla.org/show_bug.cgi?id=1609181>`__ - Detect ARM (32-bit) + CPU features on FreeBSD + - `Bug 1602386 <https://bugzilla.mozilla.org/show_bug.cgi?id=1602386>`__ - Fix build on + FreeBSD/powerpc\* + - `Bug 1608151 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608151>`__ - Introduce + NSS_DISABLE_ALTIVEC + - `Bug 1612623 <https://bugzilla.mozilla.org/show_bug.cgi?id=1612623>`__ - Depend on NSPR 4.25 + - `Bug 1609673 <https://bugzilla.mozilla.org/show_bug.cgi?id=1609673>`__ - Fix a crash when NSS + is compiled without libnssdbm support, but the nssdbm shared object is available anyway. + + This Bugzilla query returns all the bugs fixed in NSS 3.50: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.50 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.50 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.50 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.51.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.51.1_release_notes/index.rst new file mode 100644 index 0000000000..3e510d70cd --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.51.1_release_notes/index.rst @@ -0,0 +1,79 @@ +.. _mozilla_projects_nss_nss_3_51_1_release_notes: + +NSS 3.51.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.51.1 on **3 April 2020**. This is a + minor release focusing on functional bug fixes and low-risk patches only. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_51_1_RTM. NSS 3.51.1 requires NSPR 4.25 or newer. + + NSS 3.51.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_51_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.51.1: + +`Notable Changes in NSS 3.51.1 <#notable_changes_in_nss_3.51.1>`__ +------------------------------------------------------------------ + +.. container:: + + - `Bug 1617968 <https://bugzilla.mozilla.org/show_bug.cgi?id=1617968>`__ - Update Delegated + Credentials implementation to draft-07. + +.. _bugs_fixed_in_nss_3.51.1: + +`Bugs fixed in NSS 3.51.1 <#bugs_fixed_in_nss_3.51.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1619102 <https://bugzilla.mozilla.org/show_bug.cgi?id=1619102>`__ - Add workaround option + to include both DTLS and TLS versions in DTLS supported_versions. + - `Bug 1619056 <https://bugzilla.mozilla.org/show_bug.cgi?id=1619056>`__ - Update README: TLS + 1.3 is not experimental anymore. + - `Bug 1618739 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618739>`__ - Don't assert fuzzer + behavior in SSL_ParseSessionTicket. + - `Bug 1618915 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618915>`__ - Fix UBSAN issue in + ssl_ParseSessionTicket. + - `Bug 1608245 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608245>`__ - Consistently handle + NULL slot/session. + - `Bug 1608250 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608250>`__ - broken fipstest + handling of KI_len. + - `Bug 1617968 <https://bugzilla.mozilla.org/show_bug.cgi?id=1617968>`__ - Update Delegated + Credentials implementation to draft-07. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.51.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.51.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.51_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.51_release_notes/index.rst new file mode 100644 index 0000000000..c1cc36669e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.51_release_notes/index.rst @@ -0,0 +1,103 @@ +.. _mozilla_projects_nss_nss_3_51_release_notes: + +NSS 3.51 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.51 on **6 March 2020**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Dmitry Baryshkov + - Victor Tapia + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_51_RTM. NSS 3.51 requires NSPR 4.25 or newer. + + NSS 3.51 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_51_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.51: + +`Notable Changes in NSS 3.51 <#notable_changes_in_nss_3.51>`__ +-------------------------------------------------------------- + +.. container:: + + - Updated DTLS 1.3 implementation to Draft-34. See `Bug + 1608892 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608892>`__ for details. + +.. _bugs_fixed_in_nss_3.51: + +`Bugs fixed in NSS 3.51 <#bugs_fixed_in_nss_3.51>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1608892 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608892>`__ - Update DTLS 1.3 + implementation to draft-34. + - `Bug 1611209 <https://bugzilla.mozilla.org/show_bug.cgi?id=1611209>`__ - Correct swapped + PKCS11 values of CKM_AES_CMAC and CKM_AES_CMAC_GENERAL + - `Bug 1612259 <https://bugzilla.mozilla.org/show_bug.cgi?id=1612259>`__ - Complete integration + of Wycheproof ECDH test cases + - `Bug 1614183 <https://bugzilla.mozilla.org/show_bug.cgi?id=1614183>`__ - Check if PPC + \__has_include(<sys/auxv.h>) + - `Bug 1614786 <https://bugzilla.mozilla.org/show_bug.cgi?id=1614786>`__ - Fix a compilation + error for ‘getFIPSEnv’ "defined but not used" + - `Bug 1615208 <https://bugzilla.mozilla.org/show_bug.cgi?id=1615208>`__ - Send DTLS version + numbers in DTLS 1.3 supported_versions extension to avoid an incompatibility. + - `Bug 1538980 <https://bugzilla.mozilla.org/show_bug.cgi?id=1538980>`__ - SECU_ReadDERFromFile + calls strstr on a string that isn't guaranteed to be null-terminated + - `Bug 1561337 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561337>`__ - Correct a warning for + comparison of integers of different signs: 'int' and 'unsigned long' in + security/nss/lib/freebl/ecl/ecp_25519.c:88 + - `Bug 1609751 <https://bugzilla.mozilla.org/show_bug.cgi?id=1609751>`__ - Add test for mp_int + clamping + - `Bug 1582169 <https://bugzilla.mozilla.org/show_bug.cgi?id=1582169>`__ - Don't attempt to read + the fips_enabled flag on the machine unless NSS was built with FIPS enabled + - `Bug 1431940 <https://bugzilla.mozilla.org/show_bug.cgi?id=1431940>`__ - Fix a null pointer + dereference in BLAKE2B_Update + - `Bug 1617387 <https://bugzilla.mozilla.org/show_bug.cgi?id=1617387>`__ - Fix compiler warning + in secsign.c + - `Bug 1618400 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618400>`__ - Fix a OpenBSD/arm64 + compilation error: unused variable 'getauxval' + - `Bug 1610687 <https://bugzilla.mozilla.org/show_bug.cgi?id=1610687>`__ - Fix a crash on + unaligned CMACContext.aes.keySchedule when using AES-NI intrinsics + + This Bugzilla query returns all the bugs fixed in NSS 3.51: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.51 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.51 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.51 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.52.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.52.1_release_notes/index.rst new file mode 100644 index 0000000000..3e11cf658e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.52.1_release_notes/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_nss_3_52_1_release_notes: + +NSS 3.52.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.52.1 on **19 May 2020**. This is a + security patch release. + + Thank you to Cesar Pereida Garcia and the Network and Information Security Group (NISEC) at + Tampere University for reporting this issue. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_52_1_RTM. NSS 3.52.1 requires NSPR 4.25 or newer. + + NSS 3.52.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_52_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.52.1: + +`New in NSS 3.52.1 <#new_in_nss_3.52.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.52.1: + +`Bugs fixed in NSS 3.52.1 <#bugs_fixed_in_nss_3.52.1>`__ +-------------------------------------------------------- + +.. container:: + + - `CVE-2020-12399 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2020-12399>`__ - Force a + fixed length for DSA exponentiation + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.52.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.52.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.52_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.52_release_notes/index.rst new file mode 100644 index 0000000000..ef78b8713e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.52_release_notes/index.rst @@ -0,0 +1,158 @@ +.. _mozilla_projects_nss_nss_3_52_release_notes: + +NSS 3.52 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.52 on **1 May 2020**. + + The NSS team would like to recognize first-time contributors: + + - zhujianwei7 + - Hans Petter Jansson + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_52_RTM. NSS 3.52 requires NSPR 4.25 or newer. + + NSS 3.52 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_52_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.52: + +`Notable Changes in NSS 3.52 <#notable_changes_in_nss_3.52>`__ +-------------------------------------------------------------- + +.. container:: + + - `Bug 1603628 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603628>`__ - Update NSS to support + PKCS #11 v3.0. + + - Note: This change modifies the CK_GCM_PARAMS struct to include the ulIvBits field which, + prior to PKCS #11 v3.0, was ambiguously defined and not included in the NSS definition. If + an application is recompiled with NSS 3.52+, this field must be initialized to a value + corresponding to ulIvLen. Alternatively, defining NSS_PKCS11_2_0_COMPAT will yield the old + definition. See the bug for more information. + + - `Bug 1623374 <https://bugzilla.mozilla.org/show_bug.cgi?id=1623374>`__ - Support new PKCS #11 + v3.0 Message Interface for AES-GCM and ChaChaPoly. + - `Bug 1612493 <https://bugzilla.mozilla.org/show_bug.cgi?id=1612493>`__ - Integrate AVX2 + ChaCha20, Poly1305, and ChaCha20Poly1305 from HACL*. + +.. _bugs_fixed_in_nss_3.52: + +`Bugs fixed in NSS 3.52 <#bugs_fixed_in_nss_3.52>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1633498 <https://bugzilla.mozilla.org/show_bug.cgi?id=1633498>`__ - Fix unused variable + 'getauxval' error on iOS compilation. + - `Bug 1630721 <https://bugzilla.mozilla.org/show_bug.cgi?id=1630721>`__ - Add Softoken + functions for FIPS. + - `Bug 1630458 <https://bugzilla.mozilla.org/show_bug.cgi?id=1630458>`__ - Fix problem of GYP + MSVC builds not producing debug symbol files. + - `Bug 1629663 <https://bugzilla.mozilla.org/show_bug.cgi?id=1629663>`__ - Add IKEv1 Quick Mode + KDF. + - `Bug 1629661 <https://bugzilla.mozilla.org/show_bug.cgi?id=1629661>`__ - MPConfig calls in SSL + initialize policy before NSS is initialized. + - `Bug 1629655 <https://bugzilla.mozilla.org/show_bug.cgi?id=1629655>`__ - Support temporary + session objects in ckfw. + - `Bug 1629105 <https://bugzilla.mozilla.org/show_bug.cgi?id=1629105>`__ - Add PKCS11 v3.0 + functions to module debug logger. + - `Bug 1626751 <https://bugzilla.mozilla.org/show_bug.cgi?id=1626751>`__ - Fix error in + generation of fuzz32 docker image after updates. + - `Bug 1625133 <https://bugzilla.mozilla.org/show_bug.cgi?id=1625133>`__ - Fix implicit + declaration of function 'getopt' error. + - `Bug 1624864 <https://bugzilla.mozilla.org/show_bug.cgi?id=1624864>`__ - Allow building of + gcm-arm32-neon on non-armv7 architectures. + - `Bug 1624402 <https://bugzilla.mozilla.org/show_bug.cgi?id=1624402>`__ - Fix compilation error + in Firefox Android. + - `Bug 1624130 <https://bugzilla.mozilla.org/show_bug.cgi?id=1624130>`__ - Require + CK_FUNCTION_LIST structs to be packed. + - `Bug 1624377 <https://bugzilla.mozilla.org/show_bug.cgi?id=1624377>`__ - Fix clang warning for + unknown argument '-msse4'. + - `Bug 1623374 <https://bugzilla.mozilla.org/show_bug.cgi?id=1623374>`__ - Support new PKCS #11 + v3.0 Message Interface for AES-GCM and ChaChaPoly. + - `Bug 1623184 <https://bugzilla.mozilla.org/show_bug.cgi?id=1623184>`__ - Fix freebl_cpuid for + querying Extended Features. + - `Bug 1622555 <https://bugzilla.mozilla.org/show_bug.cgi?id=1622555>`__ - Fix argument parsing + in lowhashtest. + - `Bug 1620799 <https://bugzilla.mozilla.org/show_bug.cgi?id=1620799>`__ - Introduce + NSS_DISABLE_GCM_ARM32_NEON to build on arm32 without NEON support. + - `Bug 1619102 <https://bugzilla.mozilla.org/show_bug.cgi?id=1619102>`__ - Add workaround option + to include both DTLS and TLS versions in DTLS supported_versions. + - `Bug 1619056 <https://bugzilla.mozilla.org/show_bug.cgi?id=1619056>`__ - Update README: TLS + 1.3 is not experimental anymore. + - `Bug 1618915 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618915>`__ - Fix UBSAN issue in + ssl_ParseSessionTicket. + - `Bug 1618739 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618739>`__ - Don't assert fuzzer + behavior in SSL_ParseSessionTicket. + - `Bug 1617968 <https://bugzilla.mozilla.org/show_bug.cgi?id=1617968>`__ - Update Delegated + Credentials implementation to draft-07. + - `Bug 1617533 <https://bugzilla.mozilla.org/show_bug.cgi?id=1617533>`__ - Update HACL\* + dependencies for libintvector.h + - `Bug 1613238 <https://bugzilla.mozilla.org/show_bug.cgi?id=1613238>`__ - Add vector + accelerated SHA2 for POWER 8+. + - `Bug 1612493 <https://bugzilla.mozilla.org/show_bug.cgi?id=1612493>`__ - Integrate AVX2 + ChaCha20, Poly1305, and ChaCha20Poly1305 from HACL*. + - `Bug 1612281 <https://bugzilla.mozilla.org/show_bug.cgi?id=1612281>`__ - Maintain PKCS11 + C_GetAttributeValue semantics on attributes that lack NSS database columns. + - `Bug 1612260 <https://bugzilla.mozilla.org/show_bug.cgi?id=1612260>`__ - Add Wycheproof RSA + test vectors. + - `Bug 1608250 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608250>`__ - broken fipstest + handling of KI_len. + - `Bug 1608245 <https://bugzilla.mozilla.org/show_bug.cgi?id=1608245>`__ - Consistently handle + NULL slot/session. + - `Bug 1603801 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603801>`__ - Avoid dcache + pollution from sdb_measureAccess(). + - `Bug 1603628 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603628>`__ - Update NSS to support + PKCS #11 v3.0. + - `Bug 1561637 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561637>`__ - TLS 1.3 does not work + in FIPS mode. + - `Bug 1531906 <https://bugzilla.mozilla.org/show_bug.cgi?id=1531906>`__ - Fix overzealous + assertion when evicting a cached sessionID or using external cache. + - `Bug 1465613 <https://bugzilla.mozilla.org/show_bug.cgi?id=1465613>`__ - Fix issue where + testlib makefile build produced extraneous object files. + - `Bug 1619959 <https://bugzilla.mozilla.org/show_bug.cgi?id=1619959>`__ - Properly handle + multi-block SEED ECB inputs. + - `Bug 1630925 <https://bugzilla.mozilla.org/show_bug.cgi?id=1630925>`__ - Guard all instances + of NSSCMSSignedData.signerInfo to avoid a CMS crash + - `Bug 1571677 <https://bugzilla.mozilla.org/show_bug.cgi?id=1571677>`__ - Name Constraints + validation: CN treated as DNS name even when syntactically invalid as DNS name + + This Bugzilla query returns all the bugs fixed in NSS 3.52: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.52 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.52 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.52 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.53.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.53.1_release_notes/index.rst new file mode 100644 index 0000000000..3dcf2eb40b --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.53.1_release_notes/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_nss_3_53_1_release_notes: + +NSS 3.53.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.53.1 on **16 June 2020**. This is a + security patch release. + + Thank you to Sohaib ul Hassan, Billy Bob Brumley, and the Network and Information Security Group + (NISEC) at Tampere University for reporting this issue and providing a patch. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_53_1_RTM. NSS 3.53.1 requires NSPR 4.25 or newer. + + NSS 3.53.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_53_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _new_in_nss_3.53.1: + +`New in NSS 3.53.1 <#new_in_nss_3.53.1>`__ +------------------------------------------ + +.. container:: + + No new functionality is introduced in this release. + +.. _bugs_fixed_in_nss_3.53.1: + +`Bugs fixed in NSS 3.53.1 <#bugs_fixed_in_nss_3.53.1>`__ +-------------------------------------------------------- + +.. container:: + + - `CVE-2020-12402 <https://bugzilla.mozilla.org/show_bug.cgi?id=CVE-2020-12402>`__ - Use + constant-time GCD and modular inversion in MPI. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.53.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.53.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.53_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.53_release_notes/index.rst new file mode 100644 index 0000000000..c44ac93a4e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.53_release_notes/index.rst @@ -0,0 +1,128 @@ +.. _mozilla_projects_nss_nss_3_53_release_notes: + +NSS 3.53 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team released Network Security Services (NSS) 3.53 on **29 May 2020**. NSS 3.53 will be a + long-term support release, supporting Firefox 78 ESR. + + The NSS team would like to recognize first-time contributors: + + - Jan-Marek Glogowski + - Jeff Walden + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_53_RTM. NSS 3.53 requires NSPR 4.25 or newer. + + NSS 3.53 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_53_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.53: + +`Notable Changes in NSS 3.53 <#notable_changes_in_nss_3.53>`__ +-------------------------------------------------------------- + +.. container:: + + - When using the Makefiles, NSS can be built in parallel, speeding up those builds to more + similar performance as the build.sh/ninja/gyp system. (`Bug + 290526 <https://bugzilla.mozilla.org/show_bug.cgi?id=290526>`__) + - SEED is now moved into a new freebl directory freebl/deprecated (`Bug + 1636389 <https://bugzilla.mozilla.org/show_bug.cgi?id=1636389>`__). + + - SEED will be disabled by default in a future release of NSS. At that time, users will need + to set the compile-time flag (`Bug + 1622033 <https://bugzilla.mozilla.org/show_bug.cgi?id=1622033>`__) to disable that + deprecation in order to use the algorithm. + - Algorithms marked as deprecated will ultimately be removed. + + - Several root certificates in the Mozilla program now set the CKA_NSS_SERVER_DISTRUST_AFTER + attribute, which NSS consumers can query to further refine trust decisions. (`Bug + 1618404, <https://bugzilla.mozilla.org/show_bug.cgi?id=1618404>`__ `Bug + 1621159 <https://bugzilla.mozilla.org/show_bug.cgi?id=1621159>`__) If a builtin certificate + has a CKA_NSS_SERVER_DISTRUST_AFTER timestamp before the SCT or NotBefore date of a + certificate that builtin issued, then clients can elect not to trust it. + + - This attribute provides a more graceful phase-out for certificate authorities than complete + removal from the root certificate builtin store. + +.. _bugs_fixed_in_nss_3.53: + +`Bugs fixed in NSS 3.53 <#bugs_fixed_in_nss_3.53>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1640260 <https://bugzilla.mozilla.org/show_bug.cgi?id=1640260>`__ - Initialize PBE params + (ASAN fix) + - `Bug 1618404 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618404>`__ - Set + CKA_NSS_SERVER_DISTRUST_AFTER for Symantec root certs + - `Bug 1621159 <https://bugzilla.mozilla.org/show_bug.cgi?id=1621159>`__ - Set + CKA_NSS_SERVER_DISTRUST_AFTER for Consorci AOC, GRCA, and SK ID root certs + - `Bug 1629414 <https://bugzilla.mozilla.org/show_bug.cgi?id=1629414>`__ - PPC64: Correct + compilation error between VMX vs. VSX vector instructions + - `Bug 1639033 <https://bugzilla.mozilla.org/show_bug.cgi?id=1639033>`__ - Fix various compile + warnings in NSS + - `Bug 1640041 <https://bugzilla.mozilla.org/show_bug.cgi?id=1640041>`__ - Fix a null pointer in + security/nss/lib/ssl/sslencode.c:67 + - `Bug 1640042 <https://bugzilla.mozilla.org/show_bug.cgi?id=1640042>`__ - Fix a null pointer in + security/nss/lib/ssl/sslsock.c:4460 + - `Bug 1638289 <https://bugzilla.mozilla.org/show_bug.cgi?id=1638289>`__ - Avoid multiple + definitions of SHA{256,384,512}_\* symbols when linking libfreeblpriv3.so in Firefox on + ppc64le + - `Bug 1636389 <https://bugzilla.mozilla.org/show_bug.cgi?id=1636389>`__ - Relocate deprecated + SEED algorithm + - `Bug 1637083 <https://bugzilla.mozilla.org/show_bug.cgi?id=1637083>`__ - lib/ckfw: No such + file or directory. Stop. + - `Bug 1561331 <https://bugzilla.mozilla.org/show_bug.cgi?id=1561331>`__ - Additional modular + inverse test + - `Bug 1629553 <https://bugzilla.mozilla.org/show_bug.cgi?id=1629553>`__ - Rework and cleanup + gmake builds + - `Bug 1438431 <https://bugzilla.mozilla.org/show_bug.cgi?id=1438431>`__ - Remove mkdepend and + "depend" make target + - `Bug 290526 <https://bugzilla.mozilla.org/show_bug.cgi?id=290526>`__ - Support parallel + building of NSS when using the Makefiles + - `Bug 1636206 <https://bugzilla.mozilla.org/show_bug.cgi?id=1636206>`__ - HACL\* update after + changes in libintvector.h + - `Bug 1636058 <https://bugzilla.mozilla.org/show_bug.cgi?id=1636058>`__ - Fix building NSS on + Debian s390x, mips64el, and riscv64 + - `Bug 1622033 <https://bugzilla.mozilla.org/show_bug.cgi?id=1622033>`__ - Add option to build + without SEED + + This Bugzilla query returns all the bugs fixed in NSS 3.53: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.53 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.53 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.53 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.54_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.54_release_notes/index.rst new file mode 100644 index 0000000000..c85902b2f4 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.54_release_notes/index.rst @@ -0,0 +1,184 @@ +.. _mozilla_projects_nss_nss_3_54_release_notes: + +NSS 3.54 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.54 on **26 June 2020**, which is a + minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_54_RTM. NSS 3.54 requires NSPR 4.26 or newer. + + NSS 3.54 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_54_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.54: + +`Notable Changes in NSS 3.54 <#notable_changes_in_nss_3.54>`__ +-------------------------------------------------------------- + +.. container:: + + - Support for TLS 1.3 external pre-shared keys (`Bug + 1603042 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603042>`__). + - Use ARM Cryptography Extension for SHA256, when available. (`Bug + 1528113 <https://bugzilla.mozilla.org/show_bug.cgi?id=1528113>`__). + +.. _certificate_authority_changes: + +`Certificate Authority Changes <#certificate_authority_changes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The following CA certificates were Added: + + - `Bug 1645186 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645186>`__ - certSIGN Root CA + G2 + + - SHA-256 Fingerprint: 657CFE2FA73FAA38462571F332A2363A46FCE7020951710702CDFBB6EEDA3305 + + - `Bug 1645174 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645174>`__ - e-Szigno Root CA + 2017 + + - SHA-256 Fingerprint: BEB00B30839B9BC32C32E4447905950641F26421B15ED089198B518AE2EA1B99 + + - `Bug 1641716 <https://bugzilla.mozilla.org/show_bug.cgi?id=1641716>`__ - Microsoft ECC Root + Certificate Authority 2017 + + - SHA-256 Fingerprint: 358DF39D764AF9E1B766E9C972DF352EE15CFAC227AF6AD1D70E8E4A6EDCBA02 + + - `Bug 1641716 <https://bugzilla.mozilla.org/show_bug.cgi?id=1641716>`__ - Microsoft RSA Root + Certificate Authority 2017 + + - SHA-256 Fingerprint: C741F70F4B2A8D88BF2E71C14122EF53EF10EBA0CFA5E64CFA20F418853073E0 + + - The following CA certificates were Removed: + + - `Bug 1645199 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645199>`__ - AddTrust Class 1 + CA Root + + - SHA-256 Fingerprint: + 8C7209279AC04E275E16D07FD3B775E80154B5968046E31F52DD25766324E9A7 + + - `Bug 1645199 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645199>`__ - AddTrust External + CA Root + + - SHA-256 Fingerprint: + 687FA451382278FFF0C8B11F8D43D576671C6EB2BCEAB413FB83D965D06D2FF2 + + - `Bug 1641718 <https://bugzilla.mozilla.org/show_bug.cgi?id=1641718>`__ - LuxTrust Global + Root 2 + + - SHA-256 Fingerprint: 54455F7129C20B1447C418F997168F24C58FC5023BF5DA5BE2EB6E1DD8902ED5 + + - `Bug 1639987 <https://bugzilla.mozilla.org/show_bug.cgi?id=1639987>`__ - Staat der + Nederlanden Root CA - G2 + + - SHA-256 Fingerprint: 668C83947DA63B724BECE1743C31A0E6AED0DB8EC5B31BE377BB784F91B6716F + + - `Bug 1618402 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618402>`__ - Symantec Class 2 + Public Primary Certification Authority - G4 + + - SHA-256 Fingerprint: FE863D0822FE7A2353FA484D5924E875656D3DC9FB58771F6F616F9D571BC592 + + - `Bug 1618402 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618402>`__ - Symantec Class 1 + Public Primary Certification Authority - G4 + + - SHA-256 Fingerprint: 363F3C849EAB03B0A2A0F636D7B86D04D3AC7FCFE26A0A9121AB9795F6E176DF + + - `Bug 1618402 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618402>`__ - VeriSign Class 3 + Public Primary Certification Authority - G3 + + - SHA-256 Fingerprint: EB04CF5EB1F39AFA762F2BB120F296CBA520C1B97DB1589565B81CB9A17B7244 + + - A number of certificates had their Email trust bit disabled. See `Bug + 1618402 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618402#c0>`__ for a complete list. + +.. _bugs_fixed_in_nss_3.54: + +`Bugs fixed in NSS 3.54 <#bugs_fixed_in_nss_3.54>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1528113 <https://bugzilla.mozilla.org/show_bug.cgi?id=1528113>`__ - Use ARM Cryptography + Extension for SHA256. + - `Bug 1603042 <https://bugzilla.mozilla.org/show_bug.cgi?id=1603042>`__ - Add TLS 1.3 external + PSK support. + - `Bug 1642802 <https://bugzilla.mozilla.org/show_bug.cgi?id=1642802>`__ - Add uint128 support + for HACL\* curve25519 on Windows. + - `Bug 1645186 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645186>`__ - Add "certSIGN Root CA + G2" root certificate. + - `Bug 1645174 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645174>`__ - Add Microsec's + "e-Szigno Root CA 2017" root certificate. + - `Bug 1641716 <https://bugzilla.mozilla.org/show_bug.cgi?id=1641716>`__ - Add Microsoft's + non-EV root certificates. + - `Bug 1621151 <https://bugzilla.mozilla.org/show_bug.cgi?id=1621151>`__ - Disable email trust + bit for "O=Government Root Certification Authority; C=TW" root. + - `Bug 1645199 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645199>`__ - Remove AddTrust root + certificates. + - `Bug 1641718 <https://bugzilla.mozilla.org/show_bug.cgi?id=1641718>`__ - Remove "LuxTrust + Global Root 2" root certificate. + - `Bug 1639987 <https://bugzilla.mozilla.org/show_bug.cgi?id=1639987>`__ - Remove "Staat der + Nederlanden Root CA - G2" root certificate. + - `Bug 1618402 <https://bugzilla.mozilla.org/show_bug.cgi?id=1618402>`__ - Remove Symantec root + certificates and disable email trust bit. + - `Bug 1640516 <https://bugzilla.mozilla.org/show_bug.cgi?id=1640516>`__ - NSS 3.54 should + depend on NSPR 4.26. + - `Bug 1642146 <https://bugzilla.mozilla.org/show_bug.cgi?id=1642146>`__ - Fix undefined + reference to \`PORT_ZAlloc_stub' in seed.c. + - `Bug 1642153 <https://bugzilla.mozilla.org/show_bug.cgi?id=1642153>`__ - Fix infinite + recursion building NSS. + - `Bug 1642638 <https://bugzilla.mozilla.org/show_bug.cgi?id=1642638>`__ - Fix fuzzing assertion + crash. + - `Bug 1642871 <https://bugzilla.mozilla.org/show_bug.cgi?id=1642871>`__ - Enable + SSL_SendSessionTicket after resumption. + - `Bug 1643123 <https://bugzilla.mozilla.org/show_bug.cgi?id=1643123>`__ - Support + SSL_ExportEarlyKeyingMaterial with External PSKs. + - `Bug 1643557 <https://bugzilla.mozilla.org/show_bug.cgi?id=1643557>`__ - Fix numerous compile + warnings in NSS. + - `Bug 1644774 <https://bugzilla.mozilla.org/show_bug.cgi?id=1644774>`__ - SSL gtests to use + ClearServerCache when resetting self-encrypt keys. + - `Bug 1645479 <https://bugzilla.mozilla.org/show_bug.cgi?id=1645479>`__ - Don't use + SECITEM_MakeItem in secutil.c. + - `Bug 1646520 <https://bugzilla.mozilla.org/show_bug.cgi?id=1646520>`__ - Stricter enforcement + of ASN.1 INTEGER encoding. + + This Bugzilla query returns all the bugs fixed in NSS 3.54: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.54 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.54 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.54 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.55_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.55_release_notes/index.rst new file mode 100644 index 0000000000..c30d4ea540 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.55_release_notes/index.rst @@ -0,0 +1,135 @@ +.. _mozilla_projects_nss_nss_3_55_release_notes: + +NSS 3.55 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.55 on **24 July 2020**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Danh + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_55_RTM. NSS 3.55 requires NSPR 4.27 or newer. + + NSS 3.55 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_55_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.55: + +`Notable Changes in NSS 3.55 <#notable_changes_in_nss_3.55>`__ +-------------------------------------------------------------- + +.. container:: + + - P384 and P521 elliptic curve implementations are replaced with verifiable implementations from + `Fiat-Crypto <https://github.com/mit-plv/fiat-crypto>`__ and + `ECCKiila <https://gitlab.com/nisec/ecckiila/>`__. Special thanks to the Network and + Information Security Group (NISEC) at Tampere University. + - PK11_FindCertInSlot is added. With this function, a given slot can be queried with a + DER-Encoded certificate, providing performance and usability improvements over other + mechanisms. See `Bug 1649633 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649633>`__ for + more details. + - DTLS 1.3 implementation is updated to draft-38. See `Bug + 1647752 <https://bugzilla.mozilla.org/show_bug.cgi?id=1647752>`__ for details. + - NSPR dependency updated to 4.27. + +.. _known_issues: + +`Known Issues <#known_issues>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - On some platforms, using the Makefile builds fails to locate seccomon.h; ensure you are using + make all rather than just make. Another potential workaround is to use the gyp-based build.sh + script. If this affects you, please help us narrow down the cause in `Bug + 1653975. <https://bugzilla.mozilla.org/show_bug.cgi?id=1653975>`__ + +.. _bugs_fixed_in_nss_3.55: + +`Bugs fixed in NSS 3.55 <#bugs_fixed_in_nss_3.55>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1631583 <https://bugzilla.mozilla.org/show_bug.cgi?id=1631583>`__ (CVE-2020-6829, + CVE-2020-12400) - Replace P384 and P521 with new, verifiable implementations from + `Fiat-Crypto <https://github.com/mit-plv/fiat-crypto>`__ and + `ECCKiila <https://gitlab.com/nisec/ecckiila/>`__. + - `Bug 1649487 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649487>`__ - Move overzealous + assertion in VFY_EndWithSignature. + - `Bug 1631573 <https://bugzilla.mozilla.org/show_bug.cgi?id=1631573>`__ (CVE-2020-12401) - + Remove unnecessary scalar padding. + - `Bug 1636771 <https://bugzilla.mozilla.org/show_bug.cgi?id=1636771>`__ (CVE-2020-12403) - + Explicitly disable multi-part ChaCha20 (which was not functioning correctly) and more strictly + enforce tag length. + - `Bug 1649648 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649648>`__ - Don't memcpy zero + bytes (sanitizer fix). + - `Bug 1649316 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649316>`__ - Don't memcpy zero + bytes (sanitizer fix). + - `Bug 1649322 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649322>`__ - Don't memcpy zero + bytes (sanitizer fix). + - `Bug 1653202 <https://bugzilla.mozilla.org/show_bug.cgi?id=1653202>`__ - Fix initialization + bug in blapitest when compiled with NSS_DISABLE_DEPRECATED_SEED. + - `Bug 1646594 <https://bugzilla.mozilla.org/show_bug.cgi?id=1646594>`__ - Fix AVX2 detection in + makefile builds. + - `Bug 1649633 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649633>`__ - Add + PK11_FindCertInSlot to search a given slot for a DER-encoded certificate. + - `Bug 1651520 <https://bugzilla.mozilla.org/show_bug.cgi?id=1651520>`__ - Fix slotLock race in + NSC_GetTokenInfo. + - `Bug 1647752 <https://bugzilla.mozilla.org/show_bug.cgi?id=1647752>`__ - Update DTLS 1.3 + implementation to draft-38. + - `Bug 1649190 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649190>`__ - Run cipher, sdr, and + ocsp tests under standard test cycle in CI. + - `Bug 1649226 <https://bugzilla.mozilla.org/show_bug.cgi?id=1649226>`__ - Add Wycheproof ECDSA + tests. + - `Bug 1637222 <https://bugzilla.mozilla.org/show_bug.cgi?id=1637222>`__ - Consistently enforce + IV requirements for DES and 3DES. + - `Bug 1067214 <https://bugzilla.mozilla.org/show_bug.cgi?id=1067214>`__ - Enforce minimum + PKCS#1 v1.5 padding length in RSA_CheckSignRecover. + - `Bug 1643528 <https://bugzilla.mozilla.org/show_bug.cgi?id=1643528>`__ - Fix compilation error + with -Werror=strict-prototypes. + - `Bug 1646324 <https://bugzilla.mozilla.org/show_bug.cgi?id=1646324>`__ - Advertise PKCS#1 + schemes for certificates in the signature_algorithms extension. + - `Bug 1652331 <https://bugzilla.mozilla.org/show_bug.cgi?id=1652331>`__ - Update NSS 3.55 NSPR + version to 4.27. + + This Bugzilla query returns all the bugs fixed in NSS 3.55: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.55 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.55 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.55 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.56_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.56_release_notes/index.rst new file mode 100644 index 0000000000..f38570d91d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.56_release_notes/index.rst @@ -0,0 +1,98 @@ +.. _mozilla_projects_nss_nss_3_56_release_notes: + +NSS 3.56 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.56 on **21 August 2020**, which is a + minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_56_RTM. NSS 3.56 requires NSPR 4.28 or newer. + + NSS 3.56 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_56_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.56: + +`Notable Changes in NSS 3.56 <#notable_changes_in_nss_3.56>`__ +-------------------------------------------------------------- + +.. container:: + + - NSPR dependency updated to 4.28. + - The known issue where Makefile builds failed to locate seccomon.h was fixed in `Bug + 1653975 <https://bugzilla.mozilla.org/show_bug.cgi?id=1653975>`__. + +.. _bugs_fixed_in_nss_3.56: + +`Bugs fixed in NSS 3.56 <#bugs_fixed_in_nss_3.56>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1650702 <https://bugzilla.mozilla.org/show_bug.cgi?id=1650702>`__ - Support SHA-1 HW + acceleration on ARMv8 + - `Bug 1656981 <https://bugzilla.mozilla.org/show_bug.cgi?id=1656981>`__ - Use MPI comba and + mulq optimizations on x86-64 MacOS. + - `Bug 1654142 <https://bugzilla.mozilla.org/show_bug.cgi?id=1654142>`__ - Add CPU feature + detection for Intel SHA extension. + - `Bug 1648822 <https://bugzilla.mozilla.org/show_bug.cgi?id=1648822>`__ - Add stricter + validation of DH keys in FIPS mode. + - `Bug 1656986 <https://bugzilla.mozilla.org/show_bug.cgi?id=1656986>`__ - Properly detect arm64 + during GYP build architecture detection. + - `Bug 1652729 <https://bugzilla.mozilla.org/show_bug.cgi?id=1652729>`__ - Add build flag to + disable RC2 and relocate to lib/freebl/deprecated. + - `Bug 1656429 <https://bugzilla.mozilla.org/show_bug.cgi?id=1656429>`__ - Correct RTT estimate + used in 0-RTT anti-replay. + - `Bug 1588941 <https://bugzilla.mozilla.org/show_bug.cgi?id=1588941>`__ - Send empty + certificate message when scheme selection fails. + - `Bug 1652032 <https://bugzilla.mozilla.org/show_bug.cgi?id=1652032>`__ - Fix failure to build + in Windows arm64 makefile cross-compilation. + - `Bug 1625791 <https://bugzilla.mozilla.org/show_bug.cgi?id=1625791>`__ - Fix deadlock issue in + nssSlot_IsTokenPresent. + - `Bug 1653975 <https://bugzilla.mozilla.org/show_bug.cgi?id=1653975>`__ - Fix 3.53 regression + by setting "all" as the default makefile target. + - `Bug 1659792 <https://bugzilla.mozilla.org/show_bug.cgi?id=1659792>`__ - Fix broken libpkix + tests with unexpired PayPal cert. + - `Bug 1659814 <https://bugzilla.mozilla.org/show_bug.cgi?id=1659814>`__ - Fix interop.sh + failures with newer tls-interop commit and dependencies. + - `Bug 1656519 <https://bugzilla.mozilla.org/show_bug.cgi?id=1656519>`__ - Update NSPR + dependency to 4.28. + + This Bugzilla query returns all the bugs fixed in NSS 3.56: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.56 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.56 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.56 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.57_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.57_release_notes/index.rst new file mode 100644 index 0000000000..8cec594912 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.57_release_notes/index.rst @@ -0,0 +1,151 @@ +.. _mozilla_projects_nss_nss_3_57_release_notes: + +NSS 3.57 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.57 on **18 September 2020**, which is + a minor release. + + The NSS team would like to recognize first-time contributors: + + - Khem Raj + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_57_RTM. NSS 3.57 requires NSPR 4.29 or newer. + + NSS 3.57 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_57_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.57: + +`Notable Changes in NSS 3.57 <#notable_changes_in_nss_3.57>`__ +-------------------------------------------------------------- + +.. container:: + + - NSPR dependency updated to 4.29. + +.. _certificate_authority_changes: + +`Certificate Authority Changes <#certificate_authority_changes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The following CA certificates were Added: + + - `Bug 1663049 <https://bugzilla.mozilla.org/show_bug.cgi?id=1663049>`__ - CN=Trustwave + Global Certification Authority + + - SHA-256 Fingerprint: 97552015F5DDFC3C8788C006944555408894450084F100867086BC1A2BB58DC8 + + - `Bug 1663049 <https://bugzilla.mozilla.org/show_bug.cgi?id=1663049>`__ - CN=Trustwave + Global ECC P256 Certification Authority + + - SHA-256 Fingerprint: 945BBC825EA554F489D1FD51A73DDF2EA624AC7019A05205225C22A78CCFA8B4 + + - `Bug 1663049 <https://bugzilla.mozilla.org/show_bug.cgi?id=1663049>`__ - CN=Trustwave + Global ECC P384 Certification Authority + + - SHA-256 Fingerprint: 55903859C8C0C3EBB8759ECE4E2557225FF5758BBD38EBD48276601E1BD58097 + + - The following CA certificates were Removed: + + - `Bug 1651211 <https://bugzilla.mozilla.org/show_bug.cgi?id=1651211>`__ - CN=EE + Certification Centre Root CA + + - SHA-256 Fingerprint: + 3E84BA4342908516E77573C0992F0979CA084E4685681FF195CCBA8A229B8A76 + + - `Bug 1656077 <https://bugzilla.mozilla.org/show_bug.cgi?id=1656077>`__ - O=Government Root + Certification Authority; C=TW + + - SHA-256 Fingerprint: + 7600295EEFE85B9E1FD624DB76062AAAAE59818A54D2774CD4C0B2C01131E1B3 + + - Trust settings for the following CA certificates were Modified: + + - `Bug 1653092 <https://bugzilla.mozilla.org/show_bug.cgi?id=1653092>`__ - CN=OISTE WISeKey + Global Root GA CA + + - Websites (server authentication) trust bit removed. + +.. _bugs_fixed_in_nss_3.57: + +`Bugs fixed in NSS 3.57 <#bugs_fixed_in_nss_3.57>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1651211 <https://bugzilla.mozilla.org/show_bug.cgi?id=1651211>`__ - Remove EE + Certification Centre Root CA certificate. + - `Bug 1653092 <https://bugzilla.mozilla.org/show_bug.cgi?id=1653092>`__ - Turn off Websites + Trust Bit for OISTE WISeKey Global Root GA CA. + - `Bug 1656077 <https://bugzilla.mozilla.org/show_bug.cgi?id=1656077>`__ - Remove Taiwan + Government Root Certification Authority certificate. + - `Bug 1663049 <https://bugzilla.mozilla.org/show_bug.cgi?id=1663049>`__ - Add SecureTrust's + Trustwave Global root certificates to NSS. + - `Bug 1659256 <https://bugzilla.mozilla.org/show_bug.cgi?id=1659256>`__ - AArch64 AES + optimization shouldn't be enabled with gcc 4.8. + - `Bug 1651834 <https://bugzilla.mozilla.org/show_bug.cgi?id=1651834>`__ - Fix Clang static + analyzer warnings. + - `Bug 1661378 <https://bugzilla.mozilla.org/show_bug.cgi?id=1661378>`__ - Fix Build failure + with Clang 11. + - `Bug 1659727 <https://bugzilla.mozilla.org/show_bug.cgi?id=1659727>`__ - Fix mpcpucache.c + invalid output constraint on Linux/ARM. + - `Bug 1662738 <https://bugzilla.mozilla.org/show_bug.cgi?id=1662738>`__ - Only run + freebl_fips_RNG_PowerUpSelfTest when linked with NSPR. + - `Bug 1661810 <https://bugzilla.mozilla.org/show_bug.cgi?id=1661810>`__ - Fix Crash @ + arm_aes_encrypt_ecb_128 when building with Clang 11. + - `Bug 1659252 <https://bugzilla.mozilla.org/show_bug.cgi?id=1659252>`__ - Fix Make build with + NSS_DISABLE_DBM=1. + - `Bug 1660304 <https://bugzilla.mozilla.org/show_bug.cgi?id=1660304>`__ - Add POST tests for + KDFs as required by FIPS. + - `Bug 1663346 <https://bugzilla.mozilla.org/show_bug.cgi?id=1663346>`__ - Use 64-bit + compilation on e2k architecture. + - `Bug 1605922 <https://bugzilla.mozilla.org/show_bug.cgi?id=1605922>`__ - Account for negative + sign in mp_radix_size. + - `Bug 1653641 <https://bugzilla.mozilla.org/show_bug.cgi?id=1653641>`__ - Cleanup inaccurate + DTLS comments, code review fixes. + - `Bug 1660372 <https://bugzilla.mozilla.org/show_bug.cgi?id=1660372>`__ - NSS 3.57 should + depend on NSPR 4.29 + - `Bug 1660734 <https://bugzilla.mozilla.org/show_bug.cgi?id=1660734>`__ - Fix Makefile typos. + - `Bug 1660735 <https://bugzilla.mozilla.org/show_bug.cgi?id=1660735>`__ - Fix Makefile typos. + + This Bugzilla query returns all the bugs fixed in NSS 3.57: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.57 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.57 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.57 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.58_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.58_release_notes/index.rst new file mode 100644 index 0000000000..3ad673d369 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.58_release_notes/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_nss_3_58_release_notes: + +NSS 3.58 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.58 on **16 October 2020**, which is a + minor release. + + The NSS team would like to recognize first-time contributors: + + - Ricky Stewart + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_58_RTM. NSS 3.58 requires NSPR 4.29 or newer. + + NSS 3.58 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_58_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.58: + +`Bugs fixed in NSS 3.58 <#bugs_fixed_in_nss_3.58>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1641480 <https://bugzilla.mozilla.org/show_bug.cgi?id=1641480>`__ (CVE-2020-25648) - + Tighten CCS handling for middlebox compatibility mode. + - `Bug 1631890 <https://bugzilla.mozilla.org/show_bug.cgi?id=1631890>`__ - Add support for + Hybrid Public Key Encryption + (`draft-irtf-cfrg-hpke <https://datatracker.ietf.org/doc/draft-irtf-cfrg-hpke/>`__) support. + - `Bug 1657255 <https://bugzilla.mozilla.org/show_bug.cgi?id=1657255>`__ - Add CI tests that + disable SHA1/SHA2 ARM crypto extensions. + - `Bug 1668328 <https://bugzilla.mozilla.org/show_bug.cgi?id=1668328>`__ - Handle spaces in the + Python path name when using gyp on Windows. + - `Bug 1667153 <https://bugzilla.mozilla.org/show_bug.cgi?id=1667153>`__ - Add + PK11_ImportDataKey for data object import. + - `Bug 1665715 <https://bugzilla.mozilla.org/show_bug.cgi?id=1665715>`__ - Pass the embedded SCT + list extension (if present) to TrustDomain::CheckRevocation instead of the notBefore value. + + This Bugzilla query returns all the bugs fixed in NSS 3.58: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.58 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.58 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.58 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.59.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.59.1_release_notes/index.rst new file mode 100644 index 0000000000..0f72238605 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.59.1_release_notes/index.rst @@ -0,0 +1,57 @@ +.. _mozilla_projects_nss_nss_3_59_1_release_notes: + +NSS 3.59.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.59.1 on **18 December 2020**, which + is a patch release for NSS 3.59. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_59_1_RTM. NSS 3.59.1 requires NSPR 4.29 or newer. + + NSS 3.59.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_59_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.59.1: + +`Bugs fixed in NSS 3.59.1 <#bugs_fixed_in_nss_3.59.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1679290 <https://bugzilla.mozilla.org/show_bug.cgi?id=1679290>`__ - Fix potential + deadlock with certain third-party PKCS11 modules. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.59.1 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.59.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.59_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.59_release_notes/index.rst new file mode 100644 index 0000000000..fcf301be26 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.59_release_notes/index.rst @@ -0,0 +1,108 @@ +.. _mozilla_projects_nss_nss_3_59_release_notes: + +NSS 3.59 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.59 on **13 November 2020**, which is + a minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_59_RTM. NSS 3.59 requires NSPR 4.29 or newer. + + NSS 3.59 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_59_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.59: + +`Notable Changes in NSS 3.59 <#notable_changes_in_nss_3.59>`__ +-------------------------------------------------------------- + +.. container:: + + - Exported two existing functions from libnss, CERT_AddCertToListHeadWithData and + CERT_AddCertToListTailWithData + +.. _build_requirements: + +`Build Requirements <#build_requirements>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS will soon require GCC 4.8 or newer. Gyp-based builds will stop supporting older GCC + versions in the next release, NSS 3.60 planned for December, followed later by the make-based + builds. Users of older GCC versions can continue to use the make-based build system while they + upgrade to newer versions of GCC. + +.. _bugs_fixed_in_nss_3.59: + +`Bugs fixed in NSS 3.59 <#bugs_fixed_in_nss_3.59>`__ +---------------------------------------------------- + +.. container:: + + - `Bug 1607449 <https://bugzilla.mozilla.org/show_bug.cgi?id=1607449>`__ - Lock + cert->nssCertificate to prevent a potential data race + - `Bug 1672823 <https://bugzilla.mozilla.org/show_bug.cgi?id=1672823>`__ - Add Wycheproof test + cases for HMAC, HKDF, and DSA + - `Bug 1663661 <https://bugzilla.mozilla.org/show_bug.cgi?id=1663661>`__ - Guard against NULL + token in nssSlot_IsTokenPresent + - `Bug 1670835 <https://bugzilla.mozilla.org/show_bug.cgi?id=1670835>`__ - Support enabling and + disabling signatures via Crypto Policy + - `Bug 1672291 <https://bugzilla.mozilla.org/show_bug.cgi?id=1672291>`__ - Resolve libpkix OCSP + failures on SHA1 self-signed root certs when SHA1 signatures are disabled. + - `Bug 1644209 <https://bugzilla.mozilla.org/show_bug.cgi?id=1644209>`__ - Fix broken + SelectedCipherSuiteReplacer filter to solve some test intermittents + - `Bug 1672703 <https://bugzilla.mozilla.org/show_bug.cgi?id=1672703>`__ - Tolerate the first + CCS in TLS 1.3 to fix a regression in our CVE-2020-25648 fix that broke purple-discord + - `Bug 1666891 <https://bugzilla.mozilla.org/show_bug.cgi?id=1666891>`__ - Support key + wrap/unwrap with RSA-OAEP + - `Bug 1667989 <https://bugzilla.mozilla.org/show_bug.cgi?id=1667989>`__ - Fix gyp linking on + Solaris + - `Bug 1668123 <https://bugzilla.mozilla.org/show_bug.cgi?id=1668123>`__ - Export + CERT_AddCertToListHeadWithData and CERT_AddCertToListTailWithData from libnss + - `Bug 1634584 <https://bugzilla.mozilla.org/show_bug.cgi?id=1634584>`__ - Set + CKA_NSS_SERVER_DISTRUST_AFTER for Trustis FPS Root CA + - `Bug 1663091 <https://bugzilla.mozilla.org/show_bug.cgi?id=1663091>`__ - Remove unnecessary + assertions in the streaming ASN.1 decoder that affected decoding certain PKCS8 private keys + when using NSS debug builds + - `Bug 1670839 <https://bugzilla.mozilla.org/show_bug.cgi?id=1670839>`__ - Use ARM crypto + extension for AES, SHA1 and SHA2 on MacOS. + + This Bugzilla query returns all the bugs fixed in NSS 3.59: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.59 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.59 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.59 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.60.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.60.1_release_notes/index.rst new file mode 100644 index 0000000000..ee8062b4d5 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.60.1_release_notes/index.rst @@ -0,0 +1,58 @@ +.. _mozilla_projects_nss_nss_3_60_1_release_notes: + +NSS 3.60.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team released Network Security Services (NSS) 3.60.1 on **4 January 2021**, which is a + patch release for NSS 3.60. + + + +`Distribution information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_60_1_RTM. NSS 3.60.1 requires NSPR 4.29 or newer. + + NSS 3.60.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_60_1_RTM/src/ + + Other releases are available at :ref:`mozilla_projects_nss_nss_releases#past_releases`. + +.. _bugs_fixed_in_nss_3.60.1: + +`Bugs fixed in NSS 3.60.1 <#bugs_fixed_in_nss_3.60.1>`__ +-------------------------------------------------------- + +.. container:: + + - `Bug 1682863 <https://bugzilla.mozilla.org/show_bug.cgi?id=1682863>`__ - Fix remaining hang + issues with slow third-party PKCS #11 tokens. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.60.1 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.60.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report at + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ under the NSS + product.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.60_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.60_release_notes/index.rst new file mode 100644 index 0000000000..e2a7171899 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.60_release_notes/index.rst @@ -0,0 +1,144 @@ +.. _mozilla_projects_nss_nss_3_60_release_notes: + +NSS 3.60 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team has released Network Security Services (NSS) 3.60 on **11 December 2020**, which is + a minor release. + + The NSS team would like to recognize first-time contributors: + + - yogesh + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_60_RTM. NSS 3.60 requires NSPR 4.29 or newer. + + NSS 3.60 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_60_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _notable_changes_in_nss_3.60: + +`Notable Changes in NSS 3.60 <#notable_changes_in_nss_3.60>`__ +-------------------------------------------------------------- + +.. container:: + + - TLS 1.3 Encrypted Client Hello (draft-ietf-tls-esni-08) support has been added, replacing the + ESNI (draft-ietf-tls-esni-01). See `bug + 1654332 <https://bugzilla.mozilla.org/show_bug.cgi?id=1654332>`__ for more information. + +.. _certificate_authority_changes: + +`Certificate Authority Changes <#certificate_authority_changes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - The following CA certificates were added: + + - `Bug 1678166 <https://bugzilla.mozilla.org/show_bug.cgi?id=1678166>`__ - NAVER Global Root + Certification Authority + + - SHA-256 Fingerprint: 88F438DCF8FFD1FA8F429115FFE5F82AE1E06E0C70C375FAAD717B34A49E7265 + + - The following CA certificates were removed in `bug + 1670769 <https://bugzilla.mozilla.org/show_bug.cgi?id=1670769>`__: + + - GeoTrust Global CA + + - SHA-256 Fingerprint: + FF856A2D251DCD88D36656F450126798CFABAADE40799C722DE4D2B5DB36A73A + + - GeoTrust Primary Certification Authority + + - SHA-256 Fingerprint: 37D51006C512EAAB626421F1EC8C92013FC5F82AE98EE533EB4619B8DEB4D06C + + - GeoTrust Primary Certification Authority - G3 + + - SHA-256 Fingerprint: B478B812250DF878635C2AA7EC7D155EAA625EE82916E2CD294361886CD1FBD4 + + - thawte Primary Root CA + + - SHA-256 Fingerprint: 8D722F81A9C113C0791DF136A2966DB26C950A971DB46B4199F4EA54B78BFB9F + + - thawte Primary Root CA - G3 + + - SHA-256 Fingerprint: 4B03F45807AD70F21BFC2CAE71C9FDE4604C064CF5FFB686BAE5DBAAD7FDD34C + + - VeriSign Class 3 Public Primary Certification Authority - G4 + + - SHA-256 Fingerprint: 69DDD7EA90BB57C93E135DC85EA6FCD5480B603239BDC454FC758B2A26CF7F79 + + - VeriSign Class 3 Public Primary Certification Authority - G5 + + - SHA-256 Fingerprint: 9ACFAB7E43C8D880D06B262A94DEEEE4B4659989C3D0CAF19BAF6405E41AB7DF + + - thawte Primary Root CA - G2 + + - SHA-256 Fingerprint: A4310D50AF18A6447190372A86AFAF8B951FFB431D837F1E5688B45971ED1557 + + - GeoTrust Universal CA + + - SHA-256 Fingerprint: A0459B9F63B22559F5FA5D4C6DB3F9F72FF19342033578F073BF1D1B46CBB912 + + - GeoTrust Universal CA 2 + + - SHA-256 Fingerprint: A0234F3BC8527CA5628EEC81AD5D69895DA5680DC91D1CB8477F33F878B95B0B + +.. _bugs_fixed_in_nss_3.60: + +`Bugs fixed in NSS 3.60 <#bugs_fixed_in_nss_3.60>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1654332 - Implement Encrypted Client Hello (draft-ietf-tls-esni-08) in NSS. + - Bug 1678189 - Update CA list version to 2.46. + - Bug 1670769 - Remove 10 GeoTrust, thawte, and VeriSign root certs from NSS. + - Bug 1678166 - Add NAVER Global Root Certification Authority root cert to NSS. + - Bug 1678384 - Add a build flag to allow building nssckbi-testlib in m-c. + - Bug 1570539 - Remove -X alt-server-hello option from tstclnt. + - Bug 1675523 - Fix incorrect pkcs11t.h value CKR_PUBLIC_KEY_INVALID. + - Bug 1642174 - Fix PowerPC ABI version 1 build failure. + - Bug 1674819 - Fix undefined shift in fuzzer mode. + - Bug 1678990 - Fix ARM crypto extensions detection on macOS. + - Bug 1679290 - Fix lock order inversion and potential deadlock with libnsspem. + - Bug 1680400 - Fix memory leak in PK11_UnwrapPrivKey. + + This Bugzilla query returns all the bugs fixed in NSS 3.60: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.60 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.60 shared libraries are backward compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.60 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report with + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.61_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.61_release_notes/index.rst new file mode 100644 index 0000000000..3d4af88895 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.61_release_notes/index.rst @@ -0,0 +1,65 @@ +.. _mozilla_projects_nss_nss_3_61_release_notes: + +NSS 3.61 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team released Network Security Services (NSS) 3.61 on **22 January 2021**, which is a + minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_61_RTM. NSS 3.61 requires NSPR 4.29 or newer. + + NSS 3.61 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_61_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.61: + +`Bugs fixed in NSS 3.61 <#bugs_fixed_in_nss_3.61>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1682071 - Fix issue with IKE Quick mode deriving incorrect key values under certain + conditions. + - Bug 1684300 - Fix default PBE iteration count when NSS is compiled with NSS_DISABLE_DBM. + - Bug 1651411 - Improve constant-timeness in RSA operations. + - Bug 1677207 - Upgrade Google Test version to latest release. + - Bug 1654332 - Add aarch64-make target to nss-try. + + This Bugzilla query returns all the bugs fixed in NSS 3.61: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.61 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.61 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.61 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS).
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.62_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.62_release_notes/index.rst new file mode 100644 index 0000000000..e535ddee89 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.62_release_notes/index.rst @@ -0,0 +1,84 @@ +.. _mozilla_projects_nss_nss_3_62_release_notes: + +NSS 3.62 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + The NSS team released Network Security Services (NSS) 3.62 on **19 February 2021**, which is a + minor release. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_62_RTM. NSS 3.62 requires NSPR 4.29 or newer. + + NSS 3.62 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_62_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.62: + +`Bugs fixed in NSS 3.62 <#bugs_fixed_in_nss_3.62>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1688374 - Fix parallel build NSS-3.61 with make. + - Bug 1682044 - pkix_Build_GatherCerts() + pkix_CacheCert_Add() can corrupt "cachedCertTable". + - Bug 1690583 - Fix CH padding extension size calculation. + - Bug 1690421 - Adjust 3.62 ABI report formatting for new libabigail. + - Bug 1690421 - Install packaged libabigail in docker-builds image. + - Bug 1689228 - Minor ECH -09 fixes for interop testing, fuzzing. + - Bug 1674819 - Fixup a51fae403328, enum type may be signed. + - Bug 1681585 - Add ECH support to selfserv. + - Bug 1681585 - Update ECH to Draft-09. + - Bug 1678398 - Add Export/Import functions for HPKE context. + - Bug 1678398 - Update HPKE to draft-07. + + This Bugzilla query returns all the bugs fixed in NSS 3.62: + + https://bugzilla.mozilla.org/buglist.cgi?resolution=FIXED&classification=Components&query_format=advanced&product=NSS&target_milestone=3.62 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.62 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.62 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + Due to changes to MDN, we have been notified that the NSS documentation will have to move off of + MDN. It is not fully clear yet, but the proposed solution is to move the documentation in-tree + (nss/docs), to the md/sphinx format, and have it either rendered as a sub-section of the Firefox + source docs or as a standalone website. More information will follow in the NSS 3.63 notes. + + Regarding the Release day, in order to organize release process better and avoid issues, we will + likely move the release day to Thursdays. Please take a look at the release calendar for the + exact dates.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.63.1_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.63.1_release_notes/index.rst new file mode 100644 index 0000000000..ca8a733cb1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.63.1_release_notes/index.rst @@ -0,0 +1,66 @@ +.. _mozilla_projects_nss_nss_3_63_1_release_notes: + +NSS 3.63.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.63.1 was released on **6 April 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_63_1_RTM. NSS 3.63.1 requires NSPR 4.30 or newer. + + NSS 3.63.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_63_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.63.1: + +`Bugs fixed in NSS 3.63.1 <#bugs_fixed_in_nss_3.63.1>`__ +-------------------------------------------------------- + +.. container:: + + - REVERTING Bug 1692094 - Turn off Websites Trust Bit for 'Chambers of Commerce Root - 2008' and + 'Global Chambersign Root - 2008’. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.63.1 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.63.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + This version of NSS contains a minor update to the root CAs due to a delay in deprecation. + + This revert is temporary in order to prevent breaking websites with Firefox 88 and the change has + been reinstated in NSS 3.64 for Firefox 89.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.63_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.63_release_notes/index.rst new file mode 100644 index 0000000000..ec6c49f76f --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.63_release_notes/index.rst @@ -0,0 +1,90 @@ +.. _mozilla_projects_nss_nss_3_63_release_notes: + +NSS 3.63 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.63 was released on **18 March 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_63_RTM. NSS 3.63 requires NSPR 4.30 or newer. + + NSS 3.63 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_63_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.63: + +`Bugs fixed in NSS 3.63 <#bugs_fixed_in_nss_3.63>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1688374 - Fix parallel build NSS-3.61 with make. + - Bug 1697380 - Make a clang-format run on top of helpful contributions. + - Bug 1683520 - ECCKiila P384, change syntax of nested structs initialization to prevent build + isses with GCC 4.8. + - Bug 1683520 - [lib/freebl/ecl] P-384: allow zero scalars in dual scalar multiplication. + - Bug 1683520 - ECCKiila P521, change syntax of nested structs initialization to prevent build + isses with GCC 4.8. + - Bug 1683520 - [lib/freebl/ecl] P-521: allow zero scalars in dual scalar multiplication. + - Bug 1696800 - HACL\* update March 2021 - c95ab70fcb2bc21025d8845281bc4bc8987ca683. + - Bug 1694214 - tstclnt can't enable middlebox compat mode. + - Bug 1694392 - NSS does not work with PKCS #11 modules not supporting profiles. + - Bug 1685880 - Minor fix to prevent unused variable on early return. + - Bug 1685880 - Fix for the gcc compiler version 7 to support setenv with nss build. + - Bug 1693217 - Increase nssckbi.h version number for March 2021 batch of root CA changes, CA + list version 2.48. + - Bug 1692094 - Set email distrust after to 21-03-01 for Camerfirma's 'Chambers of Commerce' and + 'Global Chambersign' roots. + - Bug 1618407 - Symantec root certs - Set CKA_NSS_EMAIL_DISTRUST_AFTER. + - Bug 1693173 - Add GlobalSign R45, E45, R46, and E46 root certs to NSS. + - Bug 1683738 - Add AC RAIZ FNMT-RCM SERVIDORES SEGUROS root cert to NSS. + - Bug 1686854 - Remove GeoTrust PCA-G2 and VeriSign Universal root certs from NSS. + - Bug 1687822 - Turn off Websites trust bit for the “Staat der Nederlanden Root CA - G3” root + cert in NSS. + - Bug 1692094 - Turn off Websites Trust Bit for 'Chambers of Commerce Root - 2008' and 'Global + Chambersign Root - 2008’. + - Bug 1694291 - Tracing fixes for ECH. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.63 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.63 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + This version of NSS contains a significant update to the root CAs. + + Discussions about moving the documentation are still ongoing. (See discussion in the 3.62 release + notes.)
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_releases/nss_3.64_release_notes/index.rst b/security/nss/doc/rst/legacy/nss_releases/nss_3.64_release_notes/index.rst new file mode 100644 index 0000000000..ee5e36f08a --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_releases/nss_3.64_release_notes/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_nss_3_64_release_notes: + +NSS 3.64 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.64 was released on **15 April 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_64_RTM. NSS 3.64 requires NSPR 4.30 or newer. + + NSS 3.64 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_64_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.64: + +`Bugs fixed in NSS 3.64 <#bugs_fixed_in_nss_3.64>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1705286 - Properly detect mips64. + - Bug 1687164 - Introduce NSS_DISABLE_CRYPTO_VSX and disable_crypto_vsx. + - Bug 1698320 - replace \__builtin_cpu_supports("vsx") with ppc_crypto_support() for clang. + - Bug 1613235 - Add POWER ChaCha20 stream cipher vector acceleration. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.64 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.64 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + This version of NSS contains a number of contributions for "unsupported platforms". We would like + to thank the authors and the reviewers for their contributions to NSS. + + Discussions about moving the documentation are still ongoing. (See discussion in the 3.62 release + notes.)
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/enc_dec_mac_output_plblic_key_as_csr/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/enc_dec_mac_output_plblic_key_as_csr/index.rst new file mode 100644 index 0000000000..dfa740a911 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/enc_dec_mac_output_plblic_key_as_csr/index.rst @@ -0,0 +1,1697 @@ +.. _mozilla_projects_nss_nss_sample_code_enc_dec_mac_output_plblic_key_as_csr: + +Enc Dec MAC Output Public Key as CSR +==================================== + +.. _nss_sample_code_5_encryptiondecryption_and_mac_and_output_public_as_a_csr.: + +`NSS Sample Code 5: Encryption/Decryption and MAC and output Public as a CSR. <#nss_sample_code_5_encryptiondecryption_and_mac_and_output_public_as_a_csr.>`__ +-------------------------------------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + Generates encryption/mac keys and outputs public key as certificate signing request + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + /* NSPR Headers */ + #include + #include + #include + #include + #include + #include + #include + + /* NSS headers */ + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + /* our samples utilities */ + #include "util.h" + + #define BUFFERSIZE 80 + #define DIGESTSIZE 16 + #define PTEXT_MAC_BUFFER_SIZE 96 + #define CIPHERSIZE 96 + #define BLOCKSIZE 32 + #define DEFAULT_KEY_BITS 1024 + + + #define CIPHER_HEADER "-----BEGIN CIPHER-----" + #define CIPHER_TRAILER "-----END CIPHER-----" + #define ENCKEY_HEADER "-----BEGIN WRAPPED ENCKEY-----" + #define ENCKEY_TRAILER "-----END WRAPPED ENCKEY-----" + #define MACKEY_HEADER "-----BEGIN WRAPPED MACKEY-----" + #define MACKEY_TRAILER "-----END WRAPPED MACKEY-----" + #define IV_HEADER "-----BEGIN IV-----" + #define IV_TRAILER "-----END IV-----" + #define MAC_HEADER "-----BEGIN MAC-----" + #define MAC_TRAILER "-----END MAC-----" + #define PAD_HEADER "-----BEGIN PAD-----" + #define PAD_TRAILER "-----END PAD-----" + #define LAB_HEADER "-----BEGIN KEY LABEL-----" + #define LAB_TRAILER "-----END KEY LABEL-----" + #define PUBKEY_HEADER "-----BEGIN PUB KEY -----" + #define PUBKEY_TRAILER "-----END PUB KEY -----" + #define NS_CERTREQ_HEADER "-----BEGIN NEW CERTIFICATE REQUEST-----" + #define NS_CERTREQ_TRAILER "-----END NEW CERTIFICATE REQUEST-----" + + + typedef enum { + GEN_CSR, + ENCRYPT, + DECRYPT, + UNKNOWN + } CommandType; + + typedef enum { + SYMKEY = 0, + MACKEY = 1, + IV = 2, + MAC = 3, + PAD = 4, + PUBKEY = 5, + LAB = 6 + } HeaderType; + + /* This is conditionalized because PORT_ErrorToString was introduced with nss 3.13. + * Though PR_ErrorToString was available, support for it in nss wasn't. + * FIXME: samples should determine the version of nss that's available and refuse + * to run if not 3.13 or higher. + */ + #ifndef PORT_ErrorToString + #ifndef SEC_ERROR_BASE + #define SEC_ERROR_BASE (-0x2000) + #define PORT_ErrorToString(err) PR_ErrorToString((err), PR_LANGUAGE_I_DEFAULT) + #endif + #endif + + + /* + * Print usage message and exit + */ + static void + Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s -c -d [-z ] " + "[-p | -f ] -s -r -i -o \n\n", + progName); + fprintf(stderr, "%-20s Specify 'G' for generating RSA keypair for wrapping\n\n", + "G"); + fprintf(stderr, "%-20s Specify 'E' for encrypt operation\n\n", + "E"); + fprintf(stderr, "%-20s Specify 'D' for decrypt operation\n\n", + "D"); + fprintf(stderr, "%-20s Specify db directory path\n\n", + "-d "); + fprintf(stderr, "%-20s Specify db password [optional]\n\n", + "-p "); + fprintf(stderr, "%-20s Specify db password file [optional]\n\n", + "-f "); + fprintf(stderr, "%-20s Specify noise file name [optional]\n\n", + "-z "); + fprintf(stderr, "%-21s Specify subject\n\n", + "-s "); + fprintf(stderr, "%-21s Specify certficate request file name\n\n", + "-r "); + fprintf(stderr, "%-21s Specify an input file name\n\n", + "-i "); + fprintf(stderr, "%-21s Specify an output file name\n\n", + "-o "); + fprintf(stderr, "%-7s For encrypt, it takes as an input file and produces\n", + "Note :"); + fprintf(stderr, "%-7s .enc and .header as intermediate output files.\n\n", + ""); + fprintf(stderr, "%-7s For decrypt, it takes .enc and .header\n", + ""); + fprintf(stderr, "%-7s as input files and produces as a final output file.\n\n", + ""); + exit(-1); + } + + + /* Map option letter enumerated commad type */ + static CommandType option2Command(const char* c) + { + switch (*c) { + case 'G': return GEN_CSR; + case 'E': return ENCRYPT; + case 'D': return DECRYPT; + default: return UNKNOWN; + } + } + + /* + * Wrap the symkey using public key + */ + SECStatus + WrapKey(PK11SymKey* key, SECKEYPublicKey *pubKey, SECItem **wrappedKey) + { + SECStatus rv; + SECItem *data = (SECItem *)PORT_ZAlloc(sizeof(SECItem)); + + if (!data) { + PR_fprintf(PR_STDERR, "Error while allocating memory\n"); + rv = SECFailure; + goto cleanup; + } + + data->len = SECKEY_PublicKeyStrength(pubKey); + data->data = (unsigned char*)PORT_ZAlloc((data->len)*sizeof(unsigned int)); + + if (!data->data) { + PR_fprintf(PR_STDERR, "Error while allocating memory\n"); + rv = SECFailure; + goto cleanup; + } + + rv = PK11_PubWrapSymKey(CKM_RSA_PKCS, pubKey, key, data); + if (rv != SECSuccess) { + rv = SECFailure; + } else { + *wrappedKey = data; + return SECSuccess; + } + + cleanup: + if (data) { + SECITEM_FreeItem(data, PR_TRUE); + } + return rv; + } + + /* + * Generate a Symmetric Key + */ + PK11SymKey * + GenerateSYMKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE mechanism, + int keySize, SECItem *keyID, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + /* Generate the symmetric key */ + key = PK11_TokenKeyGen(slot, mechanism, + NULL, keySize, keyID, PR_FALSE, pwdata); + + if (!key) { + PR_fprintf(PR_STDERR, "Symmetric Key Generation Failed \n"); + } + + return key; + } + + /* + * MacInit + */ + SECStatus + MacInit(PK11Context *ctx) + { + SECStatus rv = PK11_DigestBegin(ctx); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestBegin()\n"); + } + return rv; + } + + /* + * MacUpdate + */ + SECStatus + MacUpdate(PK11Context *ctx, + unsigned char *msg, unsigned int msgLen) + { + SECStatus rv = PK11_DigestOp(ctx, msg, msgLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : DigestOp()\n"); + } + return rv; + } + + /* + * Finalize MACing + */ + SECStatus + MacFinal(PK11Context *ctx, + unsigned char *mac, unsigned int *macLen, unsigned int maxLen) + { + SECStatus rv = PK11_DigestFinal(ctx, mac, macLen, maxLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestFinal()\n"); + } + return SECSuccess; + } + + /* + * Compute Mac + */ + SECStatus + ComputeMac(PK11Context *ctxmac, + unsigned char *ptext, unsigned int ptextLen, + unsigned char *mac, unsigned int *macLen, + unsigned int maxLen) + { + SECStatus rv = MacInit(ctxmac); + if (rv != SECSuccess) return rv; + rv = MacUpdate(ctxmac, ptext, ptextLen); + if (rv != SECSuccess) return rv; + rv = MacFinal(ctxmac, mac, macLen, maxLen); + return rv; + } + + /* + * WriteToHeaderFile + */ + SECStatus + WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, + PRFileDesc *outFile) + { + SECStatus rv; + const char *header; + const char *trailer; + + switch (type) { + case SYMKEY: + header = ENCKEY_HEADER; + trailer = ENCKEY_TRAILER; + break; + case MACKEY: + header = MACKEY_HEADER; + trailer = MACKEY_TRAILER; + break; + case IV: + header = IV_HEADER; + trailer = IV_TRAILER; + break; + case MAC: + header = MAC_HEADER; + trailer = MAC_TRAILER; + break; + case PAD: + header = PAD_HEADER; + trailer = PAD_TRAILER; + break; + case PUBKEY: + header = PUBKEY_HEADER; + trailer = PUBKEY_TRAILER; + break; + case LAB: + header = LAB_HEADER; + trailer = LAB_TRAILER; + PR_fprintf(outFile, "%s\n", header); + PR_fprintf(outFile, "%s\n", buf); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + break; + default: + return SECFailure; + } + + PR_fprintf(outFile, "%s\n", header); + PrintAsAscii(outFile, buf, len); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + } + + /* + * Initialize for encryption or decryption - common code + */ + PK11Context * + CryptInit(PK11SymKey *key, + unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type, CK_ATTRIBUTE_TYPE operation) + { + SECItem ivItem = { siBuffer, iv, ivLen }; + PK11Context *ctx = NULL; + + SECItem *secParam = PK11_ParamFromIV(type, &ivItem); + if (secParam == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : secParam NULL\n"); + return NULL; + } + ctx = PK11_CreateContextBySymKey(type, operation, key, secParam); + if (ctx == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : can't create a context\n"); + goto cleanup; + + } + cleanup: + if (secParam) { + SECITEM_FreeItem(secParam, PR_TRUE); + } + return ctx; + } + + /* + * Common encryption and decryption code + */ + SECStatus + Crypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxOut, + unsigned char *in, unsigned int inLen) + { + SECStatus rv; + + rv = PK11_CipherOp(ctx, out, outLen, maxOut, in, inLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Crypt Failed : PK11_CipherOp returned %d\n", rv); + goto cleanup; + } + + cleanup: + if (rv != SECSuccess) { + return rv; + } + return SECSuccess; + } + + /* + * Decrypt + */ + SECStatus + Decrypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * Encrypt + */ + SECStatus + Encrypt(PK11Context* ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * EncryptInit + */ + PK11Context * + EncryptInit(PK11SymKey *ek, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(ek, iv, ivLen, type, CKA_ENCRYPT); + } + + /* + * DecryptInit + */ + PK11Context * + DecryptInit(PK11SymKey *dk, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(dk, iv, ivLen, type, CKA_DECRYPT); + } + + /* + * Read cryptographic parameters from the header file + */ + SECStatus + ReadFromHeaderFile(const char *fileName, HeaderType type, + SECItem *item, PRBool isHexData) + { + SECStatus rv; + SECItem filedata; + SECItem outbuf; + unsigned char *nonbody; + unsigned char *body; + char *header; + char *trailer; + PRFileDesc *file = NULL; + + outbuf.type = siBuffer; + file = PR_Open(fileName, PR_RDONLY, 0); + if (!file) { + PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); + return SECFailure; + } + switch (type) { + case PUBKEY: + header = PUBKEY_HEADER; + trailer = PUBKEY_TRAILER; + break; + case SYMKEY: + header = ENCKEY_HEADER; + trailer = ENCKEY_TRAILER; + break; + case MACKEY: + header = MACKEY_HEADER; + trailer = MACKEY_TRAILER; + break; + case IV: + header = IV_HEADER; + trailer = IV_TRAILER; + break; + case MAC: + header = MAC_HEADER; + trailer = MAC_TRAILER; + break; + case PAD: + header = PAD_HEADER; + trailer = PAD_TRAILER; + break; + case LAB: + header = LAB_HEADER; + trailer = LAB_TRAILER; + break; + default: + PR_Close(file); + return SECFailure; + } + + rv = FileToItem(&filedata, file); + nonbody = (char *)filedata.data; + if (!nonbody) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* check for headers and trailers and remove them */ + char *trail = NULL; + if ((body = strstr(nonbody, header)) != NULL) { + char *trail = NULL; + nonbody = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(nonbody, '\r'); /* maybe this is a MAC file */ + if (body) + trail = strstr(++body, trailer); + if (trail != NULL) { + *trail = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + return SECFailure; + } + } else { + /* headers didn't exist */ + body = nonbody; + if (body) { + trail = strstr(++body, trailer); + if (trail != NULL) { + PR_fprintf(PR_STDERR, + "input has no header but has trailer\n"); + PORT_Free(filedata.data); + return SECFailure; + } + } + } + + cleanup: + PR_Close(file); + ATOB_ConvertAsciiToItem(item, body); + return SECSuccess; + } + + /* + * Generate the private key + */ + SECKEYPrivateKey * + GeneratePrivateKey(KeyType keytype, PK11SlotInfo *slot, int size, + int publicExponent, const char *noiseFileName, + SECKEYPublicKey **pubkeyp, const char *pqgFile, + secuPWData *pwdata) + { + CK_MECHANISM_TYPE mechanism; + SECOidTag algtag; + PK11RSAGenParams rsaparams; + void *params; + SECKEYPrivateKey *privKey = NULL; + SECStatus rv; + unsigned char randbuf[BLOCKSIZE + 1]; + + rv = GenerateRandom(randbuf, BLOCKSIZE); + if (rv != SECSuccess) { + fprintf(stderr, "Error while generating the random numbers : %s\n", + PORT_ErrorToString(rv)); + goto cleanup; + } + PK11_RandomUpdate(randbuf, BLOCKSIZE); + switch (keytype) { + case rsaKey: + rsaparams.keySizeInBits = size; + rsaparams.pe = publicExponent; + mechanism = CKM_RSA_PKCS_KEY_PAIR_GEN; + algtag = SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION; + params = &rsaparams; + break; + default: + goto cleanup; + } + fprintf(stderr, "\n\n"); + fprintf(stderr, "Generating key. This may take a few moments...\n\n"); + privKey = PK11_GenerateKeyPair(slot, mechanism, params, pubkeyp, + PR_TRUE /*isPerm*/, PR_TRUE /*isSensitive*/, + pwdata); + cleanup: + return privKey; + } + + /* + * Extract the public key request from CSR + */ + SECKEYPublicKey * + ExtractPublicKeyFromCertRequest(const char *inFileName, PRBool ascii) + { + CERTSignedData signedData; + SECItem reqDER; + CERTCertificateRequest *certReq = NULL; + SECStatus rv = SECSuccess; + PRArenaPool *arena = NULL; + SECKEYPublicKey *publicKey = NULL; + + arena = PORT_NewArena(DER_DEFAULT_CHUNKSIZE); + if (arena == NULL) { + rv = SECFailure; + goto cleanup; + } + + rv = ReadDERFromFile(&reqDER, inFileName, ascii); + if (rv) { + rv = SECFailure; + goto cleanup; + } + certReq = (CERTCertificateRequest*) PORT_ArenaZAlloc + (arena, sizeof(CERTCertificateRequest)); + if (!certReq) { + rv = SECFailure; + goto cleanup; + } + certReq->arena = arena; + + /* Since cert request is a signed data, must decode to get the inner + data + */ + PORT_Memset(&signedData, 0, sizeof(signedData)); + rv = SEC_ASN1DecodeItem(arena, &signedData, + SEC_ASN1_GET(CERT_SignedDataTemplate), &reqDER); + if (rv) { + rv = SECFailure; + goto cleanup; + } + rv = SEC_ASN1DecodeItem(arena, certReq, + SEC_ASN1_GET(CERT_CertificateRequestTemplate), &signedData.data); + if (rv) { + rv = SECFailure; + goto cleanup; + } + rv = CERT_VerifySignedDataWithPublicKeyInfo(&signedData, + &certReq->subjectPublicKeyInfo, NULL /* wincx */); + publicKey = SECKEY_ExtractPublicKey(&certReq->subjectPublicKeyInfo); + + cleanup: + if (reqDER.data) { + SECITEM_FreeItem(&reqDER, PR_FALSE); + } + if (arena) { + PORT_FreeArena(arena, PR_FALSE); + } + return publicKey; + } + + /* + * Get the private key corresponding to public key + */ + SECKEYPrivateKey * + GetRSAPrivateKey(PK11SlotInfo *slot, + secuPWData *pwdata, + SECKEYPublicKey *pubKey) + { + SECKEYPrivateKey *privKey = NULL; + SECItem *cka_id; + + if (slot == NULL) { + fprintf(stderr, "Empty Slot\n"); + goto cleanup; + } + if (PK11_Authenticate(slot, PR_TRUE, pwdata) != SECSuccess) { + fprintf(stderr, "could not authenticate to token %s.", + PK11_GetTokenName(slot)); + goto cleanup; + } + cka_id = &pubKey->u.rsa.modulus; + cka_id = PK11_MakeIDFromPubKey(cka_id); + privKey = PK11_FindKeyByKeyID(slot, cka_id, pwdata); + cleanup: + return privKey; + } + + /* + * Generate the certificate request with subject + */ + static SECStatus + CertReq(SECKEYPrivateKey *privk, SECKEYPublicKey *pubk, KeyType keyType, + SECOidTag hashAlgTag, CERTName *subject, PRBool ascii, + const char *certReqFileName) + { + CERTSubjectPublicKeyInfo *spki = NULL; + CERTCertificateRequest *cr = NULL; + SECItem *encoding = NULL; + SECOidTag signAlgTag; + SECItem result; + SECStatus rv = SECSuccess; + PRInt32 numBytes; + void *extHandle; + PRArenaPool *arena = NULL; + PRFileDesc *outFile = NULL; + + /* Open the certificate request file to write */ + outFile = PR_Open(certReqFileName, PR_CREATE_FILE | PR_RDWR | PR_TRUNCATE, 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, + "unable to open \"%s\" for writing (%ld, %ld).\n", + certReqFileName, PR_GetError(), PR_GetOSError()); + goto cleanup; + } + /* Create info about public key */ + spki = SECKEY_CreateSubjectPublicKeyInfo(pubk); + if (!spki) { + PR_fprintf(PR_STDERR, "unable to create subject public key\n"); + rv = SECFailure; + goto cleanup; + } + + /* Generate certificate request */ + cr = CERT_CreateCertificateRequest(subject, spki, NULL); + if (!cr) { + PR_fprintf(PR_STDERR, "unable to make certificate request\n"); + rv = SECFailure; + goto cleanup; + } + + arena = PORT_NewArena(DER_DEFAULT_CHUNKSIZE); + if (!arena) { + fprintf(stderr, "out of memory"); + rv = SECFailure; + goto cleanup; + } + + extHandle = CERT_StartCertificateRequestAttributes(cr); + if (extHandle == NULL) { + PORT_FreeArena (arena, PR_FALSE); + rv = SECFailure; + goto cleanup; + } + + CERT_FinishExtensions(extHandle); + CERT_FinishCertificateRequestAttributes(cr); + + /* Der encode the request */ + encoding = SEC_ASN1EncodeItem(arena, NULL, cr, + SEC_ASN1_GET(CERT_CertificateRequestTemplate)); + if (encoding == NULL) { + PR_fprintf(PR_STDERR, "der encoding of request failed\n"); + rv = SECFailure; + goto cleanup; + } + + /* Sign the request */ + signAlgTag = SEC_GetSignatureAlgorithmOidTag(keyType, hashAlgTag); + if (signAlgTag == SEC_OID_UNKNOWN) { + PR_fprintf(PR_STDERR, "unknown Key or Hash type\n"); + rv = SECFailure; + goto cleanup; + } + rv = SEC_DerSignData(arena, &result, encoding->data, encoding->len, + privk, signAlgTag); + if (rv) { + PR_fprintf(PR_STDERR, "signing of data failed\n"); + rv = SECFailure; + goto cleanup; + } + + /* Encode request in specified format */ + if (ascii) { + char *obuf; + char *name, *email, *org, *state, *country; + SECItem *it; + int total; + + it = &result; + + obuf = BTOA_ConvertItemToAscii(it); + total = PL_strlen(obuf); + + name = CERT_GetCommonName(subject); + if (!name) { + name = strdup("(not specified)"); + } + + email = CERT_GetCertEmailAddress(subject); + if (!email) + email = strdup("(not specified)"); + + org = CERT_GetOrgName(subject); + if (!org) + org = strdup("(not specified)"); + + state = CERT_GetStateName(subject); + if (!state) + state = strdup("(not specified)"); + + country = CERT_GetCountryName(subject); + if (!country) + country = strdup("(not specified)"); + + PR_fprintf(outFile, + "\nCertificate request generated by Netscape certutil\n"); + PR_fprintf(outFile, "Common Name: %s\n", name); + PR_fprintf(outFile, "Email: %s\n", email); + PR_fprintf(outFile, "Organization: %s\n", org); + PR_fprintf(outFile, "State: %s\n", state); + PR_fprintf(outFile, "Country: %s\n\n", country); + + PR_fprintf(outFile, "%s\n", NS_CERTREQ_HEADER); + numBytes = PR_Write(outFile, obuf, total); + if (numBytes != total) { + PR_fprintf(PR_STDERR, "write error\n"); + return SECFailure; + } + PR_fprintf(outFile, "\n%s\n", NS_CERTREQ_TRAILER); + if (obuf) { + PORT_Free(obuf); + } + } else { + numBytes = PR_Write(outFile, result.data, result.len); + if (numBytes != (int)result.len) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + goto cleanup; + } + } + cleanup: + if (spki) { + SECKEY_DestroySubjectPublicKeyInfo(spki); + } + if (cr) { + CERT_DestroyCertificateRequest (cr); + } + if (arena) { + PORT_FreeArena(arena, PR_FALSE); + } + if (outFile) { + PR_Close(outFile); + } + return rv; + } + + /* + * Mac and Encrypt the input file content + */ + SECStatus + EncryptAndMac(PRFileDesc *inFile, + PRFileDesc *headerFile, + PRFileDesc *encFile, + PK11SymKey *ek, + PK11SymKey *mk, + unsigned char *iv, unsigned int ivLen, + PRBool ascii) + { + SECStatus rv; + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen; + unsigned char mac[DIGESTSIZE]; + unsigned int macLen; + unsigned int nwritten; + unsigned char encbuf[BLOCKSIZE]; + unsigned int encbufLen; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + unsigned int pad[1]; + SECItem padItem; + unsigned int paddingLength = 0; + + static unsigned int firstTime = 1; + int j; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + rv = MacInit(ctxmac); + if (rv != SECSuccess) { + goto cleanup; + } + + ctxenc = EncryptInit(ek, iv, ivLen, CKM_AES_CBC); + + /* read a buffer of plaintext from input file */ + while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { + /* Encrypt using it using CBC, using previously created IV */ + if (ptextLen != BLOCKSIZE) { + paddingLength = BLOCKSIZE - ptextLen; + for ( j=0; j < paddingLength; j++) { + ptext[ptextLen+j] = (unsigned char)paddingLength; + } + ptextLen = BLOCKSIZE; + } + rv = Encrypt(ctxenc, + encbuf, &encbufLen, sizeof(encbuf), + ptext, ptextLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Encrypt Failure\n"); + goto cleanup; + } + + /* save the last block of ciphertext as the next IV */ + iv = encbuf; + ivLen = encbufLen; + + /* write the cipher text to intermediate file */ + nwritten = PR_Write(encFile, encbuf, encbufLen); + /*PR_Assert(nwritten == encbufLen);*/ + + rv = MacUpdate(ctxmac, ptext, ptextLen); + if (rv != SECSuccess) + goto cleanup; + } + + rv = MacFinal(ctxmac, mac, &macLen, DIGESTSIZE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "MacFinal Failure\n"); + goto cleanup; + } + if (macLen == 0) { + PR_fprintf(PR_STDERR, "Bad MAC length\n"); + rv = SECFailure; + goto cleanup; + } + WriteToHeaderFile(mac, macLen, MAC, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write MAC Failure\n"); + goto cleanup; + } + + pad[0] = paddingLength; + padItem.type = siBuffer; + padItem.data = (unsigned char *)pad; + padItem.len = sizeof(pad[0]); + + WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write PAD Failure\n"); + goto cleanup; + } + + rv = SECSuccess; + + cleanup: + if (ctxmac != NULL) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc != NULL) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + + return rv; + } + + /* + * Decrypt and Verify MAC + */ + SECStatus + DecryptAndVerifyMac(PRFileDesc *outFile, + PRFileDesc *inFile, unsigned int inFileLength, + SECItem *cItem, SECItem *macItem, + PK11SymKey* ek, PK11SymKey* mk, SECItem *ivItem, SECItem *padItem) + { + SECStatus rv; + unsigned char decbuf[64]; + unsigned int decbufLen; + + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen = 0; + unsigned char ctext[64]; + unsigned int ctextLen; + unsigned char newmac[DIGESTSIZE]; + unsigned int newmacLen = 0; + unsigned int newptextLen = 0; + unsigned int count = 0; + unsigned int temp = 0; + unsigned int blockNumber = 0; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + + unsigned char iv[BLOCKSIZE]; + unsigned int ivLen = ivItem->len; + unsigned int paddingLength; + int j; + + memcpy(iv, ivItem->data, ivItem->len); + paddingLength = (unsigned int)padItem->data[0]; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + + rv = MacInit(ctxmac); + if (rv != SECSuccess) goto cleanup; + + ctxenc = DecryptInit(ek, iv, ivLen, CKM_AES_CBC); + + while ((ctextLen = PR_Read(inFile, ctext, sizeof(ctext))) > 0) { + + count += ctextLen; + + /* decrypt cipher text buffer using CBC and IV */ + + rv = Decrypt(ctxenc, decbuf, &decbufLen, sizeof(decbuf), + ctext, ctextLen); + + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Decrypt Failure\n"); + goto cleanup; + } + + if (decbufLen == 0) break; + + rv = MacUpdate(ctxmac, decbuf, decbufLen); + if (rv != SECSuccess) { goto cleanup; } + if (count == inFileLength) { + decbufLen = decbufLen-paddingLength; + } + + /* write the plain text to out file */ + temp = PR_Write(outFile, decbuf, decbufLen); + if (temp != decbufLen) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + break; + } + + blockNumber++; + } + + if (rv != SECSuccess) { goto cleanup; } + + rv = MacFinal(ctxmac, newmac, &newmacLen, sizeof(newmac)); + if (rv != SECSuccess) { goto cleanup; } + + if (PORT_Memcmp(macItem->data, newmac, newmacLen) == 0) { + rv = SECSuccess; + } else { + PR_fprintf(PR_STDERR, "Check MAC : Failure\n"); + PR_fprintf(PR_STDERR, "Extracted : "); + PrintAsAscii(PR_STDERR, macItem->data, macItem->len); + PR_fprintf(PR_STDERR, "Computed : "); + PrintAsAscii(PR_STDERR, newmac, newmacLen); + rv = SECFailure; + } + cleanup: + if (ctxmac) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + + return rv; + } + + /* + * Open intermediate file, read in IV, wrapped encryption key, + * wrapped MAC key, MAC, PAD and public key from header file + */ + SECStatus + GetDataFromHeader(const char *headerFileName, + SECItem *ivItem, + SECItem *wrappedEncKeyItem, + SECItem *wrappedMacKeyItem, + SECItem *macItem, + SECItem *padItem, + SECKEYPublicKey **pubKey) + { + SECStatus rv = SECSuccess; + CERTSubjectPublicKeyInfo *keyInfo = NULL; + SECItem pubKeyData; + + /* Read in the IV into item from the header file */ + rv = ReadFromHeaderFile(headerFileName, IV, ivItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not retrieve IV from cipher file\n"); + goto cleanup; + } + + rv = ReadFromHeaderFile(headerFileName, SYMKEY, wrappedEncKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve wrapped AES key from header file\n"); + goto cleanup; + } + /* Read in the MAC key into item from the header file */ + rv = ReadFromHeaderFile(headerFileName, MACKEY, wrappedMacKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve wrapped MAC key from header file\n"); + goto cleanup; + } + + /* Get the public key from header file */ + rv = ReadFromHeaderFile(headerFileName, PUBKEY, &pubKeyData, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve public key from header file\n"); + goto cleanup; + } + keyInfo = SECKEY_DecodeDERSubjectPublicKeyInfo(&pubKeyData); + if (!keyInfo) { + PR_fprintf(PR_STDERR, "Could not decode public key\n"); + rv = SECFailure; + goto cleanup; + } + *pubKey = SECKEY_ExtractPublicKey(keyInfo); + if (*pubKey == NULL) { + PR_fprintf(PR_STDERR, "Error while getting RSA public key\n"); + rv = SECFailure; + goto cleanup; + } + /* Read in the Mac into item from the header file */ + rv = ReadFromHeaderFile(headerFileName, MAC, macItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC from cipher file\n"); + goto cleanup; + } + if (macItem->data == NULL) { + PR_fprintf(PR_STDERR, "MAC has NULL data\n"); + rv = SECFailure; + goto cleanup; + } + if (macItem->len == 0) { + PR_fprintf(PR_STDERR, "MAC has data has 0 length\n"); + rv = SECFailure; + goto cleanup; + } + + /* Read in the PAD into item from the header file */ + rv = ReadFromHeaderFile(headerFileName, PAD, padItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve PAD detail from header file\n"); + goto cleanup; + } + + cleanup: + return rv; + } + + + /* + * DecryptFile + */ + SECStatus + DecryptFile(PK11SlotInfo *slot, + const char *outFileName, + const char *headerFileName, + char *encryptedFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open read only and we have authenticated to it + * open input file, read in header, get IV and wrapped keys and + * public key + * Unwrap the wrapped keys + * loop until EOF(input): + * read a buffer of ciphertext from input file, + * Save last block of ciphertext + * decrypt ciphertext buffer using CBC and IV, + * compute and check MAC, then remove MAC from plaintext + * replace IV with saved last block of ciphertext + * write the plain text to output file + * close files + * report success + */ + + SECStatus rv; + SECItem ivItem; + SECItem wrappedEncKeyItem; + SECItem wrappedMacKeyItem; + SECItem cipherItem; + SECItem macItem; + SECItem padItem; + SECKEYPublicKey *pubKey = NULL; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + SECKEYPrivateKey *privKey = NULL; + PRFileDesc *outFile = NULL; + PRFileDesc *inFile = NULL; + unsigned int inFileLength = 0; + + /* open intermediate file, read in header, get IV, public key and + * CKA_IDs of two keys from it + */ + rv = GetDataFromHeader(headerFileName, + &ivItem, + &wrappedEncKeyItem, + &wrappedMacKeyItem, + &macItem, + &padItem, + &pubKey); + if (rv != SECSuccess) { + goto cleanup; + } + + /* find private key from the DB token using public key */ + privKey = GetRSAPrivateKey(slot, pwdata, pubKey); + if (privKey == NULL) { + PR_fprintf(PR_STDERR, "Can't find private key\n"); + rv = SECFailure; + goto cleanup; + } + + encKey = PK11_PubUnwrapSymKey(privKey, &wrappedEncKeyItem, + CKM_AES_CBC, CKA_ENCRYPT, 0); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "Can't unwrap the encryption key\n"); + rv = SECFailure; + goto cleanup; + } + + /* CKM_MD5_HMAC or CKM_EXTRACT_KEY_FROM_KEY */ + macKey = PK11_PubUnwrapSymKey(privKey, &wrappedMacKeyItem, + CKM_MD5_HMAC, CKA_SIGN, 160/8); + if (macKey == NULL) { + PR_fprintf(PR_STDERR, "Can't unwrap the Mac key\n"); + rv = SECFailure; + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(encryptedFileName, PR_RDONLY , 0); + if (!inFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* Open the output file. */ + outFile = PR_Open(outFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR , 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + outFileName); + return SECFailure; + } + inFileLength = FileSize(encryptedFileName); + + if (rv == SECSuccess) { + /* Decrypt and Remove Mac */ + rv = DecryptAndVerifyMac(outFile, inFile, inFileLength, + &cipherItem, &macItem, encKey, macKey, &ivItem, &padItem); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed while decrypting and removing MAC\n"); + } + } + + cleanup: + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + if (privKey) { + SECKEY_DestroyPrivateKey(privKey); + } + if (pubKey) { + SECKEY_DestroyPublicKey(pubKey); + } + return rv; + } + + /* + * EncryptFile + */ + SECStatus + EncryptFile(PK11SlotInfo *slot, + const char *inFileName, + const char *certReqFileName, + const char *headerFileName, + const char *encryptedFileName, + const char *noiseFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open for read/write and we have authenticated to it. + * Read public key from certificate request + * generate a symmetric AES key as a session object. + * generate a second key to use for MACing, also a session object. + * generate a random value to use as IV for AES CBC + * open an input file and an output file, + * Wrap the symmetric and MAC keys using public key + * write a header to the output that identifies the two wrapped keys + * and public key + * loop until EOF(input) + * read a buffer of plaintext from input file, + * MAC it, append the MAC to the plaintext + * encrypt it using CBC, using previously created IV, + * store the last block of ciphertext as the new IV, + * write the cipher text to intermediate file + * close files + * report success + */ + SECStatus rv; + SECKEYPublicKey *pubKey = NULL; + SECItem *pubKeyData = NULL; + PRFileDesc *inFile = NULL; + PRFileDesc *headerFile = NULL; + PRFileDesc *encFile = NULL; + + unsigned char *encKeyId = (unsigned char *) "Encrypt Key"; + unsigned char *macKeyId = (unsigned char *) "MAC Key"; + SECItem encKeyID = { siAsciiString, encKeyId, PL_strlen(encKeyId) }; + SECItem macKeyID = { siAsciiString, macKeyId, PL_strlen(macKeyId) }; + + unsigned char iv[BLOCKSIZE]; + SECItem ivItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + SECItem *wrappedEncKey = NULL; + SECItem *wrappedMacKey = NULL; + unsigned char c; + + pubKey = ExtractPublicKeyFromCertRequest(certReqFileName, ascii); + if (pubKey == NULL) { + PR_fprintf(PR_STDERR, "Error while getting RSA public key\n"); + rv = SECFailure; + goto cleanup; + } + /* generate a symmetric AES key as a token object. */ + encKey = GenerateSYMKey(slot, CKM_AES_KEY_GEN, 128/8, &encKeyID, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for AES returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* generate a second key to use for MACing, also a token object. */ + macKey = GenerateSYMKey(slot, CKM_GENERIC_SECRET_KEY_GEN, 160/8, &macKeyID, pwdata); + if (macKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for MACing returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* Wrap encrypt key */ + rv = WrapKey(encKey, pubKey, &wrappedEncKey); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error while wrapping encrypt key\n"); + goto cleanup; + } + + /* Wrap Mac key */ + rv = WrapKey(macKey, pubKey, &wrappedMacKey); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error while wrapping Mac key\n"); + goto cleanup; + } + + if (noiseFileName) { + rv = SeedFromNoiseFile(noiseFileName); + if (rv != SECSuccess) { + PORT_SetError(PR_END_OF_FILE_ERROR); + return SECFailure; + } + rv = PK11_GenerateRandom(iv, BLOCKSIZE); + if (rv != SECSuccess) { + goto cleanup; + } + + } else { + /* generate a random value to use as IV for AES CBC */ + GenerateRandom(iv, BLOCKSIZE); + } + + headerFile = PR_Open(headerFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + headerFileName); + return SECFailure; + } + encFile = PR_Open(encryptedFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!encFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* write to a header file the IV and the CKA_IDs + * identifying the two keys + */ + ivItem.type = siBuffer; + ivItem.data = iv; + ivItem.len = BLOCKSIZE; + + rv = WriteToHeaderFile(iv, BLOCKSIZE, IV, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing IV to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + rv = WriteToHeaderFile(wrappedEncKey->data, wrappedEncKey->len, SYMKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing wrapped AES key to cipher file - %s\n", + encryptedFileName); + goto cleanup; + } + rv = WriteToHeaderFile(wrappedMacKey->data, wrappedMacKey->len, MACKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing wrapped MAC key to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + pubKeyData = SECKEY_EncodeDERSubjectPublicKeyInfo(pubKey); + rv = WriteToHeaderFile(pubKeyData->data, pubKeyData->len, PUBKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing wrapped AES key to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + + /* Macing and Encryption */ + if (rv == SECSuccess) { + rv = EncryptAndMac(inFile, headerFile, encFile, + encKey, macKey, ivItem.data, ivItem.len, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : Macing and Encryption\n"); + goto cleanup; + } + } + + cleanup: + if (inFile) { + PR_Close(inFile); + } + if (headerFile) { + PR_Close(headerFile); + } + if (encFile) { + PR_Close(encFile); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + if (wrappedEncKey) { + SECITEM_FreeItem(wrappedEncKey, PR_TRUE); + } + if (wrappedMacKey) { + SECITEM_FreeItem(wrappedMacKey, PR_TRUE); + } + if (pubKey) { + SECKEY_DestroyPublicKey(pubKey); + } + if (pubKeyData) { + SECITEM_FreeItem(pubKeyData, PR_TRUE); + } + return rv; + } + + /* + * Create certificate request with subject + */ + SECStatus CreateCertificateRequest(PK11SlotInfo *slot, + const char *dbdir, + secuPWData *pwdata, + CERTName *subject, + const char *certReqFileName, + PRBool ascii) + { + SECStatus rv; + SECKEYPrivateKey *privkey = NULL; + SECKEYPublicKey *pubkey = NULL; + KeyType keytype = rsaKey; + int keysize = DEFAULT_KEY_BITS; + int publicExponent = 0x010001; + SECOidTag hashAlgTag = SEC_OID_UNKNOWN; + + privkey = GeneratePrivateKey(keytype, slot, keysize, + publicExponent, NULL, + &pubkey, NULL, pwdata); + if (privkey == NULL) { + PR_fprintf(PR_STDERR, "unable to generate key(s)\n"); + rv = SECFailure; + goto cleanup; + } + privkey->wincx = pwdata; + PORT_Assert(pubkey != NULL); + + rv = CertReq(privkey, pubkey, keytype, hashAlgTag, subject, + ascii, certReqFileName); + + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to create Certificate Request\n"); + } + cleanup: + if (privkey) { + SECKEY_DestroyPrivateKey(privkey); + } + if (pubkey) { + SECKEY_DestroyPublicKey(pubkey); + } + return rv; + } + + /* + * This example illustrates basic encryption/decryption and MACing + * Generates the RSA key pair as token object and outputs public key as cert request. + * Generates the encryption/mac keys as session objects. + * Encrypts/MACs the input file using encryption keys and outputs the encrypted + * contents into intermediate header file. + * Extracts the public key from cert request file and Wraps the encryption keys using + * RSA public key and outputs wrapped keys and public key into intermediate header file. + * Reads the intermediate headerfile for wrapped keys,RSA public key and encrypted + * contents and decrypts into output file. + * + * How this sample is different from sample 4 ? + * + * 1. Generate same keys as sample 4, outputs public key as cert request. + * 2. Like sample 4, except that it reads in public key from cert request file instead + * of looking it up by label name, and writes public key into header instead of a + * label name. Rest is the same. + * 3. Like sample 4, except that it reads in RSA public key, and then finds matching + * private key (by key ID). Rest is the same. + */ + int + main(int argc, char **argv) + { + SECStatus rv; + SECStatus rvShutdown; + PLOptState *optstate; + PLOptStatus status; + char headerFileName[50]; + char encryptedFileName[50]; + PK11SlotInfo *slot = NULL; + PRBool ascii = PR_FALSE; + CommandType cmd = UNKNOWN; + PRFileDesc *inFile = NULL; + PRFileDesc *outFile = NULL; + char *subjectStr = NULL; + CERTName *subject = NULL; + const char *dbdir = NULL; + const char *inFileName = NULL; + const char *outFileName = NULL; + const char *certReqFileName = NULL; + const char *noiseFileName = NULL; + secuPWData pwdata = { PW_NONE, 0 }; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "c:d:i:o:f:p:z:a:s:r:"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'a': + ascii = PR_TRUE; + break; + case 'c': + cmd = option2Command(optstate->value); + break; + case 'd': + dbdir = strdup(optstate->value); + break; + case 'f': + pwdata.source = PW_FROMFILE; + pwdata.data = strdup(optstate->value); + break; + case 'p': + pwdata.source = PW_PLAINTEXT; + pwdata.data = strdup(optstate->value); + break; + case 'i': + inFileName = strdup(optstate->value); + break; + case 'o': + outFileName = strdup(optstate->value); + break; + case 'r': + certReqFileName = strdup(optstate->value); + break; + case 's': + subjectStr = strdup(optstate->value); + subject = CERT_AsciiToName(subjectStr); + break; + case 'z': + noiseFileName = strdup(optstate->value); + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (cmd == UNKNOWN || !dbdir) { + Usage(progName); + } + + /* For intermediate header file, choose filename as inputfile name + with extension ".header" */ + strcpy(headerFileName, progName); + strcat(headerFileName, ".header"); + + /* For intermediate encrypted file, choose filename as inputfile name + with extension ".enc" */ + strcpy(encryptedFileName, progName); + strcat(encryptedFileName, ".enc"); + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + + /* Open DB for read/write and authenticate to it. */ + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); + goto cleanup; + } + + PK11_SetPasswordFunc(GetModulePassword); + slot = PK11_GetInternalKeySlot(); + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + + switch (cmd) { + case GEN_CSR: + + /* Validate command for Generate CSR */ + if (!certReqFileName || !subject) { + Usage(progName); + } + /* + * Generate the cert request and save it + * in a file so public key can be retrieved later to wrap the symmetric key + */ + rv = CreateCertificateRequest(slot, dbdir, &pwdata, subject, certReqFileName, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Create Certificate Request: Failed\n"); + goto cleanup; + } + break; + case ENCRYPT: + /* Validate command for Encrypt */ + if (!certReqFileName && !inFileName) { + Usage(progName); + } + + /* + * Read cert request from a file and extract public key + * Generates an AES encryption key, session object + * Generates a MAC key, session object + * Wraps each of those keys with RSA public key + * Write wrapped keys and public key into intermediate header file + * Encryption and MACing loop + * Destroy session keys + * Close files + */ + rv = EncryptFile(slot, inFileName, certReqFileName, + headerFileName, encryptedFileName, + noiseFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "EncryptFile : Failed\n"); + return SECFailure; + } + break; + case DECRYPT: + /* Validate command for Decrypt */ + if (!inFileName && !outFileName) { + Usage(progName); + } + /* + * Reads intermediate header including public key and wrapped keys + * Finds RSA private key corresponding to the public key + * unwraps two keys, creating session key objects + * Decryption and MAC checking loop to write to output file + * Destroy session keys + * CLose files + */ + rv = DecryptFile(slot, + outFileName, headerFileName, + encryptedFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "DecryptFile : Failed\n"); + return SECFailure; + } + break; + } + + cleanup: + if (slot) { + PK11_FreeSlot(slot); + } + rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); + rv = SECFailure; + } + PR_Cleanup(); + + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/enc_dec_mac_using_key_wrap_certreq_pkcs10_csr/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/enc_dec_mac_using_key_wrap_certreq_pkcs10_csr/index.rst new file mode 100644 index 0000000000..793555ce5a --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/enc_dec_mac_using_key_wrap_certreq_pkcs10_csr/index.rst @@ -0,0 +1,2090 @@ +.. _mozilla_projects_nss_nss_sample_code_enc_dec_mac_using_key_wrap_certreq_pkcs10_csr: + +Enc Dec MAC Using Key Wrap CertReq PKCS10 CSR +============================================= + +.. _nss_sample_code_6_encryptiondecryption_and_mac_and_output_public_as_a_pkcs_11_csr.: + +`NSS Sample Code 6: Encryption/Decryption and MAC and output Public as a PKCS 11 CSR. <#nss_sample_code_6_encryptiondecryption_and_mac_and_output_public_as_a_pkcs_11_csr.>`__ +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + +.. container:: + + Generates encryption/mac keys and outputs public key as pkcs11 certificate signing request + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + /* NSPR Headers */ + #include <prthread.h> + #include <plgetopt.h> + #include <prerror.h> + #include <prinit.h> + #include <prlog.h> + #include <prtypes.h> + #include <plstr.h> + + /* NSS headers */ + #include <keyhi.h> + #include <pk11priv.h> + + /* our samples utilities */ + #include "util.h" + + /* Constants */ + #define BLOCKSIZE 32 + #define MODBLOCKSIZE 128 + #define DEFAULT_KEY_BITS 1024 + + /* Header file Constants */ + #define ENCKEY_HEADER "-----BEGIN WRAPPED ENCKEY-----" + #define ENCKEY_TRAILER "-----END WRAPPED ENCKEY-----" + #define MACKEY_HEADER "-----BEGIN WRAPPED MACKEY-----" + #define MACKEY_TRAILER "-----END WRAPPED MACKEY-----" + #define IV_HEADER "-----BEGIN IV-----" + #define IV_TRAILER "-----END IV-----" + #define MAC_HEADER "-----BEGIN MAC-----" + #define MAC_TRAILER "-----END MAC-----" + #define PAD_HEADER "-----BEGIN PAD-----" + #define PAD_TRAILER "-----END PAD-----" + #define LAB_HEADER "-----BEGIN KEY LABEL-----" + #define LAB_TRAILER "-----END KEY LABEL-----" + #define PUBKEY_HEADER "-----BEGIN PUB KEY -----" + #define PUBKEY_TRAILER "-----END PUB KEY -----" + #define NS_CERTREQ_HEADER "-----BEGIN NEW CERTIFICATE REQUEST-----" + #define NS_CERTREQ_TRAILER "-----END NEW CERTIFICATE REQUEST-----" + #define NS_CERT_ENC_HEADER "-----BEGIN CERTIFICATE FOR ENCRYPTION-----" + #define NS_CERT_ENC_TRAILER "-----END CERTIFICATE FOR ENCRYPTION-----" + #define NS_CERT_VFY_HEADER "-----BEGIN CERTIFICATE FOR SIGNATURE VERIFICATION-----" + #define NS_CERT_VFY_TRAILER "-----END CERTIFICATE FOR SIGNATURE VERIFICATION-----" + #define NS_SIG_HEADER "-----BEGIN SIGNATURE-----" + #define NS_SIG_TRAILER "-----END SIGNATURE-----" + #define NS_CERT_HEADER "-----BEGIN CERTIFICATE-----" + #define NS_CERT_TRAILER "-----END CERTIFICATE-----" + + /* sample 6 commands */ + typedef enum { + GENERATE_CSR, + ADD_CERT_TO_DB, + SAVE_CERT_TO_HEADER, + ENCRYPT, + DECRYPT, + SIGN, + VERIFY, + UNKNOWN + } CommandType; + + typedef enum { + SYMKEY = 0, + MACKEY = 1, + IV = 2, + MAC = 3, + PAD = 4, + PUBKEY = 5, + LAB = 6, + CERTENC= 7, + CERTVFY= 8, + SIG = 9 + } HeaderType; + + + /* + * Print usage message and exit + */ + static void + Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s %s %s %s %s %s %s %s %s %s\n\n", + progName, + " -<G|A|H|E|DS|V> -d <dbdirpath> ", + "[-p <dbpwd> | -f <dbpwdfile>] [-z <noisefilename>] [-a <\"\">]", + "-s <subject> -r <csr> | ", + "-n <nickName> -t <trust> -c <cert> [ -r <csr> -u <issuerNickname> [-x <\"\">] -m <serialNumber> ] | ", + "-n <nickName> -b <headerfilename> | ", + "-b <headerfilename> -i <ipfilename> -e <encryptfilename> | ", + "-b <headerfilename> -i <ipfilename> | ", + "-b <headerfilename> -i <ipfilename> | ", + "-b <headerfilename> -e <encryptfilename> -o <opfilename> \n"); + fprintf(stderr, "commands:\n\n"); + fprintf(stderr, "%s %s\n --for generating cert request (for CA also)\n\n", + progName, "-G -s <subject> -r <csr>"); + fprintf(stderr, "%s %s\n --to input and store cert (for CA also)\n\n", + progName, "-A -n <nickName> -t <trust> -c <cert> [ -r <csr> -u <issuerNickname> [-x <\"\">] -m <serialNumber> ]"); + fprintf(stderr, "%s %s\n --to put cert in header\n\n", + progName, "-H -n <nickname> -b <headerfilename> [-v <\"\">]"); + fprintf(stderr, "%s %s\n --to find public key from cert in header and encrypt\n\n", + progName, "-E -b <headerfilename> -i <ipfilename> -e <encryptfilename> "); + fprintf(stderr, "%s %s\n --decrypt using corresponding private key \n\n", + progName, "-D -b <headerfilename> -e <encryptfilename> -o <opfilename>"); + fprintf(stderr, "%s %s\n --Sign using private key \n\n", + progName, "-S -b <headerfilename> -i <infilename> "); + fprintf(stderr, "%s %s\n --Verify using public key \n\n", + progName, "-V -b <headerfilename> -i <ipfilename> "); + fprintf(stderr, "options:\n\n"); + fprintf(stderr, "%-30s - db directory path\n\n", + "-d <dbdirpath>"); + fprintf(stderr, "%-30s - db password [optional]\n\n", + "-p <dbpwd>"); + fprintf(stderr, "%-30s - db password file [optional]\n\n", + "-f <dbpwdfile>"); + fprintf(stderr, "%-30s - noise file name [optional]\n\n", + "-z <noisefilename>"); + fprintf(stderr, "%-30s - input file name\n\n", + "-i <ipfilename>"); + fprintf(stderr, "%-30s - header file name\n\n", + "-b <headerfilename>"); + fprintf(stderr, "%-30s - encrypt file name\n\n", + "-e <encryptfilename>"); + fprintf(stderr, "%-30s - output file name\n\n", + "-o <opfilename>"); + fprintf(stderr, "%-30s - certificate serial number\n\n", + "-m <serialNumber>"); + fprintf(stderr, "%-30s - certificate nickname\n\n", + "-n <nickname>"); + fprintf(stderr, "%-30s - certificate trust\n\n", + "-t <trustargs>"); + fprintf(stderr, "%-30s - certificate issuer nickname\n\n", + "-u <issuerNickname>"); + fprintf(stderr, "%-30s - certificate signing request \n\n", + "-r <csr>"); + fprintf(stderr, "%-30s - generate a self-signed cert [optional]\n\n", + "-x"); + fprintf(stderr, "%-30s - to enable ascii [optional]\n\n", + "-a"); + fprintf(stderr, "%-30s - to save certificate to header file as sig verification [optional]\n\n", + "-v"); + exit(-1); + } + + /* + * Validate the options used for Generate CSR command + */ + static void + ValidateGenerateCSRCommand(const char *progName, + const char *dbdir, + CERTName *subject, + const char *subjectStr, + const char *certReqFileName) + { + PRBool validationFailed = PR_FALSE; + if (!subject) { + PR_fprintf(PR_STDERR, "%s -G -d %s -s: improperly formatted name: \"%s\"\n", + progName, dbdir, subjectStr); + validationFailed = PR_TRUE; + } + if (!certReqFileName) { + PR_fprintf(PR_STDERR, "%s -G -d %s -s %s -r: certificate request file name not found\n", + progName, dbdir, subjectStr); + validationFailed = PR_TRUE; + } + if (validationFailed) { + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + "-G -d <dbdirpath> -s <subject> -r <csr> \n"); + exit(-1); + } + } + + /* + * Validate the options used for Add Cert to DB command + */ + static void + ValidateAddCertToDBCommand(const char *progName, + const char *dbdir, + const char *nickNameStr, + const char *trustStr, + const char *certFileName, + const char *certReqFileName, + const char *issuerNameStr, + const char *serialNumberStr, + PRBool selfsign) + { + PRBool validationFailed = PR_FALSE; + if (!nickNameStr) { + PR_fprintf(PR_STDERR, "%s -A -d %s -n : nick name is missing\n", + progName, dbdir); + validationFailed = PR_TRUE; + } + if (!trustStr) { + PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t: trust flag is missing\n", + progName, dbdir, nickNameStr); + validationFailed = PR_TRUE; + } + if (!certFileName) { + PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c: certificate file name not found\n", + progName, dbdir, nickNameStr, trustStr, serialNumberStr, certReqFileName); + validationFailed = PR_TRUE; + } + if (PR_Access(certFileName, PR_ACCESS_EXISTS) == PR_FAILURE) { + if (!certReqFileName) { + PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c %s -r: certificate file or certificate request file is not found\n", + progName, dbdir, nickNameStr, trustStr, certFileName); + validationFailed = PR_TRUE; + } + if (!selfsign && !issuerNameStr) { + PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c %s -r %s -u : issuer name is missing\n", + progName, dbdir, nickNameStr, trustStr, certFileName, certReqFileName); + validationFailed = PR_TRUE; + } + if (!serialNumberStr) { + PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c %s -r %s -u %s -m : serial number is missing\n", + progName, dbdir, nickNameStr, trustStr, certFileName, certReqFileName, issuerNameStr); + validationFailed = PR_TRUE; + } + } + if (validationFailed) { + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + " -A -d <dbdirpath> -n <nickName> -t <trust> -c <cert> \n"); + fprintf(stderr, " OR\n"); + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + "-A -d <dbdirpath> -n <nickName> -t <trust> -c <cert> -r <csr> -u <issuerNickname> -m <serialNumber> [-x <\"\">] \n"); + exit(-1); + } + } + + /* + * Validate the options used for Save Cert To Header command + */ + static void + ValidateSaveCertToHeaderCommand(const char *progName, + const char *dbdir, + const char *nickNameStr, + const char *headerFileName) + { + PRBool validationFailed = PR_FALSE; + if (!nickNameStr) { + PR_fprintf(PR_STDERR, "%s -S -d %s -n : nick name is missing\n", + progName, dbdir); + validationFailed = PR_TRUE; + } + if (!headerFileName) { + PR_fprintf(PR_STDERR, "%s -S -d %s -n %s -b : header file name is not found\n", + progName, dbdir, nickNameStr); + validationFailed = PR_TRUE; + } + if (validationFailed) { + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + "-S -d <dbdirpath> -n <nickname> -b <headerfilename> [-v <\"\">]\n"); + exit(-1); + } + } + + /* + * Validate the options used for Encrypt command + */ + static void + ValidateEncryptCommand(const char *progName, + const char *dbdir, + const char *nickNameStr, + const char *headerFileName, + const char *inFileName, + const char *encryptedFileName) + { + PRBool validationFailed = PR_FALSE; + if (!nickNameStr) { + PR_fprintf(PR_STDERR, "%s -E -d %s -n : nick name is missing\n", + progName, dbdir); + validationFailed = PR_TRUE; + } + if (!headerFileName) { + PR_fprintf(PR_STDERR, "%s -E -d %s -n %s -b : header file name is not found\n", + progName, dbdir, nickNameStr); + validationFailed = PR_TRUE; + } + if (!inFileName) { + PR_fprintf(PR_STDERR, "%s -E -d %s -n %s -b %s -i : input file name is not found\n", + progName, dbdir, nickNameStr, headerFileName); + validationFailed = PR_TRUE; + } + if (!encryptedFileName) { + PR_fprintf(PR_STDERR, "%s -E -d %s -n %s -b %s -i %s -e : encrypt file name is not found\n", + progName, dbdir, nickNameStr, headerFileName, inFileName); + validationFailed = PR_TRUE; + } + if (validationFailed) { + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + "-E -d <dbdirpath> -b <headerfilename> -i <ipfilename> -e <encryptfilename> -n <nickname> \n"); + exit(-1); + } + } + + /* + * Validate the options used for Sign command + */ + static void + ValidateSignCommand(const char *progName, + const char *dbdir, + const char *nickNameStr, + const char *headerFileName, + const char *inFileName) + { + PRBool validationFailed = PR_FALSE; + if (!nickNameStr) { + PR_fprintf(PR_STDERR, "%s -I -d %s -n : nick name is missing\n", + progName, dbdir); + validationFailed = PR_TRUE; + } + if (!headerFileName) { + PR_fprintf(PR_STDERR, "%s -I -d %s -n %s -b : header file name is not found\n", + progName, dbdir, nickNameStr); + validationFailed = PR_TRUE; + } + if (!inFileName) { + PR_fprintf(PR_STDERR, "%s -I -d %s -n %s -b %s -i : input file name is not found\n", + progName, dbdir, nickNameStr, headerFileName); + validationFailed = PR_TRUE; + } + if (validationFailed) { + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + "-I -d <dbdirpath> -b <headerfilename> -i <ipfilename> -n <nickname> \n"); + exit(-1); + } + } + + /* + * Validate the options used for verify command + */ + static void + ValidateVerifyCommand(const char *progName, + const char *dbdir, + const char *headerFileName, + const char *inFileName) + { + PRBool validationFailed = PR_FALSE; + if (!headerFileName) { + PR_fprintf(PR_STDERR, "%s -V -d %s -b : header file name is not found\n", + progName, dbdir); + validationFailed = PR_TRUE; + } + if (!inFileName) { + PR_fprintf(PR_STDERR, "%s -I -d %s -b %s -i : input file name is not found\n", + progName, dbdir, headerFileName); + validationFailed = PR_TRUE; + } + if (validationFailed) { + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + "-I -d <dbdirpath> -b <headerfilename> -i <ipfilename> \n"); + exit(-1); + } + } + + /* + * Validate the options used for Decrypt command + */ + static void + ValidateDecryptCommand(const char *progName, + const char *dbdir, + const char *headerFileName, + const char *encryptedFileName, + const char *outFileName) + { + PRBool validationFailed = PR_FALSE; + if (!headerFileName) { + PR_fprintf(PR_STDERR, "%s -D -d %s -b : header file name is not found\n", + progName, dbdir); + validationFailed = PR_TRUE; + } + if (!encryptedFileName) { + PR_fprintf(PR_STDERR, "%s -D -d %s -b %s -e : encrypt file name is not found\n", + progName, dbdir, headerFileName); + validationFailed = PR_TRUE; + } + if (!outFileName) { + PR_fprintf(PR_STDERR, "%s -D -d %s -b %s -e %s -o : output file name is not found\n", + progName, dbdir, headerFileName, encryptedFileName); + validationFailed = PR_TRUE; + } + if (validationFailed) { + fprintf(stderr, "\nUsage: %s %s \n\n", progName, + "-D -d <dbdirpath> -b <headerfilename> -e <encryptfilename> -o <opfilename>\n"); + exit(-1); + } + } + + /* + * Sign the contents of input file using private key and + * return result as SECItem + */ + SECStatus + SignData(const char *inFileName, SECKEYPrivateKey *pk, SECItem *res) + { + SECStatus rv = SECFailure; + unsigned int nb; + unsigned char ibuf[4096]; + PRFileDesc *inFile = NULL; + SGNContext *sgn = NULL; + + /* Open the input file for reading */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + rv = SECFailure; + goto cleanup; + } + + /* Sign using private key */ + + sgn = SGN_NewContext(SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION, pk); + if (!sgn) { + PR_fprintf(PR_STDERR, "unable to create context for signing\n"); + rv = SECFailure; + goto cleanup; + } + + rv = SGN_Begin(sgn); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "problem while SGN_Begin\n"); + goto cleanup; + } + while ((nb = PR_Read(inFile, ibuf, sizeof(ibuf))) > 0) { + rv = SGN_Update(sgn, ibuf, nb); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "problem while SGN_Update\n"); + goto cleanup; + } + } + rv = SGN_End(sgn, res); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "problem while SGN_End\n"); + goto cleanup; + } + cleanup: + if (inFile) { + PR_Close(inFile); + } + if (sgn) { + SGN_DestroyContext(sgn, PR_TRUE); + } + return rv; + } + + /* + * Verify the signature using public key + */ + SECStatus + VerifyData(const char *inFileName, SECKEYPublicKey *pk, + SECItem *sigItem, secuPWData *pwdata) + { + unsigned int nb; + unsigned char ibuf[4096]; + SECStatus rv = SECFailure; + VFYContext *vfy = NULL; + PRFileDesc *inFile = NULL; + + /* Open the input file for reading */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + rv = SECFailure; + goto cleanup; + } + + vfy = VFY_CreateContext(pk, + sigItem, + SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION, + pwdata); + if (!vfy) { + PR_fprintf(PR_STDERR, "unable to create context for verifying signature\n"); + rv = SECFailure; + goto cleanup; + } + rv = VFY_Begin(vfy); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "problem while VFY_Begin\n"); + goto cleanup; + } + while ((nb = PR_Read(inFile, ibuf, sizeof(ibuf))) > 0) { + rv = VFY_Update(vfy, ibuf, nb); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "problem while VFY_Update\n"); + goto cleanup; + } + } + rv = VFY_End(vfy); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "problem while VFY_End\n"); + goto cleanup; + } + + cleanup: + if (inFile) { + PR_Close(inFile); + } + if (vfy) { + VFY_DestroyContext(vfy, PR_TRUE); + } + return rv; + } + + /* + * Write Cryptographic parameters to header file + */ + SECStatus + WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, + PRFileDesc *outFile) + { + SECStatus rv; + const char *header; + const char *trailer; + + switch (type) { + case SYMKEY: + header = ENCKEY_HEADER; + trailer = ENCKEY_TRAILER; + break; + case MACKEY: + header = MACKEY_HEADER; + trailer = MACKEY_TRAILER; + break; + case IV: + header = IV_HEADER; + trailer = IV_TRAILER; + break; + case MAC: + header = MAC_HEADER; + trailer = MAC_TRAILER; + break; + case PAD: + header = PAD_HEADER; + trailer = PAD_TRAILER; + break; + case PUBKEY: + header = PUBKEY_HEADER; + trailer = PUBKEY_TRAILER; + break; + case CERTENC: + header = NS_CERT_ENC_HEADER; + trailer = NS_CERT_ENC_TRAILER; + break; + case CERTVFY: + header = NS_CERT_VFY_HEADER; + trailer = NS_CERT_VFY_TRAILER; + break; + case SIG: + header = NS_SIG_HEADER; + trailer = NS_SIG_TRAILER; + break; + case LAB: + header = LAB_HEADER; + trailer = LAB_TRAILER; + PR_fprintf(outFile, "%s\n", header); + PR_fprintf(outFile, "%s\n", buf); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + break; + default: + return SECFailure; + } + + PR_fprintf(outFile, "%s\n", header); + PrintAsHex(outFile, buf, len); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + } + + /* + * Read cryptographic parameters from the header file + */ + SECStatus + ReadFromHeaderFile(const char *fileName, HeaderType type, + SECItem *item, PRBool isHexData) + { + SECStatus rv = SECSuccess; + PRFileDesc* file = NULL; + SECItem filedata; + SECItem outbuf; + unsigned char *nonbody; + unsigned char *body; + char *header; + char *trailer; + + outbuf.type = siBuffer; + file = PR_Open(fileName, PR_RDONLY, 0); + if (!file) { + PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); + rv = SECFailure; + goto cleanup; + } + switch (type) { + case PUBKEY: + header = PUBKEY_HEADER; + trailer = PUBKEY_TRAILER; + break; + case SYMKEY: + header = ENCKEY_HEADER; + trailer = ENCKEY_TRAILER; + break; + case MACKEY: + header = MACKEY_HEADER; + trailer = MACKEY_TRAILER; + break; + case IV: + header = IV_HEADER; + trailer = IV_TRAILER; + break; + case MAC: + header = MAC_HEADER; + trailer = MAC_TRAILER; + break; + case PAD: + header = PAD_HEADER; + trailer = PAD_TRAILER; + break; + case LAB: + header = LAB_HEADER; + trailer = LAB_TRAILER; + break; + case CERTENC: + header = NS_CERT_ENC_HEADER; + trailer = NS_CERT_ENC_TRAILER; + break; + case CERTVFY: + header = NS_CERT_VFY_HEADER; + trailer = NS_CERT_VFY_TRAILER; + break; + case SIG: + header = NS_SIG_HEADER; + trailer = NS_SIG_TRAILER; + break; + default: + rv = SECFailure; + goto cleanup; + } + + rv = FileToItem(&filedata, file); + nonbody = (char *)filedata.data; + if (!nonbody) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* check for headers and trailers and remove them */ + if ((body = strstr(nonbody, header)) != NULL) { + char *trail = NULL; + nonbody = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(nonbody, '\r'); /* maybe this is a MAC file */ + if (body) + trail = strstr(++body, trailer); + if (trail != NULL) { + *trail = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + rv = SECFailure; + goto cleanup; + } + } else { + /* headers didn't exist */ + char *trail = NULL; + body = nonbody; + if (body) { + trail = strstr(++body, trailer); + if (trail != NULL) { + PR_fprintf(PR_STDERR, "input has no header but has trailer\n"); + PORT_Free(filedata.data); + rv = SECFailure; + goto cleanup; + } + } + } + HexToBuf(body, item, isHexData); + cleanup: + if (file) { + PR_Close(file); + } + return rv; + } + + /* + * Generate the private key + */ + SECKEYPrivateKey * + GeneratePrivateKey(KeyType keytype, PK11SlotInfo *slot, int size, + int publicExponent, const char *noise, + SECKEYPublicKey **pubkeyp, const char *pqgFile, + secuPWData *pwdata) + { + CK_MECHANISM_TYPE mechanism; + SECOidTag algtag; + PK11RSAGenParams rsaparams; + void *params; + SECKEYPrivateKey *privKey = NULL; + SECStatus rv; + unsigned char randbuf[BLOCKSIZE + 1]; + + rv = GenerateRandom(randbuf, BLOCKSIZE); + if (rv != SECSuccess) { + fprintf(stderr, "Error while generating the random numbers : %s\n", + PORT_ErrorToString(rv)); + goto cleanup; + } + PK11_RandomUpdate(randbuf, BLOCKSIZE); + switch (keytype) { + case rsaKey: + rsaparams.keySizeInBits = size; + rsaparams.pe = publicExponent; + mechanism = CKM_RSA_PKCS_KEY_PAIR_GEN; + algtag = SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION; + params = &rsaparams; + break; + default: + goto cleanup; + } + fprintf(stderr, "\n\n"); + fprintf(stderr, "Generating key. This may take a few moments...\n\n"); + privKey = PK11_GenerateKeyPair(slot, mechanism, params, pubkeyp, + PR_TRUE /*isPerm*/, PR_TRUE /*isSensitive*/, + pwdata); + cleanup: + return privKey; + } + + /* + * Get the certificate request from CSR + */ + static CERTCertificateRequest * + GetCertRequest(char *inFileName, PRBool ascii) + { + CERTSignedData signedData; + SECItem reqDER; + CERTCertificateRequest *certReq = NULL; + SECStatus rv = SECSuccess; + PRArenaPool *arena = NULL; + + reqDER.data = NULL; + arena = PORT_NewArena(DER_DEFAULT_CHUNKSIZE); + if (arena == NULL) { + rv = SECFailure; + goto cleanup; + } + + rv = ReadDERFromFile(&reqDER, inFileName, ascii); + if (rv) { + rv = SECFailure; + goto cleanup; + } + certReq = (CERTCertificateRequest*) PORT_ArenaZAlloc + (arena, sizeof(CERTCertificateRequest)); + if (!certReq) { + rv = SECFailure; + goto cleanup; + } + certReq->arena = arena; + + /* Since cert request is a signed data, must decode to get the inner data */ + PORT_Memset(&signedData, 0, sizeof(signedData)); + rv = SEC_ASN1DecodeItem(arena, &signedData, + SEC_ASN1_GET(CERT_SignedDataTemplate), &reqDER); + if (rv) { + rv = SECFailure; + goto cleanup; + } + rv = SEC_ASN1DecodeItem(arena, certReq, + SEC_ASN1_GET(CERT_CertificateRequestTemplate), &signedData.data); + if (rv) { + rv = SECFailure; + goto cleanup; + } + rv = CERT_VerifySignedDataWithPublicKeyInfo(&signedData, + &certReq->subjectPublicKeyInfo, NULL /* wincx */); + if (reqDER.data) { + SECITEM_FreeItem(&reqDER, PR_FALSE); + } + + cleanup: + if (rv) { + PR_fprintf(PR_STDERR, "bad certificate request\n"); + if (arena) { + PORT_FreeArena(arena, PR_FALSE); + } + certReq = NULL; + } + return certReq; + } + + /* + * Sign Cert + */ + static SECItem * + SignCert(CERTCertDBHandle *handle, CERTCertificate *cert, + PRBool selfsign, SECOidTag hashAlgTag, + SECKEYPrivateKey *privKey, char *issuerNickName, void *pwarg) + { + SECItem der; + SECStatus rv; + SECOidTag algID; + void *dummy; + PRArenaPool *arena = NULL; + SECItem *result = NULL; + SECKEYPrivateKey *caPrivateKey = NULL; + + if (!selfsign) { + CERTCertificate *issuer = PK11_FindCertFromNickname(issuerNickName, pwarg); + if ((CERTCertificate *)NULL == issuer) { + PR_fprintf(PR_STDERR, "unable to find issuer with nickname %s\n", + issuerNickName); + goto cleanup; + } + privKey = caPrivateKey = PK11_FindKeyByAnyCert(issuer, pwarg); + CERT_DestroyCertificate(issuer); + if (caPrivateKey == NULL) { + PR_fprintf(PR_STDERR, "unable to retrieve key %s\n", + issuerNickName); + goto cleanup; + } + } + arena = cert->arena; + algID = SEC_GetSignatureAlgorithmOidTag(privKey->keyType, hashAlgTag); + if (algID == SEC_OID_UNKNOWN) { + PR_fprintf(PR_STDERR, "Unknown key or hash type for issuer.\n"); + goto cleanup; + } + rv = SECOID_SetAlgorithmID(arena, &cert->signature, algID, 0); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not set signature algorithm id.\n%s\n", + PORT_ErrorToString(rv)); + goto cleanup; + } + + /* we only deal with cert v3 here */ + *(cert->version.data) = 2; + cert->version.len = 1; + + der.len = 0; + der.data = NULL; + dummy = SEC_ASN1EncodeItem (arena, &der, cert, + SEC_ASN1_GET(CERT_CertificateTemplate)); + if (!dummy) { + PR_fprintf(PR_STDERR, "Could not encode certificate.\n"); + goto cleanup; + } + + result = (SECItem *) PORT_ArenaZAlloc (arena, sizeof (SECItem)); + if (result == NULL) { + PR_fprintf(PR_STDERR, "Could not allocate item for certificate data.\n"); + goto cleanup; + } + + rv = SEC_DerSignData(arena, result, der.data, der.len, privKey, algID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not sign encoded certificate data : %s\n", + PORT_ErrorToString(rv)); + /* result allocated out of the arena, it will be freed + * when the arena is freed */ + result = NULL; + goto cleanup; + } + cert->derCert = *result; + cleanup: + if (caPrivateKey) { + SECKEY_DestroyPrivateKey(caPrivateKey); + } + return result; + } + + /* + * MakeV1Cert + */ + static CERTCertificate * + MakeV1Cert(CERTCertDBHandle *handle, + CERTCertificateRequest *req, + char * issuerNickName, + PRBool selfsign, + unsigned int serialNumber, + int warpmonths, + int validityMonths) + { + PRExplodedTime printableTime; + PRTime now; + PRTime after; + CERTValidity *validity = NULL; + CERTCertificate *issuerCert = NULL; + CERTCertificate *cert = NULL; + + if ( !selfsign ) { + issuerCert = CERT_FindCertByNicknameOrEmailAddr(handle, issuerNickName); + if (!issuerCert) { + PR_fprintf(PR_STDERR, "could not find certificate named %s\n", + issuerNickName); + goto cleanup; + } + } + + now = PR_Now(); + PR_ExplodeTime (now, PR_GMTParameters, &printableTime); + if ( warpmonths ) { + printableTime.tm_month += warpmonths; + now = PR_ImplodeTime (&printableTime); + PR_ExplodeTime (now, PR_GMTParameters, &printableTime); + } + printableTime.tm_month += validityMonths; + after = PR_ImplodeTime (&printableTime); + + /* note that the time is now in micro-second unit */ + validity = CERT_CreateValidity (now, after); + if (validity) { + cert = CERT_CreateCertificate(serialNumber, + (selfsign ? &req->subject : &issuerCert->subject), + validity, req); + + CERT_DestroyValidity(validity); + } + cleanup: + if ( issuerCert ) { + CERT_DestroyCertificate (issuerCert); + } + return cert; + } + + /* + * Add a certificate to the nss database + */ + SECStatus + AddCert(PK11SlotInfo *slot, CERTCertDBHandle *handle, + const char *name, char *trusts, char *inFileName, + PRBool ascii, PRBool emailcert, void *pwdata) + { + SECItem certDER; + SECStatus rv; + CERTCertTrust *trust = NULL; + CERTCertificate *cert = NULL; + + certDER.data = NULL; + + /* Read in the entire file specified with the -i argument */ + rv = ReadDERFromFile(&certDER, inFileName, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "unable to read input file %s : %s\n", + inFileName, PORT_ErrorToString(rv)); + goto cleanup; + } + + /* Read in an ASCII cert and return a CERTCertificate */ + cert = CERT_DecodeCertFromPackage((char *)certDER.data, certDER.len); + if (!cert) { + PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); + rv = SECFailure; + goto cleanup; + } + + /* Create a cert trust */ + trust = (CERTCertTrust *)PORT_ZAlloc(sizeof(CERTCertTrust)); + if (!trust) { + PR_fprintf(PR_STDERR, "unable to allocate cert trust\n"); + rv = SECFailure; + goto cleanup; + } + + rv = CERT_DecodeTrustString(trust, trusts); + if (rv) { + PR_fprintf(PR_STDERR, "unable to decode trust string\n"); + rv = SECFailure; + goto cleanup; + } + + rv = PK11_ImportCert(slot, cert, CK_INVALID_HANDLE, name, PR_FALSE); + if (rv != SECSuccess) { + /* sigh, PK11_Import Cert and CERT_ChangeCertTrust should have + * been coded to take a password arg. */ + if (PORT_GetError() == SEC_ERROR_TOKEN_NOT_LOGGED_IN) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "could not authenticate to token %s : %s\n", + PK11_GetTokenName(slot), PORT_ErrorToString(rv)); + rv = SECFailure; + goto cleanup; + } + rv = PK11_ImportCert(slot, cert, CK_INVALID_HANDLE, + name, PR_FALSE); + } + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "could not add certificate to token or database : %s\n", + PORT_ErrorToString(rv)); + rv = SECFailure; + goto cleanup; + } + } + rv = CERT_ChangeCertTrust(handle, cert, trust); + if (rv != SECSuccess) { + if (PORT_GetError() == SEC_ERROR_TOKEN_NOT_LOGGED_IN) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "could not authenticate to token %s : %s\n", + PK11_GetTokenName(slot), PORT_ErrorToString(rv)); + rv = SECFailure; + goto cleanup; + } + rv = CERT_ChangeCertTrust(handle, cert, trust); + } + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "could not change trust on certificate : %s\n", + PORT_ErrorToString(rv)); + rv = SECFailure; + goto cleanup; + } + } + + if (emailcert) { + CERT_SaveSMimeProfile(cert, NULL, pwdata); + } + + cleanup: + if (cert) { + CERT_DestroyCertificate (cert); + } + if (trust) { + PORT_Free(trust); + } + if (certDER.data) { + PORT_Free(certDER.data); + } + return rv; + } + + /* + * Create a certificate + */ + static SECStatus + CreateCert( + CERTCertDBHandle *handle, + PK11SlotInfo *slot, + char * issuerNickName, + char *inFileName, + char *outFileName, + SECKEYPrivateKey **selfsignprivkey, + void *pwarg, + SECOidTag hashAlgTag, + unsigned int serialNumber, + int warpmonths, + int validityMonths, + const char *dnsNames, + PRBool ascii, + PRBool selfsign) + { + void *extHandle; + SECItem reqDER; + CERTCertExtension **CRexts; + SECStatus rv = SECSuccess; + CERTCertificate *subjectCert = NULL; + CERTCertificateRequest *certReq = NULL; + PRFileDesc *outFile = NULL; + SECItem *certDER = NULL; + + reqDER.data = NULL; + outFile = PR_Open(outFileName, + PR_RDWR | PR_CREATE_FILE | PR_TRUNCATE, 00660); + + /* Create a cert request object from the input cert request der */ + certReq = GetCertRequest(inFileName, ascii); + if (certReq == NULL) { + rv = SECFailure; + goto cleanup; + } + subjectCert = MakeV1Cert(handle, certReq, issuerNickName, selfsign, + serialNumber, warpmonths, validityMonths); + if (subjectCert == NULL) { + rv = SECFailure; + goto cleanup; + } + + extHandle = CERT_StartCertExtensions (subjectCert); + if (extHandle == NULL) { + rv = SECFailure; + goto cleanup; + } + + if (certReq->attributes != NULL && + certReq->attributes[0] != NULL && + certReq->attributes[0]->attrType.data != NULL && + certReq->attributes[0]->attrType.len > 0 && + SECOID_FindOIDTag(&certReq->attributes[0]->attrType) + == SEC_OID_PKCS9_EXTENSION_REQUEST) { + rv = CERT_GetCertificateRequestExtensions(certReq, &CRexts); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "%s\n", PORT_ErrorToString(rv)); + goto cleanup; + } + rv = CERT_MergeExtensions(extHandle, CRexts); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "%s\n", PORT_ErrorToString(rv)); + goto cleanup; + } + } + + CERT_FinishExtensions(extHandle); + + /* self-signing a cert request, find the private key */ + if (*selfsignprivkey == NULL) { + *selfsignprivkey = PK11_FindKeyByDERCert(slot, subjectCert, pwarg); + if (!*selfsignprivkey) { + PR_fprintf(PR_STDERR, "Failed to locate private key.\n"); + rv = SECFailure; + goto cleanup; + } + } + + certDER = SignCert(handle, subjectCert, selfsign, hashAlgTag, + *selfsignprivkey, issuerNickName,pwarg); + if (certDER) { + if (ascii) { + PR_fprintf(outFile, "%s\n%s\n%s\n", NS_CERT_HEADER, + BTOA_DataToAscii(certDER->data, certDER->len), + NS_CERT_TRAILER); + } else { + PR_Write(outFile, certDER->data, certDER->len); + } + } + if (rv != SECSuccess) { + PRErrorCode perr = PR_GetError(); + PR_fprintf(PR_STDERR, "unable to create cert %s\n", + perr); + } + cleanup: + if (outFile) { + PR_Close(outFile); + } + if (*selfsignprivkey) { + SECKEY_DestroyPrivateKey(*selfsignprivkey); + } + if (certReq) { + CERT_DestroyCertificateRequest(certReq); + } + if (subjectCert) { + CERT_DestroyCertificate(subjectCert); + } + return rv; + } + + /* + * Generate the certificate request with subject + */ + static SECStatus + CertReq(SECKEYPrivateKey *privk, SECKEYPublicKey *pubk, KeyType keyType, + SECOidTag hashAlgTag, CERTName *subject, PRBool ascii, + const char *certReqFileName) + { + SECOidTag signAlgTag; + SECItem result; + PRInt32 numBytes; + SECStatus rv = SECSuccess; + PRArenaPool *arena = NULL; + void *extHandle = NULL; + PRFileDesc *outFile = NULL; + CERTSubjectPublicKeyInfo *spki = NULL; + CERTCertificateRequest *cr = NULL; + SECItem *encoding = NULL; + + /* If the certificate request file already exists, delete it */ + if (PR_Access(certReqFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(certReqFileName); + } + /* Open the certificate request file to write */ + outFile = PR_Open(certReqFileName, PR_CREATE_FILE | PR_RDWR | PR_TRUNCATE, 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, + "unable to open \"%s\" for writing (%ld, %ld).\n", + certReqFileName, PR_GetError(), PR_GetOSError()); + goto cleanup; + } + /* Create info about public key */ + spki = SECKEY_CreateSubjectPublicKeyInfo(pubk); + if (!spki) { + PR_fprintf(PR_STDERR, "unable to create subject public key\n"); + rv = SECFailure; + goto cleanup; + } + + /* Generate certificate request */ + cr = CERT_CreateCertificateRequest(subject, spki, NULL); + if (!cr) { + PR_fprintf(PR_STDERR, "unable to make certificate request\n"); + rv = SECFailure; + goto cleanup; + } + + arena = PORT_NewArena(DER_DEFAULT_CHUNKSIZE); + if (!arena) { + fprintf(stderr, "out of memory"); + rv = SECFailure; + goto cleanup; + } + + extHandle = CERT_StartCertificateRequestAttributes(cr); + if (extHandle == NULL) { + PORT_FreeArena (arena, PR_FALSE); + rv = SECFailure; + goto cleanup; + } + + CERT_FinishExtensions(extHandle); + CERT_FinishCertificateRequestAttributes(cr); + + /* Der encode the request */ + encoding = SEC_ASN1EncodeItem(arena, NULL, cr, + SEC_ASN1_GET(CERT_CertificateRequestTemplate)); + if (encoding == NULL) { + PR_fprintf(PR_STDERR, "der encoding of request failed\n"); + rv = SECFailure; + goto cleanup; + } + + /* Sign the request */ + signAlgTag = SEC_GetSignatureAlgorithmOidTag(keyType, hashAlgTag); + if (signAlgTag == SEC_OID_UNKNOWN) { + PR_fprintf(PR_STDERR, "unknown Key or Hash type\n"); + rv = SECFailure; + goto cleanup; + } + rv = SEC_DerSignData(arena, &result, encoding->data, encoding->len, + privk, signAlgTag); + if (rv) { + PR_fprintf(PR_STDERR, "signing of data failed\n"); + rv = SECFailure; + goto cleanup; + } + + /* Encode request in specified format */ + if (ascii) { + char *obuf; + char *name, *email, *org, *state, *country; + SECItem *it; + int total; + + it = &result; + + obuf = BTOA_ConvertItemToAscii(it); + total = PL_strlen(obuf); + + name = CERT_GetCommonName(subject); + if (!name) { + name = strdup("(not specified)"); + } + + email = CERT_GetCertEmailAddress(subject); + if (!email) + email = strdup("(not specified)"); + + org = CERT_GetOrgName(subject); + if (!org) + org = strdup("(not specified)"); + + state = CERT_GetStateName(subject); + if (!state) + state = strdup("(not specified)"); + + country = CERT_GetCountryName(subject); + if (!country) + country = strdup("(not specified)"); + + PR_fprintf(outFile, + "\nCertificate request generated by Netscape certutil\n"); + PR_fprintf(outFile, "Common Name: %s\n", name); + PR_fprintf(outFile, "Email: %s\n", email); + PR_fprintf(outFile, "Organization: %s\n", org); + PR_fprintf(outFile, "State: %s\n", state); + PR_fprintf(outFile, "Country: %s\n\n", country); + + PR_fprintf(outFile, "%s\n", NS_CERTREQ_HEADER); + numBytes = PR_Write(outFile, obuf, total); + if (numBytes != total) { + PR_fprintf(PR_STDERR, "write error\n"); + return SECFailure; + } + PR_fprintf(outFile, "\n%s\n", NS_CERTREQ_TRAILER); + } else { + numBytes = PR_Write(outFile, result.data, result.len); + if (numBytes != (int)result.len) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + goto cleanup; + } + } + cleanup: + if (outFile) { + PR_Close(outFile); + } + if (privk) { + SECKEY_DestroyPrivateKey(privk); + } + if (pubk) { + SECKEY_DestroyPublicKey(pubk); + } + return rv; + } + + /* + * Create certificate request with subject + */ + SECStatus CreateCertRequest(PK11SlotInfo *slot, + secuPWData *pwdata, + CERTName *subject, + char *certReqFileName, + PRBool ascii) + { + SECStatus rv; + SECKEYPrivateKey *privkey = NULL; + SECKEYPublicKey *pubkey = NULL; + KeyType keytype = rsaKey; + int keysize = DEFAULT_KEY_BITS; + int publicExponent = 0x010001; + SECOidTag hashAlgTag = SEC_OID_UNKNOWN; + + privkey = GeneratePrivateKey(keytype, slot, keysize, + publicExponent, NULL, + &pubkey, NULL, pwdata); + if (privkey == NULL) { + PR_fprintf(PR_STDERR, "unable to generate key(s)\n"); + rv = SECFailure; + goto cleanup; + } + privkey->wincx = pwdata; + PORT_Assert(pubkey != NULL); + rv = CertReq(privkey, pubkey, keytype, hashAlgTag, subject, + ascii, certReqFileName); + + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to create Certificate Request\n"); + } + cleanup: + return rv; + } + + /* + * Creates the certificate using CSR and adds the certificate to DB + */ + SECStatus AddCertificateToDB(PK11SlotInfo *slot, + secuPWData *pwdata, + char *certReqFileName, + char *certFileName, + char *issuerNameStr, + CERTCertDBHandle *certHandle, + const char *nickNameStr, + char *trustStr, + unsigned int serialNumber, + PRBool selfsign, + PRBool ascii) + { + SECStatus rv; + SECKEYPrivateKey *privkey = NULL; + SECKEYPublicKey *pubkey = NULL; + SECOidTag hashAlgTag = SEC_OID_UNKNOWN; + + if (PR_Access(certFileName, PR_ACCESS_EXISTS) == PR_FAILURE) { + rv = CreateCert(certHandle, slot, issuerNameStr, + certReqFileName, certFileName, &privkey, &pwdata, hashAlgTag, + serialNumber, 0, 3, NULL, ascii, selfsign); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to create Certificate\n"); + goto cleanup; + } + } + rv = AddCert(slot, certHandle, nickNameStr, + trustStr, certFileName, ascii, 0, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to add Certificate\n"); + } + cleanup: + return rv; + } + + /* + * Finds the certificate using nickname and saves it to the header file + */ + SECStatus AddCertificateToHeader(PK11SlotInfo *slot, + secuPWData *pwdata, + const char *headerFileName, + CERTCertDBHandle *certHandle, + const char *nickNameStr, + PRBool sigVerify) + + { + SECStatus rv = SECSuccess; + PRFileDesc *headerFile = NULL; + CERTCertificate *cert = NULL; + HeaderType hType = CERTENC; + + /* If the intermediate header file already exists, delete it */ + if (PR_Access(headerFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(headerFileName); + } + headerFile = PR_Open(headerFileName, PR_CREATE_FILE | PR_RDWR | PR_TRUNCATE, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, + "unable to open \"%s\" for writing (%ld, %ld).\n", + headerFileName, PR_GetError(), PR_GetOSError()); + rv = SECFailure; + goto cleanup; + } + cert = CERT_FindCertByNicknameOrEmailAddr(certHandle, nickNameStr); + if (!cert) { + PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); + rv = SECFailure; + goto cleanup; + } + if (sigVerify) { + hType = CERTVFY; + } + WriteToHeaderFile(cert->derCert.data, cert->derCert.len, hType, headerFile); + cleanup: + if (headerFile) { + PR_Close(headerFile); + } + if (cert) { + CERT_DestroyCertificate(cert); + } + return rv; + } + + /* + * Finds the public key from the certificate saved in the header file + * and encrypts with it the contents of inFileName to encryptedFileName. + */ + SECStatus FindKeyAndEncrypt(PK11SlotInfo *slot, + secuPWData *pwdata, + const char *headerFileName, + const char *encryptedFileName, + const char *inFileName) + { + SECStatus rv; + PRFileDesc *headerFile = NULL; + PRFileDesc *encFile = NULL; + PRFileDesc *inFile = NULL; + CERTCertificate *cert = NULL; + SECItem data; + unsigned char ptext[MODBLOCKSIZE]; + unsigned char encBuf[MODBLOCKSIZE]; + unsigned int ptextLen; + int index; + unsigned int nWritten; + unsigned int pad[1]; + SECItem padItem; + unsigned int paddingLength = 0; + SECKEYPublicKey *pubkey = NULL; + + /* If the intermediate encrypted file already exists, delete it*/ + if (PR_Access(encryptedFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(encryptedFileName); + } + + /* Read certificate from header file */ + rv = ReadFromHeaderFile(headerFileName, CERTENC, &data, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not read certificate from header file\n"); + goto cleanup; + } + /* Read in an ASCII cert and return a CERTCertificate */ + cert = CERT_DecodeCertFromPackage((char *)data.data, data.len); + if (!cert) { + PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); + rv = SECFailure; + goto cleanup; + } + /* Extract the public key from certificate */ + pubkey = CERT_ExtractPublicKey(cert); + if (!pubkey) { + PR_fprintf(PR_STDERR, "could not get key from certificate\n"); + rv = SECFailure; + goto cleanup; + } + + /* Open the encrypted file for writing */ + encFile = PR_Open(encryptedFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!encFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + rv = SECFailure; + goto cleanup; + } + + /* Open the input file for reading */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + rv = SECFailure; + goto cleanup; + } + + /* Open the header file to write padding */ + headerFile = PR_Open(headerFileName, PR_CREATE_FILE | PR_RDWR | PR_APPEND, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", + headerFileName); + rv = SECFailure; + goto cleanup; + } + + /* Read input file */ + while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { + if (ptextLen != MODBLOCKSIZE) { + paddingLength = MODBLOCKSIZE - ptextLen; + for ( index=0; index < paddingLength; index++) { + ptext[ptextLen+index] = (unsigned char)paddingLength; + } + ptextLen = MODBLOCKSIZE; + } + rv = PK11_PubEncryptRaw(pubkey, encBuf, ptext, ptextLen, NULL); + nWritten = PR_Write(encFile, encBuf, ptextLen); + } + + /* Write the padding to header file */ + pad[0] = paddingLength; + padItem.type = siBuffer; + padItem.data = (unsigned char *)pad; + padItem.len = sizeof(pad[0]); + WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); + + cleanup: + if (headerFile) { + PR_Close(headerFile); + } + if (encFile) { + PR_Close(encFile); + } + if (inFile) { + PR_Close(inFile); + } + if (pubkey) { + SECKEY_DestroyPublicKey(pubkey); + } + if (cert) { + CERT_DestroyCertificate(cert); + } + return rv; + } + + /* + * Finds the private key from db and signs the contents + * of inFileName and writes to signatureFileName + */ + SECStatus FindKeyAndSign(PK11SlotInfo *slot, + CERTCertDBHandle* certHandle, + secuPWData *pwdata, + const char *nickNameStr, + const char *headerFileName, + const char *inFileName) + { + SECStatus rv; + PRFileDesc *headerFile = NULL; + PRFileDesc *inFile = NULL; + CERTCertificate *cert = NULL; + unsigned int signatureLen = 0; + SECKEYPrivateKey *privkey = NULL; + SECItem sigItem; + SECOidTag hashOIDTag; + + /* Open the header file to write padding */ + headerFile = PR_Open(headerFileName, PR_CREATE_FILE | PR_RDWR | PR_APPEND, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", + headerFileName); + rv = SECFailure; + goto cleanup; + } + + /* Get the certificate by nick name and write to header file */ + cert = CERT_FindCertByNicknameOrEmailAddr(certHandle, nickNameStr); + if (!cert) { + PR_fprintf(PR_STDERR, "could not obtain certificate by name - %s\n", nickNameStr); + rv = SECFailure; + goto cleanup; + } + WriteToHeaderFile(cert->derCert.data, cert->derCert.len, CERTVFY, headerFile); + + + /* Find private key from certificate */ + privkey = PK11_FindKeyByAnyCert(cert, NULL); + if (privkey == NULL) { + fprintf(stderr, "Couldn't find private key for cert\n"); + rv = SECFailure; + goto cleanup; + } + + /* Sign the contents of the input file */ + rv = SignData(inFileName, privkey, &sigItem); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "could not sign the contents from file - %s \n", inFileName); + goto cleanup; + } + + /* write signature to header file */ + WriteToHeaderFile(sigItem.data, sigItem.len, SIG, headerFile); + + cleanup: + if (headerFile) { + PR_Close(headerFile); + } + if (privkey) { + SECKEY_DestroyPrivateKey(privkey); + } + if (cert) { + CERT_DestroyCertificate(cert); + } + return rv; + } + + /* + * Finds the public key from certificate and verifies signature + */ + SECStatus FindKeyAndVerify(PK11SlotInfo *slot, + CERTCertDBHandle* certHandle, + secuPWData *pwdata, + const char *headerFileName, + const char *inFileName) + { + SECStatus rv = SECFailure; + PRFileDesc *headerFile = NULL; + PRFileDesc *inFile = NULL; + CERTCertificate *cert = NULL; + SECKEYPublicKey *pubkey = NULL; + SECItem sigItem; + SECItem certData; + + + /* Open the input file */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for reading.\n", + inFileName); + rv = SECFailure; + goto cleanup; + } + + /* Open the header file to read the certificate and signature */ + headerFile = PR_Open(headerFileName, PR_RDONLY, 0); + if (!headerFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", + headerFileName); + rv = SECFailure; + goto cleanup; + } + + /* Read certificate from header file */ + rv = ReadFromHeaderFile(headerFileName, CERTVFY, &certData, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not read certificate from header file\n"); + goto cleanup; + } + + /* Read in an ASCII cert and return a CERTCertificate */ + cert = CERT_DecodeCertFromPackage((char *)certData.data, certData.len); + if (!cert) { + PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); + rv = SECFailure; + goto cleanup; + } + + /* Extract the public key from certificate */ + pubkey = CERT_ExtractPublicKey(cert); + if (!pubkey) { + PR_fprintf(PR_STDERR, "Could not get key from certificate\n"); + rv = SECFailure; + goto cleanup; + } + + /* Read signature from header file */ + rv = ReadFromHeaderFile(headerFileName, SIG, &sigItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not read signature from header file\n"); + goto cleanup; + } + + /* Verify with the public key */ + rv = VerifyData(inFileName, pubkey, &sigItem, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Couldn't verify the signature for file - %s\n", inFileName); + goto cleanup; + } + + cleanup: + if (headerFile) { + PR_Close(headerFile); + } + if (pubkey) { + SECKEY_DestroyPublicKey(pubkey); + } + if (cert) { + CERT_DestroyCertificate(cert); + } + return rv; + } + + /* + * Finds the private key corresponding to the certificate saved in the header file + * and decrypts with it the contents of encryptedFileName to outFileName. + */ + SECStatus FindKeyAndDecrypt(PK11SlotInfo *slot, + secuPWData *pwdata, + const char *headerFileName, + const char *encryptedFileName, + const char *outFileName) + { + SECStatus rv; + PRFileDesc *encFile = NULL; + PRFileDesc *outFile = NULL; + SECKEYPrivateKey *pvtkey = NULL; + unsigned int inFileLength = 0; + unsigned int paddingLength = 0; + unsigned int count = 0; + unsigned int temp = 0; + unsigned char ctext[MODBLOCKSIZE]; + unsigned char decBuf[MODBLOCKSIZE]; + unsigned int ctextLen; + unsigned int decBufLen; + SECItem padItem; + SECItem data; + SECItem signature; + CERTCertificate *cert = NULL; + + /* Read certificate from header file */ + rv = ReadFromHeaderFile(headerFileName, CERTENC, &data, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not read certificate from header file\n"); + goto cleanup; + } + + /* Read padding from header file */ + rv = ReadFromHeaderFile(headerFileName, PAD, &padItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve PAD detail from header file\n"); + goto cleanup; + } + paddingLength = (unsigned int)padItem.data[0]; + inFileLength = FileSize(encryptedFileName); + + /* Read in an ASCII cert and return a CERTCertificate */ + cert = CERT_DecodeCertFromPackage((char *)data.data, data.len); + if (!cert) { + PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); + rv = SECFailure; + goto cleanup; + } + + /* Find private key from certificate */ + pvtkey = PK11_FindKeyByAnyCert(cert, NULL); + if (pvtkey == NULL) { + fprintf(stderr, "Couldn't find private key for cert\n"); + rv = SECFailure; + goto cleanup; + } + + /* Open the out file to write */ + outFile = PR_Open(outFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", + outFileName); + rv = SECFailure; + goto cleanup; + } + /* Open the encrypted file for reading */ + encFile = PR_Open(encryptedFileName, PR_RDONLY, 0); + if (!encFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + encryptedFileName); + rv = SECFailure; + goto cleanup; + } + /* Read the encrypt file, decrypt and write to out file */ + while ((ctextLen = PR_Read(encFile, ctext, sizeof(ctext))) > 0) { + count += ctextLen; + rv = PK11_PubDecryptRaw(pvtkey, decBuf, &decBufLen, sizeof(decBuf), ctext, ctextLen); + if (rv != SECSuccess) { + fprintf(stderr, "Couldn't decrypt\n"); + goto cleanup; + } + if (decBufLen == 0) { + break; + } + if (count == inFileLength) { + decBufLen = decBufLen - paddingLength; + } + /* write the plain text to out file */ + temp = PR_Write(outFile, decBuf, decBufLen); + if (temp != decBufLen) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + break; + } + } + cleanup: + if (encFile) { + PR_Close(encFile); + } + if (outFile) { + PR_Close(outFile); + } + if (pvtkey) { + SECKEY_DestroyPrivateKey(pvtkey); + } + if (cert) { + CERT_DestroyCertificate(cert); + } + return rv; + } + + /* Map option letter to command */ + static CommandType option2Command(char c) + { + switch (c) { + case 'G': return GENERATE_CSR; + case 'A': return ADD_CERT_TO_DB; + case 'H': return SAVE_CERT_TO_HEADER; + case 'E': return ENCRYPT; + case 'D': return DECRYPT; + case 'S': return SIGN; + case 'V': return VERIFY; + default: return UNKNOWN; + } + } + + /* + * This example illustrates basic encryption/decryption and MACing + * Generates the RSA key pair as token object and outputs public key as cert request. + * Reads cert request file and stores certificate in DB. + * Input, store and trust CA certificate. + * Write certificate to intermediate header file + * Extract public key from certificate, encrypts the input file and write to external file. + * Finds the matching private key, decrypts and write to external file + * + * How this sample is different from sample 5 ? + * + * 1. As in sample 5, output is a PKCS#10 CSR + * 2. Input and store a cert in cert DB and also used to input, store and trust CA cert. + * 3. Like sample 5, but puts cert in header + * 4. Like sample 5, but finds key matching cert in header + */ + int + main(int argc, char **argv) + { + SECStatus rv; + PLOptState *optstate; + PLOptStatus status; + PRBool initialized = PR_FALSE; + + CommandType cmd = UNKNOWN; + const char *dbdir = NULL; + secuPWData pwdata = { PW_NONE, 0 }; + + char *subjectStr = NULL; + CERTName *subject = 0; + + unsigned int serialNumber = 0; + char *serialNumberStr = NULL; + char *trustStr = NULL; + CERTCertDBHandle *certHandle; + const char *nickNameStr = NULL; + char *issuerNameStr = NULL; + PRBool selfsign = PR_FALSE; + PRBool ascii = PR_FALSE; + PRBool sigVerify = PR_FALSE; + + const char *headerFileName = NULL; + const char *encryptedFileName = NULL; + const char *inFileName = NULL; + const char *outFileName = NULL; + char *certReqFileName = NULL; + char *certFileName = NULL; + const char *noiseFileName = NULL; + PK11SlotInfo *slot = NULL; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "GAHEDSVad:i:o:f:p:z:s:r:n:x:m:t:c:u:e:b:v:"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'a': + ascii = PR_TRUE; + break; + case 'G': /* Generate a CSR */ + case 'A': /* Add cert to database */ + case 'H': /* Save cert to the header file */ + case 'E': /* Encrypt with public key from cert in header file */ + case 'S': /* Sign with private key */ + case 'D': /* Decrypt with the matching private key */ + case 'V': /* Verify with the matching public key */ + cmd = option2Command(optstate->option); + break; + case 'd': + dbdir = strdup(optstate->value); + break; + case 'f': + pwdata.source = PW_FROMFILE; + pwdata.data = strdup(optstate->value); + break; + case 'p': + pwdata.source = PW_PLAINTEXT; + pwdata.data = strdup(optstate->value); + break; + case 'i': + inFileName = strdup(optstate->value); + break; + case 'b': + headerFileName = strdup(optstate->value); + break; + case 'e': + encryptedFileName = strdup(optstate->value); + break; + case 'o': + outFileName = strdup(optstate->value); + break; + case 'z': + noiseFileName = strdup(optstate->value); + break; + case 's': + subjectStr = strdup(optstate->value); + subject = CERT_AsciiToName(subjectStr); + break; + case 'r': + certReqFileName = strdup(optstate->value); + break; + case 'c': + certFileName = strdup(optstate->value); + break; + case 'u': + issuerNameStr = strdup(optstate->value); + break; + case 'n': + nickNameStr = strdup(optstate->value); + break; + case 'x': + selfsign = PR_TRUE; + break; + case 'm': + serialNumberStr = strdup(optstate->value); + serialNumber = atoi(serialNumberStr); + break; + case 't': + trustStr = strdup(optstate->value); + break; + case 'v': + sigVerify = PR_TRUE; + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (cmd == UNKNOWN || !dbdir) + Usage(progName); + + /* Open DB for read/write and authenticate to it */ + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + initialized = PR_TRUE; + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); + goto cleanup; + } + + PK11_SetPasswordFunc(GetModulePassword); + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + + switch (cmd) { + case GENERATE_CSR: + ValidateGenerateCSRCommand(progName, dbdir, subject, subjectStr, + certReqFileName); + /* Generate a CSR */ + rv = CreateCertRequest(slot, &pwdata, subject, + certReqFileName, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Create Certificate Request: Failed\n"); + goto cleanup; + } + break; + case ADD_CERT_TO_DB: + ValidateAddCertToDBCommand(progName, dbdir, nickNameStr, trustStr, + certFileName, certReqFileName, + issuerNameStr, serialNumberStr, selfsign); + /* Add cert to database */ + rv = AddCertificateToDB(slot, &pwdata, certReqFileName, certFileName, + issuerNameStr, certHandle, nickNameStr, + trustStr, serialNumber, selfsign, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Add Certificate to DB: Failed\n"); + goto cleanup; + } + break; + case SAVE_CERT_TO_HEADER: + ValidateSaveCertToHeaderCommand(progName, dbdir, nickNameStr, headerFileName); + /* Save cert to the header file */ + rv = AddCertificateToHeader(slot, &pwdata, headerFileName, certHandle, nickNameStr, sigVerify); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Saving Certificate to header: Failed\n"); + goto cleanup; + } + break; + case ENCRYPT: + ValidateEncryptCommand(progName, dbdir, nickNameStr, headerFileName, inFileName, encryptedFileName); + /* Encrypt with public key from cert in header file */ + rv = FindKeyAndEncrypt(slot, &pwdata, headerFileName, encryptedFileName, inFileName); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Find public key and Encrypt : Failed\n"); + goto cleanup; + } + break; + case SIGN: + ValidateSignCommand(progName, dbdir, nickNameStr, headerFileName, inFileName); + /* Sign with private key */ + rv = FindKeyAndSign(slot, certHandle, &pwdata, nickNameStr, headerFileName, inFileName); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Find private key and sign : Failed\n"); + goto cleanup; + } + break; + case DECRYPT: + ValidateDecryptCommand(progName, dbdir, headerFileName, encryptedFileName, outFileName); + /* Decrypt with the matching private key */ + rv = FindKeyAndDecrypt(slot, &pwdata, headerFileName, encryptedFileName, outFileName); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Find private key and Decrypt : Failed\n"); + } + break; + case VERIFY: + ValidateVerifyCommand(progName, dbdir, headerFileName, inFileName); + /* Verify with the matching public key */ + rv = FindKeyAndVerify(slot, certHandle, &pwdata, headerFileName, inFileName); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Find public key and verify signature : Failed\n"); + goto cleanup; + } + } + cleanup: + if (slot) { + PK11_FreeSlot(slot); + } + if (initialized) { + SECStatus rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown() - %s", + PORT_ErrorToString(rvShutdown)); + rv = SECFailure; + } + PR_Cleanup(); + } + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/encrypt_decrypt_mac_using_token/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/encrypt_decrypt_mac_using_token/index.rst new file mode 100644 index 0000000000..712823698d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/encrypt_decrypt_mac_using_token/index.rst @@ -0,0 +1,1206 @@ +.. _mozilla_projects_nss_nss_sample_code_encrypt_decrypt_mac_using_token: + +Encrypt Decrypt_MAC_Using Token +=============================== + +.. _nss_sample_code_3_encryptiondecryption_and_mac_using_token_object.: + +`NSS Sample Code 3: Encryption/Decryption and MAC Using Token Object. <#nss_sample_code_3_encryptiondecryption_and_mac_using_token_object.>`__ +---------------------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + Generates encryption/mac keys and uses token for storing. + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + /* NSPR Headers */ + #include + #include + #include + #include + #include + #include + #include + + /* NSS headers */ + #include + #include + + /* Our samples utilities */ + #include "util.h" + + #define BUFFERSIZE 80 + #define DIGESTSIZE 16 + #define PTEXT_MAC_BUFFER_SIZE 96 + #define CIPHERSIZE 96 + #define BLOCKSIZE 32 + + #define CIPHER_HEADER "-----BEGIN CIPHER-----" + #define CIPHER_TRAILER "-----END CIPHER-----" + #define ENCKEY_HEADER "-----BEGIN AESKEY CKAID-----" + #define ENCKEY_TRAILER "-----END AESKEY CKAID-----" + #define MACKEY_HEADER "-----BEGIN MACKEY CKAID-----" + #define MACKEY_TRAILER "-----END MACKEY CKAID-----" + #define IV_HEADER "-----BEGIN IV-----" + #define IV_TRAILER "-----END IV-----" + #define MAC_HEADER "-----BEGIN MAC-----" + #define MAC_TRAILER "-----END MAC-----" + #define PAD_HEADER "-----BEGIN PAD-----" + #define PAD_TRAILER "-----END PAD-----" + + typedef enum { + ENCRYPT, + DECRYPT, + UNKNOWN + } CommandType; + + typedef enum { + SYMKEY = 0, + MACKEY = 1, + IV = 2, + MAC = 3, + PAD = 4 + } HeaderType; + + + /* + * Print usage message and exit. + */ + static void + Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s -c -d [-z ] " + "[-p | -f ] -i -o \n\n", + progName); + fprintf(stderr, "%-20s Specify 'a' for encrypt operation\n\n", + "-c "); + fprintf(stderr, "%-20s Specify 'b' for decrypt operation\n\n", + " "); + fprintf(stderr, "%-20s Specify db directory path\n\n", + "-d "); + fprintf(stderr, "%-20s Specify db password [optional]\n\n", + "-p "); + fprintf(stderr, "%-20s Specify db password file [optional]\n\n", + "-f "); + fprintf(stderr, "%-20s Specify noise file name [optional]\n\n", + "-z "); + fprintf(stderr, "%-21s Specify an input file name\n\n", + "-i "); + fprintf(stderr, "%-21s Specify an output file name\n\n", + "-o "); + fprintf(stderr, "%-7s For encrypt, it takes as an input file and produces\n", + "Note :"); + fprintf(stderr, "%-7s .enc and .header as intermediate output files.\n\n", + ""); + fprintf(stderr, "%-7s For decrypt, it takes .enc and .header\n", + ""); + fprintf(stderr, "%-7s as input files and produces as a final output file.\n\n", + ""); + exit(-1); + } + + /* + * Gather a CKA_ID. + */ + SECStatus + GatherCKA_ID(PK11SymKey* key, SECItem* buf) + { + SECStatus rv = PK11_ReadRawAttribute(PK11_TypeSymKey, key, CKA_ID, buf); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "PK11_ReadRawAttribute returned (%d)\n", rv); + PR_fprintf(PR_STDERR, "Could not read SymKey CKA_ID attribute\n"); + return rv; + } + return rv; + } + + /* + * Generate a Symmetric Key. + */ + PK11SymKey * + GenerateSYMKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE mechanism, + int keySize, SECItem *keyID, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + return NULL; + } + } + + /* Generate the symmetric key. */ + key = PK11_TokenKeyGen(slot, mechanism, + NULL, keySize, keyID, PR_TRUE, pwdata); + + if (!key) { + PR_fprintf(PR_STDERR, "Symmetric Key Generation Failed \n"); + } + + return key; + } + + /* + * MacInit + */ + SECStatus + MacInit(PK11Context *ctx) + { + SECStatus rv = PK11_DigestBegin(ctx); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestBegin()\n"); + } + return rv; + } + + /* + * MacUpdate + */ + SECStatus + MacUpdate(PK11Context *ctx, + unsigned char *msg, unsigned int msgLen) + { + SECStatus rv = PK11_DigestOp(ctx, msg, msgLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : DigestOp()\n"); + } + return rv; + } + + /* + * Finalize MACing. + */ + SECStatus + MacFinal(PK11Context *ctx, + unsigned char *mac, unsigned int *macLen, unsigned int maxLen) + { + SECStatus rv = PK11_DigestFinal(ctx, mac, macLen, maxLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestFinal()\n"); + } + return SECSuccess; + } + + /* + * Compute Mac. + */ + SECStatus + ComputeMac(PK11Context *ctxmac, + unsigned char *ptext, unsigned int ptextLen, + unsigned char *mac, unsigned int *macLen, + unsigned int maxLen) + { + SECStatus rv = MacInit(ctxmac); + if (rv != SECSuccess) return rv; + rv = MacUpdate(ctxmac, ptext, ptextLen); + if (rv != SECSuccess) return rv; + rv = MacFinal(ctxmac, mac, macLen, maxLen); + return rv; + } + + /* + * WriteToHeaderFile + */ + SECStatus + WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, + PRFileDesc *outFile) + { + SECStatus rv; + char header[40]; + char trailer[40]; + char *outString = NULL; + + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + PR_fprintf(outFile, "%s\n", header); + PrintAsHex(outFile, buf, len); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + } + + /* + * Initialize for encryption or decryption - common code. + */ + PK11Context * + CryptInit(PK11SymKey *key, + unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type, CK_ATTRIBUTE_TYPE operation) + { + SECItem ivItem = { siBuffer, iv, ivLen }; + PK11Context *ctx = NULL; + + SECItem *secParam = PK11_ParamFromIV(CKM_AES_CBC, &ivItem); + if (secParam == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : secParam NULL\n"); + return NULL; + } + ctx = PK11_CreateContextBySymKey(CKM_AES_CBC, operation, key, secParam); + if (ctx == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : can't create a context\n"); + goto cleanup; + + } + cleanup: + if (secParam) { + SECITEM_FreeItem(secParam, PR_TRUE); + } + return ctx; + } + + /* + * Common encryption and decryption code. + */ + SECStatus + Crypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxOut, + unsigned char *in, unsigned int inLen) + { + SECStatus rv; + + rv = PK11_CipherOp(ctx, out, outLen, maxOut, in, inLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Crypt Failed : PK11_CipherOp returned %d\n", rv); + goto cleanup; + } + + cleanup: + if (rv != SECSuccess) { + return rv; + } + return SECSuccess; + } + + /* + * Decrypt + */ + SECStatus + Decrypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * Encrypt + */ + SECStatus + Encrypt(PK11Context* ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * EncryptInit + */ + PK11Context * + EncryptInit(PK11SymKey *ek, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(ek, iv, ivLen, type, CKA_ENCRYPT); + } + + /* + * DecryptInit + */ + PK11Context * + DecryptInit(PK11SymKey *dk, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(dk, iv, ivLen, type, CKA_DECRYPT); + } + + /* + * Read cryptographic parameters from the header file. + */ + SECStatus + ReadFromHeaderFile(const char *fileName, HeaderType type, + SECItem *item, PRBool isHexData) + { + SECStatus rv; + PRFileDesc* file; + SECItem filedata; + SECItem outbuf; + unsigned char *nonbody; + unsigned char *body; + char header[40]; + char trailer[40]; + + outbuf.type = siBuffer; + file = PR_Open(fileName, PR_RDONLY, 0); + if (!file) { + PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); + return SECFailure; + } + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + rv = FileToItem(&filedata, file); + nonbody = (char *)filedata.data; + if (!nonbody) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* Check for headers and trailers and remove them. */ + if ((body = strstr(nonbody, header)) != NULL) { + char *trail = NULL; + nonbody = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(nonbody, '\r'); /* Maybe this is a MAC file. */ + if (body) + trail = strstr(++body, trailer); + if (trail != NULL) { + *trail = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + return SECFailure; + } + } else { + body = nonbody; + } + + cleanup: + PR_Close(file); + HexToBuf(body, item, isHexData); + return SECSuccess; + } + + /* + * EncryptAndMac + */ + SECStatus + EncryptAndMac(PRFileDesc *inFile, + PRFileDesc *headerFile, + PRFileDesc *encFile, + PK11SymKey *ek, + PK11SymKey *mk, + unsigned char *iv, unsigned int ivLen, + PRBool ascii) + { + SECStatus rv; + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen; + unsigned char mac[DIGESTSIZE]; + unsigned int macLen; + unsigned int nwritten; + unsigned char encbuf[BLOCKSIZE]; + unsigned int encbufLen; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + unsigned int pad[1]; + SECItem padItem; + unsigned int paddingLength; + + static unsigned int firstTime = 1; + int j; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + rv = MacInit(ctxmac); + if (rv != SECSuccess) { + goto cleanup; + } + + ctxenc = EncryptInit(ek, iv, ivLen, CKM_AES_CBC); + + /* Read a buffer of plaintext from input file. */ + while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { + + /* Encrypt using it using CBC, using previously created IV. */ + if (ptextLen != BLOCKSIZE) { + paddingLength = BLOCKSIZE - ptextLen; + for ( j=0; j < paddingLength; j++) { + ptext[ptextLen+j] = (unsigned char)paddingLength; + } + ptextLen = BLOCKSIZE; + } + rv = Encrypt(ctxenc, + encbuf, &encbufLen, sizeof(encbuf), + ptext, ptextLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Encrypt Failure\n"); + goto cleanup; + } + + /* Save the last block of ciphertext as the next IV. */ + iv = encbuf; + ivLen = encbufLen; + + /* Write the cipher text to intermediate file. */ + nwritten = PR_Write(encFile, encbuf, encbufLen); + /* PR_Assert(nwritten == encbufLen); */ + + rv = MacUpdate(ctxmac, ptext, ptextLen); + } + + rv = MacFinal(ctxmac, mac, &macLen, DIGESTSIZE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "MacFinal Failure\n"); + goto cleanup; + } + if (macLen == 0) { + PR_fprintf(PR_STDERR, "Bad MAC length\n"); + rv = SECFailure; + goto cleanup; + } + WriteToHeaderFile(mac, macLen, MAC, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write MAC Failure\n"); + goto cleanup; + } + + pad[0] = paddingLength; + padItem.type = siBuffer; + padItem.data = (unsigned char *)pad; + padItem.len = sizeof(pad[0]); + + WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write PAD Failure\n"); + goto cleanup; + } + + rv = SECSuccess; + + cleanup: + if (ctxmac != NULL) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc != NULL) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + + return rv; + } + + /* + * Find the Key for the given mechanism. + */ + PK11SymKey* + FindKey(PK11SlotInfo *slot, + CK_MECHANISM_TYPE mechanism, + SECItem *keyBuf, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + if (slot) { + PK11_FreeSlot(slot); + } + return NULL; + } + } + + key = PK11_FindFixedKey(slot, mechanism, keyBuf, 0); + if (!key) { + PR_fprintf(PR_STDERR, + "PK11_FindFixedKey failed (err %d)\n", + PR_GetError()); + PK11_FreeSlot(slot); + return NULL; + } + return key; + } + + /* + * Decrypt and Verify MAC. + */ + SECStatus + DecryptAndVerifyMac(const char* outFileName, + char *encryptedFileName, + SECItem *cItem, SECItem *macItem, + PK11SymKey* ek, PK11SymKey* mk, SECItem *ivItem, SECItem *padItem) + { + SECStatus rv; + PRFileDesc* inFile; + PRFileDesc* outFile; + + unsigned char decbuf[64]; + unsigned int decbufLen; + + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen = 0; + unsigned char ctext[64]; + unsigned int ctextLen; + unsigned char newmac[DIGESTSIZE]; + unsigned int newmacLen = 0; + unsigned int newptextLen = 0; + unsigned int count = 0; + unsigned int temp = 0; + unsigned int blockNumber = 0; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + + unsigned char iv[BLOCKSIZE]; + unsigned int ivLen = ivItem->len; + unsigned int fileLength; + unsigned int paddingLength; + int j; + + memcpy(iv, ivItem->data, ivItem->len); + paddingLength = (unsigned int)padItem->data[0]; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(encryptedFileName, PR_RDONLY , 0); + if (!inFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* Open the output file. */ + outFile = PR_Open(outFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR , 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + outFileName); + return SECFailure; + } + + rv = MacInit(ctxmac); + if (rv != SECSuccess) goto cleanup; + + ctxenc = DecryptInit(ek, iv, ivLen, CKM_AES_CBC); + fileLength = FileSize(encryptedFileName); + + while ((ctextLen = PR_Read(inFile, ctext, sizeof(ctext))) > 0) { + + count += ctextLen; + + /* Decrypt cipher text buffer using CBC and IV. */ + + rv = Decrypt(ctxenc, decbuf, &decbufLen, sizeof(decbuf), + ctext, ctextLen); + + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Decrypt Failure\n"); + goto cleanup; + } + + if (decbufLen == 0) break; + + rv = MacUpdate(ctxmac, decbuf, decbufLen); + if (rv != SECSuccess) { goto cleanup; } + if (count == fileLength) { + decbufLen = decbufLen-paddingLength; + } + + /* Write the plain text to out file. */ + temp = PR_Write(outFile, decbuf, decbufLen); + if (temp != decbufLen) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + break; + } + + /* Save last block of ciphertext. */ + memcpy(iv, decbuf, decbufLen); + ivLen = decbufLen; + blockNumber++; + } + + if (rv != SECSuccess) { goto cleanup; } + + rv = MacFinal(ctxmac, newmac, &newmacLen, sizeof(newmac)); + if (rv != SECSuccess) { goto cleanup; } + + if (PORT_Memcmp(macItem->data, newmac, newmacLen) == 0) { + rv = SECSuccess; + } else { + PR_fprintf(PR_STDERR, "Check MAC : Failure\n"); + PR_fprintf(PR_STDERR, "Extracted : "); + PrintAsHex(PR_STDERR, macItem->data, macItem->len); + PR_fprintf(PR_STDERR, "Computed : "); + PrintAsHex(PR_STDERR, newmac, newmacLen); + rv = SECFailure; + } + cleanup: + if (ctxmac) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + if (outFile) { + PR_Close(outFile); + } + + return rv; + } + + /* + * Gets IV and CKAIDS from Header File. + */ + SECStatus + GetIVandCKAIDSFromHeader(const char *cipherFileName, + SECItem *ivItem, SECItem *encKeyItem, SECItem *macKeyItem) + { + SECStatus rv; + + /* Open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it. + */ + rv = ReadFromHeaderFile(cipherFileName, IV, ivItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not retrieve IV from cipher file\n"); + goto cleanup; + } + + rv = ReadFromHeaderFile(cipherFileName, SYMKEY, encKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve AES CKA_ID from cipher file\n"); + goto cleanup; + } + rv = ReadFromHeaderFile(cipherFileName, MACKEY, macKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC CKA_ID from cipher file\n"); + goto cleanup; + } + cleanup: + return rv; + } + + /* + * DecryptFile + */ + SECStatus + DecryptFile(PK11SlotInfo *slot, + const char *dbdir, + const char *outFileName, + const char *headerFileName, + char *encryptedFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open read only and we have authenticated to it: + * Open input file, read in header, get IV and CKA_IDs of two keys from it. + * Find those keys in the DB token. + * Open output file. + * Loop until EOF(input): + * Read a buffer of ciphertext from input file. + * Save last block of ciphertext. + * Decrypt ciphertext buffer using CBC and IV. + * Compute and check MAC, then remove MAC from plaintext. + * Replace IV with saved last block of ciphertext. + * Write the plain text to output file. + * Close files. + * Report success. + */ + + SECStatus rv; + SECItem ivItem; + SECItem encKeyItem; + SECItem macKeyItem; + SECItem cipherItem; + SECItem macItem; + SECItem padItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + + + /* Open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it. + */ + rv = GetIVandCKAIDSFromHeader(headerFileName, + &ivItem, &encKeyItem, &macKeyItem); + if (rv != SECSuccess) { + goto cleanup; + } + + /* Find those keys in the DB token. */ + encKey = FindKey(slot, CKM_AES_CBC, &encKeyItem, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "Can't find the encryption key\n"); + rv = SECFailure; + goto cleanup; + } + /* CKM_MD5_HMAC or CKM_EXTRACT_KEY_FROM_KEY */ + macKey = FindKey(slot, CKM_MD5_HMAC, &macKeyItem, pwdata); + if (macKey == NULL) { + rv = SECFailure; + goto cleanup; + } + + /* Read in the Mac into item from the intermediate file. */ + rv = ReadFromHeaderFile(headerFileName, MAC, &macItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC from cipher file\n"); + goto cleanup; + } + if (macItem.data == NULL) { + PR_fprintf(PR_STDERR, "MAC has NULL data\n"); + rv = SECFailure; + goto cleanup; + } + if (macItem.len == 0) { + PR_fprintf(PR_STDERR, "MAC has data has 0 length\n"); + /*rv = SECFailure; + goto cleanup;*/ + } + + rv = ReadFromHeaderFile(headerFileName, PAD, &padItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve PAD detail from header file\n"); + goto cleanup; + } + + if (rv == SECSuccess) { + /* Decrypt and Remove Mac */ + rv = DecryptAndVerifyMac(outFileName, encryptedFileName, + &cipherItem, &macItem, encKey, macKey, &ivItem, &padItem); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed while decrypting and removing MAC\n"); + } + } + + cleanup: + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * EncryptFile + */ + SECStatus + EncryptFile(PK11SlotInfo *slot, + const char *dbdir, + const char *inFileName, + const char *headerFileName, + const char *encryptedFileName, + const char *noiseFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open for read/write and we have authenticated to it. + * generate a symmetric AES key as a token object. + * generate a second key to use for MACing, also a token object. + * get their CKA_IDs + * generate a random value to use as IV for AES CBC + * open an input file and an output file, + * write a header to the output that identifies the two keys by + * their CKA_IDs, May include original file name and length. + * loop until EOF(input) + * read a buffer of plaintext from input file, + * MAC it, append the MAC to the plaintext + * encrypt it using CBC, using previously created IV, + * store the last block of ciphertext as the new IV, + * write the cipher text to intermediate file + * close files + * report success + */ + SECStatus rv; + PRFileDesc *inFile; + PRFileDesc *headerFile; + PRFileDesc *encFile; + + unsigned char *encKeyId = (unsigned char *) "Encrypt Key"; + unsigned char *macKeyId = (unsigned char *) "MAC Key"; + SECItem encKeyID = { siAsciiString, encKeyId, PL_strlen(encKeyId) }; + SECItem macKeyID = { siAsciiString, macKeyId, PL_strlen(macKeyId) }; + + SECItem encCKAID; + SECItem macCKAID; + unsigned char iv[BLOCKSIZE]; + SECItem ivItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + SECItem temp; + unsigned char c; + + /* Generate a symmetric AES key as a token object. */ + encKey = GenerateSYMKey(slot, CKM_AES_KEY_GEN, 128/8, &encKeyID, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for AES returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* Generate a second key to use for MACing, also a token object. */ + macKey = GenerateSYMKey(slot, CKM_GENERIC_SECRET_KEY_GEN, 160/8, + &macKeyID, pwdata); + if (macKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for MACing returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* Get the encrypt key CKA_ID */ + rv = GatherCKA_ID(encKey, &encCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error while wrapping encrypt key\n"); + goto cleanup; + } + + /* Get the MAC key CKA_ID */ + rv = GatherCKA_ID(macKey, &macCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Can't get the MAC key CKA_ID.\n"); + goto cleanup; + } + + if (noiseFileName) { + rv = SeedFromNoiseFile(noiseFileName); + if (rv != SECSuccess) { + PORT_SetError(PR_END_OF_FILE_ERROR); + return SECFailure; + } + rv = PK11_GenerateRandom(iv, BLOCKSIZE); + if (rv != SECSuccess) { + goto cleanup; + } + + } else { + /* Generate a random value to use as IV for AES CBC. */ + GenerateRandom(iv, BLOCKSIZE); + } + + headerFile = PR_Open(headerFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + headerFileName); + return SECFailure; + } + encFile = PR_Open(encryptedFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!encFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* Write to a header file the IV and the CKA_IDs + * identifying the two keys. + */ + ivItem.type = siBuffer; + ivItem.data = iv; + ivItem.len = BLOCKSIZE; + + rv = WriteToHeaderFile(iv, BLOCKSIZE, IV, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing IV to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + rv = WriteToHeaderFile(encCKAID.data, encCKAID.len, SYMKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing AES CKA_ID to cipher file - %s\n", + encryptedFileName); + goto cleanup; + } + rv = WriteToHeaderFile(macCKAID.data, macCKAID.len, MACKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing MAC CKA_ID to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + + /* Macing and Encryption */ + if (rv == SECSuccess) { + rv = EncryptAndMac(inFile, headerFile, encFile, + encKey, macKey, ivItem.data, ivItem.len, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : Macing and Encryption\n"); + goto cleanup; + } + } + + cleanup: + if (inFile) { + PR_Close(inFile); + } + if (headerFile) { + PR_Close(headerFile); + } + if (encFile) { + PR_Close(encFile); + } + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * This example illustrates basic encryption/decryption and MACing. + * Generates the encryption/mac keys and uses token for storing. + * Encrypts the input file and appends MAC before storing in intermediate + * header file. + * Writes the CKA_IDs of the encryption keys into intermediate header file. + * Reads the intermediate headerfile for CKA_IDs and encrypted + * contents and decrypts into output file. + */ + int + main(int argc, char **argv) + { + SECStatus rv; + SECStatus rvShutdown; + PK11SlotInfo *slot = NULL; + PLOptState *optstate; + PLOptStatus status; + char headerFileName[50]; + char encryptedFileName[50]; + PRFileDesc *inFile; + PRFileDesc *outFile; + PRBool ascii = PR_FALSE; + CommandType cmd = UNKNOWN; + const char *command = NULL; + const char *dbdir = NULL; + const char *inFileName = NULL; + const char *outFileName = NULL; + const char *noiseFileName = NULL; + secuPWData pwdata = { PW_NONE, 0 }; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "c:d:i:o:f:p:z:a"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'a': + ascii = PR_TRUE; + break; + case 'c': + command = strdup(optstate->value); + break; + case 'd': + dbdir = strdup(optstate->value); + break; + case 'f': + pwdata.source = PW_FROMFILE; + pwdata.data = strdup(optstate->value); + break; + case 'p': + pwdata.source = PW_PLAINTEXT; + pwdata.data = strdup(optstate->value); + break; + case 'i': + inFileName = strdup(optstate->value); + break; + case 'o': + outFileName = strdup(optstate->value); + break; + case 'z': + noiseFileName = strdup(optstate->value); + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (!command || !dbdir || !inFileName || !outFileName) + Usage(progName); + if (PL_strlen(command)==0) + Usage(progName); + + cmd = command[0] == 'a' ? ENCRYPT : command[0] == 'b' ? DECRYPT : UNKNOWN; + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + PR_Close(inFile); + + /* For intermediate header file, choose filename as inputfile name + with extension ".header" */ + strcpy(headerFileName, inFileName); + strcat(headerFileName, ".header"); + + /* For intermediate encrypted file, choose filename as inputfile name + with extension ".enc" */ + strcpy(encryptedFileName, inFileName); + strcat(encryptedFileName, ".enc"); + + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + + switch (cmd) { + case ENCRYPT: + /* If the intermediate header file already exists, delete it. */ + if (PR_Access(headerFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(headerFileName); + } + /* If the intermediate encrypted already exists, delete it. */ + if (PR_Access(encryptedFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(encryptedFileName); + } + + /* Open DB for read/write and authenticate to it. */ + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); + goto cleanup; + } + + PK11_SetPasswordFunc(GetModulePassword); + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + rv = EncryptFile(slot, dbdir, + inFileName, headerFileName, encryptedFileName, + noiseFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "EncryptFile : Failed\n"); + return SECFailure; + } + break; + case DECRYPT: + /* Open DB read only, authenticate to it. */ + PK11_SetPasswordFunc(GetModulePassword); + + rv = NSS_Init(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_Init Failed\n"); + return SECFailure; + } + + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + + rv = DecryptFile(slot, dbdir, + outFileName, headerFileName, + encryptedFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "DecryptFile : Failed\n"); + return SECFailure; + } + break; + } + + cleanup: + rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); + rv = SECFailure; + } + + PR_Cleanup(); + + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/index.rst new file mode 100644 index 0000000000..88f1e7bdab --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/index.rst @@ -0,0 +1,31 @@ +.. _mozilla_projects_nss_nss_sample_code: + +NSS Sample Code +=============== + +.. container:: + + The collection of sample code here demonstrates how NSS can be used for cryptographic operations, + certificate handling, SSL, etc. It also demonstrates some best practices in the application of + cryptography. + + Old samples in the process of being replaced. + + #. :ref:`mozilla_projects_nss_sample_code_sample1` + #. :ref:`mozilla_projects_nss_sample_code_sample2` + #. :ref:`mozilla_projects_nss_sample_code_sample3` + #. :ref:`mozilla_projects_nss_sample_code_sample4` + #. :ref:`mozilla_projects_nss_sample_code_sample5` + #. :ref:`mozilla_projects_nss_sample_code_sample6` + + | + | These are very old examples in need of replacement. See + https://bugzilla.mozilla.org/show_bug.cgi?id=490238 + + You are welcome to download the new samples via: + + .. code:: sh + + hg clone https://hg.mozilla.org/projects/nss; cd nss; hg update SAMPLES_BRANCH + + The new samples: :ref:`mozilla_projects_nss_new_nss_samples`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample1/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample1/index.rst new file mode 100644 index 0000000000..10926903af --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample1/index.rst @@ -0,0 +1,713 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample1: + +NSS Sample Code Sample1 +======================= + +.. _nss_sample_code_1_key_generation_and_transport_between_servers.: + +`NSS Sample Code 1: Key Generation and Transport Between Servers. <#nss_sample_code_1_key_generation_and_transport_between_servers.>`__ +--------------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + This is an example program that demonstrates how to do key generation and transport between + cooperating servers. This program shows the following: + + - RSA key pair generation + - Naming RSA key pairs + - Looking up a previously generated key pair by name + - Creating AES and MAC keys (or encryption and MAC keys in general) + - Wrapping symmetric keys using your own RSA key pair so that they can be stored on disk or in a + database. + + - As an alternative to TOKEN symmetric keys + + - As a way to store large numbers of symmetric keys + + - Wrapping symmetric keys using an RSA key from another server + - Unwrapping keys using your own RSA key pair + + | The main part of the program shows a typical sequence of events for two servers that are trying + to extablish a shared key pair. + | We will add message protection (encryption and MACing) examples to this program in the future. + +.. _sample_code: + +`Sample Code <#sample_code>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <iostream.h> + #include "pk11pub.h" + #include "keyhi.h" + #include "nss.h" + + // Key management for keys share among multiple hosts + // + // This example shows how to use NSS functions to create and + // distribute keys that need to be shared among multiple servers + // or hosts. + // + // The management scheme assumes that one host is PRIMARY. It + // generates the secret keys that will be used by all participating + // hosts. The other hosts (SECONDARY) request keys from the + // primary host. As an alternative, new keys may be sent to the + // current set of SECONDARY hosts when they are generated by the + // PRIMARY. In this case, the PRIMARY maintains a list of the + // secondary hosts. + // + // The sequence of events is: + // 1. The primary host generates a new symmetric key. This key + // may be used for an encryption mechanism (DES or AES) or for + // integrity (MD5_HMAC or SHA1_HMAC). This key needs to be + // permanent, since it may be used during several runs of the + // server. (Currently NSS doesn't store persistant keys. Steps + // 1a through 1x show how to do this). + // 1a. The primary host generates an RSA keypair that will be used + // store keys locally. + // 1b. The primary host wraps the newly generated key using the + // RSA key and stores the wrapped key data in a local file. + // 1c. The primary host unwraps the key using the RSA key each time + // access to the key is required, such as at server startup. + // 2. The secondary host generates an RSA keypair that will be used + // to transport keys between the primary host and itself. This + // key needs to exist long enough to be used to process the + // response to a key transport request that is made to the primary + // server. The example here shows how to create a permanent (token) + // RSA key for this purpose. (This key will also be used for + // storage of the keys, since NSS does not support permanent symmetric + // keys at the current time.) + // 3. The secondary host sends its RSA public key to the primary host as + // part of a request for a particular key, or to be added to a list + // of secondary hosts. + // 4. The administrator of the primary host verifies that the RSA key + // that was received belongs to a valid secondary host. The adminstrator + // may do this by checking that the key was received in a signed email + // message, or by checking a digest value with the adminstrator of the + // secondary host. [Need support for digest check values] + // 5. The primary host exports (wraps) the symmetric key using the + // secondary host's RSA key. The wrapped value is sent back to + // the secondary host. + // 6. The administrator of the secondary host verifies that the wrapped + // key data came from the primary host. The same methods outlined + // in step 4 may be used here. + // 7. The secondary host unwraps the key using its own RSA private key. + // NOTE: currently NSS does not support permanent symmetric keys. + // The secondary host may store the wrapped value that was received + // from the primary in a file, and unwrap it each time the key is required + // (such as at server startup). + + // NSS actually has some support for permanent symmetric keys. However this + // example will need to be modified somewhat in order to demonstrate it. + + // Utility function to print hex data + static void + printBuffer(unsigned char *digest, unsigned int len) + { + int i; + + cout << "length: " << len << endl; + for(i = 0;i < len;i++) printf("%02x ", digest[i]); + cout << endl; + } + + // XXX Data protection + // - takes an input buffer, applies the encryption + // and MAC, and generates a buffer with the result. + // - the application sends or uses the result (possibly + // after base64 encoding it. + + // + // Server - an instance of a server that is part of a + // cluster of servers that are sharing a common set + // of encryption and MACing keys. + // + class Server + { + public: + // Initializes the server instance. In particular, this + // creates the key pair that is used for wrapping keys + int Init(); + + // Generates keys for encryption (AES) and MACing. The + // wrapped keys are stored in data files. + int GenerateKeys(); + + // Gets the server's public key (wrapping key) to + // send to another server. This becomes the input to + // the ExportKeys method on the remote server. + int ExportPublicKey(SECItem **pubKeyData); + + // Export the encryption and key using the key + // provided. The key should come from another server + // in the cluster. (The admin should verify this.) + // + // In this example, the server must be started to perform + // this function (see Start()) + int ExportKeys(SECItem *pubKey, SECItem **wrappedEncKey, + SECItem **wrappedMacKey); + + // Import the keys received from another server in the + // cluster. The admin should make sure the keys actually + // came from the correct source. + int ImportKeys(SECItem *wrappedEncKey, SECItem *wrappedMacKey); + + // Start the server, loading the encryption and MACing keys + // from files + int Start(); + + // Shut down the server. (For completeness) + int Shutdown(); + + // Compare keys in two server instances. Use this in the + // example to make sure the keys are transferred correctly. + // This will not work in real life! + // + // The servers must be started + int CompareKeys(Server *peer); + + // Create a server - the name distiguish the keys in the + // shared database in this example + Server(const char *serverName); + ~Server(); + + private: + int getPrivateKey(SECKEYPrivateKey **prvKey); + int getPublicKey(SECKEYPublicKey **pubKey); + int wrapKey(PK11SymKey *key, SECKEYPublicKey *pubKey, SECItem **data); + + // export raw key (unwrapped) DO NOT USE + int rawExportKey(PK11SymKey *key, SECItem **data); + + char *mServerName; + + // These items represent data that might be stored + // in files or in a configuration file + SECItem *mWrappedEncKey; + SECItem *mWrappedMacKey; + + // These are the runtime keys as loaded from the files + PK11SymKey *mEncKey; + PK11SymKey *mMacKey; + }; + + Server::Server(const char *serverName) + : mServerName(0), mWrappedEncKey(0), mWrappedMacKey(0), + mEncKey(0), mMacKey(0) + { + // Copy the server name + mServerName = PL_strdup(serverName); + } + + Server::~Server() + { + if (mServerName) PL_strfree(mServerName); + if (mWrappedEncKey) SECITEM_FreeItem(mWrappedEncKey, PR_TRUE); + if (mWrappedMacKey) SECITEM_FreeItem(mWrappedMacKey, PR_TRUE); + if (mEncKey) PK11_FreeSymKey(mEncKey); + if (mMacKey) PK11_FreeSymKey(mMacKey); + } + + int + Server::Init() + { + int rv = 0; + SECKEYPrivateKey *prvKey = 0; + SECKEYPublicKey *pubKey = 0; + PK11SlotInfo *slot = 0; + PK11RSAGenParams rsaParams; + SECStatus s; + + // See if there is already a private key with this name. + // If there is one, no further action is required. + rv = getPrivateKey(&prvKey); + if (rv == 0 && prvKey) goto done; + + rv = 0; + + // These could be parameters to the Init function + rsaParams.keySizeInBits = 1024; + rsaParams.pe = 65537; + + slot = PK11_GetInternalKeySlot(); + if (!slot) { rv = 1; goto done; } + + prvKey = PK11_GenerateKeyPair(slot, CKM_RSA_PKCS_KEY_PAIR_GEN, &rsaParams, + &pubKey, PR_TRUE, PR_TRUE, 0); + if (!prvKey) { rv = 1; goto done; } + + // Set the nickname on the private key so that it + // can be found later. + s = PK11_SetPrivateKeyNickname(prvKey, mServerName); + if (s != SECSuccess) { rv = 1; goto done; } + + done: + if (slot) PK11_FreeSlot(slot); + if (pubKey) SECKEY_DestroyPublicKey(pubKey); + if (prvKey) SECKEY_DestroyPrivateKey(prvKey); + + return rv; + } + + int + Server::GenerateKeys() + { + int rv = 0; + SECKEYPublicKey *pubKey = 0; + PK11SlotInfo *slot = 0; + + // Choose a slot to use + slot = PK11_GetInternalKeySlot(); + if (!slot) { rv = 1; goto done; } + + // Get our own public key to use for wrapping + rv = getPublicKey(&pubKey); + if (rv) goto done; + + // Do the Encryption (AES) key + if (!mWrappedEncKey) + { + PK11SymKey *key = 0; + + // The key size is 128 bits (16 bytes) + key = PK11_KeyGen(slot, CKM_AES_KEY_GEN, 0, 128/8, 0); + if (!key) { rv = 1; goto aes_done; } + + rv = wrapKey(key, pubKey, &mWrappedEncKey); + + aes_done: + if (key) PK11_FreeSymKey(key); + + if (rv) goto done; + } + + // Do the Mac key + if (!mWrappedMacKey) + { + PK11SymKey *key = 0; + + // The key size is 160 bits (20 bytes) + key = PK11_KeyGen(slot, CKM_GENERIC_SECRET_KEY_GEN, 0, 160/8, 0); + if (!key) { rv = 1; goto mac_done; } + + rv = wrapKey(key, pubKey, &mWrappedMacKey); + + mac_done: + if (key) PK11_FreeSymKey(key); + } + + done: + if (slot) PK11_FreeSlot(slot); + + return rv; + } + + int + Server::ExportPublicKey(SECItem **pubKeyData) + { + int rv = 0; + SECKEYPublicKey *pubKey = 0; + + rv = getPublicKey(&pubKey); + if (rv) goto done; + + *pubKeyData = SECKEY_EncodeDERSubjectPublicKeyInfo(pubKey); + if (!*pubKeyData) { rv = 1; goto done; } + + done: + if (pubKey) SECKEY_DestroyPublicKey(pubKey); + + return rv; + } + + int + Server::ExportKeys(SECItem *pubKeyData, SECItem **wrappedEncKey, + SECItem **wrappedMacKey) + { + int rv; + CERTSubjectPublicKeyInfo *keyInfo = 0; + SECKEYPublicKey *pubKey = 0; + SECItem *data = 0; + + // Make sure the keys are available (server running) + if (!mEncKey || !mMacKey) { rv = 1; goto done; } + + // Import the public key of the other server + keyInfo = SECKEY_DecodeDERSubjectPublicKeyInfo(pubKeyData); + if (!keyInfo) { rv = 1; goto done; } + + pubKey = SECKEY_ExtractPublicKey(keyInfo); + if (!pubKey) { rv = 1; goto done; } + + // Export the encryption key + rv = wrapKey(mEncKey, pubKey, &data); + if (rv) goto done; + + // Export the MAC key + rv = wrapKey(mMacKey, pubKey, wrappedMacKey); + if (rv) goto done; + + // Commit the rest of the operation + *wrappedEncKey = data; + data = 0; + + done: + if (data) SECITEM_FreeItem(data, PR_TRUE); + if (pubKey) SECKEY_DestroyPublicKey(pubKey); + if (keyInfo) SECKEY_DestroySubjectPublicKeyInfo(keyInfo); + + return rv; + } + + int + Server::ImportKeys(SECItem *wrappedEncKey, SECItem *wrappedMacKey) + { + int rv = 0; + + if (mWrappedEncKey || mWrappedMacKey) { rv = 1; goto done; } + + mWrappedEncKey = SECITEM_DupItem(wrappedEncKey); + if (!mWrappedEncKey) { rv = 1; goto done; } + + mWrappedMacKey = SECITEM_DupItem(wrappedMacKey); + if (!mWrappedMacKey) { rv = 1; goto done; } + + done: + return rv; + } + + int + Server::Start() + { + int rv; + SECKEYPrivateKey *prvKey = 0; + + rv = getPrivateKey(&prvKey); + if (rv) goto done; + + if (!mEncKey) + { + // Unwrap the encryption key from the "file" + // This function uses a mechanism rather than a key type + // Does this need to be "WithFlags"?? + mEncKey = PK11_PubUnwrapSymKey(prvKey, mWrappedEncKey, + CKM_AES_CBC_PAD, CKA_ENCRYPT, 0); + if (!mEncKey) { rv = 1; goto done; } + } + + if (!mMacKey) + { + // Unwrap the MAC key from the "file" + // This function uses a mechanism rather than a key type + // Does this need to be "WithFlags"?? + mMacKey = PK11_PubUnwrapSymKey(prvKey, mWrappedMacKey, + CKM_MD5_HMAC, CKA_SIGN, 0); + if (!mMacKey) { rv = 1; goto done; } + } + + done: + if (prvKey) SECKEY_DestroyPrivateKey(prvKey); + + return rv; + } + + int + Server::Shutdown() + { + if (mEncKey) PK11_FreeSymKey(mEncKey); + if (mMacKey) PK11_FreeSymKey(mMacKey); + + mEncKey = 0; + mMacKey = 0; + + return 0; + } + + int + Server::CompareKeys(Server *peer) + { + int rv; + SECItem *macKey1 = 0; + SECItem *macKey2 = 0; + SECItem *encKey1 = 0; + SECItem *encKey2 = 0; + + // Export each of the keys in raw form + rv = rawExportKey(mMacKey, &macKey1); + if (rv) goto done; + + rv = rawExportKey(peer->mMacKey, &macKey2); + if (rv) goto done; + + rv = rawExportKey(mEncKey, &encKey1); + if (rv) goto done; + + rv = rawExportKey(peer->mEncKey, &encKey2); + if (rv) goto done; + + if (!SECITEM_ItemsAreEqual(macKey1, macKey2)) { rv = 1; goto done; } + if (!SECITEM_ItemsAreEqual(encKey1, encKey2)) { rv = 1; goto done; } + + done: + if (macKey1) SECITEM_ZfreeItem(macKey1, PR_TRUE); + if (macKey2) SECITEM_ZfreeItem(macKey2, PR_TRUE); + if (encKey1) SECITEM_ZfreeItem(encKey1, PR_TRUE); + if (encKey2) SECITEM_ZfreeItem(encKey2, PR_TRUE); + + return rv; + } + + // Private helper, retrieves the private key for the server + // from the database. Free the key using SECKEY_DestroyPrivateKey + int + Server::getPrivateKey(SECKEYPrivateKey **prvKey) + { + int rv = 0; + PK11SlotInfo *slot = 0; + SECKEYPrivateKeyList *list = 0; + SECKEYPrivateKeyListNode *n; + char *nickname; + + slot = PK11_GetInternalKeySlot(); + if (!slot) goto done; + + // ListPrivKeysInSlot looks like it should check the + // nickname and only return keys that match. However, + // that doesn't seem to work at the moment. + // BUG: XXXXX + list = PK11_ListPrivKeysInSlot(slot, mServerName, 0); + cout << "getPrivateKey: list = " << list << endl; + if (!list) { rv = 1; goto done; } + + for(n = PRIVKEY_LIST_HEAD(list); + !PRIVKEY_LIST_END(n, list); + n = PRIVKEY_LIST_NEXT(n)) + { + nickname = PK11_GetPrivateKeyNickname(n->key); + if (PL_strcmp(nickname, mServerName) == 0) break; + } + if (PRIVKEY_LIST_END(n, list)) { rv = 1; goto done; } + + *prvKey = SECKEY_CopyPrivateKey(n->key); + + done: + if (list) SECKEY_DestroyPrivateKeyList(list); + + return rv; + } + + int + Server::getPublicKey(SECKEYPublicKey **pubKey) + { + int rv; + SECKEYPrivateKey *prvKey = 0; + + rv = getPrivateKey(&prvKey); + if (rv) goto done; + + *pubKey = SECKEY_ConvertToPublicKey(prvKey); + if (!*pubKey) { rv = 1; goto done; } + + done: + if (prvKey) SECKEY_DestroyPrivateKey(prvKey); + + return rv; + } + + int + Server::wrapKey(PK11SymKey *key, SECKEYPublicKey *pubKey, SECItem **ret) + { + int rv = 0; + SECItem *data; + SECStatus s; + + data = (SECItem *)PORT_ZAlloc(sizeof(SECItem)); + if (!data) { rv = 1; goto done; } + + // Allocate space for output of wrap + data->len = SECKEY_PublicKeyStrength(pubKey); + data->data = new unsigned char[data->len]; + if (!data->data) { rv = 1; goto done; } + + s = PK11_PubWrapSymKey(CKM_RSA_PKCS, pubKey, key, data); + if (s != SECSuccess) { rv = 1; goto done; } + + *ret = data; + data = 0; + + done: + if (data) SECITEM_FreeItem(data, PR_TRUE); + + return rv; + } + + // Example of how to do a raw export (no wrapping of a key) + // This should not be used. Use the RSA-based wrapping + // methods instead. + int + Server::rawExportKey(PK11SymKey *key, SECItem **res) + { + int rv = 0; + SECItem *data; + SECStatus s; + + s = PK11_ExtractKeyValue(key); + if (s != SECSuccess) { rv = 1; goto done; } + + data = PK11_GetKeyData(key); + + *res = SECITEM_DupItem(data); + if (!*res) { rv = 1; goto done; } + + done: + return rv; + } + + // Initialize the NSS library. Normally this + // would be done as part of each server's startup. + // However, this example uses the same databases + // to store keys for server in the "cluster" so + // it is done once. + int + InitNSS() + { + int rv = 0; + SECStatus s; + + s = NSS_InitReadWrite("."); + if (s != SECSuccess) rv = 1; // Error + + // For this example, we don't use database passwords + PK11_InitPin(PK11_GetInternalKeySlot(), "", ""); + + return rv; + } + + int + main(int argc, char *argv[]) + { + int rv; + Server *server1 = 0; + Server *server2 = 0; + + // Initialize NSS + rv = InitNSS(); + if (rv) { cout << "InitNSS failed" << endl; goto done; } + + // Create the first "server" + server1 = new Server("Server1"); + if (!server1 || server1->Init()) + { + cout << "Server1 could not be created" << endl; + rv = 1; + goto done; + } + + // Generate encryption and mac keys. These keys will + // be used by all the servers in the cluster. + rv = server1->GenerateKeys(); + if (rv) { cout << "GenerateKeys failed" << endl; goto done; } + + // Now that everything is ready, start server1. This loads + // the encryption and MAC keys from the "files" + rv = server1->Start(); + if (rv) { cout << "Cannot start server 1" << endl; goto done; } + + // Create a second server in the cluster. We will need + // to transfer the keys from the first server to this + // one + server2 = new Server("Server2"); + if (!server2 || server2->Init()) + { + cout << "Server2 could not be created" << endl; + rv = 1; // Error + goto done; + } + + // Transfer the keys from server1 + { + SECItem *wrappedEncKey = 0; + SECItem *wrappedMacKey = 0; + SECItem *pubKeyData = 0; + + // Get the public key for server 2 so that it can + // be sent to server 1 + rv = server2->ExportPublicKey(&pubKeyData); + if (rv) { cout << "ExportPublicKey failed" << endl; goto trans_done; } + + // Send the public key to server 1 and get back the + // wrapped key values + rv = server1->ExportKeys(pubKeyData, &wrappedEncKey, &wrappedMacKey); + if (rv) { cout << "ExportKeys failed" << endl; goto trans_done; } + + // Print - for information + cout << "Wrapped Encryption Key" << endl; + printBuffer(wrappedEncKey->data, wrappedEncKey->len); + cout << "Wrapped MAC Key" << endl; + printBuffer(wrappedMacKey->data, wrappedMacKey->len); + + // Import the keys into server 2 - this just puts the wrapped + // values into the "files" + rv = server2->ImportKeys(wrappedEncKey, wrappedMacKey); + if (rv) { cout << "ImportKeys failed" << endl; goto trans_done; } + + trans_done: + if (wrappedEncKey) SECITEM_FreeItem(wrappedEncKey, PR_TRUE); + if (wrappedMacKey) SECITEM_FreeItem(wrappedMacKey, PR_TRUE); + if (pubKeyData) SECITEM_FreeItem(pubKeyData, PR_TRUE); + } + if (rv) goto done; + + // Start server 2 - this unwraps the encryption and MAC keys + // so that they can be used + rv = server2->Start(); + if (rv) { cout << "Cannot start server 2" << endl; goto done; } + + // List keys in the token - informational + { + PK11SlotInfo *slot = 0; + SECKEYPrivateKeyList *list = 0; + SECKEYPrivateKeyListNode *n; + + slot = PK11_GetInternalKeySlot(); + if (!slot) goto list_done; + + cout << "List Private Keys" << endl; + + list = PK11_ListPrivKeysInSlot(slot, 0, 0); + if (!list) goto list_done; + + for(n = PRIVKEY_LIST_HEAD(list); + !PRIVKEY_LIST_END(n, list); + n = PRIVKEY_LIST_NEXT(n)) + { + char *name; + + name = PK11_GetPrivateKeyNickname(n->key); + cout << "Key: " << name << endl; + } + list_done: + if (slot) PK11_FreeSlot(slot); + if (list) SECKEY_DestroyPrivateKeyList(list); + + cout << "Done" << endl; + } + + // Let's see if the keys are the same + rv = server1->CompareKeys(server2); + if (rv) { cout << "Key Comparison failed" << endl; } + + server1->Shutdown(); + server2->Shutdown(); + + done: + if (server1) delete server1; + if (server2) delete server2; + + NSS_Shutdown(); + + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample2/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample2/index.rst new file mode 100644 index 0000000000..76f6c21d8f --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample2/index.rst @@ -0,0 +1,166 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample2: + +NSS Sample Code sample2 +======================= + +.. _nss_sample_code_2_symmetric_encryption: + +`NSS Sample Code 2: Symmetric Encryption <#nss_sample_code_2_symmetric_encryption>`__ +------------------------------------------------------------------------------------- + +.. container:: + + .. code:: + + /* Example code to illustrate DES enccryption/decryption using NSS. + * The example skips the details of obtaining the Key & IV to use, and + * just uses a hardcoded Key & IV. + * Note: IV is only needed if Cipher Blocking Chaining (CBC) mode of encryption + * is used + * + * The recommended approach is to store and transport WRAPPED (encrypted) + * DES Keys (IVs can be in the clear). However, it is a common (and dangerous) + * practice to use raw DES Keys. This example shows the use of a RAW key. + */ + + + #include "nss.h" + #include "pk11pub.h" + + /* example Key & IV */ + unsigned char gKey[] = {0xe8, 0xa7, 0x7c, 0xe2, 0x05, 0x63, 0x6a, 0x31}; + unsigned char gIV[] = {0xe4, 0xbb, 0x3b, 0xd3, 0xc3, 0x71, 0x2e, 0x58}; + + int main(int argc, char **argv) + { + CK_MECHANISM_TYPE cipherMech; + PK11SlotInfo* slot = NULL; + PK11SymKey* SymKey = NULL; + SECItem* SecParam = NULL; + PK11Context* EncContext = NULL; + SECItem keyItem, ivItem; + SECStatus rv, rv1, rv2; + unsigned char data[1024], buf1[1024], buf2[1024]; + int i, result_len, tmp1_outlen, tmp2_outlen; + + /* Initialize NSS + * If your application code has already initialized NSS, you can skip it + * here. + * This code uses the simplest of the Init functions, which does not + * require a NSS database to exist + */ + rv = NSS_NoDB_Init("."); + if (rv != SECSuccess) + { + fprintf(stderr, "NSS initialization failed (err %d)\n", + PR_GetError()); + goto out; + } + + /* choose mechanism: CKM_DES_CBC_PAD, CKM_DES3_ECB, CKM_DES3_CBC..... + * Note that some mechanisms (*_PAD) imply the padding is handled for you + * by NSS. If you choose something else, then data padding is the + * application's responsibility + */ + cipherMech = CKM_DES_CBC_PAD; + slot = PK11_GetBestSlot(cipherMech, NULL); + /* slot = PK11_GetInternalKeySlot(); is a simpler alternative but in + * theory, it *may not* return the optimal slot for the operation. For + * DES ops, Internal slot is typically the best slot + */ + if (slot == NULL) + { + fprintf(stderr, "Unable to find security device (err %d)\n", + PR_GetError()); + goto out; + } + + /* NSS passes blobs around as SECItems. These contain a pointer to + * data and a length. Turn the raw key into a SECItem. */ + keyItem.type = siBuffer; + keyItem.data = gKey; + keyItem.len = sizeof(gKey); + + /* Turn the raw key into a key object. We use PK11_OriginUnwrap + * to indicate the key was unwrapped - which is what should be done + * normally anyway - using raw keys isn't a good idea */ + SymKey = PK11_ImportSymKey(slot, cipherMech, PK11_OriginUnwrap, CKA_ENCRYPT, + &keyItem, NULL); + if (SymKey == NULL) + { + fprintf(stderr, "Failure to import key into NSS (err %d)\n", + PR_GetError()); + goto out; + } + + /* set up the PKCS11 encryption parameters. + * when not using CBC mode, ivItem.data and ivItem.len can be 0, or you + * can simply pass NULL for the iv parameter in PK11_ParamFromIV func + */ + ivItem.type = siBuffer; + ivItem.data = gIV; + ivItem.len = sizeof(gIV); + SecParam = PK11_ParamFromIV(cipherMech, &ivItem); + if (SecParam == NULL) + { + fprintf(stderr, "Failure to set up PKCS11 param (err %d)\n", + PR_GetError()); + goto out; + } + + /* sample data we'll encrypt and decrypt */ + strcpy(data, "Encrypt me!"); + fprintf(stderr, "Clear Data: %s\n", data); + + /* ========================= START SECTION ============================= */ + /* If using the same key and iv over and over, stuff before this */ + /* section and after this section needs to be done only ONCE */ + + /* ENCRYPT data into buf1. buf1 len must be atleast (data len + 8) */ + tmp1_outlen = tmp2_outlen = 0; + + /* Create cipher context */ + EncContext = PK11_CreateContextBySymKey(cipherMech, CKA_ENCRYPT, + SymKey, SecParam); + rv1 = PK11_CipherOp(EncContext, buf1, &tmp1_outlen, sizeof(buf1), + data, strlen(data)+1); + rv2 = PK11_DigestFinal(EncContext, buf1+tmp1_outlen, &tmp2_outlen, + sizeof(buf1)-tmp1_outlen); + PK11_DestroyContext(EncContext, PR_TRUE); + result_len = tmp1_outlen + tmp2_outlen; + if (rv1 != SECSuccess || rv2 != SECSuccess) + goto out; + + fprintf(stderr, "Encrypted Data: "); + for (i=0; i<result_len; i++) + fprintf(stderr, "%02x ", buf1[i]); + fprintf(stderr, "\n"); + + + /* DECRYPT buf1 into buf2. buf2 len must be atleast buf1 len */ + tmp1_outlen = tmp2_outlen = 0; + + /* Create cipher context */ + EncContext = PK11_CreateContextBySymKey(cipherMech, CKA_DECRYPT, + SymKey, SecParam); + rv1 = PK11_CipherOp(EncContext, buf2, &tmp1_outlen, sizeof(buf2), + buf1, result_len); + rv2 = PK11_DigestFinal(EncContext, buf2+tmp1_outlen, &tmp2_outlen, + result_len-tmp1_outlen); + PK11_DestroyContext(EncContext, PR_TRUE); + result_len = tmp1_outlen + tmp2_outlen; + if (rv1 != SECSuccess || rv2 != SECSuccess) + goto out; + + fprintf(stderr, "Decrypted Data: %s\n", buf2); + + /* =========================== END SECTION ============================= */ + + + out: + if (SymKey) + PK11_FreeSymKey(SymKey); + if (SecParam) + SECITEM_FreeItem(SecParam, PR_TRUE); + + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample3/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample3/index.rst new file mode 100644 index 0000000000..51f37f6619 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample3/index.rst @@ -0,0 +1,169 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample3: + +NSS Sample Code sample3 +======================= + +.. _sample_code_3_hashing_mac: + +`Sample Code 3: Hashing, MAC <#sample_code_3_hashing_mac>`__ +------------------------------------------------------------ + +.. container:: + + .. code:: + + /* + * Demonstration program for hashing and MACs + */ + + #include <iostream.h> + + #include "pk11pub.h" + #include "nss.h" + + static void + printDigest(unsigned char *digest, unsigned int len) + { + int i; + + cout << "length: " << len << endl; + for(i = 0;i < len;i++) printf("%02x ", digest[i]); + cout << endl; + } + + /* + * main + */ + int + main(int argc, const char *argv[]) + { + int status = 0; + PK11SlotInfo *slot = 0; + PK11SymKey *key = 0; + PK11Context *context = 0; + unsigned char data[80]; + unsigned char digest[20]; /*Is there a way to tell how large the output is?*/ + unsigned int len; + SECStatus s; + + /* Initialize NSS + * If your application code has already initialized NSS, you can skip it + * here. + * This code uses the simplest of the Init functions, which does not + * require a NSS database to exist + */ + NSS_NoDB_Init("."); + + /* Get a slot to use for the crypto operations */ + slot = PK11_GetInternalKeySlot(); + if (!slot) + { + cout << "GetInternalKeySlot failed" << endl; + status = 1; + goto done; + } + + /* + * Part 1 - Simple hashing + */ + cout << "Part 1 -- Simple hashing" << endl; + + /* Initialize data */ + memset(data, 0xbc, sizeof data); + + /* Create a context for hashing (digesting) */ + context = PK11_CreateDigestContext(SEC_OID_MD5); + if (!context) { cout << "CreateDigestContext failed" << endl; goto done; } + + s = PK11_DigestBegin(context); + if (s != SECSuccess) { cout << "DigestBegin failed" << endl; goto done; } + + s = PK11_DigestOp(context, data, sizeof data); + if (s != SECSuccess) { cout << "DigestUpdate failed" << endl; goto done; } + + s = PK11_DigestFinal(context, digest, &len, sizeof digest); + if (s != SECSuccess) { cout << "DigestFinal failed" << endl; goto done; } + + /* Print digest */ + printDigest(digest, len); + + PK11_DestroyContext(context, PR_TRUE); + context = 0; + + /* + * Part 2 - Hashing with included secret key + */ + cout << "Part 2 -- Hashing with included secret key" << endl; + + /* Initialize data */ + memset(data, 0xbc, sizeof data); + + /* Create a Key */ + key = PK11_KeyGen(slot, CKM_GENERIC_SECRET_KEY_GEN, 0, 128, 0); + if (!key) { cout << "Create key failed" << endl; goto done; } + + cout << (void *)key << endl; + + /* Create parameters for crypto context */ + /* NOTE: params must be provided, but may be empty */ + SECItem noParams; + noParams.type = siBuffer; + noParams.data = 0; + noParams.len = 0; + + /* Create context using the same slot as the key */ + // context = PK11_CreateDigestContext(SEC_OID_MD5); + context = PK11_CreateContextBySymKey(CKM_MD5, CKA_DIGEST, key, &noParams); + if (!context) { cout << "CreateDigestContext failed" << endl; goto done; } + + s = PK11_DigestBegin(context); + if (s != SECSuccess) { cout << "DigestBegin failed" << endl; goto done; } + + s = PK11_DigestKey(context, key); + if (s != SECSuccess) { cout << "DigestKey failed" << endl; goto done; } + + s = PK11_DigestOp(context, data, sizeof data); + if (s != SECSuccess) { cout << "DigestUpdate failed" << endl; goto done; } + + s = PK11_DigestFinal(context, digest, &len, sizeof digest); + if (s != SECSuccess) { cout << "DigestFinal failed" << endl; goto done; } + + /* Print digest */ + printDigest(digest, len); + + PK11_DestroyContext(context, PR_TRUE); + context = 0; + + /* + * Part 3 - MAC (with secret key) + */ + cout << "Part 3 -- MAC (with secret key)" << endl; + + /* Initialize data */ + memset(data, 0xbc, sizeof data); + + context = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, key, &noParams); + if (!context) { cout << "CreateContextBySymKey failed" << endl; goto done; } + + s = PK11_DigestBegin(context); + if (s != SECSuccess) { cout << "DigestBegin failed" << endl; goto done; } + + s = PK11_DigestOp(context, data, sizeof data); + if (s != SECSuccess) { cout << "DigestOp failed" << endl; goto done; } + + s = PK11_DigestFinal(context, digest, &len, sizeof digest); + if (s != SECSuccess) { cout << "DigestFinal failed" << endl; goto done; } + + /* Print digest */ + printDigest(digest, len); + + PK11_DestroyContext(context, PR_TRUE); + context = 0; + + done: + if (context) PK11_DestroyContext(context, PR_TRUE); /* freeit ?? */ + if (key) PK11_FreeSymKey(key); + if (slot) PK11_FreeSlot(slot); + + return status; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample4/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample4/index.rst new file mode 100644 index 0000000000..1d5cba11ce --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample4/index.rst @@ -0,0 +1,158 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample4: + +NSS Sample Code sample4 +======================= + +.. _nss_sample_code_4_pki_encryption: + +`NSS Sample Code 4: PKI Encryption <#nss_sample_code_4_pki_encryption>`__ +------------------------------------------------------------------------- + +.. container:: + + .. code:: + + /* Example code to illustrate PKI crypto ops (encrypt with public key, + * decrypt with private key) + * + * Code assumes that you have set up a NSS database with a certificate + * and a private key. The db password should be "test" and the cert + * nickname should be "TestCA" + * Here is one way of doing it: + * # create CA cert db, if -f not provided, prompts for passwd + * $ certutil -N -d . + * # create CA cert, self-signed, generates key-pair, prompts for key + * # type, cert type etc + * # answers for prompts: 5,9,n,y,-1,n,5,6,7,9,n + * $ certutil -S -s "CN=Test CA, O=BOGUS Inc, L=Mtn View, ST=CA, C=US" \ + * -n TestCA -t CTu,CTu,CTu -v 60 -x -d . -1 -2 -5 + * + * There are many ways to setup a public/private key to use - this + * example shows one of them. + * + * This example does not do any padding. It simply encrypts/decrypts a block + * of length equal to modulus length of the public/private key. + */ + + + #include "nss.h" + #include "pk11pub.h" + + + /* this callback is responsible for returning the password to the NSS + * key database. for example purposes, this function hardcodes the password. + * In a real app, this function should obtain the password using secure means + * such as prompting an operator, or retrieving it over a secure communication + * channel + */ + char *passwdcb(PK11SlotInfo *info, PRBool retry, void *arg); + + + int main(int argc, char **argv) + { + SECStatus rv; + CERTCertificate *cert = NULL; + SECKEYPublicKey *pubkey = NULL; + SECKEYPrivateKey *pvtkey = NULL; + int modulus_len, i, outlen; + char *buf1 = NULL; + char *buf2 = NULL; + + /* Initialize NSS */ + PK11_SetPasswordFunc(passwdcb); + rv = NSS_Init("."); + if (rv != SECSuccess) + { + fprintf(stderr, "NSS initialization failed (err %d)\n", + PR_GetError()); + goto cleanup; + } + + cert = PK11_FindCertFromNickname("TestCA", NULL); + if (cert == NULL) + { + fprintf(stderr, "Couldn't find cert TestCA in NSS db (err %d)\n", + PR_GetError()); + goto cleanup; + } + + pubkey = CERT_ExtractPublicKey(cert); + if (pubkey == NULL) + { + fprintf(stderr, "Couldn't extract public key from cert TestCA (err %d)\n", + PR_GetError()); + goto cleanup; + } + + modulus_len = SECKEY_PublicKeyStrength(pubkey); + fprintf(stderr, "Public Key Modulus %d bytes\n", modulus_len); + buf1 = (char *)malloc(modulus_len); + buf2 = (char *)malloc(modulus_len); + + /* initialize buf1 */ + for (i=0;i<modulus_len;i++) + { + buf1[i]= (i %26) + 'A'; + } + buf1[modulus_len-1] = '\0'; + fprintf(stderr, "Buffer being encrypted = \n%s\n", buf1); + + /* encrypt buf1, result will be in buf2 */ + rv = PK11_PubEncryptRaw(pubkey, buf2, buf1, modulus_len, NULL); + if (rv != SECSuccess) + { + fprintf(stderr, "Encrypt with Public Key failed (err %d)\n", + PR_GetError()); + goto cleanup; + } + + pvtkey = PK11_FindKeyByAnyCert(cert, NULL); + if (pvtkey == NULL) + { + fprintf(stderr, "Couldn't find private key for cert TestCA (err %d)\n", + PR_GetError()); + goto cleanup; + } + + /* clear buf1 */ + for (i=0;i<modulus_len;i++) + { + buf1[i]= '\0'; + } + + /* decrypt buf2, result will be in buf1 */ + rv = PK11_PubDecryptRaw(pvtkey, buf1, &outlen, modulus_len, buf2, + modulus_len); + if (rv != SECSuccess) + { + fprintf(stderr, "Decrypt with Private Key failed (err %d)\n", + PR_GetError()); + goto cleanup; + } + + fprintf(stderr, "Result of decryption, outlen = %d\n", outlen); + fprintf(stderr, "Result of decryption, buf = \n%s\n", buf1); + + exit(0); + + cleanup: + if (cert) + CERT_DestroyCertificate(cert); + if (pubkey) + SECKEY_DestroyPublicKey(pubkey); + if (pvtkey) + SECKEY_DestroyPrivateKey(pvtkey); + if (buf1) + free(buf1); + if (buf2) + free(buf2); + exit(1); + } + + char *passwdcb(PK11SlotInfo *info, PRBool retry, void *arg) + { + if (!retry) + return PL_strdup("test"); + else + return NULL; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample5/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample5/index.rst new file mode 100644 index 0000000000..f4e8235ad5 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample5/index.rst @@ -0,0 +1,174 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample5: + +NSS Sample Code sample5 +======================= + +.. _nss_sample_code_5_pki_encryption_with_a_raw_public_private_key_in_der_format: + +`NSS Sample Code 5: PKI Encryption with a raw public & private key in DER format <#nss_sample_code_5_pki_encryption_with_a_raw_public_private_key_in_der_format>`__ +------------------------------------------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + .. code:: + + /* Example code to illustrate PKI crypto ops (encrypt with public key, + * decrypt with private key) + * + * No NSS db needed. The Public Key & Private Key to use are + * sourced from a base64-encoded DER SubjectPublicKeyInfo structure, + * and a base64-encoded DER PrivateKeyInfo structure. + * + * There is no attempt to link the public & private key together + * + * This example does not do any padding. It simply encrypts/decrypts a block + * of length equal to modulus length of the public/private key. + */ + + + #include "nss.h" + #include "pk11pub.h" + + #define BASE64_ENCODED_SUBJECTPUBLICKEYINFO "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAL3F6TIc3JEYsugo+a2fPU3W+Epv/FeIX21DC86WYnpFtW4srFtz2oNUzyLUzDHZdb+k//8dcT3IAOzUUi3R2eMCAwEAAQ==" + + #define BASE64_ENCODED_PRIVATEKEYINFO "MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEAvcXpMhzckRiy6Cj5rZ89Tdb4Sm/8V4hfbUMLzpZiekW1biysW3Pag1TPItTMMdl1v6T//x1xPcgA7NRSLdHZ4wIDAQABAkEAjh8+4qncwcmGivnM6ytbpQT+k/jEOeXG2bQhjojvnXN3FazGCEFXvpuIBcJVfaIJS9YBCMOzzrAtO0+k2hWnOQIhAOC4NVbo8FQhZS4yXM1M86kMl47FA9ui//OUfbhlAdw1AiEA2DBmIXnsboKB+OHver69p0gNeWlvcJc9bjDVfdLVsLcCIQCPtV3vGYJv2vdwxqZQaHC+YB4gIGAqOqBCbmjD3lyFLQIgA+VTYdUNoqwtZWvE4gRf7IzK2V5CCNhg3gR5RGwxN58CIGCcafoRrUKsM66ISg0ITI04G9V/w+wMx91wjEEB+QBz" + + + int main(int argc, char **argv) + { + SECStatus rv; + CERTCertificate *cert = NULL; + SECKEYPublicKey *pubkey = NULL; + CERTSubjectPublicKeyInfo *spki = NULL; + SECKEYPrivateKey *pvtkey = NULL; + int modulus_len, i, outlen; + char *buf1 = NULL; + char *buf2 = NULL; + char *pubkstr = BASE64_ENCODED_SUBJECTPUBLICKEYINFO; + char *pvtkstr = BASE64_ENCODED_PRIVATEKEYINFO; + SECItem der; + SECItem nickname; + PK11SlotInfo *slot = NULL; + + /* Initialize NSS + * You need to explicitly authenticate to the internal token if you use + * NSS_Init insteadf of NSS_NoDB_Init + * Invoke this after getting the internal token handle + * PK11_Authenticate(slot, PR_FALSE, NULL); + */ + rv = NSS_NoDB_Init("."); + if (rv != SECSuccess) + { + fprintf(stderr, "NSS initialization failed (err %d)\n", + PR_GetError()); + goto cleanup; + } + + /* get internal slot */ + slot = PK11_GetInternalKeySlot(); + if (slot == NULL) + { + fprintf(stderr, "Couldn't find slot (err %d)\n", PR_GetError()); + goto cleanup; + } + + rv = ATOB_ConvertAsciiToItem(&der, pubkstr); + if (rv!= SECSuccess) + { + fprintf(stderr, "ATOB_ConvertAsciiToItem failed %d\n", PR_GetError()); + goto cleanup; + } + spki = SECKEY_DecodeDERSubjectPublicKeyInfo(&der); + SECITEM_FreeItem(&der, PR_FALSE); + pubkey = SECKEY_ExtractPublicKey(spki); + + if (pubkey == NULL) + { + fprintf(stderr, "Couldn't extract public key (err %d)\n", PR_GetError()); + goto cleanup; + } + + modulus_len = SECKEY_PublicKeyStrength(pubkey); + fprintf(stderr, "Public Key Modulus %d bytes\n", modulus_len); + buf1 = (char *)malloc(modulus_len); + buf2 = (char *)malloc(modulus_len); + + /* initialize buf1 */ + for (i=0;i<modulus_len;i++) + { + buf1[i]= (i %26) + 'A'; + } + buf1[modulus_len-1] = '\0'; + fprintf(stderr, "Buffer being encrypted = \n%s\n", buf1); + + /* encrypt buf1, result will be in buf2 */ + rv = PK11_PubEncryptRaw(pubkey, buf2, buf1, modulus_len, NULL); + if (rv != SECSuccess) + { + fprintf(stderr, "Encrypt with Public Key failed (err %d)\n", + PR_GetError()); + goto cleanup; + } + + nickname.type = siBuffer; + nickname.data = "pvtkeynickname"; + nickname.len = strlen("pvtkeynickname"); + rv = ATOB_ConvertAsciiToItem(&der, pvtkstr); + if (rv!= SECSuccess) + { + fprintf(stderr, "ATOB_ConvertAsciiToItem failed %d\n", PR_GetError()); + goto cleanup; + } + + /* KU_ALL includes a lot of different key usages, KU_DATA_ENCIPHERMENT + * is enough for just RSA encryption. + * publicValue arg (4th) can be NULL for RSA key - I think it is even + * ignored + */ + PK11_ImportDERPrivateKeyInfoAndReturnKey(slot, &der, NULL, + NULL, PR_FALSE, PR_TRUE, + KU_ALL, &pvtkey, NULL); + SECITEM_FreeItem(&der, PR_FALSE); + + if (pvtkey == NULL) + { + fprintf(stderr, "Couldn't extract private key (err %d)\n", PR_GetError()); + goto cleanup; + } + + /* clear buf1 */ + for (i=0;i<modulus_len;i++) + { + buf1[i]= '\0'; + } + + /* decrypt buf2, result will be in buf1 */ + rv = PK11_PubDecryptRaw(pvtkey, buf1, &outlen, modulus_len, buf2, + modulus_len); + if (rv != SECSuccess) + { + fprintf(stderr, "Decrypt with Private Key failed (err %d)\n", + PR_GetError()); + goto cleanup; + } + + fprintf(stderr, "Result of decryption, outlen = %d\n", outlen); + fprintf(stderr, "Result of decryption, buf = \n%s\n", buf1); + + cleanup: + if (cert) + CERT_DestroyCertificate(cert); + if (pubkey) + SECKEY_DestroyPublicKey(pubkey); + if (pvtkey) + SECKEY_DestroyPrivateKey(pvtkey); + if (spki) + SECKEY_DestroySubjectPublicKeyInfo(spki); + if (slot) + PK11_FreeSlot(slot); + if (buf1) + free(buf1); + if (buf2) + free(buf2); + exit(1); + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample6/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample6/index.rst new file mode 100644 index 0000000000..b194873bc4 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample6/index.rst @@ -0,0 +1,153 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample6: + +NSS Sample Code sample6 +======================= + +.. _nss_sample_code_6_persistent_symmetric_keys_in_nss_database: + +`NSS Sample Code 6: Persistent Symmetric Keys in NSS database <#nss_sample_code_6_persistent_symmetric_keys_in_nss_database>`__ +------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + .. code:: + + /* Example code to illustrate generation of a secret symmetric key ring + * that PERSISTS in the NSS database. The symmetric keys can then be used + * without ever exposing them in the clear. + * + * To encrypt, you need the id of the key to use. + * To decrypt, you need the ciphertext and the id of the key that was used + * to encrypt + * + * Before running this example, create the NSS database + * certutil -N -d . + * (enter "test" when prompted for password) + */ + + + #include "nss.h" + #include "pk11pub.h" + + /* the key id can be any sequence of bytes. this example happens to use an + * integer */ + void genkey(int id); + + /* this callback is responsible for returning the password to the NSS + * key database. for example purposes, this function hardcodes the password. + * In a real app, this function should obtain the password using secure means + * such as prompting an operator, or retrieving it over a secure communication + * channel + */ + char *passwdcb(PK11SlotInfo *info, PRBool retry, void *arg); + + + int main(int argc, char **argv) + { + SECStatus rv; + + /* Initialize NSS */ + PK11_SetPasswordFunc(passwdcb); + + /* The NSS db must be initialized read-write since we'll be creating + * keys in it. Once keys are generated, it can be opened without read-write + * subsequently (NSS_Init). + */ + rv = NSS_InitReadWrite("."); + if (rv != SECSuccess) + { + fprintf(stderr, "NSS initialization failed (err %d)\n", + PR_GetError()); + exit(1); + } + + /* generate a key with id 1. should succeed on first run on a fresh db, + * should fail on successive runs because key with that id already exists */ + genkey(1); + + /* generate a key with id 2. should succeed on first run on a fresh db, + * should fail on successive runs because key with that id already exists */ + genkey(2); + + /* generate a key with id 1 - this will fail because key with that id + * already exists */ + genkey(1); + } + + + void genkey(int id) + { + PK11SlotInfo* slot = NULL; + PK11SymKey* key = NULL; + SECItem keyiditem; + int keyid[1]; + CK_MECHANISM_TYPE cipherMech; + + /* using CKM_AES_CBC_PAD mechanism for example */ + cipherMech = CKM_AES_CBC_PAD; + + slot = PK11_GetInternalKeySlot(); + /* slot = PK11_GetBestSlot(cipherMech, NULL); didn't work. + * Error code: token is read-only. ?? + */ + if (slot == NULL) + { + fprintf(stderr, "Unable to find security device (err %d)\n", + PR_GetError()); + return; + } + + keyid[0] = id; + keyiditem.type = siBuffer; + keyiditem.data = (void *)keyid; + keyiditem.len = sizeof(keyid[0]); + + /* Note: keysize must be 0 for fixed key-length algorithms like DES. + * Since we're using AES in this example, we're specifying + * one of the valid keysizes (16, 24, 32) + */ + key = PK11_TokenKeyGen(slot, cipherMech, 0, 32 /*keysize*/, + &keyiditem, PR_TRUE, 0); + if (key == NULL) + { + fprintf(stderr, "PK11_TokenKeyGen failed (err %d)\n", + PR_GetError()); + PK11_FreeSlot(slot); + return; + } + + fprintf(stderr, "key length of generated key is %d\n", + PK11_GetKeyLength(key)); + fprintf(stderr, "mechanism of key is %d (asked for %d)\n", + PK11_GetMechanism(key), cipherMech); + + PK11_FreeSymKey(key); + + + key = PK11_FindFixedKey(slot, cipherMech, &keyiditem, 0); + if (key == NULL) + { + fprintf(stderr, "PK11_FindFixedKey failed (err %d)\n", + PR_GetError()); + PK11_FreeSlot(slot); + return; + } + + fprintf(stderr, "Found key!\n"); + fprintf(stderr, "key length of generated key is %d\n", + PK11_GetKeyLength(key)); + fprintf(stderr, "mechanism of key is %d (asked for %d)\n", + PK11_GetMechanism(key), cipherMech); + + PK11_FreeSymKey(key); + + PK11_FreeSlot(slot); + } + + char *passwdcb(PK11SlotInfo *info, PRBool retry, void *arg) + { + if (!retry) + return PL_strdup("test"); + else + return NULL; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_1_hashing/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_1_hashing/index.rst new file mode 100644 index 0000000000..5ea9c8cadd --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_1_hashing/index.rst @@ -0,0 +1,253 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample_1_hashing: + +NSS Sample Code Sample_1_Hashing +================================ + +.. _nss_sample_code_1_hashing_a_file.: + +`NSS Sample Code 1: Hashing a file. <#nss_sample_code_1_hashing_a_file.>`__ +--------------------------------------------------------------------------- + +.. container:: + + This is an example program that demonstrates how to compute the hash of a file and save it to + another file. This program illustrates the use of NSS message APIs. + +.. _sample_code_1: + +`Sample Code 1 <#sample_code_1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: c + + /* NSPR Headers */ + #include <prprf.h> + #include <prtypes.h> + #include <plgetopt.h> + #include <prio.h> + + /* NSS headers */ + #include <secoid.h> + #include <secmodt.h> + #include <sechash.h> + + typedef struct { + const char *hashName; + SECOidTag oid; + } NameTagPair; + + /* The hash algorithms supported */ + static const NameTagPair HASH_NAMES[] = { + { "MD2", SEC_OID_MD2 }, + { "MD5", SEC_OID_MD5 }, + { "SHA1", SEC_OID_SHA1 }, + { "SHA256", SEC_OID_SHA256 }, + { "SHA384", SEC_OID_SHA384 }, + { "SHA512", SEC_OID_SHA512 } + }; + + /* + * Maps a hash name to a SECOidTag. + * Returns NULL if the name is not a supported algorithm + */ + static SECOidTag HashNameToOIDTag(const char *hashName) + { + int i, nhashes = sizeof(HASH_NAMES); + SECOidTag hashtag = SEC_OID_UNKNOWN; + + for (i = 0; i < nhashes; i++) { + if (PORT_Strcasecmp(hashName, HASH_NAMES[i].hashName) == 0) { + hashtag = HASH_NAMES[i].oid; + break; + } + } + return hashtag; + } + + /* + * Newline + */ + static void Newline(PRFileDesc* out) { PR_fprintf(out, "\n"); } + + /* + * PrintAsHex + */ + void PrintAsHex(PRFileDesc* out, unsigned char *data, unsigned int len) + { + unsigned i; + int column; + unsigned int limit = 15; + unsigned int level = 1; + + column = level; + if (!len) { + PR_fprintf(out, "(empty)\n"); + return; + } + + for (i = 0; i < len; i++) { + if (i != len - 1) { + PR_fprintf(out, "%02x:", data[i]); + column += 3; + } else { + PR_fprintf(out, "%02x", data[i]); + column += 2; + break; + } + if (column > 76 || (i % 16 == limit)) { + Newline(out); + column = level; + limit = i % 16; + } + } + if (column != level) { + Newline(out); + } + } + + /* + * Prints a usage message and exits + */ + static void Usage(const char *progName) + { + int htype; + int HASH_AlgTOTAL = sizeof(HASH_NAMES) / sizeof(HASH_NAMES[0]); + + fprintf(stderr, "Usage: %s -t type [ < input ] [ > output ]\n", progName); + fprintf(stderr, "%-20s Specify the digest method (must be one of\n", + "-t type"); + fprintf(stderr, "%-20s ", ""); + for (htype = 0; htype < HASH_AlgTOTAL; htype++) { + fprintf(stderr, HASH_NAMES[htype].hashName); + if (htype == (HASH_AlgTOTAL - 2)) + fprintf(stderr, " or "); + else if (htype != (HASH_AlgTOTAL - 1)) + fprintf(stderr, ", "); + } + fprintf(stderr, " (case ignored))\n"); + fprintf(stderr, "%-20s Define an input file to use (default is stdin)\n", + "< input"); + fprintf(stderr, "%-20s Define an output file to use (default is stdout)\n", + "> output"); + exit(-1); + } + + /* + * Check for the missing arguments + */ + static void PrintMsgAndExit(const char *progName, char opt) + { + fprintf(stderr, "%s: option -%c requires an argument\n", progName, opt); + Usage(progName); + } + + #define REQUIRE_ARG(opt,value) if (!(value)) PrintMsgAndExit(progName, opt) + + /* + * Digests a file according to the specified algorithm. + * It writes out the digest as a hexadecimal string. + */ + static int DigestFile(PRFileDesc *outFile, PRFileDesc *inFile, SECOidTag hashOIDTag) + { + unsigned int nb; + unsigned char ibuf[4096]; + unsigned char digest[64]; + unsigned int len; + unsigned int digestLen; + HASH_HashType hashType; + HASHContext *hashContext = NULL; + + hashType = HASH_GetHashTypeByOidTag(hashOIDTag); + hashContext = HASH_Create(hashType); + if (hashContext == NULL) { + return SECFailure; + } + + do { + + HASH_Begin(hashContext); + + /* Incrementally hash the file contents */ + while ((nb = PR_Read(inFile, ibuf, sizeof(ibuf))) > 0) { + HASH_Update(hashContext, ibuf, nb); + } + + HASH_End(hashContext, digest, &len, 64); + + /* Normally we would write it out in binary with + * nb = PR_Write(outFile, digest, len); + * but for illustration let's print it in hex. + */ + PrintAsHex(outFile, digest, len); + + } while (0); + + /* cleanup */ + if (hashContext != NULL) + HASH_Destroy(hashContext); + + return SECSuccess; + } + + /* + * This sample computes the hash of a file and saves it + * to another file. It illustrates the use of NSS message + * APIs. + */ + int main(int argc, char **argv) + { + SECOidTag hashOIDTag; + PLOptState *optstate; + PLOptStatus status; + SECStatus rv; + char *hashName = NULL; + char *progName = strrchr(argv[0], '/'); + + progName = progName ? progName + 1 : argv[0]; + + rv = NSS_NoDB_Init("/tmp"); + if (rv != SECSuccess) { + fprintf(stderr, "%s: NSS_Init failed in directory %s\n", + progName, "/tmp"); + return -1; + } + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "t:"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 't': + REQUIRE_ARG(optstate->option, optstate->value); + hashName = strdup(optstate->value); + break; + } + } + + if (!hashName) + Usage(progName); + + /* convert and validate */ + hashOIDTag = HashNameToOIDTag(hashName); + if (hashOIDTag == SEC_OID_UNKNOWN) { + fprintf(stderr, "%s: invalid digest type - %s\n", progName, hashName); + Usage(progName); + } + + /* Digest it and print the result */ + rv = DigestFile(PR_STDOUT, PR_STDIN, hashOIDTag); + if (rv != SECSuccess) { + fprintf(stderr, "%s: problem digesting data (%d)\n", + progName, PORT_GetError()); + } + + rv = NSS_Shutdown(); + if (rv != SECSuccess) { + exit(-1); + } + + return 0; + } + + </sechash.h></secmodt.h></secoid.h></prio.h></plgetopt.h></prtypes.h></prprf.h>
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_2_initialization_of_nss/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_2_initialization_of_nss/index.rst new file mode 100644 index 0000000000..a8ad843b49 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_2_initialization_of_nss/index.rst @@ -0,0 +1,257 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample_2_initialization_of_nss: + +NSS Sample Code Sample_2_Initialization of NSS +============================================== + +.. _nss_sample_code_2_initializing_nss: + +`NSS Sample Code 2: Initializing NSS <#nss_sample_code_2_initializing_nss>`__ +----------------------------------------------------------------------------- + +.. container:: + + This example program demonstrates how to initialize the NSS Database. This program illustrates + password handling. + +.. _sample_code_1: + +`Sample Code 1 <#sample_code_1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: c + + /* NSPR Headers */ + #include <prthread.h> + #include <plgetopt.h> + #include <prprf.h> + + /* NSS headers */ + #include <nss.h> + #include <pk11func.h> + + #include "util.h" + + /* Print a usage message and exit */ + static void Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s -d <dbdirpath> [-p <plainpasswc>]" + " [-f <passwdffile>]\n\n", + progName); + fprintf(stderr, "%-15s Specify a DB directory path\n\n", + "-d <dbdirpath>"); + fprintf(stderr, "%-15s Specify a plaintext password\n\n", + "-p <plainpasswc>"); + fprintf(stderr, "%-15s Specify a password file\n\n", + "-f <plainpasswc>"); + exit(-1); + } + + /* Initialize the slot password */ + char *InitSlotPassword(PK11SlotInfo *slot, PRBool retry, void *arg) + { + FILE *input; + FILE *output; + char *p0 = NULL; + char *p1 = NULL; + secuPWData *pwdata = (secuPWData *) arg; + + if (pwdata->source == PW_FROMFILE) { + return FilePasswd(slot, retry, pwdata->data); + } + if (pwdata->source == PW_PLAINTEXT) { + return PL_strdup(pwdata->data); + } + + /* open terminal */ + input = fopen("/dev/tty", "r"); + if (input == NULL) { + PR_fprintf(PR_STDERR, "Error opening input terminal for read\n"); + return NULL; + } + + /* we have no password, so initialize database with one */ + PR_fprintf(PR_STDERR, + "Enter a password which will be used to encrypt your keys.\n" + "The password should be at least 8 characters long,\n" + "and should contain at least one non-alphabetic character.\n\n"); + + output = fopen("/dev/tty", "w"); + if (output == NULL) { + PR_fprintf(PR_STDERR, "Error opening output terminal for write\n"); + return NULL; + } + + for (;;) { + if (p0) + PORT_Free(p0); + p0 = GetPassword(input, output, "Enter new password: ", + CheckPassword); + if (p1) + PORT_Free(p1); + p1 = GetPassword(input, output, "Re-enter password: ", + CheckPassword); + if (p0 && p1 && !PORT_Strcmp(p0, p1)) { + break; + } + PR_fprintf(PR_STDERR, "Passwords do not match. Try again.\n"); + } + + /* clear out the duplicate password string */ + if (p1) { + PORT_Memset(p1, 0, PORT_Strlen(p1)); + PORT_Free(p1); + } + fclose(input); + fclose(output); + + return p0; + } + + /* Change the password */ + SECStatus ChangePW(PK11SlotInfo *slot, char *oldPass, char *newPass, + char *oldPwFile, char *newPwFile) + { + SECStatus rv; + secuPWData pwdata; + secuPWData newpwdata; + char *oldpw = NULL; + char *newpw = NULL; + + if (oldPass) { + pwdata.source = PW_PLAINTEXT; + pwdata.data = oldPass; + } else if (oldPwFile) { + pwdata.source = PW_FROMFILE; + pwdata.data = oldPwFile; + } else { + pwdata.source = PW_NONE; + pwdata.data = NULL; + } + + if (newPass) { + newpwdata.source = PW_PLAINTEXT; + newpwdata.data = newPass; + } else if (newPwFile) { + newpwdata.source = PW_FROMFILE; + newpwdata.data = NULL; + } else { + newpwdata.source = PW_NONE; + newpwdata.data = NULL; + } + + if (PK11_NeedUserInit(slot)) { + newpw = InitSlotPassword(slot, PR_FALSE, &pwdata); + rv = PK11_InitPin(slot, (char*)NULL, newpw); + } + else { + for (;;) { + oldpw = GetModulePassword(slot, PR_FALSE, &pwdata); + + if (PK11_CheckUserPassword(slot, oldpw) != SECSuccess) { + if (pwdata.source == PW_NONE) { + PR_fprintf(PR_STDERR, "Invalid password. Try again.\n"); + } else { + PR_fprintf(PR_STDERR, "Invalid password.\n"); + PORT_Memset(oldpw, 0, PL_strlen(oldpw)); + PORT_Free(oldpw); + return SECFailure; + } + } else { + break; + } + PORT_Free(oldpw); + } + newpw = InitSlotPassword(slot, PR_FALSE, &newpwdata); + + if (PK11_ChangePW(slot, oldpw, newpw) != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to change password.\n"); + return SECFailure; + } + PORT_Memset(oldpw, 0, PL_strlen(oldpw)); + PORT_Free(oldpw); + PR_fprintf(PR_STDOUT, "Password changed successfully.\n"); + } + PORT_Memset(newpw, 0, PL_strlen(newpw)); + PORT_Free(newpw); + return SECSuccess; + } + + /* + * This example illustrates initialization of the NSS database. + * It creates an nss configuration directory with empty databases + * and initializes the databases. It also illustrates techniques for + * password handling. + */ + int main(int argc, char **argv) + { + PLOptState *optstate; + PLOptStatus status; + SECStatus rv; + SECStatus rvShutdown; + char *slotname = "internal"; + PK11SlotInfo *slot = NULL; + char *dbdir = NULL; + char *plainPass = NULL; + char *pwFile = NULL; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "d:p:q:f:g:"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'd': + dbdir = strdup(optstate->value); + break; + case 'p': + plainPass = strdup(optstate->value); + break; + case 'f': + pwFile = strdup(optstate->value); + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (!dbdir) + Usage(progName); + + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + + /* Create the database */ + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_Initialize Failed"); + PR_Cleanup(); + exit(rv); + } + + if (PL_strcmp(slotname, "internal") == 0) + slot = PK11_GetInternalKeySlot(); + + /* If creating new database, initialize the password. */ + rv = ChangePW(slot, plainPass, 0, pwFile, 0); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to change password\n"); + } + + if (slot) { + PK11_FreeSlot(slot); + } + rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); + rv = SECFailure; + } + + PR_Cleanup(); + + return rv; + } + </plainpasswc></plainpasswc></dbdirpath></passwdffile></plainpasswc></dbdirpath></pk11func.h></nss.h></prprf.h></plgetopt.h></prthread.h>
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_3_basic_encryption_and_maci/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_3_basic_encryption_and_maci/index.rst new file mode 100644 index 0000000000..059c6861b8 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_sample_3_basic_encryption_and_maci/index.rst @@ -0,0 +1,1221 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_sample_3_basic_encryption_and_maci: + +NSS Sample Code Sample_3_Basic Encryption and MACing +==================================================== + +.. _nss_sample_code_3_basic_encryption_and_macing: + +`NSS Sample Code 3: Basic Encryption and MACing <#nss_sample_code_3_basic_encryption_and_macing>`__ +--------------------------------------------------------------------------------------------------- + +.. container:: + + This example program demonstrates how to encrypt and MAC a file. + +.. _sample_code_3: + +`Sample Code 3 <#sample_code_3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: c + + /* NSPR Headers */ + #include <prthread.h> + #include <plgetopt.h> + #include <prerror.h> + #include <prinit.h> + #include <prlog.h> + #include <prtypes.h> + #include <plstr.h> + + /* NSS headers */ + #include <keyhi.h> + #include <pk11priv.h> + + /* our samples utilities */ + #include "util.h" + + #define BUFFERSIZE 80 + #define DIGESTSIZE 16 + #define PTEXT_MAC_BUFFER_SIZE 96 + #define CIPHERSIZE 96 + #define BLOCKSIZE 32 + + #define CIPHER_HEADER "-----BEGIN CIPHER-----" + #define CIPHER_TRAILER "-----END CIPHER-----" + #define ENCKEY_HEADER "-----BEGIN AESKEY CKAID-----" + #define ENCKEY_TRAILER "-----END AESKEY CKAID-----" + #define MACKEY_HEADER "-----BEGIN MACKEY CKAID-----" + #define MACKEY_TRAILER "-----END MACKEY CKAID-----" + #define IV_HEADER "-----BEGIN IV-----" + #define IV_TRAILER "-----END IV-----" + #define MAC_HEADER "-----BEGIN MAC-----" + #define MAC_TRAILER "-----END MAC-----" + #define PAD_HEADER "-----BEGIN PAD-----" + #define PAD_TRAILER "-----END PAD-----" + + typedef enum { + ENCRYPT, + DECRYPT, + UNKNOWN + } CommandType; + + typedef enum { + SYMKEY = 0, + MACKEY = 1, + IV = 2, + MAC = 3, + PAD = 4 + } HeaderType; + + + /* Print a usage message and exit */ + static void Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s -c <a|b> -d <dbdirpath> [-z <noisefilename>] " + "[-p <dbpwd> | -f <dbpwdfile>] -i <ipfilename> -o <opfilename>\n\n", + progName); + fprintf(stderr, "%-20s Specify 'a' for encrypt operation\n\n", + "-c <a|b>"); + fprintf(stderr, "%-20s Specify 'b' for decrypt operation\n\n", + " "); + fprintf(stderr, "%-20s Specify db directory path\n\n", + "-d <dbdirpath>"); + fprintf(stderr, "%-20s Specify db password [optional]\n\n", + "-p <dbpwd>"); + fprintf(stderr, "%-20s Specify db password file [optional]\n\n", + "-f <dbpwdfile>"); + fprintf(stderr, "%-20s Specify noise file name [optional]\n\n", + "-z <noisefilename>"); + fprintf(stderr, "%-21s Specify an input file name\n\n", + "-i <ipfilename>"); + fprintf(stderr, "%-21s Specify an output file name\n\n", + "-o <opfilename>"); + fprintf(stderr, "%-7s For encrypt, it takes <ipfilename> as an input file and produces\n", + "Note :"); + fprintf(stderr, "%-7s <ipfilename>.enc and <ipfilename>.header as intermediate output files.\n\n", + ""); + fprintf(stderr, "%-7s For decrypt, it takes <ipfilename>.enc and <ipfilename>.header\n", + ""); + fprintf(stderr, "%-7s as input files and produces <opfilename> as a final output file.\n\n", + ""); + exit(-1); + } + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, you can obtain one at https://mozilla.org/MPL/2.0/. */ + + /* NSPR Headers */ + #include <prthread.h> + #include <plgetopt.h> + #include <prerror.h> + #include <prinit.h> + #include <prlog.h> + #include <prtypes.h> + #include <plstr.h> + + /* + * Gather a CKA_ID + */ + SECStatus + GatherCKA_ID(PK11SymKey* key, SECItem* buf) + { + SECStatus rv = PK11_ReadRawAttribute(PK11_TypeSymKey, key, CKA_ID, buf); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "PK11_ReadRawAttribute returned (%d)\n", rv); + PR_fprintf(PR_STDERR, "Could not read SymKey CKA_ID attribute\n"); + return rv; + } + return rv; + } + + /* + * Generate a Symmetric Key + */ + PK11SymKey * + GenerateSYMKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE mechanism, + int keySize, SECItem *keyID, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + return NULL; + } + } + + /* Generate the symmetric key */ + key = PK11_TokenKeyGen(slot, mechanism, + NULL, keySize, keyID, PR_TRUE, pwdata); + + if (!key) { + PR_fprintf(PR_STDERR, "Symmetric Key Generation Failed \n"); + } + + return key; + } + + /* + * MacInit + */ + SECStatus + MacInit(PK11Context *ctx) + { + SECStatus rv = PK11_DigestBegin(ctx); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestBegin()\n"); + } + return rv; + } + + /* + * MacUpdate + */ + SECStatus + MacUpdate(PK11Context *ctx, + unsigned char *msg, unsigned int msgLen) + { + SECStatus rv = PK11_DigestOp(ctx, msg, msgLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : DigestOp()\n"); + } + return rv; + } + + /* + * Finalize MACing + */ + SECStatus + MacFinal(PK11Context *ctx, + unsigned char *mac, unsigned int *macLen, unsigned int maxLen) + { + SECStatus rv = PK11_DigestFinal(ctx, mac, macLen, maxLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestFinal()\n"); + } + return SECSuccess; + } + + /* + * Compute Mac + */ + SECStatus + ComputeMac(PK11Context *ctxmac, + unsigned char *ptext, unsigned int ptextLen, + unsigned char *mac, unsigned int *macLen, + unsigned int maxLen) + { + SECStatus rv = MacInit(ctxmac); + if (rv != SECSuccess) return rv; + rv = MacUpdate(ctxmac, ptext, ptextLen); + if (rv != SECSuccess) return rv; + rv = MacFinal(ctxmac, mac, macLen, maxLen); + return rv; + } + + /* + * Write To Header File + */ + SECStatus + WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, + PRFileDesc *outFile) + { + SECStatus rv; + char header[40]; + char trailer[40]; + char *outString = NULL; + + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + PR_fprintf(outFile, "%s\n", header); + PrintAsHex(outFile, buf, len); + PR_fprintf(outFile, "%s\n\n", trailer); + return SECSuccess; + } + + /* + * Initialize for encryption or decryption - common code + */ + PK11Context * + CryptInit(PK11SymKey *key, + unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type, CK_ATTRIBUTE_TYPE operation) + { + SECItem ivItem = { siBuffer, iv, ivLen }; + PK11Context *ctx = NULL; + + SECItem *secParam = PK11_ParamFromIV(CKM_AES_CBC, &ivItem); + if (secParam == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : secParam NULL\n"); + return NULL; + } + ctx = PK11_CreateContextBySymKey(CKM_AES_CBC, operation, key, secParam); + if (ctx == NULL) { + PR_fprintf(PR_STDERR, "Crypt Failed : can't create a context\n"); + goto cleanup; + + } + cleanup: + if (secParam) { + SECITEM_FreeItem(secParam, PR_TRUE); + } + return ctx; + } + + /* + * Common encryption and decryption code + */ + SECStatus + Crypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxOut, + unsigned char *in, unsigned int inLen) + { + SECStatus rv; + + rv = PK11_CipherOp(ctx, out, outLen, maxOut, in, inLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Crypt Failed : PK11_CipherOp returned %d\n", rv); + goto cleanup; + } + + cleanup: + if (rv != SECSuccess) { + return rv; + } + return SECSuccess; + } + + /* + * Decrypt + */ + SECStatus + Decrypt(PK11Context *ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * Encrypt + */ + SECStatus + Encrypt(PK11Context* ctx, + unsigned char *out, unsigned int *outLen, unsigned int maxout, + unsigned char *in, unsigned int inLen) + { + return Crypt(ctx, out, outLen, maxout, in, inLen); + } + + /* + * EncryptInit + */ + PK11Context * + EncryptInit(PK11SymKey *ek, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(ek, iv, ivLen, type, CKA_ENCRYPT); + } + + /* + * DecryptInit + */ + PK11Context * + DecryptInit(PK11SymKey *dk, unsigned char *iv, unsigned int ivLen, + CK_MECHANISM_TYPE type) + { + return CryptInit(dk, iv, ivLen, type, CKA_DECRYPT); + } + + /* + * Read cryptographic parameters from the header file + */ + SECStatus + ReadFromHeaderFile(const char *fileName, HeaderType type, + SECItem *item, PRBool isHexData) + { + SECStatus rv; + PRFileDesc* file; + SECItem filedata; + SECItem outbuf; + unsigned char *nonbody; + unsigned char *body; + char header[40]; + char trailer[40]; + + outbuf.type = siBuffer; + file = PR_Open(fileName, PR_RDONLY, 0); + if (!file) { + PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); + return SECFailure; + } + switch (type) { + case SYMKEY: + strcpy(header, ENCKEY_HEADER); + strcpy(trailer, ENCKEY_TRAILER); + break; + case MACKEY: + strcpy(header, MACKEY_HEADER); + strcpy(trailer, MACKEY_TRAILER); + break; + case IV: + strcpy(header, IV_HEADER); + strcpy(trailer, IV_TRAILER); + break; + case MAC: + strcpy(header, MAC_HEADER); + strcpy(trailer, MAC_TRAILER); + break; + case PAD: + strcpy(header, PAD_HEADER); + strcpy(trailer, PAD_TRAILER); + break; + } + + rv = FileToItem(&filedata, file); + nonbody = (char *)filedata.data; + if (!nonbody) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* check for headers and trailers and remove them */ + if ((body = strstr(nonbody, header)) != NULL) { + char *trail = NULL; + nonbody = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(nonbody, '\r'); /* maybe this is a MAC file */ + if (body) + trail = strstr(++body, trailer); + if (trail != NULL) { + *trail = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + return SECFailure; + } + } else { + body = nonbody; + } + + cleanup: + PR_Close(file); + HexToBuf(body, item, isHexData); + return SECSuccess; + } + + /* + * EncryptAndMac + */ + SECStatus + EncryptAndMac(PRFileDesc *inFile, + PRFileDesc *headerFile, + PRFileDesc *encFile, + PK11SymKey *ek, + PK11SymKey *mk, + unsigned char *iv, unsigned int ivLen, + PRBool ascii) + { + SECStatus rv; + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen; + unsigned char mac[DIGESTSIZE]; + unsigned int macLen; + unsigned int nwritten; + unsigned char encbuf[BLOCKSIZE]; + unsigned int encbufLen; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + unsigned int pad[1]; + SECItem padItem; + unsigned int paddingLength; + + static unsigned int firstTime = 1; + int j; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + rv = MacInit(ctxmac); + if (rv != SECSuccess) { + goto cleanup; + } + + ctxenc = EncryptInit(ek, iv, ivLen, CKM_AES_CBC); + + /* read a buffer of plaintext from input file */ + while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { + + /* Encrypt using it using CBC, using previously created IV */ + if (ptextLen != BLOCKSIZE) { + paddingLength = BLOCKSIZE - ptextLen; + for ( j=0; j < paddingLength; j++) { + ptext[ptextLen+j] = (unsigned char)paddingLength; + } + ptextLen = BLOCKSIZE; + } + rv = Encrypt(ctxenc, + encbuf, &encbufLen, sizeof(encbuf), + ptext, ptextLen); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Encrypt Failure\n"); + goto cleanup; + } + + /* save the last block of ciphertext as the next IV */ + iv = encbuf; + ivLen = encbufLen; + + /* write the cipher text to intermediate file */ + nwritten = PR_Write(encFile, encbuf, encbufLen); + /*PR_Assert(nwritten == encbufLen);*/ + + rv = MacUpdate(ctxmac, ptext, ptextLen); + } + + rv = MacFinal(ctxmac, mac, &macLen, DIGESTSIZE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "MacFinal Failure\n"); + goto cleanup; + } + if (macLen == 0) { + PR_fprintf(PR_STDERR, "Bad MAC length\n"); + rv = SECFailure; + goto cleanup; + } + WriteToHeaderFile(mac, macLen, MAC, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write MAC Failure\n"); + goto cleanup; + } + + pad[0] = paddingLength; + padItem.type = siBuffer; + padItem.data = (unsigned char *)pad; + padItem.len = sizeof(pad[0]); + + WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Write PAD Failure\n"); + goto cleanup; + } + + rv = SECSuccess; + + cleanup: + if (ctxmac != NULL) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc != NULL) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + + return rv; + } + + /* + * Find the Key for the given mechanism + */ + PK11SymKey* + FindKey(PK11SlotInfo *slot, + CK_MECHANISM_TYPE mechanism, + SECItem *keyBuf, secuPWData *pwdata) + { + SECStatus rv; + PK11SymKey *key; + + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + if (slot) { + PK11_FreeSlot(slot); + } + return NULL; + } + } + + key = PK11_FindFixedKey(slot, mechanism, keyBuf, 0); + if (!key) { + PR_fprintf(PR_STDERR, + "PK11_FindFixedKey failed (err %d)\n", + PR_GetError()); + PK11_FreeSlot(slot); + return NULL; + } + return key; + } + + /* + * Decrypt and Verify MAC + */ + SECStatus + DecryptAndVerifyMac( + const char* outFileName, + char *encryptedFileName, + SECItem *cItem, SECItem *macItem, + PK11SymKey* ek, PK11SymKey* mk, SECItem *ivItem, SECItem *padItem) + { + SECStatus rv; + PRFileDesc* inFile; + PRFileDesc* outFile; + + unsigned char decbuf[64]; + unsigned int decbufLen; + + unsigned char ptext[BLOCKSIZE]; + unsigned int ptextLen = 0; + unsigned char ctext[64]; + unsigned int ctextLen; + unsigned char newmac[DIGESTSIZE]; + unsigned int newmacLen = 0; + unsigned int newptextLen = 0; + unsigned int count = 0; + unsigned int temp = 0; + unsigned int blockNumber = 0; + SECItem noParams = { siBuffer, NULL, 0 }; + PK11Context *ctxmac = NULL; + PK11Context *ctxenc = NULL; + + unsigned char iv[BLOCKSIZE]; + unsigned int ivLen = ivItem->len; + unsigned int fileLength; + unsigned int paddingLength; + int j; + + memcpy(iv, ivItem->data, ivItem->len); + paddingLength = (unsigned int)padItem->data[0]; + + ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); + if (ctxmac == NULL) { + PR_fprintf(PR_STDERR, "Can't create MAC context\n"); + rv = SECFailure; + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(encryptedFileName, PR_RDONLY , 0); + if (!inFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* Open the output file. */ + outFile = PR_Open(outFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR , 00660); + if (!outFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + outFileName); + return SECFailure; + } + + rv = MacInit(ctxmac); + if (rv != SECSuccess) goto cleanup; + + ctxenc = DecryptInit(ek, iv, ivLen, CKM_AES_CBC); + fileLength = FileSize(encryptedFileName); + + while ((ctextLen = PR_Read(inFile, ctext, sizeof(ctext))) > 0) { + + count += ctextLen; + + /* decrypt cipher text buffer using CBC and IV */ + + rv = Decrypt(ctxenc, decbuf, &decbufLen, sizeof(decbuf), + ctext, ctextLen); + + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Decrypt Failure\n"); + goto cleanup; + } + + if (decbufLen == 0) break; + + rv = MacUpdate(ctxmac, decbuf, decbufLen); + if (rv != SECSuccess) { goto cleanup; } + if (count == fileLength) { + decbufLen = decbufLen-paddingLength; + } + + /* write the plain text to out file */ + temp = PR_Write(outFile, decbuf, decbufLen); + if (temp != decbufLen) { + PR_fprintf(PR_STDERR, "write error\n"); + rv = SECFailure; + break; + } + + /* save last block of ciphertext */ + memcpy(iv, decbuf, decbufLen); + ivLen = decbufLen; + blockNumber++; + } + + if (rv != SECSuccess) { goto cleanup; } + + rv = MacFinal(ctxmac, newmac, &newmacLen, sizeof(newmac)); + if (rv != SECSuccess) { goto cleanup; } + + if (PORT_Memcmp(macItem->data, newmac, newmacLen) == 0) { + rv = SECSuccess; + } else { + PR_fprintf(PR_STDERR, "Check MAC : Failure\n"); + PR_fprintf(PR_STDERR, "Extracted : "); + PrintAsHex(PR_STDERR, macItem->data, macItem->len); + PR_fprintf(PR_STDERR, "Computed : "); + PrintAsHex(PR_STDERR, newmac, newmacLen); + rv = SECFailure; + } + cleanup: + if (ctxmac) { + PK11_DestroyContext(ctxmac, PR_TRUE); + } + if (ctxenc) { + PK11_DestroyContext(ctxenc, PR_TRUE); + } + if (outFile) { + PR_Close(outFile); + } + + return rv; + } + + /* + * Gets IV and CKAIDs From Header File + */ + SECStatus + GetIVandCKAIDSFromHeader(const char *cipherFileName, + SECItem *ivItem, SECItem *encKeyItem, SECItem *macKeyItem) + { + SECStatus rv; + + /* open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it + */ + rv = ReadFromHeaderFile(cipherFileName, IV, ivItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not retrieve IV from cipher file\n"); + goto cleanup; + } + + rv = ReadFromHeaderFile(cipherFileName, SYMKEY, encKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve AES CKA_ID from cipher file\n"); + goto cleanup; + } + rv = ReadFromHeaderFile(cipherFileName, MACKEY, macKeyItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC CKA_ID from cipher file\n"); + goto cleanup; + } + cleanup: + return rv; + } + + /* + * Decrypt a File + */ + SECStatus + DecryptFile(PK11SlotInfo *slot, + const char *dbdir, + const char *outFileName, + const char *headerFileName, + char *encryptedFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open read only and we have authenticated to it + * open input file, read in header, get IV and CKA_IDs of two keys from it + * find those keys in the DB token + * Open output file + * loop until EOF(input): + * read a buffer of ciphertext from input file + * save last block of ciphertext + * decrypt ciphertext buffer using CBC and IV + * compute and check MAC, then remove MAC from plaintext + * replace IV with saved last block of ciphertext + * write the plain text to output file + * close files + * report success + */ + + SECStatus rv; + SECItem ivItem; + SECItem encKeyItem; + SECItem macKeyItem; + SECItem cipherItem; + SECItem macItem; + SECItem padItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + + + /* open intermediate file, read in header, get IV and CKA_IDs of two keys + * from it + */ + rv = GetIVandCKAIDSFromHeader(headerFileName, + &ivItem, &encKeyItem, &macKeyItem); + if (rv != SECSuccess) { + goto cleanup; + } + + /* find those keys in the DB token */ + encKey = FindKey(slot, CKM_AES_CBC, &encKeyItem, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "Can't find the encryption key\n"); + rv = SECFailure; + goto cleanup; + } + /* CKM_MD5_HMAC or CKM_EXTRACT_KEY_FROM_KEY */ + macKey = FindKey(slot, CKM_MD5_HMAC, &macKeyItem, pwdata); + if (macKey == NULL) { + rv = SECFailure; + goto cleanup; + } + + /* Read in the Mac into item from the intermediate file */ + rv = ReadFromHeaderFile(headerFileName, MAC, &macItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve MAC from cipher file\n"); + goto cleanup; + } + if (macItem.data == NULL) { + PR_fprintf(PR_STDERR, "MAC has NULL data\n"); + rv = SECFailure; + goto cleanup; + } + if (macItem.len == 0) { + PR_fprintf(PR_STDERR, "MAC has data has 0 length\n"); + /*rv = SECFailure; + goto cleanup;*/ + } + + rv = ReadFromHeaderFile(headerFileName, PAD, &padItem, PR_TRUE); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, + "Could not retrieve PAD detail from header file\n"); + goto cleanup; + } + + if (rv == SECSuccess) { + /* Decrypt and Remove Mac */ + rv = DecryptAndVerifyMac(outFileName, encryptedFileName, + &cipherItem, &macItem, encKey, macKey, &ivItem, &padItem); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed while decrypting and removing MAC\n"); + } + } + + cleanup: + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * Encrypt a File + */ + SECStatus + EncryptFile( + PK11SlotInfo *slot, + const char *dbdir, + const char *inFileName, + const char *headerFileName, + const char *encryptedFileName, + const char *noiseFileName, + secuPWData *pwdata, + PRBool ascii) + { + /* + * The DB is open for read/write and we have authenticated to it. + * generate a symmetric AES key as a token object. + * generate a second key to use for MACing, also a token object. + * get their CKA_IDs + * generate a random value to use as IV for AES CBC + * open an input file and an output file, + * write a header to the output that identifies the two keys by + * their CKA_IDs, May include original file name and length. + * loop until EOF(input) + * read a buffer of plaintext from input file + * MAC it, append the MAC to the plaintext + * encrypt it using CBC, using previously created IV + * store the last block of ciphertext as the new IV + * write the cipher text to intermediate file + * close files + * report success + */ + SECStatus rv; + PRFileDesc *inFile; + PRFileDesc *headerFile; + PRFileDesc *encFile; + + unsigned char *encKeyId = (unsigned char *) "Encrypt Key"; + unsigned char *macKeyId = (unsigned char *) "MAC Key"; + SECItem encKeyID = { siAsciiString, encKeyId, PL_strlen(encKeyId) }; + SECItem macKeyID = { siAsciiString, macKeyId, PL_strlen(macKeyId) }; + + SECItem encCKAID; + SECItem macCKAID; + unsigned char iv[BLOCKSIZE]; + SECItem ivItem; + PK11SymKey *encKey = NULL; + PK11SymKey *macKey = NULL; + SECItem temp; + unsigned char c; + + /* generate a symmetric AES key as a token object. */ + encKey = GenerateSYMKey(slot, CKM_AES_KEY_GEN, 128/8, &encKeyID, pwdata); + if (encKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for AES returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* generate a second key to use for MACing, also a token object. */ + macKey = GenerateSYMKey(slot, CKM_GENERIC_SECRET_KEY_GEN, 160/8, + &macKeyID, pwdata); + if (macKey == NULL) { + PR_fprintf(PR_STDERR, "GenerateSYMKey for MACing returned NULL.\n"); + rv = SECFailure; + goto cleanup; + } + + /* get the encrypt key CKA_ID */ + rv = GatherCKA_ID(encKey, &encCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error while wrapping encrypt key\n"); + goto cleanup; + } + + /* get the MAC key CKA_ID */ + rv = GatherCKA_ID(macKey, &macCKAID); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Can't get the MAC key CKA_ID.\n"); + goto cleanup; + } + + if (noiseFileName) { + rv = SeedFromNoiseFile(noiseFileName); + if (rv != SECSuccess) { + PORT_SetError(PR_END_OF_FILE_ERROR); + return SECFailure; + } + rv = PK11_GenerateRandom(iv, BLOCKSIZE); + if (rv != SECSuccess) { + goto cleanup; + } + + } else { + /* generate a random value to use as IV for AES CBC */ + GenerateRandom(iv, BLOCKSIZE); + } + + headerFile = PR_Open(headerFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!headerFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + headerFileName); + return SECFailure; + } + encFile = PR_Open(encryptedFileName, + PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); + if (!encFile) { + PR_fprintf(PR_STDERR, + "Unable to open \"%s\" for writing.\n", + encryptedFileName); + return SECFailure; + } + /* write to a header file the IV and the CKA_IDs + * identifying the two keys + */ + ivItem.type = siBuffer; + ivItem.data = iv; + ivItem.len = BLOCKSIZE; + + rv = WriteToHeaderFile(iv, BLOCKSIZE, IV, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing IV to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + rv = WriteToHeaderFile(encCKAID.data, encCKAID.len, SYMKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing AES CKA_ID to cipher file - %s\n", + encryptedFileName); + goto cleanup; + } + rv = WriteToHeaderFile(macCKAID.data, macCKAID.len, MACKEY, headerFile); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Error writing MAC CKA_ID to cipher file - %s\n", + headerFileName); + goto cleanup; + } + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + + /* Macing and Encryption */ + if (rv == SECSuccess) { + rv = EncryptAndMac(inFile, headerFile, encFile, + encKey, macKey, ivItem.data, ivItem.len, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : MACing and Encryption\n"); + goto cleanup; + } + } + + cleanup: + if (inFile) { + PR_Close(inFile); + } + if (headerFile) { + PR_Close(headerFile); + } + if (encFile) { + PR_Close(encFile); + } + if (slot) { + PK11_FreeSlot(slot); + } + if (encKey) { + PK11_FreeSymKey(encKey); + } + if (macKey) { + PK11_FreeSymKey(macKey); + } + + return rv; + } + + /* + * This example illustrates basic encryption/decryption and MACing. + * Generates the encryption/mac keys and uses token for storing. + * Encrypts the input file and appends MAC before storing in intermediate + * header file. + * Writes the CKA_IDs of the encryption keys into intermediate header file. + * Reads the intermediate header file for CKA_IDs and encrypted + * contents and decrypts into output file. + */ + int main(int argc, char **argv) + { + SECStatus rv; + SECStatus rvShutdown; + PK11SlotInfo *slot = NULL; + PLOptState *optstate; + PLOptStatus status; + char headerFileName[50]; + char encryptedFileName[50]; + PRFileDesc *inFile; + PRFileDesc *outFile; + PRBool ascii = PR_FALSE; + CommandType cmd = UNKNOWN; + const char *command = NULL; + const char *dbdir = NULL; + const char *inFileName = NULL; + const char *outFileName = NULL; + const char *noiseFileName = NULL; + secuPWData pwdata = { PW_NONE, 0 }; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "c:d:i:o:f:p:z:a"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'a': + ascii = PR_TRUE; + break; + case 'c': + command = strdup(optstate->value); + break; + case 'd': + dbdir = strdup(optstate->value); + break; + case 'f': + pwdata.source = PW_FROMFILE; + pwdata.data = strdup(optstate->value); + break; + case 'p': + pwdata.source = PW_PLAINTEXT; + pwdata.data = strdup(optstate->value); + break; + case 'i': + inFileName = strdup(optstate->value); + break; + case 'o': + outFileName = strdup(optstate->value); + break; + case 'z': + noiseFileName = strdup(optstate->value); + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (!command || !dbdir || !inFileName || !outFileName) + Usage(progName); + if (PL_strlen(command)==0) + Usage(progName); + + cmd = command[0] == 'a' ? ENCRYPT : command[0] == 'b' ? DECRYPT : UNKNOWN; + + /* Open the input file. */ + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", + inFileName); + return SECFailure; + } + PR_Close(inFile); + + /* For intermediate header file, choose filename as inputfile name + with extension ".header" */ + strcpy(headerFileName, inFileName); + strcat(headerFileName, ".header"); + + /* For intermediate encrypted file, choose filename as inputfile name + with extension ".enc" */ + strcpy(encryptedFileName, inFileName); + strcat(encryptedFileName, ".enc"); + + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + + switch (cmd) { + case ENCRYPT: + /* If the intermediate header file already exists, delete it */ + if (PR_Access(headerFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(headerFileName); + } + /* If the intermediate encrypted already exists, delete it */ + if (PR_Access(encryptedFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { + PR_Delete(encryptedFileName); + } + + /* Open DB for read/write and authenticate to it. */ + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); + goto cleanup; + } + + PK11_SetPasswordFunc(GetModulePassword); + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + rv = EncryptFile(slot, dbdir, + inFileName, headerFileName, encryptedFileName, + noiseFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "EncryptFile : Failed\n"); + return SECFailure; + } + break; + case DECRYPT: + /* Open DB read only, authenticate to it */ + PK11_SetPasswordFunc(GetModulePassword); + + rv = NSS_Init(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_Init Failed\n"); + return SECFailure; + } + + slot = PK11_GetInternalKeySlot(); + if (PK11_NeedLogin(slot)) { + rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", + PK11_GetTokenName(slot)); + goto cleanup; + } + } + + rv = DecryptFile(slot, dbdir, + outFileName, headerFileName, + encryptedFileName, &pwdata, ascii); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "DecryptFile : Failed\n"); + return SECFailure; + } + break; + } + + cleanup: + rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); + rv = SECFailure; + } + + PR_Cleanup(); + + return rv; + } + </plstr.h></prtypes.h></prlog.h></prinit.h></prerror.h></plgetopt.h></prthread.h></opfilename></ipfilename></ipfilename></ipfilename></ipfilename></ipfilename></opfilename></ipfilename></noisefilename></dbpwdfile></dbpwd></dbdirpath></a|b></opfilename></ipfilename></dbpwdfile></dbpwd></noisefilename></dbdirpath></a|b></pk11priv.h></keyhi.h></plstr.h></prtypes.h></prlog.h></prinit.h></prerror.h></plgetopt.h></prthread.h>
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_utililies_1/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_utililies_1/index.rst new file mode 100644 index 0000000000..261b587f9f --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/nss_sample_code_utililies_1/index.rst @@ -0,0 +1,553 @@ +.. _mozilla_projects_nss_nss_sample_code_nss_sample_code_utililies_1: + +NSS Sample Code Utilities_1 +=========================== + +.. _nss_sample_code_common_utilities: + +`NSS Sample Code Common: Utilities <#nss_sample_code_common_utilities>`__ +------------------------------------------------------------------------- + +.. container:: + + This is a library of utilities used by many of the samples. This code shows the following: + + - Extract seed from noise file + - Read DER encoding from a file + - Extract the password from a text file + - Get the module password + - Print as ascii or hexadecimal + +.. _sample_code: + +`Sample Code <#sample_code>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <prlog.h> + #include <termios.h> + #include <base64.h> + #include <unistd.h> + #include <sys/stat.h> + #include <prprf.h> + #include "util.h" + + + /* + * These utility functions are adapted from those found in + * the sectool library used by the NSS security tools and + * other NSS test applications. + */ + + /* + * Newline + */ + static void Newline(PRFileDesc* out) { + PR_fprintf(out, "\n"); + } + + /* + * PrintAsAscii + */ + void PrintAsAscii(PRFileDesc* out, const unsigned char *data, unsigned int len) + { + char *b64Data = NULL; + + b64Data = BTOA_DataToAscii(data, len); + PR_fprintf(out, "%s", b64Data); + PR_fprintf(out, "\n"); + if (b64Data) { + PORT_Free(b64Data); + } + } + + /* + * PrintAsHex + */ + void PrintAsHex(PRFileDesc* out, const unsigned char *data, unsigned int len) + { + unsigned i; + int column; + unsigned int limit = 15; + unsigned int level = 1; + + column = level; + if (!len) { + PR_fprintf(out, "(empty)\n"); + return; + } + + for (i = 0; i < len; i++) { + if (i != len - 1) { + PR_fprintf(out, "%02x:", data[i]); + column += 3; + } else { + PR_fprintf(out, "%02x", data[i]); + column += 2; + break; + } + if (column > 76 || (i % 16 == limit)) { + Newline(out); + column = level; + limit = i % 16; + } + } + if (column != level) { + Newline(out); + } + } + + /* + * GetDigit + */ + int GetDigit(char c) + { + if (c == 0) { + return -1; + } + if (c <= '9' && c >= '0') { + return c - '0'; + } + if (c <= 'f' && c >= 'a') { + return c - 'a' + 0xa; + } + if (c <= 'F' && c >= 'A') { + return c - 'A' + 0xa; + } + return -1; + } + + /* + * HexToBuf + */ + int HexToBuf(unsigned char *inString, SECItem *outbuf, PRBool isHexData) + { + int len = strlen(inString); + int outLen = len+1/2; + int trueLen = 0; + int digit1, digit2; + + outbuf->data = isHexData + ? PORT_Alloc(outLen) + : PORT_Alloc(len); + if (!outbuf->data) { + return -1; + } + if (isHexData) { + while (*inString) { + if ((*inString == '\n') || (*inString == ':')) { + inString++; + continue; + } + digit1 = GetDigit(*inString++); + digit2 = GetDigit(*inString++); + if ((digit1 == -1) || (digit2 == -1)) { + PORT_Free(outbuf->data); + outbuf->data = NULL; + return -1; + } + outbuf->data[trueLen++] = digit1 << 4 | digit2; + } + } else { + while (*inString) { + if (*inString == '\n') { + inString++; + continue; + } + outbuf->data[trueLen++] = *inString++; + } + outbuf->data[trueLen] = '\0'; + trueLen = trueLen-1; + } + outbuf->len = trueLen; + return 0; + } + + /* + * FileToItem + */ + SECStatus FileToItem(SECItem *dst, PRFileDesc *src) + { + PRFileInfo info; + PRInt32 numBytes; + PRStatus prStatus; + + prStatus = PR_GetOpenFileInfo(src, &info); + + if (prStatus != PR_SUCCESS) { + return SECFailure; + } + + dst->data = 0; + if (SECITEM_AllocItem(NULL, dst, info.size)) { + numBytes = PR_Read(src, dst->data, info.size); + if (numBytes == info.size) { + return SECSuccess; + } + } + SECITEM_FreeItem(dst, PR_FALSE); + dst->data = NULL; + return SECFailure; + } + + /* + * echoOff + */ + static void echoOff(int fd) + { + if (isatty(fd)) { + struct termios tio; + tcgetattr(fd, &tio); + tio.c_lflag &= ~ECHO; + tcsetattr(fd, TCSAFLUSH, &tio); + } + } + + /* + * echoOn + */ + static void echoOn(int fd) + { + if (isatty(fd)) { + struct termios tio; + tcgetattr(fd, &tio); + tio.c_lflag |= ECHO; + tcsetattr(fd, TCSAFLUSH, &tio); + } + } + + /* + * CheckPassword + */ + PRBool CheckPassword(char *cp) + { + int len; + char *end; + len = PORT_Strlen(cp); + if (len < 8) { + return PR_FALSE; + } + end = cp + len; + while (cp < end) { + unsigned char ch = *cp++; + if (!((ch >= 'A') && (ch <= 'Z')) && + !((ch >= 'a') && (ch <= 'z'))) { + return PR_TRUE; + } + } + return PR_FALSE; + } + + /* + * GetPassword + */ + char* GetPassword(FILE *input, FILE *output, char *prompt, + PRBool (*ok)(char *)) + { + char phrase[200] = {'\0'}; + int infd = fileno(input); + int isTTY = isatty(infd); + + for (;;) { + /* Prompt for password */ + if (isTTY) { + fprintf(output, "%s", prompt); + fflush (output); + echoOff(infd); + } + fgets(phrase, sizeof(phrase), input); + if (isTTY) { + fprintf(output, "\n"); + echoOn(infd); + } + /* stomp on newline */ + phrase[PORT_Strlen(phrase)-1] = 0; + /* Validate password */ + if (!(*ok)(phrase)) { + if (!isTTY) return 0; + fprintf(output, "Password must be at least 8 characters long with one or more\n"); + fprintf(output, "non-alphabetic characters\n"); + continue; + } + return (char*) PORT_Strdup(phrase); + } + } + + /* + * FilePasswd extracts the password from a text file + * + * Storing passwords is often used with server environments + * where prompting the user for a password or requiring it + * to be entered in the command line is not a feasible option. + * + * This function supports password extraction from files with + * multiple passwords, one for each token. In the single password + * case a line would just have the password whereas in the multi- + * password variant they could be of the form + * + * token_1_name:its_password + * token_2_name:its_password + * + */ + char *FilePasswd(PK11SlotInfo *slot, PRBool retry, void *arg) + { + char* phrases, *phrase; + PRFileDesc *fd; + PRInt32 nb; + char *pwFile = arg; + int i; + const long maxPwdFileSize = 4096; + char* tokenName = NULL; + int tokenLen = 0; + + if (!pwFile) + return 0; + + if (retry) { + return 0; /* no good retrying - the file contents will be the same */ + } + + phrases = PORT_ZAlloc(maxPwdFileSize); + + if (!phrases) { + return 0; /* out of memory */ + } + + fd = PR_Open(pwFile, PR_RDONLY, 0); + if (!fd) { + fprintf(stderr, "No password file \"%s\" exists.\n", pwFile); + PORT_Free(phrases); + return NULL; + } + + nb = PR_Read(fd, phrases, maxPwdFileSize); + + PR_Close(fd); + + if (nb == 0) { + fprintf(stderr,"password file contains no data\n"); + PORT_Free(phrases); + return NULL; + } + + if (slot) { + tokenName = PK11_GetTokenName(slot); + if (tokenName) { + tokenLen = PORT_Strlen(tokenName); + } + } + i = 0; + do { + int startphrase = i; + int phraseLen; + + /* handle the Windows EOL case */ + while (phrases[i] != '\r' && phrases[i] != '\n' && i < nb) i++; + + /* terminate passphrase */ + phrases[i++] = '\0'; + /* clean up any EOL before the start of the next passphrase */ + while ( (i<nb) analyze="" char="" current="" getmodulepassword="" if="" int="" now="" passphrase="" phrase="&phrases[startphrase];" phraselen="" pk11slotinfo="" pwdata="=" pwdata-="" retry="" return="" secupwdata="" the="" void="" while="">source != PW_NONE) { + PR_fprintf(PR_STDERR, "Incorrect password/PIN entered.\n"); + return NULL; + } + + switch (pwdata->source) { + case PW_NONE: + sprintf(prompt, "Enter Password or Pin for \"%s\":", + PK11_GetTokenName(slot)); + return GetPassword(stdin, stdout, prompt, CheckPassword); + case PW_FROMFILE: + pw = FilePasswd(slot, retry, pwdata->data); + pwdata->source = PW_PLAINTEXT; + pwdata->data = PL_strdup(pw); + return pw; + case PW_PLAINTEXT: + return PL_strdup(pwdata->data); + default: + break; + } + PR_fprintf(PR_STDERR, "Password check failed: No password found.\n"); + return NULL; + } + + /* + * GenerateRandom + */ + SECStatus GenerateRandom(unsigned char *rbuf, int rsize) + { + char meter[] = { + "\r| |" }; + int fd, count; + int c; + SECStatus rv = SECSuccess; + cc_t orig_cc_min; + cc_t orig_cc_time; + tcflag_t orig_lflag; + struct termios tio; + + fprintf(stderr, "To generate random numbers, " + "continue typing until the progress meter is full:\n\n"); + fprintf(stderr, "%s", meter); + fprintf(stderr, "\r|"); + + /* turn off echo on stdin & return on 1 char instead of NL */ + fd = fileno(stdin); + + tcgetattr(fd, &tio); + orig_lflag = tio.c_lflag; + orig_cc_min = tio.c_cc[VMIN]; + orig_cc_time = tio.c_cc[VTIME]; + tio.c_lflag &= ~ECHO; + tio.c_lflag &= ~ICANON; + tio.c_cc[VMIN] = 1; + tio.c_cc[VTIME] = 0; + tcsetattr(fd, TCSAFLUSH, &tio); + /* Get random noise from keyboard strokes */ + count = 0; + while (count < rsize) { + c = getc(stdin); + if (c == EOF) { + rv = SECFailure; + break; + } + *(rbuf + count) = c; + if (count == 0 || c != *(rbuf + count -1)) { + count++; + fprintf(stderr, "*"); + } + } + rbuf[count] = '\0'; + + fprintf(stderr, "\n\nFinished. Press enter to continue: "); + while ((c = getc(stdin)) != '\n' && c != EOF) + ; + if (c == EOF) + rv = SECFailure; + fprintf(stderr, "\n"); + + /* set back termio the way it was */ + tio.c_lflag = orig_lflag; + tio.c_cc[VMIN] = orig_cc_min; + tio.c_cc[VTIME] = orig_cc_time; + tcsetattr(fd, TCSAFLUSH, &tio); + return rv; + } + + /* + * SeedFromNoiseFile + */ + SECStatus SeedFromNoiseFile(const char *noiseFileName) + { + char buf[2048]; + PRFileDesc *fd; + PRInt32 count; + + fd = PR_Open(noiseFileName, PR_RDONLY, 0); + if (!fd) { + fprintf(stderr, "failed to open noise file."); + return SECFailure; + } + + do { + count = PR_Read(fd,buf,sizeof(buf)); + if (count > 0) { + PK11_RandomUpdate(buf,count); + } + } while (count > 0); + + PR_Close(fd); + return SECSuccess; + } + + /* + * FileSize + */ + long FileSize(const char* filename) + { + struct stat stbuf; + stat(filename, &stbuf); + return stbuf.st_size; + } + + /* + * ReadDERFromFile + */ + SECStatus ReadDERFromFile(SECItem *der, const char *inFileName, PRBool ascii) + { + SECStatus rv = SECSuccess; + PRFileDesc *inFile = NULL; + + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Failed to open file \"%s\" (%ld, %ld).\n", + inFileName, PR_GetError(), PR_GetOSError()); + rv = SECFailure; + goto cleanup; + } + + if (ascii) { + /* First convert ascii to binary */ + SECItem filedata; + char *asc, *body; + + /* Read in ascii data */ + rv = FileToItem(&filedata, inFile); + asc = (char *)filedata.data; + if (!asc) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* check for headers and trailers and remove them */ + if ((body = strstr(asc, "-----BEGIN")) != NULL) { + char *trailer = NULL; + asc = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(asc, '\r'); /* maybe this is a MAC file */ + if (body) + trailer = strstr(++body, "-----END"); + if (trailer != NULL) { + *trailer = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + rv = SECFailure; + goto cleanup; + } + } else { + body = asc; + } + + /* Convert to binary */ + rv = ATOB_ConvertAsciiToItem(der, body); + if (rv) { + PR_fprintf(PR_STDERR, "error converting ascii to binary %s\n", + PORT_GetError()); + PORT_Free(filedata.data); + rv = SECFailure; + goto cleanup; + } + + PORT_Free(filedata.data); + } else { + /* Read in binary der */ + rv = FileToItem(der, inFile); + if (rv) { + PR_fprintf(PR_STDERR, "error converting der \n"); + rv = SECFailure; + } + } + cleanup: + if (inFile) { + PR_Close(inFile); + } + return rv; + } + + </nb)>
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/sample1/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/sample1/index.rst new file mode 100644 index 0000000000..ee1bb2dcf1 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/sample1/index.rst @@ -0,0 +1,230 @@ +.. _mozilla_projects_nss_nss_sample_code_sample1: + +sample1 +======= + +.. container:: + + 1. A program to compute the hash of a file and save it to another file. + + .. code:: c + + /* NSPR Headers */ + #include <prprf.h> + #include <prtypes.h> + #include <plgetopt.h> + #include <prio.h> + #include <prprf.h> + + /* NSS headers */ + #include <secoid.h> + #include <secmodt.h> + #include <sechash.h> + + typedef struct { + const char *hashName; + SECOidTag oid; + } NameTagPair; + + /* The hash algorithms supported */ + static const NameTagPair HASH_NAMES[] = { + { "MD2", SEC_OID_MD2 }, + { "MD5", SEC_OID_MD5 }, + { "SHA1", SEC_OID_SHA1 }, + { "SHA256", SEC_OID_SHA256 }, + { "SHA384", SEC_OID_SHA384 }, + { "SHA512", SEC_OID_SHA512 } + }; + + /* Maps a hash name to a SECOidTag. + * Returns NULL if the name is not a supported algorithm + */ + static SECOidTag HashNameToOIDTag(const char *hashName) + { + int i, nhashes = sizeof(HASH_NAMES); + SECOidTag hashtag = SEC_OID_UNKNOWN; + + for (i = 0; i < nhashes; i++) { + if (PORT_Strcasecmp(hashName, HASH_NAMES[i].hashName) == 0) { + hashtag = HASH_NAMES[i].oid; + break; + } + } + return hashtag; + } + + /* Newline */ + static void Newline(PRFileDesc* out) + { + PR_fprintf(out, "\n"); + } + + /* PrintAsHex */ + void PrintAsHex(PRFileDesc* out, unsigned char *data, unsigned int len) + { + unsigned i; + int column; + unsigned int limit = 15; + unsigned int level = 1; + + column = level; + if (!len) { + PR_fprintf(out, "(empty)\n"); + return; + } + + for (i = 0; i < len; i++) { + if (i != len - 1) { + PR_fprintf(out, "%02x:", data[i]); + column += 3; + } else { + PR_fprintf(out, "%02x", data[i]); + column += 2; + break; + } + if (column > 76 || (i % 16 == limit)) { + Newline(out); + column = level; + limit = i % 16; + } + } + if (column != level) { + Newline(out); + } + } + + + /* Prints a usage message and exits */ + static void Usage(const char *progName) + { + int htype; + int HASH_AlgTOTAL = sizeof(HASH_NAMES) / sizeof(HASH_NAMES[0]); + + fprintf(stderr, "Usage: %s -t type [ < input ] [ > output ]\n", progName); + fprintf(stderr, "%-20s Specify the digest method (must be one of\n", + "-t type"); + fprintf(stderr, "%-20s ", ""); + for (htype = 0; htype < HASH_AlgTOTAL; htype++) { + fprintf(stderr, HASH_NAMES[htype].hashName); + if (htype == (HASH_AlgTOTAL - 2)) + fprintf(stderr, " or "); + else if (htype != (HASH_AlgTOTAL - 1)) + fprintf(stderr, ", "); + } + fprintf(stderr, " (case ignored))\n"); + fprintf(stderr, "%-20s Define an input file to use (default is stdin)\n", + "< input"); + fprintf(stderr, "%-20s Define an output file to use (default is stdout)\n", + "> output"); + exit(-1); + } + + /* Check for the missing arguments */ + static void + PrintMsgAndExit(const char *progName, char opt) + { + fprintf(stderr, "%s: option -%c requires an argument\n", progName, opt); + Usage(progName); + } + + #define REQUIRE_ARG(opt,value) if (!(value)) PrintMsgAndExit(progName, opt) + + /* Digests a file according to the specified algorithm. + * It writes out the digest as a hexadecimal string. + */ + static int + DigestFile(PRFileDesc *outFile, PRFileDesc *inFile, SECOidTag hashOIDTag) + { + unsigned int nb; + unsigned char ibuf[4096]; + unsigned char digest[64]; + unsigned int len; + unsigned int digestLen; + HASH_HashType hashType; + HASHContext *hashContext = NULL; + + hashType = HASH_GetHashTypeByOidTag(hashOIDTag); + hashContext = HASH_Create(hashType); + if (hashContext == NULL) { + return SECFailure; + } + + do { + HASH_Begin(hashContext); + + /* Incrementally hash the file contents */ + while ((nb = PR_Read(inFile, ibuf, sizeof(ibuf))) > 0) { + HASH_Update(hashContext, ibuf, nb); + } + + HASH_End(hashContext, digest, &len, 64); + + /* Normally we would write it out in binary with + * nb = PR_Write(outFile, digest, len); + * but for illustration let's print it in hex. + */ + PrintAsHex(outFile, digest, len); + + } while (0); + + /* cleanup */ + if (hashContext != NULL) + HASH_Destroy(hashContext); + + return SECSuccess; + } + + /* + * This sample computes the hash of a file and saves it to another file. It illustrates the use of NSS message APIs. + */ + int main(int argc, char **argv) + { + SECOidTag hashOIDTag; + PLOptState *optstate; + PLOptStatus status; + SECStatus rv; + char *hashName = NULL; + char *progName = strrchr(argv[0], '/'); + + progName = progName ? progName + 1 : argv[0]; + + rv = NSS_NoDB_Init("/tmp"); + if (rv != SECSuccess) { + fprintf(stderr, "%s: NSS_Init failed in directory %s\n", progName, "/tmp"); + return -1; + } + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "t:"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 't': + REQUIRE_ARG(optstate->option, optstate->value); + hashName = strdup(optstate->value); + break; + } + } + + if (!hashName) + Usage(progName); + + /* convert and validate */ + hashOIDTag = HashNameToOIDTag(hashName); + if (hashOIDTag == SEC_OID_UNKNOWN) { + fprintf(stderr, "%s: invalid digest type - %s\n", progName, hashName); + Usage(progName); + } + + /* Digest it and print the result */ + rv = DigestFile(PR_STDOUT, PR_STDIN, hashOIDTag); + if (rv != SECSuccess) { + fprintf(stderr, "%s: problem digesting data (%d)\n", progName, PORT_GetError()); + } + + rv = NSS_Shutdown(); + if (rv != SECSuccess) { + exit(-1); + } + + return 0; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/sample1_-_hashing/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/sample1_-_hashing/index.rst new file mode 100644 index 0000000000..3fe6f2fb17 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/sample1_-_hashing/index.rst @@ -0,0 +1,257 @@ +.. _mozilla_projects_nss_nss_sample_code_sample1_-_hashing: + +Hashing - sample 1 +================== + +.. _nss_sample_code_1_hashing.: + +`NSS sample code 1: hashing. <#nss_sample_code_1_hashing.>`__ +------------------------------------------------------------- + +.. container:: + + The NSS same code below computes the hash of a file and saves it to another file, this + illustrates the use of NSS message APIs. + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + /* NSPR Headers */ + #include <prprf.h> + #include <prtypes.h> + #include <plgetopt.h> + #include <prio.h> + + /* NSS headers */ + #include <secoid.h> + #include <secmodt.h> + #include <sechash.h> + #include <nss.h> + + typedef struct { + const char *hashName; + SECOidTag oid; + } NameTagPair; + + /* The hash algorithms supported */ + static const NameTagPair HASH_NAMES[] = { + { "MD2", SEC_OID_MD2 }, + { "MD5", SEC_OID_MD5 }, + { "SHA1", SEC_OID_SHA1 }, + { "SHA256", SEC_OID_SHA256 }, + { "SHA384", SEC_OID_SHA384 }, + { "SHA512", SEC_OID_SHA512 } + }; + + /* + * Maps a hash name to a SECOidTag. + * Returns NULL if the name if not a supported algorithm + */ + static SECOidTag HashNameToOIDTag(const char *hashName) + { + int i, nhashes = sizeof(HASH_NAMES); + SECOidTag hashtag = SEC_OID_UNKNOWN; + + for (i = 0; i < nhashes; i++) { + if (PORT_Strcasecmp(hashName, HASH_NAMES[i].hashName) == 0) { + hashtag = HASH_NAMES[i].oid; + break; + } + } + return hashtag; + } + + /* + * Newline + */ + static void + Newline(PRFileDesc* out) + { + PR_fprintf(out, "\n"); + } + + /* + * PrintAsHex + */ + void + PrintAsHex(PRFileDesc* out, unsigned char *data, unsigned int len) + { + unsigned i; + int column; + unsigned int limit = 15; + unsigned int level = 1; + + column = level; + if (!len) { + PR_fprintf(out, "(empty)\n"); + return; + } + + for (i = 0; i < len; i++) { + if (i != len - 1) { + PR_fprintf(out, "%02x:", data[i]); + column += 3; + } else { + PR_fprintf(out, "%02x", data[i]); + column += 2; + break; + } + if (column > 76 || (i % 16 == limit)) { + Newline(out); + column = level; + limit = i % 16; + } + } + if (column != level) { + Newline(out); + } + } + + + /* + * Prints a usage message and exits + */ + static void + Usage(const char *progName) + { + int htype; + int HASH_AlgTOTAL = sizeof(HASH_NAMES) / sizeof(HASH_NAMES[0]); + + fprintf(stderr, "Usage: %s -t type [ < input ] [ > output ]\n", progName); + fprintf(stderr, "%-20s Specify the digest method (must be one of\n", + "-t type"); + fprintf(stderr, "%-20s ", ""); + for (htype = 0; htype < HASH_AlgTOTAL; htype++) { + fprintf(stderr, HASH_NAMES[htype].hashName); + if (htype == (HASH_AlgTOTAL - 2)) + fprintf(stderr, " or "); + else if (htype != (HASH_AlgTOTAL - 1)) + fprintf(stderr, ", "); + } + fprintf(stderr, " (case ignored))\n"); + fprintf(stderr, "%-20s Define an input file to use (default is stdin)\n", + "< input"); + fprintf(stderr, "%-20s Define an output file to use (default is stdout)\n", + "> output"); + exit(-1); + } + + /* + * Check for the missing arguments + */ + static void + PrintMsgAndExit(const char *progName, char opt) + { + fprintf(stderr, "%s: option -%c requires an argument\n", progName, opt); + Usage(progName); + } + + #define REQUIRE_ARG(opt,value) if (!(value)) PrintMsgAndExit(progName, opt) + + /* + * Digests a file according to the specified algorithm. + * It writes out the digest as a hexadecimal string. + */ + static int + DigestFile(PRFileDesc *outFile, PRFileDesc *inFile, SECOidTag hashOIDTag) + { + unsigned int nb; + unsigned char ibuf[4096]; + unsigned char digest[64]; + unsigned int len; + HASH_HashType hashType; + HASHContext *hashContext = NULL; + + hashType = HASH_GetHashTypeByOidTag(hashOIDTag); + hashContext = HASH_Create(hashType); + if (hashContext == NULL) { + return SECFailure; + } + + do { + + HASH_Begin(hashContext); + + /* Incrementally hash the file contents */ + while ((nb = PR_Read(inFile, ibuf, sizeof(ibuf))) > 0) { + HASH_Update(hashContext, ibuf, nb); + } + + HASH_End(hashContext, digest, &len, 64); + + /* Normally we would write it out in binary with + * nb = PR_Write(outFile, digest, len); + * but for illustration let's print it in hex. + */ + PrintAsHex(outFile, digest, len); + + } while (0); + + /* cleanup */ + if (hashContext != NULL) + HASH_Destroy(hashContext); + + return SECSuccess; + } + + /* + * This sample computes the hash of a file and saves it + * to another file. It illustrates the use of NSS message + * APIs. + */ + int main(int argc, char **argv) + { + SECOidTag hashOIDTag; + PLOptState *optstate; + PLOptStatus status; + SECStatus rv; + char *hashName = NULL; + char *progName = strrchr(argv[0], '/'); + + progName = progName ? progName + 1 : argv[0]; + + rv = NSS_NoDB_Init("/tmp"); + if (rv != SECSuccess) { + fprintf(stderr, "%s: NSS_Init failed in directory %s\n", + progName, "/tmp"); + return -1; + } + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "t:"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 't': + REQUIRE_ARG(optstate->option, optstate->value); + hashName = strdup(optstate->value); + break; + } + } + + if (!hashName) + Usage(progName); + + /* convert and validate */ + hashOIDTag = HashNameToOIDTag(hashName); + if (hashOIDTag == SEC_OID_UNKNOWN) { + fprintf(stderr, "%s: invalid digest type - %s\n", progName, hashName); + Usage(progName); + } + + /* Digest it and print the result */ + rv = DigestFile(PR_STDOUT, PR_STDIN, hashOIDTag); + if (rv != SECSuccess) { + fprintf(stderr, "%s: problem digesting data (%d)\n", + progName, PORT_GetError()); + } + + rv = NSS_Shutdown(); + if (rv != SECSuccess) { + exit(-1); + } + + return 0; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/sample2/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/sample2/index.rst new file mode 100644 index 0000000000..5243b05e4d --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/sample2/index.rst @@ -0,0 +1,12 @@ +.. _mozilla_projects_nss_nss_sample_code_sample2: + +sample2 +======= + +.. container:: + + .. container:: summary + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ /* NSPR Headers */ #include <prthread.h> #include <plgetopt.h> #include <prerror.h> #include <prinit.h> #include <prlog.h> #include <prtypes.h> #include <plstr.h> /* NSS headers */ #include <cryptohi.h> #include <keyhi.h> #include <pk11priv.h> #include <cert.h> #include <base64.h> #include <secerr.h> #include <secport.h> #include <secoid.h> #include <secmodt.h> #include <secoidt.h> #include <sechash.h> /* our samples utilities */ #include "util.h" /* Constants */ #define BLOCKSIZE 32 #define MODBLOCKSIZE 128 #define DEFAULT_KEY_BITS 1024 /* Header file Constants */ #define ENCKEY_HEADER "-----BEGIN WRAPPED ENCKEY-----" #define ENCKEY_TRAILER "-----END WRAPPED ENCKEY-----" #define MACKEY_HEADER "-----BEGIN WRAPPED MACKEY-----" #define MACKEY_TRAILER "-----END WRAPPED MACKEY-----" #define IV_HEADER "-----BEGIN IV-----" #define IV_TRAILER "-----END IV-----" #define MAC_HEADER "-----BEGIN MAC-----" #define MAC_TRAILER "-----END MAC-----" #define PAD_HEADER "-----BEGIN PAD-----" #define PAD_TRAILER "-----END PAD-----" #define LAB_HEADER "-----BEGIN KEY LABEL-----" #define LAB_TRAILER "-----END KEY LABEL-----" #define PUBKEY_HEADER "-----BEGIN PUB KEY -----" #define PUBKEY_TRAILER "-----END PUB KEY -----" #define NS_CERTREQ_HEADER "-----BEGIN NEW CERTIFICATE REQUEST-----" #define NS_CERTREQ_TRAILER "-----END NEW CERTIFICATE REQUEST-----" #define NS_CERT_ENC_HEADER "-----BEGIN CERTIFICATE FOR ENCRYPTION-----" #define NS_CERT_ENC_TRAILER "-----END CERTIFICATE FOR ENCRYPTION-----" #define NS_CERT_VFY_HEADER "-----BEGIN CERTIFICATE FOR SIGNATURE VERIFICATION-----" #define NS_CERT_VFY_TRAILER "-----END CERTIFICATE FOR SIGNATURE VERIFICATION-----" #define NS_SIG_HEADER "-----BEGIN SIGNATURE-----" #define NS_SIG_TRAILER "-----END SIGNATURE-----" #define NS_CERT_HEADER "-----BEGIN CERTIFICATE-----" #define NS_CERT_TRAILER "-----END CERTIFICATE-----" /* Missing publically from nss versions earlier than 3.13 */ #ifndef SEC_ERROR_BASE #define SEC_ERROR_BASE (-0x2000) typedef enum { SEC_ERROR_IO = SEC_ERROR_BASE + 0, SEC_ERROR_TOKEN_NOT_LOGGED_IN = (SEC_ERROR_BASE + 155), SEC_ERROR_END_OF_LIST } SECErrorCodes; #endif /* PORT_ErrorToString introduced in nss 3.13. On earlier versions of nss that * don't support error tables, PR_ErrorToString will return "Unknown code". */ #ifndef PORT_ErrorToString #define PORT_ErrorToString(err) PR_ErrorToString((err), PR_LANGUAGE_I_DEFAULT) #endif /* sample 6 commands */ typedef enum { GENERATE_CSR, ADD_CERT_TO_DB, SAVE_CERT_TO_HEADER, ENCRYPT, DECRYPT, SIGN, VERIFY, UNKNOWN } CommandType; typedef enum { SYMKEY = 0, MACKEY = 1, IV = 2, MAC = 3, PAD = 4, PUBKEY = 5, LAB = 6, CERTENC= 7, CERTVFY= 8, SIG = 9 } HeaderType; /* * Print usage message and exit */ static void Usage(const char *progName) { fprintf(stderr, "\nUsage: %s %s %s %s %s %s %s %s %s %s\n\n", progName, " -<g|a|h|e|ds|v> -d <dbdirpath> ", "[-p <dbpwd> | -f <dbpwdfile>] [-z <noisefilename>] [-a <\"\">]", "-s <subject> -r <csr> | ", "-n <nickname> -t <trust> -c <cert> [ -r <csr> -u <issuernickname> [-x <\"\">] -m <serialnumber> ] | ", "-n <nickname> -b <headerfilename> | ", "-b <headerfilename> -i <ipfilename> -e <encryptfilename> | ", "-b <headerfilename> -i <ipfilename> | ", "-b <headerfilename> -i <ipfilename> | ", "-b <headerfilename> -e <encryptfilename> -o <opfilename> \n"); fprintf(stderr, "commands:\n\n"); fprintf(stderr, "%s %s\n --for generating cert request (for CA also)\n\n", progName, "-G -s <subject> -r <csr>"); fprintf(stderr, "%s %s\n --to input and store cert (for CA also)\n\n", progName, "-A -n <nickname> -t <trust> -c <cert> [ -r <csr> -u <issuernickname> [-x <\"\">] -m <serialnumber> ]"); fprintf(stderr, "%s %s\n --to put cert in header\n\n", progName, "-H -n <nickname> -b <headerfilename> [-v <\"\">]"); fprintf(stderr, "%s %s\n --to find public key from cert in header and encrypt\n\n", progName, "-E -b <headerfilename> -i <ipfilename> -e <encryptfilename> "); fprintf(stderr, "%s %s\n --decrypt using corresponding private key \n\n", progName, "-D -b <headerfilename> -e <encryptfilename> -o <opfilename>"); fprintf(stderr, "%s %s\n --Sign using private key \n\n", progName, "-S -b <headerfilename> -i <infilename> "); fprintf(stderr, "%s %s\n --Verify using public key \n\n", progName, "-V -b <headerfilename> -i <ipfilename> "); fprintf(stderr, "options:\n\n"); fprintf(stderr, "%-30s - db directory path\n\n", "-d <dbdirpath>"); fprintf(stderr, "%-30s - db password [optional]\n\n", "-p <dbpwd>"); fprintf(stderr, "%-30s - db password file [optional]\n\n", "-f <dbpwdfile>"); fprintf(stderr, "%-30s - noise file name [optional]\n\n", "-z <noisefilename>"); fprintf(stderr, "%-30s - input file name\n\n", "-i <ipfilename>"); fprintf(stderr, "%-30s - header file name\n\n", "-b <headerfilename>"); fprintf(stderr, "%-30s - encrypt file name\n\n", "-e <encryptfilename>"); fprintf(stderr, "%-30s - output file name\n\n", "-o <opfilename>"); fprintf(stderr, "%-30s - certificate serial number\n\n", "-m <serialnumber>"); fprintf(stderr, "%-30s - certificate nickname\n\n", "-n <nickname>"); fprintf(stderr, "%-30s - certificate trust\n\n", "-t <trustargs>"); fprintf(stderr, "%-30s - certificate issuer nickname\n\n", "-u <issuernickname>"); fprintf(stderr, "%-30s - certificate signing request \n\n", "-r <csr>"); fprintf(stderr, "%-30s - generate a self-signed cert [optional]\n\n", "-x"); fprintf(stderr, "%-30s - to enable ascii [optional]\n\n", "-a"); fprintf(stderr, "%-30s - to save certificate to header file as sig verification [optional]\n\n", "-v"); exit(-1); } /* * Validate the options used for Generate CSR command */ static void ValidateGenerateCSRCommand(const char *progName, const char *dbdir, CERTName *subject, const char *subjectStr, const char *certReqFileName) { PRBool validationFailed = PR_FALSE; if (!subject) { PR_fprintf(PR_STDERR, "%s -G -d %s -s: improperly formatted name: \"%s\"\n", progName, dbdir, subjectStr); validationFailed = PR_TRUE; } if (!certReqFileName) { PR_fprintf(PR_STDERR, "%s -G -d %s -s %s -r: certificate request file name not found\n", progName, dbdir, subjectStr); validationFailed = PR_TRUE; } if (validationFailed) { fprintf(stderr, "\nUsage: %s %s \n\n", progName, "-G -d <dbdirpath> -s <subject> -r <csr> \n"); exit(-1); } } /* * Validate the options used for Add Cert to DB command */ static void ValidateAddCertToDBCommand(const char *progName, const char *dbdir, const char *nickNameStr, const char *trustStr, const char *certFileName, const char *certReqFileName, const char *issuerNameStr, const char *serialNumberStr, PRBool selfsign) { PRBool validationFailed = PR_FALSE; if (!nickNameStr) { PR_fprintf(PR_STDERR, "%s -A -d %s -n : nick name is missing\n", progName, dbdir); validationFailed = PR_TRUE; } if (!trustStr) { PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t: trust flag is missing\n", progName, dbdir, nickNameStr); validationFailed = PR_TRUE; } if (!certFileName) { PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c: certificate file name not found\n", progName, dbdir, nickNameStr, trustStr, serialNumberStr, certReqFileName); validationFailed = PR_TRUE; } if (PR_Access(certFileName, PR_ACCESS_EXISTS) == PR_FAILURE) { if (!certReqFileName) { PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c %s -r: certificate file or certificate request file is not found\n", progName, dbdir, nickNameStr, trustStr, certFileName); validationFailed = PR_TRUE; } if (!selfsign && !issuerNameStr) { PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c %s -r %s -u : issuer name is missing\n", progName, dbdir, nickNameStr, trustStr, certFileName, certReqFileName); validationFailed = PR_TRUE; } if (!serialNumberStr) { PR_fprintf(PR_STDERR, "%s -A -d %s -n %s -t %s -c %s -r %s -u %s -m : serial number is missing\n", progName, dbdir, nickNameStr, trustStr, certFileName, certReqFileName, issuerNameStr); validationFailed = PR_TRUE; } } if (validationFailed) { fprintf(stderr, "\nUsage: %s %s \n\n", progName, " -A -d <dbdirpath> -n <nickname> -t <trust> -c <cert> \n"); fprintf(stderr, " OR\n"); fprintf(stderr, "\nUsage: %s %s \n\n", progName, "-A -d <dbdirpath> -n <nickname> -t <trust> -c <cert> -r <csr> -u <issuernickname> -m <serialnumber> [-x <\"\">] \n"); exit(-1); } } /* * Validate the options used for Save Cert To Header command */ static void ValidateSaveCertToHeaderCommand(const char *progName, const char *dbdir, const char *nickNameStr, const char *headerFileName) { PRBool validationFailed = PR_FALSE; if (!nickNameStr) { PR_fprintf(PR_STDERR, "%s -S -d %s -n : nick name is missing\n", progName, dbdir); validationFailed = PR_TRUE; } if (!headerFileName) { PR_fprintf(PR_STDERR, "%s -S -d %s -n %s -b : header file name is not found\n", progName, dbdir, nickNameStr); validationFailed = PR_TRUE; } if (validationFailed) { fprintf(stderr, "\nUsage: %s %s \n\n", progName, "-S -d <dbdirpath> -n <nickname> -b <headerfilename> [-v <\"\">]\n"); exit(-1); } } /* * Validate the options used for Encrypt command */ static void ValidateEncryptCommand(const char *progName, const char *dbdir, const char *nickNameStr, const char *headerFileName, const char *inFileName, const char *encryptedFileName) { PRBool validationFailed = PR_FALSE; if (!nickNameStr) { PR_fprintf(PR_STDERR, "%s -E -d %s -n : nick name is missing\n", progName, dbdir); validationFailed = PR_TRUE; } if (!headerFileName) { PR_fprintf(PR_STDERR, "%s -E -d %s -n %s -b : header file name is not found\n", progName, dbdir, nickNameStr); validationFailed = PR_TRUE; } if (!inFileName) { PR_fprintf(PR_STDERR, "%s -E -d %s -n %s -b %s -i : input file name is not found\n", progName, dbdir, nickNameStr, headerFileName); validationFailed = PR_TRUE; } if (!encryptedFileName) { PR_fprintf(PR_STDERR, "%s -E -d %s -n %s -b %s -i %s -e : encrypt file name is not found\n", progName, dbdir, nickNameStr, headerFileName, inFileName); validationFailed = PR_TRUE; } if (validationFailed) { fprintf(stderr, "\nUsage: %s %s \n\n", progName, "-E -d <dbdirpath> -b <headerfilename> -i <ipfilename> -e <encryptfilename> -n <nickname> \n"); exit(-1); } } /* * Validate the options used for Sign command */ static void ValidateSignCommand(const char *progName, const char *dbdir, const char *nickNameStr, const char *headerFileName, const char *inFileName) { PRBool validationFailed = PR_FALSE; if (!nickNameStr) { PR_fprintf(PR_STDERR, "%s -I -d %s -n : nick name is missing\n", progName, dbdir); validationFailed = PR_TRUE; } if (!headerFileName) { PR_fprintf(PR_STDERR, "%s -I -d %s -n %s -b : header file name is not found\n", progName, dbdir, nickNameStr); validationFailed = PR_TRUE; } if (!inFileName) { PR_fprintf(PR_STDERR, "%s -I -d %s -n %s -b %s -i : input file name is not found\n", progName, dbdir, nickNameStr, headerFileName); validationFailed = PR_TRUE; } if (validationFailed) { fprintf(stderr, "\nUsage: %s %s \n\n", progName, "-I -d <dbdirpath> -b <headerfilename> -i <ipfilename> -n <nickname> \n"); exit(-1); } } /* * Validate the options used for verify command */ static void ValidateVerifyCommand(const char *progName, const char *dbdir, const char *headerFileName, const char *inFileName) { PRBool validationFailed = PR_FALSE; if (!headerFileName) { PR_fprintf(PR_STDERR, "%s -V -d %s -b : header file name is not found\n", progName, dbdir); validationFailed = PR_TRUE; } if (!inFileName) { PR_fprintf(PR_STDERR, "%s -I -d %s -b %s -i : input file name is not found\n", progName, dbdir, headerFileName); validationFailed = PR_TRUE; } if (validationFailed) { fprintf(stderr, "\nUsage: %s %s \n\n", progName, "-I -d <dbdirpath> -b <headerfilename> -i <ipfilename> \n"); exit(-1); } } /* * Validate the options used for Decrypt command */ static void ValidateDecryptCommand(const char *progName, const char *dbdir, const char *headerFileName, const char *encryptedFileName, const char *outFileName) { PRBool validationFailed = PR_FALSE; if (!headerFileName) { PR_fprintf(PR_STDERR, "%s -D -d %s -b : header file name is not found\n", progName, dbdir); validationFailed = PR_TRUE; } if (!encryptedFileName) { PR_fprintf(PR_STDERR, "%s -D -d %s -b %s -e : encrypt file name is not found\n", progName, dbdir, headerFileName); validationFailed = PR_TRUE; } if (!outFileName) { PR_fprintf(PR_STDERR, "%s -D -d %s -b %s -e %s -o : output file name is not found\n", progName, dbdir, headerFileName, encryptedFileName); validationFailed = PR_TRUE; } if (validationFailed) { fprintf(stderr, "\nUsage: %s %s \n\n", progName, "-D -d <dbdirpath> -b <headerfilename> -e <encryptfilename> -o <opfilename>\n"); exit(-1); } } /* * Sign the contents of input file using private key and * return result as SECItem */ SECStatus SignData(const char *inFileName, SECKEYPrivateKey *pk, SECItem *res) { SECStatus rv = SECFailure; unsigned int nb; unsigned char ibuf[4096]; PRFileDesc *inFile = NULL; SGNContext *sgn = NULL; /* Open the input file for reading */ inFile = PR_Open(inFileName, PR_RDONLY, 0); if (!inFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", inFileName); rv = SECFailure; goto cleanup; } /* Sign using private key */ sgn = SGN_NewContext(SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION, pk); if (!sgn) { PR_fprintf(PR_STDERR, "unable to create context for signing\n"); rv = SECFailure; goto cleanup; } rv = SGN_Begin(sgn); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "problem while SGN_Begin\n"); goto cleanup; } while ((nb = PR_Read(inFile, ibuf, sizeof(ibuf))) > 0) { rv = SGN_Update(sgn, ibuf, nb); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "problem while SGN_Update\n"); goto cleanup; } } rv = SGN_End(sgn, res); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "problem while SGN_End\n"); goto cleanup; } cleanup: if (inFile) { PR_Close(inFile); } if (sgn) { SGN_DestroyContext(sgn, PR_TRUE); } return rv; } /* * Verify the signature using public key */ SECStatus VerifyData(const char *inFileName, SECKEYPublicKey *pk, SECItem *sigItem, secuPWData *pwdata) { unsigned int nb; unsigned char ibuf[4096]; SECStatus rv = SECFailure; VFYContext *vfy = NULL; PRFileDesc *inFile = NULL; /* Open the input file for reading */ inFile = PR_Open(inFileName, PR_RDONLY, 0); if (!inFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", inFileName); rv = SECFailure; goto cleanup; } vfy = VFY_CreateContext(pk, sigItem, SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION, pwdata); if (!vfy) { PR_fprintf(PR_STDERR, "unable to create context for verifying signature\n"); rv = SECFailure; goto cleanup; } rv = VFY_Begin(vfy); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "problem while VFY_Begin\n"); goto cleanup; } while ((nb = PR_Read(inFile, ibuf, sizeof(ibuf))) > 0) { rv = VFY_Update(vfy, ibuf, nb); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "problem while VFY_Update\n"); goto cleanup; } } rv = VFY_End(vfy); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "problem while VFY_End\n"); goto cleanup; } cleanup: if (inFile) { PR_Close(inFile); } if (vfy) { VFY_DestroyContext(vfy, PR_TRUE); } return rv; } /* * Write Cryptographic parameters to header file */ SECStatus WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, PRFileDesc *outFile) { SECStatus rv; const char *header; const char *trailer; switch (type) { case SYMKEY: header = ENCKEY_HEADER; trailer = ENCKEY_TRAILER; break; case MACKEY: header = MACKEY_HEADER; trailer = MACKEY_TRAILER; break; case IV: header = IV_HEADER; trailer = IV_TRAILER; break; case MAC: header = MAC_HEADER; trailer = MAC_TRAILER; break; case PAD: header = PAD_HEADER; trailer = PAD_TRAILER; break; case PUBKEY: header = PUBKEY_HEADER; trailer = PUBKEY_TRAILER; break; case CERTENC: header = NS_CERT_ENC_HEADER; trailer = NS_CERT_ENC_TRAILER; break; case CERTVFY: header = NS_CERT_VFY_HEADER; trailer = NS_CERT_VFY_TRAILER; break; case SIG: header = NS_SIG_HEADER; trailer = NS_SIG_TRAILER; break; case LAB: header = LAB_HEADER; trailer = LAB_TRAILER; PR_fprintf(outFile, "%s\n", header); PR_fprintf(outFile, "%s\n", buf); PR_fprintf(outFile, "%s\n\n", trailer); return SECSuccess; break; default: return SECFailure; } PR_fprintf(outFile, "%s\n", header); PrintAsHex(outFile, buf, len); PR_fprintf(outFile, "%s\n\n", trailer); return SECSuccess; } /* * Read cryptographic parameters from the header file */ SECStatus ReadFromHeaderFile(const char *fileName, HeaderType type, SECItem *item, PRBool isHexData) { SECStatus rv = SECSuccess; PRFileDesc* file = NULL; SECItem filedata; SECItem outbuf; unsigned char *nonbody; unsigned char *body; char *header; char *trailer; outbuf.type = siBuffer; file = PR_Open(fileName, PR_RDONLY, 0); if (!file) { PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); rv = SECFailure; goto cleanup; } switch (type) { case PUBKEY: header = PUBKEY_HEADER; trailer = PUBKEY_TRAILER; break; case SYMKEY: header = ENCKEY_HEADER; trailer = ENCKEY_TRAILER; break; case MACKEY: header = MACKEY_HEADER; trailer = MACKEY_TRAILER; break; case IV: header = IV_HEADER; trailer = IV_TRAILER; break; case MAC: header = MAC_HEADER; trailer = MAC_TRAILER; break; case PAD: header = PAD_HEADER; trailer = PAD_TRAILER; break; case LAB: header = LAB_HEADER; trailer = LAB_TRAILER; break; case CERTENC: header = NS_CERT_ENC_HEADER; trailer = NS_CERT_ENC_TRAILER; break; case CERTVFY: header = NS_CERT_VFY_HEADER; trailer = NS_CERT_VFY_TRAILER; break; case SIG: header = NS_SIG_HEADER; trailer = NS_SIG_TRAILER; break; default: rv = SECFailure; goto cleanup; } rv = FileToItem(&filedata, file); nonbody = (char *)filedata.data; if (!nonbody) { PR_fprintf(PR_STDERR, "unable to read data from input file\n"); rv = SECFailure; goto cleanup; } /* check for headers and trailers and remove them */ if ((body = strstr(nonbody, header)) != NULL) { char *trail = NULL; nonbody = body; body = PORT_Strchr(body, '\n'); if (!body) body = PORT_Strchr(nonbody, '\r'); /* maybe this is a MAC file */ if (body) trail = strstr(++body, trailer); if (trail != NULL) { *trail = '\0'; } else { PR_fprintf(PR_STDERR, "input has header but no trailer\n"); PORT_Free(filedata.data); rv = SECFailure; goto cleanup; } } else { /* headers didn't exist */ char *trail = NULL; body = nonbody; if (body) { trail = strstr(++body, trailer); if (trail != NULL) { PR_fprintf(PR_STDERR, "input has no header but has trailer\n"); PORT_Free(filedata.data); rv = SECFailure; goto cleanup; } } } HexToBuf(body, item, isHexData); cleanup: if (file) { PR_Close(file); } return rv; } /* * Generate the private key */ SECKEYPrivateKey * GeneratePrivateKey(KeyType keytype, PK11SlotInfo *slot, int size, int publicExponent, const char *noise, SECKEYPublicKey **pubkeyp, const char *pqgFile, secuPWData *pwdata) { CK_MECHANISM_TYPE mechanism; SECOidTag algtag; PK11RSAGenParams rsaparams; void *params; SECKEYPrivateKey *privKey = NULL; SECStatus rv; unsigned char randbuf[BLOCKSIZE + 1]; rv = GenerateRandom(randbuf, BLOCKSIZE); if (rv != SECSuccess) { fprintf(stderr, "Error while generating the random numbers : %s\n", PORT_ErrorToString(rv)); goto cleanup; } PK11_RandomUpdate(randbuf, BLOCKSIZE); switch (keytype) { case rsaKey: rsaparams.keySizeInBits = size; rsaparams.pe = publicExponent; mechanism = CKM_RSA_PKCS_KEY_PAIR_GEN; algtag = SEC_OID_PKCS1_MD5_WITH_RSA_ENCRYPTION; params = &rsaparams; break; default: goto cleanup; } fprintf(stderr, "\n\n"); fprintf(stderr, "Generating key. This may take a few moments...\n\n"); privKey = PK11_GenerateKeyPair(slot, mechanism, params, pubkeyp, PR_TRUE /*isPerm*/, PR_TRUE /*isSensitive*/, pwdata); cleanup: return privKey; } /* * Get the certificate request from CSR */ static CERTCertificateRequest * GetCertRequest(char *inFileName, PRBool ascii) { CERTSignedData signedData; SECItem reqDER; CERTCertificateRequest *certReq = NULL; SECStatus rv = SECSuccess; PRArenaPool *arena = NULL; reqDER.data = NULL; arena = PORT_NewArena(DER_DEFAULT_CHUNKSIZE); if (arena == NULL) { rv = SECFailure; goto cleanup; } rv = ReadDERFromFile(&reqDER, inFileName, ascii); if (rv) { rv = SECFailure; goto cleanup; } certReq = (CERTCertificateRequest*) PORT_ArenaZAlloc (arena, sizeof(CERTCertificateRequest)); if (!certReq) { rv = SECFailure; goto cleanup; } certReq->arena = arena; /* Since cert request is a signed data, must decode to get the inner data */ PORT_Memset(&signedData, 0, sizeof(signedData)); rv = SEC_ASN1DecodeItem(arena, &signedData, SEC_ASN1_GET(CERT_SignedDataTemplate), &reqDER); if (rv) { rv = SECFailure; goto cleanup; } rv = SEC_ASN1DecodeItem(arena, certReq, SEC_ASN1_GET(CERT_CertificateRequestTemplate), &signedData.data); if (rv) { rv = SECFailure; goto cleanup; } rv = CERT_VerifySignedDataWithPublicKeyInfo(&signedData, &certReq->subjectPublicKeyInfo, NULL /* wincx */); if (reqDER.data) { SECITEM_FreeItem(&reqDER, PR_FALSE); } cleanup: if (rv) { PR_fprintf(PR_STDERR, "bad certificate request\n"); if (arena) { PORT_FreeArena(arena, PR_FALSE); } certReq = NULL; } return certReq; } /* * Sign Cert */ static SECItem * SignCert(CERTCertDBHandle *handle, CERTCertificate *cert, PRBool selfsign, SECOidTag hashAlgTag, SECKEYPrivateKey *privKey, char *issuerNickName, void *pwarg) { SECItem der; SECStatus rv; SECOidTag algID; void *dummy; PRArenaPool *arena = NULL; SECItem *result = NULL; SECKEYPrivateKey *caPrivateKey = NULL; if (!selfsign) { CERTCertificate *issuer = PK11_FindCertFromNickname(issuerNickName, pwarg); if ((CERTCertificate *)NULL == issuer) { PR_fprintf(PR_STDERR, "unable to find issuer with nickname %s\n", issuerNickName); goto cleanup; } privKey = caPrivateKey = PK11_FindKeyByAnyCert(issuer, pwarg); CERT_DestroyCertificate(issuer); if (caPrivateKey == NULL) { PR_fprintf(PR_STDERR, "unable to retrieve key %s\n", issuerNickName); goto cleanup; } } arena = cert->arena; algID = SEC_GetSignatureAlgorithmOidTag(privKey->keyType, hashAlgTag); if (algID == SEC_OID_UNKNOWN) { PR_fprintf(PR_STDERR, "Unknown key or hash type for issuer.\n"); goto cleanup; } rv = SECOID_SetAlgorithmID(arena, &cert->signature, algID, 0); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not set signature algorithm id.\n%s\n", PORT_ErrorToString(rv)); goto cleanup; } /* we only deal with cert v3 here */ *(cert->version.data) = 2; cert->version.len = 1; der.len = 0; der.data = NULL; dummy = SEC_ASN1EncodeItem (arena, &der, cert, SEC_ASN1_GET(CERT_CertificateTemplate)); if (!dummy) { PR_fprintf(PR_STDERR, "Could not encode certificate.\n"); goto cleanup; } result = (SECItem *) PORT_ArenaZAlloc (arena, sizeof (SECItem)); if (result == NULL) { PR_fprintf(PR_STDERR, "Could not allocate item for certificate data.\n"); goto cleanup; } rv = SEC_DerSignData(arena, result, der.data, der.len, privKey, algID); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not sign encoded certificate data : %s\n", PORT_ErrorToString(rv)); /* result allocated out of the arena, it will be freed * when the arena is freed */ result = NULL; goto cleanup; } cert->derCert = *result; cleanup: if (caPrivateKey) { SECKEY_DestroyPrivateKey(caPrivateKey); } return result; } /* * MakeV1Cert */ static CERTCertificate * MakeV1Cert(CERTCertDBHandle *handle, CERTCertificateRequest *req, char * issuerNickName, PRBool selfsign, unsigned int serialNumber, int warpmonths, int validityMonths) { PRExplodedTime printableTime; PRTime now; PRTime after; CERTValidity *validity = NULL; CERTCertificate *issuerCert = NULL; CERTCertificate *cert = NULL; if ( !selfsign ) { issuerCert = CERT_FindCertByNicknameOrEmailAddr(handle, issuerNickName); if (!issuerCert) { PR_fprintf(PR_STDERR, "could not find certificate named %s\n", issuerNickName); goto cleanup; } } now = PR_Now(); PR_ExplodeTime (now, PR_GMTParameters, &printableTime); if ( warpmonths ) { printableTime.tm_month += warpmonths; now = PR_ImplodeTime (&printableTime); PR_ExplodeTime (now, PR_GMTParameters, &printableTime); } printableTime.tm_month += validityMonths; after = PR_ImplodeTime (&printableTime); /* note that the time is now in micro-second unit */ validity = CERT_CreateValidity (now, after); if (validity) { cert = CERT_CreateCertificate(serialNumber, (selfsign ? &req->subject : &issuerCert->subject), validity, req); CERT_DestroyValidity(validity); } cleanup: if ( issuerCert ) { CERT_DestroyCertificate (issuerCert); } return cert; } /* * Add a certificate to the nss database */ SECStatus AddCert(PK11SlotInfo *slot, CERTCertDBHandle *handle, const char *name, char *trusts, char *inFileName, PRBool ascii, PRBool emailcert, void *pwdata) { SECItem certDER; SECStatus rv; CERTCertTrust *trust = NULL; CERTCertificate *cert = NULL; certDER.data = NULL; /* Read in the entire file specified with the -i argument */ rv = ReadDERFromFile(&certDER, inFileName, ascii); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "unable to read input file %s : %s\n", inFileName, PORT_ErrorToString(rv)); goto cleanup; } /* Read in an ASCII cert and return a CERTCertificate */ cert = CERT_DecodeCertFromPackage((char *)certDER.data, certDER.len); if (!cert) { PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); rv = SECFailure; goto cleanup; } /* Create a cert trust */ trust = (CERTCertTrust *)PORT_ZAlloc(sizeof(CERTCertTrust)); if (!trust) { PR_fprintf(PR_STDERR, "unable to allocate cert trust\n"); rv = SECFailure; goto cleanup; } rv = CERT_DecodeTrustString(trust, trusts); if (rv) { PR_fprintf(PR_STDERR, "unable to decode trust string\n"); rv = SECFailure; goto cleanup; } rv = PK11_ImportCert(slot, cert, CK_INVALID_HANDLE, name, PR_FALSE); if (rv != SECSuccess) { /* sigh, PK11_Import Cert and CERT_ChangeCertTrust should have * been coded to take a password arg. */ if (PORT_GetError() == SEC_ERROR_TOKEN_NOT_LOGGED_IN) { rv = PK11_Authenticate(slot, PR_TRUE, pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "could not authenticate to token %s : %s\n", PK11_GetTokenName(slot), PORT_ErrorToString(rv)); rv = SECFailure; goto cleanup; } rv = PK11_ImportCert(slot, cert, CK_INVALID_HANDLE, name, PR_FALSE); } if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "could not add certificate to token or database : %s\n", PORT_ErrorToString(rv)); rv = SECFailure; goto cleanup; } } rv = CERT_ChangeCertTrust(handle, cert, trust); if (rv != SECSuccess) { if (PORT_GetError() == SEC_ERROR_TOKEN_NOT_LOGGED_IN) { rv = PK11_Authenticate(slot, PR_TRUE, pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "could not authenticate to token %s : %s\n", PK11_GetTokenName(slot), PORT_ErrorToString(rv)); rv = SECFailure; goto cleanup; } rv = CERT_ChangeCertTrust(handle, cert, trust); } if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "could not change trust on certificate : %s\n", PORT_ErrorToString(rv)); rv = SECFailure; goto cleanup; } } if (emailcert) { CERT_SaveSMimeProfile(cert, NULL, pwdata); } cleanup: if (cert) { CERT_DestroyCertificate (cert); } if (trust) { PORT_Free(trust); } if (certDER.data) { PORT_Free(certDER.data); } return rv; } /* * Create a certificate */ static SECStatus CreateCert( CERTCertDBHandle *handle, PK11SlotInfo *slot, char * issuerNickName, char *inFileName, char *outFileName, SECKEYPrivateKey **selfsignprivkey, void *pwarg, SECOidTag hashAlgTag, unsigned int serialNumber, int warpmonths, int validityMonths, const char *dnsNames, PRBool ascii, PRBool selfsign) { void *extHandle; SECItem reqDER; CERTCertExtension **CRexts; SECStatus rv = SECSuccess; CERTCertificate *subjectCert = NULL; CERTCertificateRequest *certReq = NULL; PRFileDesc *outFile = NULL; SECItem *certDER = NULL; reqDER.data = NULL; outFile = PR_Open(outFileName, PR_RDWR | PR_CREATE_FILE | PR_TRUNCATE, 00660); /* Create a cert request object from the input cert request der */ certReq = GetCertRequest(inFileName, ascii); if (certReq == NULL) { rv = SECFailure; goto cleanup; } subjectCert = MakeV1Cert(handle, certReq, issuerNickName, selfsign, serialNumber, warpmonths, validityMonths); if (subjectCert == NULL) { rv = SECFailure; goto cleanup; } extHandle = CERT_StartCertExtensions (subjectCert); if (extHandle == NULL) { rv = SECFailure; goto cleanup; } if (certReq->attributes != NULL && certReq->attributes[0] != NULL && certReq->attributes[0]->attrType.data != NULL && certReq->attributes[0]->attrType.len > 0 && SECOID_FindOIDTag(&certReq->attributes[0]->attrType) == SEC_OID_PKCS9_EXTENSION_REQUEST) { rv = CERT_GetCertificateRequestExtensions(certReq, &CRexts); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "%s\n", PORT_ErrorToString(rv)); goto cleanup; } rv = CERT_MergeExtensions(extHandle, CRexts); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "%s\n", PORT_ErrorToString(rv)); goto cleanup; } } CERT_FinishExtensions(extHandle); /* self-signing a cert request, find the private key */ if (*selfsignprivkey == NULL) { *selfsignprivkey = PK11_FindKeyByDERCert(slot, subjectCert, pwarg); if (!*selfsignprivkey) { PR_fprintf(PR_STDERR, "Failed to locate private key.\n"); rv = SECFailure; goto cleanup; } } certDER = SignCert(handle, subjectCert, selfsign, hashAlgTag, *selfsignprivkey, issuerNickName,pwarg); if (certDER) { if (ascii) { PR_fprintf(outFile, "%s\n%s\n%s\n", NS_CERT_HEADER, BTOA_DataToAscii(certDER->data, certDER->len), NS_CERT_TRAILER); } else { PR_Write(outFile, certDER->data, certDER->len); } } if (rv != SECSuccess) { PRErrorCode perr = PR_GetError(); PR_fprintf(PR_STDERR, "unable to create cert %s\n", perr); } cleanup: if (outFile) { PR_Close(outFile); } if (*selfsignprivkey) { SECKEY_DestroyPrivateKey(*selfsignprivkey); } if (certReq) { CERT_DestroyCertificateRequest(certReq); } if (subjectCert) { CERT_DestroyCertificate(subjectCert); } return rv; } /* * Generate the certificate request with subject */ static SECStatus CertReq(SECKEYPrivateKey *privk, SECKEYPublicKey *pubk, KeyType keyType, SECOidTag hashAlgTag, CERTName *subject, PRBool ascii, const char *certReqFileName) { SECOidTag signAlgTag; SECItem result; PRInt32 numBytes; SECStatus rv = SECSuccess; PRArenaPool *arena = NULL; void *extHandle = NULL; PRFileDesc *outFile = NULL; CERTSubjectPublicKeyInfo *spki = NULL; CERTCertificateRequest *cr = NULL; SECItem *encoding = NULL; /* If the certificate request file already exists, delete it */ if (PR_Access(certReqFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { PR_Delete(certReqFileName); } /* Open the certificate request file to write */ outFile = PR_Open(certReqFileName, PR_CREATE_FILE | PR_RDWR | PR_TRUNCATE, 00660); if (!outFile) { PR_fprintf(PR_STDERR, "unable to open \"%s\" for writing (%ld, %ld).\n", certReqFileName, PR_GetError(), PR_GetOSError()); goto cleanup; } /* Create info about public key */ spki = SECKEY_CreateSubjectPublicKeyInfo(pubk); if (!spki) { PR_fprintf(PR_STDERR, "unable to create subject public key\n"); rv = SECFailure; goto cleanup; } /* Generate certificate request */ cr = CERT_CreateCertificateRequest(subject, spki, NULL); if (!cr) { PR_fprintf(PR_STDERR, "unable to make certificate request\n"); rv = SECFailure; goto cleanup; } arena = PORT_NewArena(DER_DEFAULT_CHUNKSIZE); if (!arena) { fprintf(stderr, "out of memory"); rv = SECFailure; goto cleanup; } extHandle = CERT_StartCertificateRequestAttributes(cr); if (extHandle == NULL) { PORT_FreeArena (arena, PR_FALSE); rv = SECFailure; goto cleanup; } CERT_FinishExtensions(extHandle); CERT_FinishCertificateRequestAttributes(cr); /* Der encode the request */ encoding = SEC_ASN1EncodeItem(arena, NULL, cr, SEC_ASN1_GET(CERT_CertificateRequestTemplate)); if (encoding == NULL) { PR_fprintf(PR_STDERR, "der encoding of request failed\n"); rv = SECFailure; goto cleanup; } /* Sign the request */ signAlgTag = SEC_GetSignatureAlgorithmOidTag(keyType, hashAlgTag); if (signAlgTag == SEC_OID_UNKNOWN) { PR_fprintf(PR_STDERR, "unknown Key or Hash type\n"); rv = SECFailure; goto cleanup; } rv = SEC_DerSignData(arena, &result, encoding->data, encoding->len, privk, signAlgTag); if (rv) { PR_fprintf(PR_STDERR, "signing of data failed\n"); rv = SECFailure; goto cleanup; } /* Encode request in specified format */ if (ascii) { char *obuf; char *name, *email, *org, *state, *country; SECItem *it; int total; it = &result; obuf = BTOA_ConvertItemToAscii(it); total = PL_strlen(obuf); name = CERT_GetCommonName(subject); if (!name) { name = strdup("(not specified)"); } email = CERT_GetCertEmailAddress(subject); if (!email) email = strdup("(not specified)"); org = CERT_GetOrgName(subject); if (!org) org = strdup("(not specified)"); state = CERT_GetStateName(subject); if (!state) state = strdup("(not specified)"); country = CERT_GetCountryName(subject); if (!country) country = strdup("(not specified)"); PR_fprintf(outFile, "\nCertificate request generated by Netscape certutil\n"); PR_fprintf(outFile, "Common Name: %s\n", name); PR_fprintf(outFile, "Email: %s\n", email); PR_fprintf(outFile, "Organization: %s\n", org); PR_fprintf(outFile, "State: %s\n", state); PR_fprintf(outFile, "Country: %s\n\n", country); PR_fprintf(outFile, "%s\n", NS_CERTREQ_HEADER); numBytes = PR_Write(outFile, obuf, total); if (numBytes != total) { PR_fprintf(PR_STDERR, "write error\n"); return SECFailure; } PR_fprintf(outFile, "\n%s\n", NS_CERTREQ_TRAILER); } else { numBytes = PR_Write(outFile, result.data, result.len); if (numBytes != (int)result.len) { PR_fprintf(PR_STDERR, "write error\n"); rv = SECFailure; goto cleanup; } } cleanup: if (outFile) { PR_Close(outFile); } if (privk) { SECKEY_DestroyPrivateKey(privk); } if (pubk) { SECKEY_DestroyPublicKey(pubk); } return rv; } /* * Create certificate request with subject */ SECStatus CreateCertRequest(PK11SlotInfo *slot, secuPWData *pwdata, CERTName *subject, char *certReqFileName, PRBool ascii) { SECStatus rv; SECKEYPrivateKey *privkey = NULL; SECKEYPublicKey *pubkey = NULL; KeyType keytype = rsaKey; int keysize = DEFAULT_KEY_BITS; int publicExponent = 0x010001; SECOidTag hashAlgTag = SEC_OID_UNKNOWN; privkey = GeneratePrivateKey(keytype, slot, keysize, publicExponent, NULL, &pubkey, NULL, pwdata); if (privkey == NULL) { PR_fprintf(PR_STDERR, "unable to generate key(s)\n"); rv = SECFailure; goto cleanup; } privkey->wincx = pwdata; PORT_Assert(pubkey != NULL); rv = CertReq(privkey, pubkey, keytype, hashAlgTag, subject, ascii, certReqFileName); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Failed to create Certificate Request\n"); } cleanup: return rv; } /* * Creates the certificate using CSR and adds the certificate to DB */ SECStatus AddCertificateToDB(PK11SlotInfo *slot, secuPWData *pwdata, char *certReqFileName, char *certFileName, char *issuerNameStr, CERTCertDBHandle *certHandle, const char *nickNameStr, char *trustStr, unsigned int serialNumber, PRBool selfsign, PRBool ascii) { SECStatus rv; SECKEYPrivateKey *privkey = NULL; SECKEYPublicKey *pubkey = NULL; SECOidTag hashAlgTag = SEC_OID_UNKNOWN; if (PR_Access(certFileName, PR_ACCESS_EXISTS) == PR_FAILURE) { rv = CreateCert(certHandle, slot, issuerNameStr, certReqFileName, certFileName, &privkey, &pwdata, hashAlgTag, serialNumber, 0, 3, NULL, ascii, selfsign); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Failed to create Certificate\n"); goto cleanup; } } rv = AddCert(slot, certHandle, nickNameStr, trustStr, certFileName, ascii, 0, &pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Failed to add Certificate\n"); } cleanup: return rv; } /* * Finds the certificate using nickname and saves it to the header file */ SECStatus AddCertificateToHeader(PK11SlotInfo *slot, secuPWData *pwdata, const char *headerFileName, CERTCertDBHandle *certHandle, const char *nickNameStr, PRBool sigVerify) { SECStatus rv = SECSuccess; PRFileDesc *headerFile = NULL; CERTCertificate *cert = NULL; HeaderType hType = CERTENC; /* If the intermediate header file already exists, delete it */ if (PR_Access(headerFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { PR_Delete(headerFileName); } headerFile = PR_Open(headerFileName, PR_CREATE_FILE | PR_RDWR | PR_TRUNCATE, 00660); if (!headerFile) { PR_fprintf(PR_STDERR, "unable to open \"%s\" for writing (%ld, %ld).\n", headerFileName, PR_GetError(), PR_GetOSError()); rv = SECFailure; goto cleanup; } cert = CERT_FindCertByNicknameOrEmailAddr(certHandle, nickNameStr); if (!cert) { PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); rv = SECFailure; goto cleanup; } if (sigVerify) { hType = CERTVFY; } WriteToHeaderFile(cert->derCert.data, cert->derCert.len, hType, headerFile); cleanup: if (headerFile) { PR_Close(headerFile); } if (cert) { CERT_DestroyCertificate(cert); } return rv; } /* * Finds the public key from the certificate saved in the header file * and encrypts with it the contents of inFileName to encryptedFileName. */ SECStatus FindKeyAndEncrypt(PK11SlotInfo *slot, secuPWData *pwdata, const char *headerFileName, const char *encryptedFileName, const char *inFileName) { SECStatus rv; PRFileDesc *headerFile = NULL; PRFileDesc *encFile = NULL; PRFileDesc *inFile = NULL; CERTCertificate *cert = NULL; SECItem data; unsigned char ptext[MODBLOCKSIZE]; unsigned char encBuf[MODBLOCKSIZE]; unsigned int ptextLen; int index; unsigned int nWritten; unsigned int pad[1]; SECItem padItem; unsigned int paddingLength = 0; SECKEYPublicKey *pubkey = NULL; /* If the intermediate encrypted file already exists, delete it*/ if (PR_Access(encryptedFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { PR_Delete(encryptedFileName); } /* Read certificate from header file */ rv = ReadFromHeaderFile(headerFileName, CERTENC, &data, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not read certificate from header file\n"); goto cleanup; } /* Read in an ASCII cert and return a CERTCertificate */ cert = CERT_DecodeCertFromPackage((char *)data.data, data.len); if (!cert) { PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); rv = SECFailure; goto cleanup; } /* Extract the public key from certificate */ pubkey = CERT_ExtractPublicKey(cert); if (!pubkey) { PR_fprintf(PR_STDERR, "could not get key from certificate\n"); rv = SECFailure; goto cleanup; } /* Open the encrypted file for writing */ encFile = PR_Open(encryptedFileName, PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); if (!encFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", encryptedFileName); rv = SECFailure; goto cleanup; } /* Open the input file for reading */ inFile = PR_Open(inFileName, PR_RDONLY, 0); if (!inFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", inFileName); rv = SECFailure; goto cleanup; } /* Open the header file to write padding */ headerFile = PR_Open(headerFileName, PR_CREATE_FILE | PR_RDWR | PR_APPEND, 00660); if (!headerFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", headerFileName); rv = SECFailure; goto cleanup; } /* Read input file */ while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { if (ptextLen != MODBLOCKSIZE) { paddingLength = MODBLOCKSIZE - ptextLen; for ( index=0; index < paddingLength; index++) { ptext[ptextLen+index] = (unsigned char)paddingLength; } ptextLen = MODBLOCKSIZE; } rv = PK11_PubEncryptRaw(pubkey, encBuf, ptext, ptextLen, NULL); nWritten = PR_Write(encFile, encBuf, ptextLen); } /* Write the padding to header file */ pad[0] = paddingLength; padItem.type = siBuffer; padItem.data = (unsigned char *)pad; padItem.len = sizeof(pad[0]); WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); cleanup: if (headerFile) { PR_Close(headerFile); } if (encFile) { PR_Close(encFile); } if (inFile) { PR_Close(inFile); } if (pubkey) { SECKEY_DestroyPublicKey(pubkey); } if (cert) { CERT_DestroyCertificate(cert); } return rv; } /* * Finds the private key from db and signs the contents * of inFileName and writes to signatureFileName */ SECStatus FindKeyAndSign(PK11SlotInfo *slot, CERTCertDBHandle* certHandle, secuPWData *pwdata, const char *nickNameStr, const char *headerFileName, const char *inFileName) { SECStatus rv; PRFileDesc *headerFile = NULL; PRFileDesc *inFile = NULL; CERTCertificate *cert = NULL; unsigned int signatureLen = 0; SECKEYPrivateKey *privkey = NULL; SECItem sigItem; SECOidTag hashOIDTag; /* Open the header file to write padding */ headerFile = PR_Open(headerFileName, PR_CREATE_FILE | PR_RDWR | PR_APPEND, 00660); if (!headerFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", headerFileName); rv = SECFailure; goto cleanup; } /* Get the certificate by nick name and write to header file */ cert = CERT_FindCertByNicknameOrEmailAddr(certHandle, nickNameStr); if (!cert) { PR_fprintf(PR_STDERR, "could not obtain certificate by name - %s\n", nickNameStr); rv = SECFailure; goto cleanup; } WriteToHeaderFile(cert->derCert.data, cert->derCert.len, CERTVFY, headerFile); /* Find private key from certificate */ privkey = PK11_FindKeyByAnyCert(cert, NULL); if (privkey == NULL) { fprintf(stderr, "Couldn't find private key for cert\n"); rv = SECFailure; goto cleanup; } /* Sign the contents of the input file */ rv = SignData(inFileName, privkey, &sigItem); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "could not sign the contents from file - %s \n", inFileName); goto cleanup; } /* write signature to header file */ WriteToHeaderFile(sigItem.data, sigItem.len, SIG, headerFile); cleanup: if (headerFile) { PR_Close(headerFile); } if (privkey) { SECKEY_DestroyPrivateKey(privkey); } if (cert) { CERT_DestroyCertificate(cert); } return rv; } /* * Finds the public key from certificate and verifies signature */ SECStatus FindKeyAndVerify(PK11SlotInfo *slot, CERTCertDBHandle* certHandle, secuPWData *pwdata, const char *headerFileName, const char *inFileName) { SECStatus rv = SECFailure; PRFileDesc *headerFile = NULL; PRFileDesc *inFile = NULL; CERTCertificate *cert = NULL; SECKEYPublicKey *pubkey = NULL; SECItem sigItem; SECItem certData; /* Open the input file */ inFile = PR_Open(inFileName, PR_RDONLY, 0); if (!inFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", inFileName); rv = SECFailure; goto cleanup; } /* Open the header file to read the certificate and signature */ headerFile = PR_Open(headerFileName, PR_RDONLY, 0); if (!headerFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", headerFileName); rv = SECFailure; goto cleanup; } /* Read certificate from header file */ rv = ReadFromHeaderFile(headerFileName, CERTVFY, &certData, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not read certificate from header file\n"); goto cleanup; } /* Read in an ASCII cert and return a CERTCertificate */ cert = CERT_DecodeCertFromPackage((char *)certData.data, certData.len); if (!cert) { PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); rv = SECFailure; goto cleanup; } /* Extract the public key from certificate */ pubkey = CERT_ExtractPublicKey(cert); if (!pubkey) { PR_fprintf(PR_STDERR, "Could not get key from certificate\n"); rv = SECFailure; goto cleanup; } /* Read signature from header file */ rv = ReadFromHeaderFile(headerFileName, SIG, &sigItem, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not read signature from header file\n"); goto cleanup; } /* Verify with the public key */ rv = VerifyData(inFileName, pubkey, &sigItem, pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Couldn't verify the signature for file - %s\n", inFileName); goto cleanup; } cleanup: if (headerFile) { PR_Close(headerFile); } if (pubkey) { SECKEY_DestroyPublicKey(pubkey); } if (cert) { CERT_DestroyCertificate(cert); } return rv; } /* * Finds the private key corresponding to the certificate saved in the header file * and decrypts with it the contents of encryptedFileName to outFileName. */ SECStatus FindKeyAndDecrypt(PK11SlotInfo *slot, secuPWData *pwdata, const char *headerFileName, const char *encryptedFileName, const char *outFileName) { SECStatus rv; PRFileDesc *encFile = NULL; PRFileDesc *outFile = NULL; SECKEYPrivateKey *pvtkey = NULL; unsigned int inFileLength = 0; unsigned int paddingLength = 0; unsigned int count = 0; unsigned int temp = 0; unsigned char ctext[MODBLOCKSIZE]; unsigned char decBuf[MODBLOCKSIZE]; unsigned int ctextLen; unsigned int decBufLen; SECItem padItem; SECItem data; SECItem signature; CERTCertificate *cert = NULL; /* Read certificate from header file */ rv = ReadFromHeaderFile(headerFileName, CERTENC, &data, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not read certificate from header file\n"); goto cleanup; } /* Read padding from header file */ rv = ReadFromHeaderFile(headerFileName, PAD, &padItem, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not retrieve PAD detail from header file\n"); goto cleanup; } paddingLength = (unsigned int)padItem.data[0]; inFileLength = FileSize(encryptedFileName); /* Read in an ASCII cert and return a CERTCertificate */ cert = CERT_DecodeCertFromPackage((char *)data.data, data.len); if (!cert) { PR_fprintf(PR_STDERR, "could not obtain certificate from file\n"); rv = SECFailure; goto cleanup; } /* Find private key from certificate */ pvtkey = PK11_FindKeyByAnyCert(cert, NULL); if (pvtkey == NULL) { fprintf(stderr, "Couldn't find private key for cert\n"); rv = SECFailure; goto cleanup; } /* Open the out file to write */ outFile = PR_Open(outFileName, PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); if (!outFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", outFileName); rv = SECFailure; goto cleanup; } /* Open the encrypted file for reading */ encFile = PR_Open(encryptedFileName, PR_RDONLY, 0); if (!encFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", encryptedFileName); rv = SECFailure; goto cleanup; } /* Read the encrypt file, decrypt and write to out file */ while ((ctextLen = PR_Read(encFile, ctext, sizeof(ctext))) > 0) { count += ctextLen; rv = PK11_PubDecryptRaw(pvtkey, decBuf, &decBufLen, sizeof(decBuf), ctext, ctextLen); if (rv != SECSuccess) { fprintf(stderr, "Couldn't decrypt\n"); goto cleanup; } if (decBufLen == 0) { break; } if (count == inFileLength) { decBufLen = decBufLen - paddingLength; } /* write the plain text to out file */ temp = PR_Write(outFile, decBuf, decBufLen); if (temp != decBufLen) { PR_fprintf(PR_STDERR, "write error\n"); rv = SECFailure; break; } } cleanup: if (encFile) { PR_Close(encFile); } if (outFile) { PR_Close(outFile); } if (pvtkey) { SECKEY_DestroyPrivateKey(pvtkey); } if (cert) { CERT_DestroyCertificate(cert); } return rv; } /* Map option letter to command */ static CommandType option2Command(char c) { switch (c) { case 'G': return GENERATE_CSR; case 'A': return ADD_CERT_TO_DB; case 'H': return SAVE_CERT_TO_HEADER; case 'E': return ENCRYPT; case 'D': return DECRYPT; case 'S': return SIGN; case 'V': return VERIFY; default: return UNKNOWN; } } /* * This example illustrates basic encryption/decryption and MACing * Generates the RSA key pair as token object and outputs public key as cert request. * Reads cert request file and stores certificate in DB. * Input, store and trust CA certificate. * Write certificate to intermediate header file * Extract public key from certificate, encrypts the input file and write to external file. * Finds the matching private key, decrypts and write to external file * * How this sample is different from sample 5 ? * * 1. As in sample 5, output is a PKCS#10 CSR * 2. Input and store a cert in cert DB and also used to input, store and trust CA cert. * 3. Like sample 5, but puts cert in header * 4. Like sample 5, but finds key matching cert in header */ int main(int argc, char **argv) { SECStatus rv; PLOptState *optstate; PLOptStatus status; PRBool initialized = PR_FALSE; CommandType cmd = UNKNOWN; const char *dbdir = NULL; secuPWData pwdata = { PW_NONE, 0 }; char *subjectStr = NULL; CERTName *subject = 0; unsigned int serialNumber = 0; char *serialNumberStr = NULL; char *trustStr = NULL; CERTCertDBHandle *certHandle; const char *nickNameStr = NULL; char *issuerNameStr = NULL; PRBool selfsign = PR_FALSE; PRBool ascii = PR_FALSE; PRBool sigVerify = PR_FALSE; const char *headerFileName = NULL; const char *encryptedFileName = NULL; const char *inFileName = NULL; const char *outFileName = NULL; char *certReqFileName = NULL; char *certFileName = NULL; const char *noiseFileName = NULL; PK11SlotInfo *slot = NULL; char * progName = strrchr(argv[0], '/'); progName = progName ? progName + 1 : argv[0]; /* Parse command line arguments */ optstate = PL_CreateOptState(argc, argv, "GAHEDSVad:i:o:f:p:z:s:r:n:x:m:t:c:u:e:b:v:"); while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { switch (optstate->option) { case 'a': ascii = PR_TRUE; break; case 'G': /* Generate a CSR */ case 'A': /* Add cert to database */ case 'H': /* Save cert to the header file */ case 'E': /* Encrypt with public key from cert in header file */ case 'S': /* Sign with private key */ case 'D': /* Decrypt with the matching private key */ case 'V': /* Verify with the matching public key */ cmd = option2Command(optstate->option); break; case 'd': dbdir = strdup(optstate->value); break; case 'f': pwdata.source = PW_FROMFILE; pwdata.data = strdup(optstate->value); break; case 'p': pwdata.source = PW_PLAINTEXT; pwdata.data = strdup(optstate->value); break; case 'i': inFileName = strdup(optstate->value); break; case 'b': headerFileName = strdup(optstate->value); break; case 'e': encryptedFileName = strdup(optstate->value); break; case 'o': outFileName = strdup(optstate->value); break; case 'z': noiseFileName = strdup(optstate->value); break; case 's': subjectStr = strdup(optstate->value); subject = CERT_AsciiToName(subjectStr); break; case 'r': certReqFileName = strdup(optstate->value); break; case 'c': certFileName = strdup(optstate->value); break; case 'u': issuerNameStr = strdup(optstate->value); break; case 'n': nickNameStr = strdup(optstate->value); break; case 'x': selfsign = PR_TRUE; break; case 'm': serialNumberStr = strdup(optstate->value); serialNumber = atoi(serialNumberStr); break; case 't': trustStr = strdup(optstate->value); break; case 'v': sigVerify = PR_TRUE; break; default: Usage(progName); break; } } PL_DestroyOptState(optstate); if (cmd == UNKNOWN || !dbdir) Usage(progName); /* Open DB for read/write and authenticate to it */ PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); initialized = PR_TRUE; rv = NSS_InitReadWrite(dbdir); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); goto cleanup; } PK11_SetPasswordFunc(GetModulePassword); slot = PK11_GetInternalKeySlot(); if (PK11_NeedLogin(slot)) { rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", PK11_GetTokenName(slot)); goto cleanup; } } switch (cmd) { case GENERATE_CSR: ValidateGenerateCSRCommand(progName, dbdir, subject, subjectStr, certReqFileName); /* Generate a CSR */ rv = CreateCertRequest(slot, &pwdata, subject, certReqFileName, ascii); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Create Certificate Request: Failed\n"); goto cleanup; } break; case ADD_CERT_TO_DB: ValidateAddCertToDBCommand(progName, dbdir, nickNameStr, trustStr, certFileName, certReqFileName, issuerNameStr, serialNumberStr, selfsign); /* Add cert to database */ rv = AddCertificateToDB(slot, &pwdata, certReqFileName, certFileName, issuerNameStr, certHandle, nickNameStr, trustStr, serialNumber, selfsign, ascii); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Add Certificate to DB: Failed\n"); goto cleanup; } break; case SAVE_CERT_TO_HEADER: ValidateSaveCertToHeaderCommand(progName, dbdir, nickNameStr, headerFileName); /* Save cert to the header file */ rv = AddCertificateToHeader(slot, &pwdata, headerFileName, certHandle, nickNameStr, sigVerify); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Saving Certificate to header: Failed\n"); goto cleanup; } break; case ENCRYPT: ValidateEncryptCommand(progName, dbdir, nickNameStr, headerFileName, inFileName, encryptedFileName); /* Encrypt with public key from cert in header file */ rv = FindKeyAndEncrypt(slot, &pwdata, headerFileName, encryptedFileName, inFileName); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Find public key and Encrypt : Failed\n"); goto cleanup; } break; case SIGN: ValidateSignCommand(progName, dbdir, nickNameStr, headerFileName, inFileName); /* Sign with private key */ rv = FindKeyAndSign(slot, certHandle, &pwdata, nickNameStr, headerFileName, inFileName); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Find private key and sign : Failed\n"); goto cleanup; } break; case DECRYPT: ValidateDecryptCommand(progName, dbdir, headerFileName, encryptedFileName, outFileName); /* Decrypt with the matching private key */ rv = FindKeyAndDecrypt(slot, &pwdata, headerFileName, encryptedFileName, outFileName); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Find private key and Decrypt : Failed\n"); } break; case VERIFY: ValidateVerifyCommand(progName, dbdir, headerFileName, inFileName); /* Verify with the matching public key */ rv = FindKeyAndVerify(slot, certHandle, &pwdata, headerFileName, inFileName); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Find public key and verify signature : Failed\n"); goto cleanup; } } cleanup: if (slot) { PK11_FreeSlot(slot); } if (initialized) { SECStatus rvShutdown = NSS_Shutdown(); if (rvShutdown != SECSuccess) { PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown() - %s", PORT_ErrorToString(rvShutdown)); rv = SECFailure; } PR_Cleanup(); } return rv; }</opfilename></encryptfilename></headerfilename></dbdirpath></ipfilename></headerfilename></dbdirpath></nickname></ipfilename></headerfilename></dbdirpath></nickname></encryptfilename></ipfilename></headerfilename></dbdirpath></headerfilename></nickname></dbdirpath></serialnumber></issuernickname></csr></cert></trust></nickname></dbdirpath></cert></trust></nickname></dbdirpath></csr></subject></dbdirpath></csr></issuernickname></trustargs></nickname></serialnumber></opfilename></encryptfilename></headerfilename></ipfilename></noisefilename></dbpwdfile></dbpwd></dbdirpath></ipfilename></headerfilename></infilename></headerfilename></opfilename></encryptfilename></headerfilename></encryptfilename></ipfilename></headerfilename></headerfilename></nickname></serialnumber></issuernickname></csr></cert></trust></nickname></csr></subject></opfilename></encryptfilename></headerfilename></ipfilename></headerfilename></ipfilename></headerfilename></encryptfilename></ipfilename></headerfilename></headerfilename></nickname></serialnumber></issuernickname></csr></cert></trust></nickname></csr></subject></noisefilename></dbpwdfile></dbpwd></dbdirpath></g|a|h|e|ds|v></sechash.h></secoidt.h></secmodt.h></secoid.h></secport.h></secerr.h></base64.h></cert.h></pk11priv.h></keyhi.h></cryptohi.h></plstr.h></prtypes.h></prlog.h></prinit.h></prerror.h></plgetopt.h></prthread.h> diff --git a/security/nss/doc/rst/legacy/nss_sample_code/sample2_-_initialize_nss_database/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/sample2_-_initialize_nss_database/index.rst new file mode 100644 index 0000000000..fe1d83fc61 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/sample2_-_initialize_nss_database/index.rst @@ -0,0 +1,250 @@ +.. _mozilla_projects_nss_nss_sample_code_sample2_-_initialize_nss_database: + +Initialize NSS database - sample 2 +================================== + +.. _nss_sample_code_2_initialize_the_nss_database.: + +`NSS sample code 2: initialize the NSS database. <#nss_sample_code_2_initialize_the_nss_database.>`__ +----------------------------------------------------------------------------------------------------- + +.. container:: + + The NSS sample code below demonstrates how to initialize the NSS database. + + .. code:: c + + /* + * Print a usage message and exit + */ + static void + Usage(const char *progName) + { + fprintf(stderr, "\nUsage: %s -d [-p ]" + " [-f ]\n\n", + progName); + fprintf(stderr, "%-15s Specify a DB directory path\n\n", + "-d "); + fprintf(stderr, "%-15s Specify a plaintext password\n\n", + "-p "); + fprintf(stderr, "%-15s Specify a password file\n\n", + "-f "); + exit(-1); + } + + /* + * InitSlotPassword + */ + char * + InitSlotPassword(PK11SlotInfo *slot, PRBool retry, void *arg) + { + FILE *input; + FILE *output; + char *p0 = NULL; + char *p1 = NULL; + secuPWData *pwdata = (secuPWData *) arg; + + if (pwdata->source == PW_FROMFILE) { + return FilePasswd(slot, retry, pwdata->data); + } + if (pwdata->source == PW_PLAINTEXT) { + return PL_strdup(pwdata->data); + } + + /* open terminal */ + input = fopen("/dev/tty", "r"); + if (input == NULL) { + PR_fprintf(PR_STDERR, "Error opening input terminal for read\n"); + return NULL; + } + + /* we have no password, so initialize database with one */ + PR_fprintf(PR_STDERR, + "Enter a password which will be used to encrypt your keys.\n" + "The password should be at least 8 characters long,\n" + "and should contain at least one non-alphabetic character.\n\n"); + + output = fopen("/dev/tty", "w"); + if (output == NULL) { + PR_fprintf(PR_STDERR, "Error opening output terminal for write\n"); + return NULL; + } + + for (;;) { + if (p0) + PORT_Free(p0); + p0 = GetPassword(input, output, "Enter new password: ", + CheckPassword); + if (p1) + PORT_Free(p1); + p1 = GetPassword(input, output, "Re-enter password: ", + CheckPassword); + if (p0 && p1 && !PORT_Strcmp(p0, p1)) { + break; + } + PR_fprintf(PR_STDERR, "Passwords do not match. Try again.\n"); + } + + /* clear out the duplicate password string */ + if (p1) { + PORT_Memset(p1, 0, PORT_Strlen(p1)); + PORT_Free(p1); + } + fclose(input); + fclose(output); + + return p0; + } + + /* + * ChangePW + */ + SECStatus + ChangePW(PK11SlotInfo *slot, char *oldPass, char *newPass, + char *oldPwFile, char *newPwFile) + { + SECStatus rv; + secuPWData pwdata; + secuPWData newpwdata; + char *oldpw = NULL; + char *newpw = NULL; + + if (oldPass) { + pwdata.source = PW_PLAINTEXT; + pwdata.data = oldPass; + } else if (oldPwFile) { + pwdata.source = PW_FROMFILE; + pwdata.data = oldPwFile; + } else { + pwdata.source = PW_NONE; + pwdata.data = NULL; + } + + if (newPass) { + newpwdata.source = PW_PLAINTEXT; + newpwdata.data = newPass; + } else if (newPwFile) { + newpwdata.source = PW_FROMFILE; + newpwdata.data = NULL; + } else { + newpwdata.source = PW_NONE; + newpwdata.data = NULL; + } + + if (PK11_NeedUserInit(slot)) { + newpw = InitSlotPassword(slot, PR_FALSE, &pwdata); + rv = PK11_InitPin(slot, (char*)NULL, newpw); + if (rv == SECSuccess) { + PR_fprintf(PR_STDERR, "PK11_InitPin failed.\n"); + return SECFailure; + } + } + else { + for (;;) { + oldpw = GetModulePassword(slot, PR_FALSE, &pwdata); + + if (PK11_CheckUserPassword(slot, oldpw) != SECSuccess) { + if (pwdata.source == PW_NONE) { + PR_fprintf(PR_STDERR, "Invalid password. Try again.\n"); + } else { + PR_fprintf(PR_STDERR, "Invalid password.\n"); + PORT_Memset(oldpw, 0, PL_strlen(oldpw)); + PORT_Free(oldpw); + return SECFailure; + } + } else { + break; + } + PORT_Free(oldpw); + } + newpw = InitSlotPassword(slot, PR_FALSE, &newpwdata); + + if (PK11_ChangePW(slot, oldpw, newpw) != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to change password.\n"); + return SECFailure; + } + PORT_Memset(oldpw, 0, PL_strlen(oldpw)); + PORT_Free(oldpw); + PR_fprintf(PR_STDOUT, "Password changed successfully.\n"); + } + PORT_Memset(newpw, 0, PL_strlen(newpw)); + PORT_Free(newpw); + return SECSuccess; + } + + /* + * This example illustrates initialization of the NSS database. + * It creates an nss configuration directory with empty databases + * and initializes the databases. It also illustrates techniques for + * password handling. + */ + int main(int argc, char **argv) + { + PLOptState *optstate; + PLOptStatus status; + SECStatus rv; + SECStatus rvShutdown; + char *slotname = "internal"; + PK11SlotInfo *slot = NULL; + char *dbdir = NULL; + char *plainPass = NULL; + char *pwFile = NULL; + + char * progName = strrchr(argv[0], '/'); + progName = progName ? progName + 1 : argv[0]; + + /* Parse command line arguments */ + optstate = PL_CreateOptState(argc, argv, "d:p:q:f:g:"); + while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { + switch (optstate->option) { + case 'd': + dbdir = strdup(optstate->value); + break; + case 'p': + plainPass = strdup(optstate->value); + break; + case 'f': + pwFile = strdup(optstate->value); + break; + default: + Usage(progName); + break; + } + } + PL_DestroyOptState(optstate); + + if (!dbdir) + Usage(progName); + + PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); + + /* Create the database */ + rv = NSS_InitReadWrite(dbdir); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "NSS_Initialize Failed"); + PR_Cleanup(); + exit(rv); + } + + if (PL_strcmp(slotname, "internal") == 0) + slot = PK11_GetInternalKeySlot(); + + /* If creating new database, initialize the password. */ + rv = ChangePW(slot, plainPass, 0, pwFile, 0); + if (rv != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed to change password\n"); + } + + if (slot) { + PK11_FreeSlot(slot); + } + rvShutdown = NSS_Shutdown(); + if (rvShutdown != SECSuccess) { + PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); + rv = SECFailure; + } + + PR_Cleanup(); + + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/sample3_-_encdecmac_using_token_object/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/sample3_-_encdecmac_using_token_object/index.rst new file mode 100644 index 0000000000..ec6ff208fb --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/sample3_-_encdecmac_using_token_object/index.rst @@ -0,0 +1,30 @@ +.. _mozilla_projects_nss_nss_sample_code_sample3_-_encdecmac_using_token_object: + +EncDecMAC using token object - sample 3 +======================================= + +.. _encdecmac_using_token_object: + +`EncDecMAC using token object <#encdecmac_using_token_object>`__ +---------------------------------------------------------------- + +.. container:: + +`Example: <#example>`__ +~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _nss_sample_code_3_hashing.: + +`NSS Sample Code 3: Enc/Dec/MAC Using Token Object ID. <#nss_sample_code_3_hashing.>`__ +--------------------------------------------------------------------------------------- + +.. container:: + + Computes the hash of a file and saves it to another file, illustrates the use of NSS message + APIs. + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ /* NSPR Headers */ #include #include #include #include #include #include #include /* NSS headers */ #include #include /* our samples utilities */ #include "util.h" #define BUFFERSIZE 80 #define DIGESTSIZE 16 #define PTEXT_MAC_BUFFER_SIZE 96 #define CIPHERSIZE 96 #define BLOCKSIZE 32 #define CIPHER_HEADER "-----BEGIN CIPHER-----" #define CIPHER_TRAILER "-----END CIPHER-----" #define ENCKEY_HEADER "-----BEGIN AESKEY CKAID-----" #define ENCKEY_TRAILER "-----END AESKEY CKAID-----" #define MACKEY_HEADER "-----BEGIN MACKEY CKAID-----" #define MACKEY_TRAILER "-----END MACKEY CKAID-----" #define IV_HEADER "-----BEGIN IV-----" #define IV_TRAILER "-----END IV-----" #define MAC_HEADER "-----BEGIN MAC-----" #define MAC_TRAILER "-----END MAC-----" #define PAD_HEADER "-----BEGIN PAD-----" #define PAD_TRAILER "-----END PAD-----" typedef enum { ENCRYPT, DECRYPT, UNKNOWN } CommandType; typedef enum { SYMKEY = 0, MACKEY = 1, IV = 2, MAC = 3, PAD = 4 } HeaderType; /* * Print usage message and exit */ static void Usage(const char *progName) { fprintf(stderr, "\nUsage: %s -c -d [-z ] " "[-p | -f ] -i -o \n\n", progName); fprintf(stderr, "%-20s Specify 'a' for encrypt operation\n\n", "-c "); fprintf(stderr, "%-20s Specify 'b' for decrypt operation\n\n", " "); fprintf(stderr, "%-20s Specify db directory path\n\n", "-d "); fprintf(stderr, "%-20s Specify db password [optional]\n\n", "-p "); fprintf(stderr, "%-20s Specify db password file [optional]\n\n", "-f "); fprintf(stderr, "%-20s Specify noise file name [optional]\n\n", "-z "); fprintf(stderr, "%-21s Specify an input file name\n\n", "-i "); fprintf(stderr, "%-21s Specify an output file name\n\n", "-o "); fprintf(stderr, "%-7s For encrypt, it takes as an input file and produces\n", "Note :"); fprintf(stderr, "%-7s .enc and .header as intermediate output files.\n\n", ""); fprintf(stderr, "%-7s For decrypt, it takes .enc and .header\n", ""); fprintf(stderr, "%-7s as input files and produces as a final output file.\n\n", ""); exit(-1); } /* * Gather a CKA_ID */ SECStatus GatherCKA_ID(PK11SymKey* key, SECItem* buf) { SECStatus rv = PK11_ReadRawAttribute(PK11_TypeSymKey, key, CKA_ID, buf); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "PK11_ReadRawAttribute returned (%d)\n", rv); PR_fprintf(PR_STDERR, "Could not read SymKey CKA_ID attribute\n"); return rv; } return rv; } /* * Generate a Symmetric Key */ PK11SymKey * GenerateSYMKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE mechanism, int keySize, SECItem *keyID, secuPWData *pwdata) { SECStatus rv; PK11SymKey *key; if (PK11_NeedLogin(slot)) { rv = PK11_Authenticate(slot, PR_TRUE, pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", PK11_GetTokenName(slot)); return NULL; } } /* Generate the symmetric key */ key = PK11_TokenKeyGen(slot, mechanism, NULL, keySize, keyID, PR_TRUE, pwdata); if (!key) { PR_fprintf(PR_STDERR, "Symmetric Key Generation Failed \n"); } return key; } /* * MacInit */ SECStatus MacInit(PK11Context *ctx) { SECStatus rv = PK11_DigestBegin(ctx); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestBegin()\n"); } return rv; } /* * MacUpdate */ SECStatus MacUpdate(PK11Context *ctx, unsigned char *msg, unsigned int msgLen) { SECStatus rv = PK11_DigestOp(ctx, msg, msgLen); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Compute MAC Failed : DigestOp()\n"); } return rv; } /* * Finalize MACing */ SECStatus MacFinal(PK11Context *ctx, unsigned char *mac, unsigned int *macLen, unsigned int maxLen) { SECStatus rv = PK11_DigestFinal(ctx, mac, macLen, maxLen); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Compute MAC Failed : PK11_DigestFinal()\n"); } return SECSuccess; } /* * Compute Mac */ SECStatus ComputeMac(PK11Context *ctxmac, unsigned char *ptext, unsigned int ptextLen, unsigned char *mac, unsigned int *macLen, unsigned int maxLen) { SECStatus rv = MacInit(ctxmac); if (rv != SECSuccess) return rv; rv = MacUpdate(ctxmac, ptext, ptextLen); if (rv != SECSuccess) return rv; rv = MacFinal(ctxmac, mac, macLen, maxLen); return rv; } /* * WriteToHeaderFile */ SECStatus WriteToHeaderFile(const char *buf, unsigned int len, HeaderType type, PRFileDesc *outFile) { SECStatus rv; char header[40]; char trailer[40]; char *outString = NULL; switch (type) { case SYMKEY: strcpy(header, ENCKEY_HEADER); strcpy(trailer, ENCKEY_TRAILER); break; case MACKEY: strcpy(header, MACKEY_HEADER); strcpy(trailer, MACKEY_TRAILER); break; case IV: strcpy(header, IV_HEADER); strcpy(trailer, IV_TRAILER); break; case MAC: strcpy(header, MAC_HEADER); strcpy(trailer, MAC_TRAILER); break; case PAD: strcpy(header, PAD_HEADER); strcpy(trailer, PAD_TRAILER); break; } PR_fprintf(outFile, "%s\n", header); PrintAsHex(outFile, buf, len); PR_fprintf(outFile, "%s\n\n", trailer); return SECSuccess; } /* * Initialize for encryption or decryption - common code */ PK11Context * CryptInit(PK11SymKey *key, unsigned char *iv, unsigned int ivLen, CK_MECHANISM_TYPE type, CK_ATTRIBUTE_TYPE operation) { SECItem ivItem = { siBuffer, iv, ivLen }; PK11Context *ctx = NULL; SECItem *secParam = PK11_ParamFromIV(CKM_AES_CBC, &ivItem); if (secParam == NULL) { PR_fprintf(PR_STDERR, "Crypt Failed : secParam NULL\n"); return NULL; } ctx = PK11_CreateContextBySymKey(CKM_AES_CBC, operation, key, secParam); if (ctx == NULL) { PR_fprintf(PR_STDERR, "Crypt Failed : can't create a context\n"); goto cleanup; } cleanup: if (secParam) { SECITEM_FreeItem(secParam, PR_TRUE); } return ctx; } /* * Common encryption and decryption code */ SECStatus Crypt(PK11Context *ctx, unsigned char *out, unsigned int *outLen, unsigned int maxOut, unsigned char *in, unsigned int inLen) { SECStatus rv; rv = PK11_CipherOp(ctx, out, outLen, maxOut, in, inLen); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Crypt Failed : PK11_CipherOp returned %d\n", rv); goto cleanup; } cleanup: if (rv != SECSuccess) { return rv; } return SECSuccess; } /* * Decrypt */ SECStatus Decrypt(PK11Context *ctx, unsigned char *out, unsigned int *outLen, unsigned int maxout, unsigned char *in, unsigned int inLen) { return Crypt(ctx, out, outLen, maxout, in, inLen); } /* * Encrypt */ SECStatus Encrypt(PK11Context* ctx, unsigned char *out, unsigned int *outLen, unsigned int maxout, unsigned char *in, unsigned int inLen) { return Crypt(ctx, out, outLen, maxout, in, inLen); } /* * EncryptInit */ PK11Context * EncryptInit(PK11SymKey *ek, unsigned char *iv, unsigned int ivLen, CK_MECHANISM_TYPE type) { return CryptInit(ek, iv, ivLen, type, CKA_ENCRYPT); } /* * DecryptInit */ PK11Context * DecryptInit(PK11SymKey *dk, unsigned char *iv, unsigned int ivLen, CK_MECHANISM_TYPE type) { return CryptInit(dk, iv, ivLen, type, CKA_DECRYPT); } /* * Read cryptographic parameters from the header file */ SECStatus ReadFromHeaderFile(const char *fileName, HeaderType type, SECItem *item, PRBool isHexData) { SECStatus rv; PRFileDesc* file; SECItem filedata; SECItem outbuf; unsigned char *nonbody; unsigned char *body; char header[40]; char trailer[40]; outbuf.type = siBuffer; file = PR_Open(fileName, PR_RDONLY, 0); if (!file) { PR_fprintf(PR_STDERR, "Failed to open %s\n", fileName); return SECFailure; } switch (type) { case SYMKEY: strcpy(header, ENCKEY_HEADER); strcpy(trailer, ENCKEY_TRAILER); break; case MACKEY: strcpy(header, MACKEY_HEADER); strcpy(trailer, MACKEY_TRAILER); break; case IV: strcpy(header, IV_HEADER); strcpy(trailer, IV_TRAILER); break; case MAC: strcpy(header, MAC_HEADER); strcpy(trailer, MAC_TRAILER); break; case PAD: strcpy(header, PAD_HEADER); strcpy(trailer, PAD_TRAILER); break; } rv = FileToItem(&filedata, file); nonbody = (char *)filedata.data; if (!nonbody) { PR_fprintf(PR_STDERR, "unable to read data from input file\n"); rv = SECFailure; goto cleanup; } /* check for headers and trailers and remove them */ if ((body = strstr(nonbody, header)) != NULL) { char *trail = NULL; nonbody = body; body = PORT_Strchr(body, '\n'); if (!body) body = PORT_Strchr(nonbody, '\r'); /* maybe this is a MAC file */ if (body) trail = strstr(++body, trailer); if (trail != NULL) { *trail = '\0'; } else { PR_fprintf(PR_STDERR, "input has header but no trailer\n"); PORT_Free(filedata.data); return SECFailure; } } else { body = nonbody; } cleanup: PR_Close(file); HexToBuf(body, item, isHexData); return SECSuccess; } /* * EncryptAndMac */ SECStatus EncryptAndMac(PRFileDesc *inFile, PRFileDesc *headerFile, PRFileDesc *encFile, PK11SymKey *ek, PK11SymKey *mk, unsigned char *iv, unsigned int ivLen, PRBool ascii) { SECStatus rv; unsigned char ptext[BLOCKSIZE]; unsigned int ptextLen; unsigned char mac[DIGESTSIZE]; unsigned int macLen; unsigned int nwritten; unsigned char encbuf[BLOCKSIZE]; unsigned int encbufLen; SECItem noParams = { siBuffer, NULL, 0 }; PK11Context *ctxmac = NULL; PK11Context *ctxenc = NULL; unsigned int pad[1]; SECItem padItem; unsigned int paddingLength; static unsigned int firstTime = 1; int j; ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); if (ctxmac == NULL) { PR_fprintf(PR_STDERR, "Can't create MAC context\n"); rv = SECFailure; goto cleanup; } rv = MacInit(ctxmac); if (rv != SECSuccess) { goto cleanup; } ctxenc = EncryptInit(ek, iv, ivLen, CKM_AES_CBC); /* read a buffer of plaintext from input file */ while ((ptextLen = PR_Read(inFile, ptext, sizeof(ptext))) > 0) { /* Encrypt using it using CBC, using previously created IV */ if (ptextLen != BLOCKSIZE) { paddingLength = BLOCKSIZE - ptextLen; for ( j=0; j < paddingLength; j++) { ptext[ptextLen+j] = (unsigned char)paddingLength; } ptextLen = BLOCKSIZE; } rv = Encrypt(ctxenc, encbuf, &encbufLen, sizeof(encbuf), ptext, ptextLen); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Encrypt Failure\n"); goto cleanup; } /* save the last block of ciphertext as the next IV */ iv = encbuf; ivLen = encbufLen; /* write the cipher text to intermediate file */ nwritten = PR_Write(encFile, encbuf, encbufLen); /*PR_Assert(nwritten == encbufLen);*/ rv = MacUpdate(ctxmac, ptext, ptextLen); } rv = MacFinal(ctxmac, mac, &macLen, DIGESTSIZE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "MacFinal Failure\n"); goto cleanup; } if (macLen == 0) { PR_fprintf(PR_STDERR, "Bad MAC length\n"); rv = SECFailure; goto cleanup; } WriteToHeaderFile(mac, macLen, MAC, headerFile); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Write MAC Failure\n"); goto cleanup; } pad[0] = paddingLength; padItem.type = siBuffer; padItem.data = (unsigned char *)pad; padItem.len = sizeof(pad[0]); WriteToHeaderFile(padItem.data, padItem.len, PAD, headerFile); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Write PAD Failure\n"); goto cleanup; } rv = SECSuccess; cleanup: if (ctxmac != NULL) { PK11_DestroyContext(ctxmac, PR_TRUE); } if (ctxenc != NULL) { PK11_DestroyContext(ctxenc, PR_TRUE); } return rv; } /* * Find the Key for the given mechanism */ PK11SymKey* FindKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE mechanism, SECItem *keyBuf, secuPWData *pwdata) { SECStatus rv; PK11SymKey *key; if (PK11_NeedLogin(slot)) { rv = PK11_Authenticate(slot, PR_TRUE, pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", PK11_GetTokenName(slot)); if (slot) { PK11_FreeSlot(slot); } return NULL; } } key = PK11_FindFixedKey(slot, mechanism, keyBuf, 0); if (!key) { PR_fprintf(PR_STDERR, "PK11_FindFixedKey failed (err %d)\n", PR_GetError()); PK11_FreeSlot(slot); return NULL; } return key; } /* * Decrypt and Verify MAC */ SECStatus DecryptAndVerifyMac(const char* outFileName, char *encryptedFileName, SECItem *cItem, SECItem *macItem, PK11SymKey* ek, PK11SymKey* mk, SECItem *ivItem, SECItem *padItem) { SECStatus rv; PRFileDesc* inFile; PRFileDesc* outFile; unsigned char decbuf[64]; unsigned int decbufLen; unsigned char ptext[BLOCKSIZE]; unsigned int ptextLen = 0; unsigned char ctext[64]; unsigned int ctextLen; unsigned char newmac[DIGESTSIZE]; unsigned int newmacLen = 0; unsigned int newptextLen = 0; unsigned int count = 0; unsigned int temp = 0; unsigned int blockNumber = 0; SECItem noParams = { siBuffer, NULL, 0 }; PK11Context *ctxmac = NULL; PK11Context *ctxenc = NULL; unsigned char iv[BLOCKSIZE]; unsigned int ivLen = ivItem->len; unsigned int fileLength; unsigned int paddingLength; int j; memcpy(iv, ivItem->data, ivItem->len); paddingLength = (unsigned int)padItem->data[0]; ctxmac = PK11_CreateContextBySymKey(CKM_MD5_HMAC, CKA_SIGN, mk, &noParams); if (ctxmac == NULL) { PR_fprintf(PR_STDERR, "Can't create MAC context\n"); rv = SECFailure; goto cleanup; } /* Open the input file. */ inFile = PR_Open(encryptedFileName, PR_RDONLY , 0); if (!inFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", encryptedFileName); return SECFailure; } /* Open the output file. */ outFile = PR_Open(outFileName, PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR , 00660); if (!outFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", outFileName); return SECFailure; } rv = MacInit(ctxmac); if (rv != SECSuccess) goto cleanup; ctxenc = DecryptInit(ek, iv, ivLen, CKM_AES_CBC); fileLength = FileSize(encryptedFileName); while ((ctextLen = PR_Read(inFile, ctext, sizeof(ctext))) > 0) { count += ctextLen; /* decrypt cipher text buffer using CBC and IV */ rv = Decrypt(ctxenc, decbuf, &decbufLen, sizeof(decbuf), ctext, ctextLen); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Decrypt Failure\n"); goto cleanup; } if (decbufLen == 0) break; rv = MacUpdate(ctxmac, decbuf, decbufLen); if (rv != SECSuccess) { goto cleanup; } if (count == fileLength) { decbufLen = decbufLen-paddingLength; } /* write the plain text to out file */ temp = PR_Write(outFile, decbuf, decbufLen); if (temp != decbufLen) { PR_fprintf(PR_STDERR, "write error\n"); rv = SECFailure; break; } /* save last block of ciphertext */ memcpy(iv, decbuf, decbufLen); ivLen = decbufLen; blockNumber++; } if (rv != SECSuccess) { goto cleanup; } rv = MacFinal(ctxmac, newmac, &newmacLen, sizeof(newmac)); if (rv != SECSuccess) { goto cleanup; } if (PORT_Memcmp(macItem->data, newmac, newmacLen) == 0) { rv = SECSuccess; } else { PR_fprintf(PR_STDERR, "Check MAC : Failure\n"); PR_fprintf(PR_STDERR, "Extracted : "); PrintAsHex(PR_STDERR, macItem->data, macItem->len); PR_fprintf(PR_STDERR, "Computed : "); PrintAsHex(PR_STDERR, newmac, newmacLen); rv = SECFailure; } cleanup: if (ctxmac) { PK11_DestroyContext(ctxmac, PR_TRUE); } if (ctxenc) { PK11_DestroyContext(ctxenc, PR_TRUE); } if (outFile) { PR_Close(outFile); } return rv; } /* * Gets IV and CKAIDS From Header File */ SECStatus GetIVandCKAIDSFromHeader(const char *cipherFileName, SECItem *ivItem, SECItem *encKeyItem, SECItem *macKeyItem) { SECStatus rv; /* open intermediate file, read in header, get IV and CKA_IDs of two keys * from it */ rv = ReadFromHeaderFile(cipherFileName, IV, ivItem, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not retrieve IV from cipher file\n"); goto cleanup; } rv = ReadFromHeaderFile(cipherFileName, SYMKEY, encKeyItem, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not retrieve AES CKA_ID from cipher file\n"); goto cleanup; } rv = ReadFromHeaderFile(cipherFileName, MACKEY, macKeyItem, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not retrieve MAC CKA_ID from cipher file\n"); goto cleanup; } cleanup: return rv; } /* * DecryptFile */ SECStatus DecryptFile(PK11SlotInfo *slot, const char *dbdir, const char *outFileName, const char *headerFileName, char *encryptedFileName, secuPWData *pwdata, PRBool ascii) { /* * The DB is open read only and we have authenticated to it * open input file, read in header, get IV and CKA_IDs of two keys from it * find those keys in the DB token * Open output file * loop until EOF(input): * read a buffer of ciphertext from input file, * Save last block of ciphertext * decrypt ciphertext buffer using CBC and IV, * compute and check MAC, then remove MAC from plaintext * replace IV with saved last block of ciphertext * write the plain text to output file * close files * report success */ SECStatus rv; SECItem ivItem; SECItem encKeyItem; SECItem macKeyItem; SECItem cipherItem; SECItem macItem; SECItem padItem; PK11SymKey *encKey = NULL; PK11SymKey *macKey = NULL; /* open intermediate file, read in header, get IV and CKA_IDs of two keys * from it */ rv = GetIVandCKAIDSFromHeader(headerFileName, &ivItem, &encKeyItem, &macKeyItem); if (rv != SECSuccess) { goto cleanup; } /* find those keys in the DB token */ encKey = FindKey(slot, CKM_AES_CBC, &encKeyItem, pwdata); if (encKey == NULL) { PR_fprintf(PR_STDERR, "Can't find the encryption key\n"); rv = SECFailure; goto cleanup; } /* CKM_MD5_HMAC or CKM_EXTRACT_KEY_FROM_KEY */ macKey = FindKey(slot, CKM_MD5_HMAC, &macKeyItem, pwdata); if (macKey == NULL) { rv = SECFailure; goto cleanup; } /* Read in the Mac into item from the intermediate file */ rv = ReadFromHeaderFile(headerFileName, MAC, &macItem, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not retrieve MAC from cipher file\n"); goto cleanup; } if (macItem.data == NULL) { PR_fprintf(PR_STDERR, "MAC has NULL data\n"); rv = SECFailure; goto cleanup; } if (macItem.len == 0) { PR_fprintf(PR_STDERR, "MAC has data has 0 length\n"); /*rv = SECFailure; goto cleanup;*/ } rv = ReadFromHeaderFile(headerFileName, PAD, &padItem, PR_TRUE); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not retrieve PAD detail from header file\n"); goto cleanup; } if (rv == SECSuccess) { /* Decrypt and Remove Mac */ rv = DecryptAndVerifyMac(outFileName, encryptedFileName, &cipherItem, &macItem, encKey, macKey, &ivItem, &padItem); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Failed while decrypting and removing MAC\n"); } } cleanup: if (slot) { PK11_FreeSlot(slot); } if (encKey) { PK11_FreeSymKey(encKey); } if (macKey) { PK11_FreeSymKey(macKey); } return rv; } /* * EncryptFile */ SECStatus EncryptFile(PK11SlotInfo *slot, const char *dbdir, const char *inFileName, const char *headerFileName, const char *encryptedFileName, const char *noiseFileName, secuPWData *pwdata, PRBool ascii) { /* * The DB is open for read/write and we have authenticated to it. * generate a symmetric AES key as a token object. * generate a second key to use for MACing, also a token object. * get their CKA_IDs * generate a random value to use as IV for AES CBC * open an input file and an output file, * write a header to the output that identifies the two keys by * their CKA_IDs, May include original file name and length. * loop until EOF(input) * read a buffer of plaintext from input file, * MAC it, append the MAC to the plaintext * encrypt it using CBC, using previously created IV, * store the last block of ciphertext as the new IV, * write the cipher text to intermediate file * close files * report success */ SECStatus rv; PRFileDesc *inFile; PRFileDesc *headerFile; PRFileDesc *encFile; unsigned char *encKeyId = (unsigned char *) "Encrypt Key"; unsigned char *macKeyId = (unsigned char *) "MAC Key"; SECItem encKeyID = { siAsciiString, encKeyId, PL_strlen(encKeyId) }; SECItem macKeyID = { siAsciiString, macKeyId, PL_strlen(macKeyId) }; SECItem encCKAID; SECItem macCKAID; unsigned char iv[BLOCKSIZE]; SECItem ivItem; PK11SymKey *encKey = NULL; PK11SymKey *macKey = NULL; SECItem temp; unsigned char c; /* generate a symmetric AES key as a token object. */ encKey = GenerateSYMKey(slot, CKM_AES_KEY_GEN, 128/8, &encKeyID, pwdata); if (encKey == NULL) { PR_fprintf(PR_STDERR, "GenerateSYMKey for AES returned NULL.\n"); rv = SECFailure; goto cleanup; } /* generate a second key to use for MACing, also a token object. */ macKey = GenerateSYMKey(slot, CKM_GENERIC_SECRET_KEY_GEN, 160/8, &macKeyID, pwdata); if (macKey == NULL) { PR_fprintf(PR_STDERR, "GenerateSYMKey for MACing returned NULL.\n"); rv = SECFailure; goto cleanup; } /* get the encrypt key CKA_ID */ rv = GatherCKA_ID(encKey, &encCKAID); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Error while wrapping encrypt key\n"); goto cleanup; } /* get the MAC key CKA_ID */ rv = GatherCKA_ID(macKey, &macCKAID); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Can't get the MAC key CKA_ID.\n"); goto cleanup; } if (noiseFileName) { rv = SeedFromNoiseFile(noiseFileName); if (rv != SECSuccess) { PORT_SetError(PR_END_OF_FILE_ERROR); return SECFailure; } rv = PK11_GenerateRandom(iv, BLOCKSIZE); if (rv != SECSuccess) { goto cleanup; } } else { /* generate a random value to use as IV for AES CBC */ GenerateRandom(iv, BLOCKSIZE); } headerFile = PR_Open(headerFileName, PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); if (!headerFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", headerFileName); return SECFailure; } encFile = PR_Open(encryptedFileName, PR_CREATE_FILE | PR_TRUNCATE | PR_RDWR, 00660); if (!encFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for writing.\n", encryptedFileName); return SECFailure; } /* write to a header file the IV and the CKA_IDs * identifying the two keys */ ivItem.type = siBuffer; ivItem.data = iv; ivItem.len = BLOCKSIZE; rv = WriteToHeaderFile(iv, BLOCKSIZE, IV, headerFile); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Error writing IV to cipher file - %s\n", headerFileName); goto cleanup; } rv = WriteToHeaderFile(encCKAID.data, encCKAID.len, SYMKEY, headerFile); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Error writing AES CKA_ID to cipher file - %s\n", encryptedFileName); goto cleanup; } rv = WriteToHeaderFile(macCKAID.data, macCKAID.len, MACKEY, headerFile); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Error writing MAC CKA_ID to cipher file - %s\n", headerFileName); goto cleanup; } /* Open the input file. */ inFile = PR_Open(inFileName, PR_RDONLY, 0); if (!inFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", inFileName); return SECFailure; } /* Macing and Encryption */ if (rv == SECSuccess) { rv = EncryptAndMac(inFile, headerFile, encFile, encKey, macKey, ivItem.data, ivItem.len, ascii); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Failed : Macing and Encryption\n"); goto cleanup; } } cleanup: if (inFile) { PR_Close(inFile); } if (headerFile) { PR_Close(headerFile); } if (encFile) { PR_Close(encFile); } if (slot) { PK11_FreeSlot(slot); } if (encKey) { PK11_FreeSymKey(encKey); } if (macKey) { PK11_FreeSymKey(macKey); } return rv; } /* * This example illustrates basic encryption/decryption and MACing * Generates the encryption/mac keys and uses token for storing. * Encrypts the input file and appends MAC before storing in intermediate * header file. * Writes the CKA_IDs of the encryption keys into intermediate header file. * Reads the intermediate headerfile for CKA_IDs and encrypted * contents and decrypts into output file. */ int main(int argc, char **argv) { SECStatus rv; SECStatus rvShutdown; PK11SlotInfo *slot = NULL; PLOptState *optstate; PLOptStatus status; char headerFileName[50]; char encryptedFileName[50]; PRFileDesc *inFile; PRFileDesc *outFile; PRBool ascii = PR_FALSE; CommandType cmd = UNKNOWN; const char *command = NULL; const char *dbdir = NULL; const char *inFileName = NULL; const char *outFileName = NULL; const char *noiseFileName = NULL; secuPWData pwdata = { PW_NONE, 0 }; char * progName = strrchr(argv[0], '/'); progName = progName ? progName + 1 : argv[0]; /* Parse command line arguments */ optstate = PL_CreateOptState(argc, argv, "c:d:i:o:f:p:z:a"); while ((status = PL_GetNextOpt(optstate)) == PL_OPT_OK) { switch (optstate->option) { case 'a': ascii = PR_TRUE; break; case 'c': command = strdup(optstate->value); break; case 'd': dbdir = strdup(optstate->value); break; case 'f': pwdata.source = PW_FROMFILE; pwdata.data = strdup(optstate->value); break; case 'p': pwdata.source = PW_PLAINTEXT; pwdata.data = strdup(optstate->value); break; case 'i': inFileName = strdup(optstate->value); break; case 'o': outFileName = strdup(optstate->value); break; case 'z': noiseFileName = strdup(optstate->value); break; default: Usage(progName); break; } } PL_DestroyOptState(optstate); if (!command || !dbdir || !inFileName || !outFileName) Usage(progName); if (PL_strlen(command)==0) Usage(progName); cmd = command[0] == 'a' ? ENCRYPT : command[0] == 'b' ? DECRYPT : UNKNOWN; /* Open the input file. */ inFile = PR_Open(inFileName, PR_RDONLY, 0); if (!inFile) { PR_fprintf(PR_STDERR, "Unable to open \"%s\" for reading.\n", inFileName); return SECFailure; } PR_Close(inFile); /* For intermediate header file, choose filename as inputfile name with extension ".header" */ strcpy(headerFileName, inFileName); strcat(headerFileName, ".header"); /* For intermediate encrypted file, choose filename as inputfile name with extension ".enc" */ strcpy(encryptedFileName, inFileName); strcat(encryptedFileName, ".enc"); PR_Init(PR_USER_THREAD, PR_PRIORITY_NORMAL, 0); switch (cmd) { case ENCRYPT: /* If the intermediate header file already exists, delete it */ if (PR_Access(headerFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { PR_Delete(headerFileName); } /* If the intermediate encrypted already exists, delete it */ if (PR_Access(encryptedFileName, PR_ACCESS_EXISTS) == PR_SUCCESS) { PR_Delete(encryptedFileName); } /* Open DB for read/write and authenticate to it. */ rv = NSS_InitReadWrite(dbdir); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "NSS_InitReadWrite Failed\n"); goto cleanup; } PK11_SetPasswordFunc(GetModulePassword); slot = PK11_GetInternalKeySlot(); if (PK11_NeedLogin(slot)) { rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", PK11_GetTokenName(slot)); goto cleanup; } } rv = EncryptFile(slot, dbdir, inFileName, headerFileName, encryptedFileName, noiseFileName, &pwdata, ascii); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "EncryptFile : Failed\n"); return SECFailure; } break; case DECRYPT: /* Open DB read only, authenticate to it */ PK11_SetPasswordFunc(GetModulePassword); rv = NSS_Init(dbdir); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "NSS_Init Failed\n"); return SECFailure; } slot = PK11_GetInternalKeySlot(); if (PK11_NeedLogin(slot)) { rv = PK11_Authenticate(slot, PR_TRUE, &pwdata); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "Could not authenticate to token %s.\n", PK11_GetTokenName(slot)); goto cleanup; } } rv = DecryptFile(slot, dbdir, outFileName, headerFileName, encryptedFileName, &pwdata, ascii); if (rv != SECSuccess) { PR_fprintf(PR_STDERR, "DecryptFile : Failed\n"); return SECFailure; } break; } cleanup: rvShutdown = NSS_Shutdown(); if (rvShutdown != SECSuccess) { PR_fprintf(PR_STDERR, "Failed : NSS_Shutdown()\n"); rv = SECFailure; } PR_Cleanup(); return rv; }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sample_code/utiltiies_for_nss_samples/index.rst b/security/nss/doc/rst/legacy/nss_sample_code/utiltiies_for_nss_samples/index.rst new file mode 100644 index 0000000000..a1df68437e --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sample_code/utiltiies_for_nss_samples/index.rst @@ -0,0 +1,747 @@ +.. _mozilla_projects_nss_nss_sample_code_utiltiies_for_nss_samples: + +Utilities for nss samples +========================= + +.. _nss_sample_code_0_utilities.: + +`NSS Sample Code 0: Utilities. <#nss_sample_code_0_utilities.>`__ +----------------------------------------------------------------- + +.. container:: + + These utility functions are adapted from those found in the sectool library used by the NSS + security tools and other NSS test applications. + + It shows the following: + + - Read DER from a file. + - Compile file size. + - Get seed From a noise gile. + - Generate random numbers. + - Get a module password. + - Extract the password from a text file. + - Print data as hexadecimal. + +`util.h <#util.h>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + #ifndef _UTIL_H + #define _UTIL_H + + #include <prlog.h> + #include <termios.h> + #include <base64.h> + #include <unistd.h> + #include <sys/stat.h> + #include "util.h" + #include <prprf.h> + #include <prerror.h> + #include <nss.h> + #include <pk11func.h> + + /* + * These utility functions are adapted from those found in + * the sectool library used by the NSS security tools and + * other NSS test applications. + */ + + typedef struct { + enum { + PW_NONE = 0, /* no password */ + PW_FROMFILE = 1, /* password stored in a file */ + PW_PLAINTEXT = 2 /* plain-text password passed in buffer */ + /* PW_EXTERNAL = 3 */ + } source; + char *data; + /* depending on source this can be the actual + * password or the file to read it from + */ + } secuPWData; + + /* + * PrintAsAscii + */ + extern void + PrintAsAscii(PRFileDesc* out, const unsigned char *data, unsigned int len); + + /* + * PrintAsHex + */ + extern void + PrintAsHex(PRFileDesc* out, const unsigned char *data, unsigned int len); + + /* + * GetDigit + */ + extern int + GetDigit(char c); + + /* + * HexToBuf + */ + extern int + HexToBuf(unsigned char *inString, SECItem *outbuf, PRBool isHexData); + + /* + * FileToItem + */ + extern SECStatus + FileToItem(SECItem *dst, PRFileDesc *src); + + /* + * CheckPassword + */ + extern PRBool + CheckPassword(char *cp); + + /* + * GetPassword + */ + extern char * + GetPassword(FILE *input, + FILE *output, + char *prompt, + PRBool (*ok)(char *)); + + /* + * FilePasswd extracts the password from a text file + * + * Storing passwords is often used with server environments + * where prompting the user for a password or requiring it + * to be entered in the commnd line is not a feasible option. + * + * This function supports password extraction from files with + * multipe passwords, one for each token. In the single password + * case a line would just have the passord whereas in the multi- + * password variant they could be of the form + * + * token_1_name:its_password + * token_2_name:its_password + * + */ + extern char * + FilePasswd(PK11SlotInfo * + slot, PRBool retry, void *arg); + + /* + * GetModulePassword + */ + extern char * + GetModulePassword(PK11SlotInfo *slot, + int retry, + void *pwdata); + + /* + * GenerateRandom + */ + extern SECStatus + GenerateRandom(unsigned char *rbuf, + int rsize); + + /* + * FileToItem + */ + extern SECStatus + FileToItem(SECItem *dst, + PRFileDesc *src); + + /* + * SeedFromNoiseFile + */ + extern SECStatus + SeedFromNoiseFile(const char *noiseFileName); + + /* + * FileSize + */ + extern long + FileSize(const char* filename); + + /* + * ReadDERFromFile + */ + extern SECStatus + ReadDERFromFile(SECItem *der, const char *inFileName, PRBool ascii); + + #endif /* _UTIL_H */ + +`Util.c <#util.c>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: c + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ + + #include "util.h" + + /* + * These utility functions are adapted from those found in + * the sectool library used by the NSS security tools and + * other NSS test applications. + */ + + /* + * Newline + */ + static void + Newline(PRFileDesc* out) + { + PR_fprintf(out, "\n"); + } + + /* + * PrintAsAscii + */ + void + PrintAsAscii(PRFileDesc* out, const unsigned char *data, unsigned int len) + { + char *b64Data = NULL; + + b64Data = BTOA_DataToAscii(data, len); + PR_fprintf(out, "%s", b64Data); + PR_fprintf(out, "\n"); + if (b64Data) { + PORT_Free(b64Data); + } + } + + /* + * PrintAsHex + */ + void + PrintAsHex(PRFileDesc* out, const unsigned char *data, unsigned int len) + { + unsigned i; + int column; + unsigned int limit = 15; + unsigned int level = 1; + + column = level; + if (!len) { + PR_fprintf(out, "(empty)\n"); + return; + } + + for (i = 0; i < len; i++) { + if (i != len - 1) { + PR_fprintf(out, "%02x:", data[i]); + column += 3; + } else { + PR_fprintf(out, "%02x", data[i]); + column += 2; + break; + } + if (column > 76 || (i % 16 == limit)) { + Newline(out); + column = level; + limit = i % 16; + } + } + if (column != level) { + Newline(out); + } + } + + /* + * GetDigit + */ + int + GetDigit(char c) + { + if (c == 0) { + return -1; + } + if (c <= '9' && c >= '0') { + return c - '0'; + } + if (c <= 'f' && c >= 'a') { + return c - 'a' + 0xa; + } + if (c <= 'F' && c >= 'A') { + return c - 'A' + 0xa; + } + return -1; + } + + /* + * HexToBuf + */ + int + HexToBuf(unsigned char *inString, SECItem *outbuf, PRBool isHexData) + { + int len = strlen((const char *)inString); + int outLen = len+1/2; + int trueLen = 0; + int digit1, digit2; + + outbuf->data = isHexData + ? PORT_Alloc(outLen) + : PORT_Alloc(len); + if (!outbuf->data) { + return -1; + } + if (isHexData) { + while (*inString) { + if ((*inString == '\n') || (*inString == ':')) { + inString++; + continue; + } + digit1 = GetDigit(*inString++); + digit2 = GetDigit(*inString++); + if ((digit1 == -1) || (digit2 == -1)) { + PORT_Free(outbuf->data); + outbuf->data = NULL; + return -1; + } + outbuf->data[trueLen++] = digit1 << 4 | digit2; + } + } else { + while (*inString) { + if (*inString == '\n') { + inString++; + continue; + } + outbuf->data[trueLen++] = *inString++; + } + outbuf->data[trueLen] = '\0'; + trueLen = trueLen-1; + } + outbuf->len = trueLen; + return 0; + } + + /* + * FileToItem + */ + SECStatus + FileToItem(SECItem *dst, PRFileDesc *src) + { + PRFileInfo info; + PRInt32 numBytes; + PRStatus prStatus; + + prStatus = PR_GetOpenFileInfo(src, &info); + + if (prStatus != PR_SUCCESS) { + return SECFailure; + } + + dst->data = 0; + if (SECITEM_AllocItem(NULL, dst, info.size)) { + numBytes = PR_Read(src, dst->data, info.size); + if (numBytes == info.size) { + return SECSuccess; + } + } + SECITEM_FreeItem(dst, PR_FALSE); + dst->data = NULL; + return SECFailure; + } + + /* + * echoOff + */ + static void echoOff(int fd) + { + if (isatty(fd)) { + struct termios tio; + tcgetattr(fd, &tio); + tio.c_lflag &= ~ECHO; + tcsetattr(fd, TCSAFLUSH, &tio); + } + } + + /* + * echoOn + */ + static void echoOn(int fd) + { + if (isatty(fd)) { + struct termios tio; + tcgetattr(fd, &tio); + tio.c_lflag |= ECHO; + tcsetattr(fd, TCSAFLUSH, &tio); + } + } + + /* + * CheckPassword + */ + PRBool CheckPassword(char *cp) + { + int len; + char *end; + len = PORT_Strlen(cp); + if (len < 8) { + return PR_FALSE; + } + end = cp + len; + while (cp < end) { + unsigned char ch = *cp++; + if (!((ch >= 'A') && (ch <= 'Z')) && + !((ch >= 'a') && (ch <= 'z'))) { + return PR_TRUE; + } + } + return PR_FALSE; + } + + /* + * GetPassword + */ + char* GetPassword(FILE *input, FILE *output, char *prompt, + PRBool (*ok)(char *)) + { + char phrase[200] = {'\0'}; + int infd = fileno(input); + int isTTY = isatty(infd); + + for (;;) { + /* Prompt for password */ + if (isTTY) { + fprintf(output, "%s", prompt); + fflush (output); + echoOff(infd); + } + fgets(phrase, sizeof(phrase), input); + if (isTTY) { + fprintf(output, "\n"); + echoOn(infd); + } + /* stomp on newline */ + phrase[PORT_Strlen(phrase)-1] = 0; + /* Validate password */ + if (!(*ok)(phrase)) { + if (!isTTY) return 0; + fprintf(output, "Password must be at least 8 characters long with one or more\n"); + fprintf(output, "non-alphabetic characters\n"); + continue; + } + return (char*) PORT_Strdup(phrase); + } + } + + /* + * FilePasswd extracts the password from a text file + * + * Storing passwords is often used with server environments + * where prompting the user for a password or requiring it + * to be entered in the commnd line is not a feasible option. + * + * This function supports password extraction from files with + * multipe passwords, one for each token. In the single password + * case a line would just have the passord whereas in the multi- + * password variant they could be of the form + * + * token_1_name:its_password + * token_2_name:its_password + * + */ + char * + FilePasswd(PK11SlotInfo *slot, PRBool retry, void *arg) + { + char* phrases, *phrase; + PRFileDesc *fd; + PRInt32 nb; + char *pwFile = arg; + int i; + const long maxPwdFileSize = 4096; + char* tokenName = NULL; + int tokenLen = 0; + + if (!pwFile) + return 0; + + if (retry) { + return 0; /* no good retrying - the files contents will be the same */ + } + + phrases = PORT_ZAlloc(maxPwdFileSize); + + if (!phrases) { + return 0; /* out of memory */ + } + + fd = PR_Open(pwFile, PR_RDONLY, 0); + if (!fd) { + fprintf(stderr, "No password file \"%s\" exists.\n", pwFile); + PORT_Free(phrases); + return NULL; + } + + nb = PR_Read(fd, phrases, maxPwdFileSize); + + PR_Close(fd); + + if (nb == 0) { + fprintf(stderr,"password file contains no data\n"); + PORT_Free(phrases); + return NULL; + } + + if (slot) { + tokenName = PK11_GetTokenName(slot); + if (tokenName) { + tokenLen = PORT_Strlen(tokenName); + } + } + i = 0; + do { + int startphrase = i; + int phraseLen; + + /* handle the Windows EOL case */ + while (phrases[i] != '\r' && phrases[i] != '\n' && i < nb) i++; + + /* terminate passphrase */ + phrases[i++] = '\0'; + /* clean up any EOL before the start of the next passphrase */ + while ( (i<nb) && (phrases[i] == '\r' || phrases[i] == '\n')) { + phrases[i++] = '\0'; + } + /* now analyze the current passphrase */ + phrase = &phrases[startphrase]; + if (!tokenName) + break; + if (PORT_Strncmp(phrase, tokenName, tokenLen)) continue; + phraseLen = PORT_Strlen(phrase); + if (phraseLen < (tokenLen+1)) continue; + if (phrase[tokenLen] != ':') continue; + phrase = &phrase[tokenLen+1]; + break; + + } while (i<nb); + + phrase = PORT_Strdup((char*)phrase); + PORT_Free(phrases); + return phrase; + } + + /* + * GetModulePassword + */ + char* GetModulePassword(PK11SlotInfo *slot, int retry, void *arg) + { + char prompt[255]; + secuPWData *pwdata = (secuPWData *)arg; + char *pw; + + if (pwdata == NULL) { + return NULL; + } + + if (retry && pwdata->source != PW_NONE) { + PR_fprintf(PR_STDERR, "Incorrect password/PIN entered.\n"); + return NULL; + } + + switch (pwdata->source) { + case PW_NONE: + sprintf(prompt, "Enter Password or Pin for \"%s\":", + PK11_GetTokenName(slot)); + return GetPassword(stdin, stdout, prompt, CheckPassword); + case PW_FROMFILE: + pw = FilePasswd(slot, retry, pwdata->data); + pwdata->source = PW_PLAINTEXT; + pwdata->data = PL_strdup(pw); + return pw; + case PW_PLAINTEXT: + return PL_strdup(pwdata->data); + default: + break; + } + PR_fprintf(PR_STDERR, "Password check failed: No password found.\n"); + return NULL; + } + + /* + * GenerateRandom + */ + SECStatus + GenerateRandom(unsigned char *rbuf, int rsize) + { + char meter[] = { + "\r| |" }; + int fd, count; + int c; + SECStatus rv = SECSuccess; + cc_t orig_cc_min; + cc_t orig_cc_time; + tcflag_t orig_lflag; + struct termios tio; + + fprintf(stderr, "To generate random numbers, " + "continue typing until the progress meter is full:\n\n"); + fprintf(stderr, "%s", meter); + fprintf(stderr, "\r|"); + + /* turn off echo on stdin & return on 1 char instead of NL */ + fd = fileno(stdin); + + tcgetattr(fd, &tio); + orig_lflag = tio.c_lflag; + orig_cc_min = tio.c_cc[VMIN]; + orig_cc_time = tio.c_cc[VTIME]; + tio.c_lflag &= ~ECHO; + tio.c_lflag &= ~ICANON; + tio.c_cc[VMIN] = 1; + tio.c_cc[VTIME] = 0; + tcsetattr(fd, TCSAFLUSH, &tio); + /* Get random noise from keyboard strokes */ + count = 0; + while (count < rsize) { + c = getc(stdin); + if (c == EOF) { + rv = SECFailure; + break; + } + *(rbuf + count) = c; + if (count == 0 || c != *(rbuf + count -1)) { + count++; + fprintf(stderr, "*"); + } + } + rbuf[count] = '\0'; + + fprintf(stderr, "\n\nFinished. Press enter to continue: "); + while ((c = getc(stdin)) != '\n' && c != EOF) + ; + if (c == EOF) + rv = SECFailure; + fprintf(stderr, "\n"); + + /* set back termio the way it was */ + tio.c_lflag = orig_lflag; + tio.c_cc[VMIN] = orig_cc_min; + tio.c_cc[VTIME] = orig_cc_time; + tcsetattr(fd, TCSAFLUSH, &tio); + return rv; + } + + /* + * SeedFromNoiseFile + */ + SECStatus + SeedFromNoiseFile(const char *noiseFileName) + { + char buf[2048]; + PRFileDesc *fd; + PRInt32 count; + + fd = PR_Open(noiseFileName, PR_RDONLY, 0); + if (!fd) { + fprintf(stderr, "failed to open noise file."); + return SECFailure; + } + + do { + count = PR_Read(fd,buf,sizeof(buf)); + if (count > 0) { + PK11_RandomUpdate(buf,count); + } + } while (count > 0); + + PR_Close(fd); + return SECSuccess; + } + + /* + * FileSize + */ + long FileSize(const char* filename) + { + struct stat stbuf; + stat(filename, &stbuf); + return stbuf.st_size; + } + + /* + * ReadDERFromFile + */ + SECStatus + ReadDERFromFile(SECItem *der, const char *inFileName, PRBool ascii) + { + SECStatus rv = SECSuccess; + PRFileDesc *inFile = NULL; + + inFile = PR_Open(inFileName, PR_RDONLY, 0); + if (!inFile) { + PR_fprintf(PR_STDERR, "Failed to open file \"%s\" (%ld, %ld).\n", + inFileName, PR_GetError(), PR_GetOSError()); + rv = SECFailure; + goto cleanup; + } + + if (ascii) { + /* First convert ascii to binary */ + SECItem filedata; + char *asc, *body; + + /* Read in ascii data */ + rv = FileToItem(&filedata, inFile); + asc = (char *)filedata.data; + if (!asc) { + PR_fprintf(PR_STDERR, "unable to read data from input file\n"); + rv = SECFailure; + goto cleanup; + } + + /* check for headers and trailers and remove them */ + if ((body = strstr(asc, "-----BEGIN")) != NULL) { + char *trailer = NULL; + asc = body; + body = PORT_Strchr(body, '\n'); + if (!body) + body = PORT_Strchr(asc, '\r'); /* maybe this is a MAC file */ + if (body) + trailer = strstr(++body, "-----END"); + if (trailer != NULL) { + *trailer = '\0'; + } else { + PR_fprintf(PR_STDERR, "input has header but no trailer\n"); + PORT_Free(filedata.data); + rv = SECFailure; + goto cleanup; + } + } else { + body = asc; + } + + /* Convert to binary */ + rv = ATOB_ConvertAsciiToItem(der, body); + if (rv) { + PR_fprintf(PR_STDERR, "error converting ascii to binary %s\n", + PORT_GetError()); + PORT_Free(filedata.data); + rv = SECFailure; + goto cleanup; + } + + PORT_Free(filedata.data); + } else { + /* Read in binary der */ + rv = FileToItem(der, inFile); + if (rv) { + PR_fprintf(PR_STDERR, "error converting der \n"); + rv = SECFailure; + } + } + cleanup: + if (inFile) { + PR_Close(inFile); + } + return rv; + }
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_sources_building_testing/index.rst b/security/nss/doc/rst/legacy/nss_sources_building_testing/index.rst new file mode 100644 index 0000000000..bb92d90391 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_sources_building_testing/index.rst @@ -0,0 +1,123 @@ +.. _mozilla_projects_nss_nss_sources_building_testing: + +NSS sources building testing +============================ + +.. container:: + + Getting the source code of :ref:`mozilla_projects_nss`, how to build it, and how to run its test + suite. + +.. _getting_source_code_and_a_quick_overview: + +`Getting source code, and a quick overview <#getting_source_code_and_a_quick_overview>`__ +----------------------------------------------------------------------------------------- + +.. container:: + + The easiest way is to download archives of NSS releases from `Mozilla's download + server <https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/>`__. Find the directory + that contains the highest version number. Because NSS depends on the base library + `NSPR <https://developer.mozilla.org/en-US/docs/NSPR>`__, you should download the archive that + combines both NSS and NSPR. + + If you are a software developer and intend to contribute enhancements to NSS, you should obtain + the latest development snapshot of NSS using mercurial/hg (a `distributed source control + management tool <https://www.mercurial-scm.org/>`__). In order to get started, anonymous + read-only access is sufficient. Create a new directory on your computer that you will use as your + local work area, and run the following commands. + + .. code:: sh + + hg clone https://hg.mozilla.org/projects/nspr + hg clone https://hg.mozilla.org/projects/nss + + After the above commands complete, you should have two local directories, named nspr and nss, + next to each other. + + (Historical information: NSPR and NSS source code have recently been re-organized into a new + directory structure. In past versions, all files were located in a directory hierarchy that + started with the "mozilla" prefix. The NSPR base library was located in directory + mozilla/nsprpub. The subdirectories dbm, security/dbm, security/coreconf, security/nss were part + of the NSS sources.) + + The nss directory contains the following important subdirectories: + + - nss/coreconf + Contains knowledge for cross platform building. + - nss/lib + Contains all the library code that is used to create the runtime libraries used by + applications. + - nss/cmd + Contains a set of various tool programs that are built using NSS. Several tools are general + purpose and can be used to inspect and manipulate the storage files that software using the + NSS library creates and modifies. Other tools are only used for testing purposes. However, all + these tools are good examples of how to write software that makes use of the NSS library. + - nss/test + This directory contains the NSS test suite, which is routinely used to ensure that changes to + NSS don't introduce regressions. + - nss/gtests + Code for NSS unit tests running in `Googletest <https://github.com/abseil/googletest>`__. + + It is important to mention the difference between internal NSS code and exported interfaces. + Software that would like to use the NSS library must use only the exported interfaces. These can + be found by looking at the files with the .def file extension, inside the nss/lib directory + hierarchy. Any C function that isn't contained in .def files is strictly for private use within + NSS, and applications and test tools are not allowed to call them. For any functions that are + listed in the .def files, NSS promises that the binary function interface (ABI) will remain + stable. + +.. _building_nss: + +`Building NSS <#building_nss>`__ +-------------------------------- + +.. container:: + + NSS is built using `gyp <https://gyp.gsrc.io/>`__ and `ninja <https://ninja-build.org/>`__, or + with `make <https://www.gnu.org/software/make/>`__ on systems that don't have those tools. The + :ref:`mozilla_projects_nss_building` include more information. + + Once the build is done, you can find the build output below directory dist/?, where ? will be a + name dynamically derived from your system's architecture. Exported header files for NSS + applications can be found in directory "include", library files in directory "lib", and the tools + in directory "bin". In order to run the tools, you should set your system environment to use the + libraries of your build from the "lib" directory, e.g., using the LD_LIBRARY_PATH or + DYLD_LIBRARY_PATH environment variable. + +.. _running_the_nss_test_suite: + +`Running the NSS test suite <#running_the_nss_test_suite>`__ +------------------------------------------------------------ + +.. container:: + + This is an important part of development work, in order to ensure your changes don't introduce + regressions. When adding new features to NSS, tests for the new feature should be added as well. + + You must build NSS prior to running the tests. After the build on your computer has succeeded, + before you can run the tests on your computer, it might be necessary to set additional + environment variables. The NSS tests will start TCP/IP server tools on your computer, and in + order for that to work, the NSS test suite needs to know which hostname can be used by client + tools to connect to the server tools. On machines that are configured with a hostname that has + been registered in your network's DNS, this should work automatically. In other environments (for + example in home networks), you could set the HOST and DOMSUF (for domain suffix) environment + variables to tell the NSS suite which hostname to use. As a test, it must be possible to + successfully use the command "ping $HOST.$DOMSUF" on your computer (ping reports receiving + replies). On many computers the variables HOST=localhost DOMSUF=localdomain works. In case you + built NSS in 64 bits, you need to set the USE_64 environment variable to 1 to run the tests. If + you get name resolution errors, try to disable IPv6 on the loopback device. + + After you have set the required environment variables, use "cd nss/tests" and start the tests + using "./all.sh". The tests will take a while to complete; on a slow computer it could take a + couple of hours. + + Once the test suite has completed, a summary will be printed that shows the number of failures. + You can find the test suite results in directory nss/../tests_results (i.e. the results directory + ends up next to the nss directory, not within it). Each test suite execution will create a new + subdirectory; you should clean them up from time to time. Inside the directory you'll find text + file output.log, which contains a detailed report of all tests being executed. In order to learn + about the details of test failures, search the file for the uppercase test FAILED. + + If desired, it's possible to run only subsets of the tests. Read the contents of file all.sh to + learn how that works.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/index.rst new file mode 100644 index 0000000000..ddd92f87cd --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/index.rst @@ -0,0 +1,23 @@ +.. _mozilla_projects_nss_nss_tech_notes: + +NSS Tech Notes +============== + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + NSS technical notes provide latest information about new NSS features and supplementary + documentation for advanced topics in programming with NSS. + + #. TN1: `How to use the NSS ASN.1 and QuickDER decoders <nss_tech_notes/nss_tech_note1>`__. + #. TN2: `Using the PKCS #11 Module Logger <nss_tech_notes/nss_tech_note2>`__. + #. TN3: `All About Certificate Extensions <nss_tech_notes/nss_tech_note3>`__. + #. TN4: `Pulling certificate extension information out of SSL + certificates <nss_tech_notes/nss_tech_note4>`__. + #. TN5: `Using NSS to perform miscellaneous cryptographic + operations <nss_tech_notes/nss_tech_note5>`__. + #. TN6: `NSS .chk Files for the FIPS Mode <nss_tech_notes/nss_tech_note6>`__. + #. TN7: `RSA Signing and Encryption with NSS <nss_tech_notes/nss_tech_note7>`__. + #. TN8: `Background Information on libSSL's Cache Functions and + SIDs <nss_tech_notes/nss_tech_note8>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note1/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note1/index.rst new file mode 100644 index 0000000000..3b8313fd3a --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note1/index.rst @@ -0,0 +1,196 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note1: + +nss tech note1 +============== + +.. _how_to_use_the_nss_asn.1_and_quickder_decoders: + +`How to use the NSS ASN.1 and QuickDER decoders <#how_to_use_the_nss_asn.1_and_quickder_decoders>`__ +---------------------------------------------------------------------------------------------------- + +.. container:: + +.. _nss_technical_note_1: + +`NSS Technical Note: 1 <#nss_technical_note_1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS 3.6 contains several decoders for ASN.1 and DER.Two of them are extensively used and are part + of the public NSS API : + + #. The "classic" ASN.1 decoder, written by Lisa Repka . This was written to be a generic decoder, + that includes both DER (Distinguished Encoding Rules) and BER (Basic Encoding Rules).† It + handles both streaming and non-streaming input. + #. The "QuickDER" decoder, written by Julien Pierre for NSS 3.6 . This decoder was written when + performance issues were discovered with the classic decoder. It can only decode DER .† It does + not handle streaming input, and requires that all input be present before beginning to decode. + + Despite their differences, the two decoders have a lot in common. QuickDER was written to be as + compatible as possible with the classic decoder, in order to ease migration to it in areas of + critical performance bottlenecks. For this reason, I will first describe all the common + functionality of the two decoders, before outlining their differences. + The main non-streaming APIs for these two decoders have an identical prototype : + + - SECStatus SEC_ASN1DecodeItem(PRArenaPool \*pool, void \*dest, const SEC_ASN1Template \*t, + SECItem \*item); + - SECStatus SEC_QuickDERDecodeItem(PRArenaPool\* arena, void\* dest, const SEC_ASN1Template\* + templateEntry, SECItem\* src); + + Here is a description of the arguments : + + - *SECItem\* src*\ † is a structure containing a pointer to the binary data to be decoded, as + well as its size. + - *const SEC_ASN1Template\* templateEntry* is a pointer to one or more `decoder + templates <#templates>`__. The number of required templates is determined by the type of the + first template.When multiple templates are required, the pointer must point to a + NULL-terminated array of templates. The syntax of these templates is identical for both + decoders, except where noted. A "NULL Template" is a template that is all zeros, having a zero + kind.† The term "NULL-terminated array", as used throughout this document, means an array of + templates, the last of which is a NULL template. + - *void\* dest* is a pointer to the target area. This is where the decoder stores its output. + The type is undefined as it is completely dependent on the content of the decoder templates.† + This typically points to a struct that is described (or partially described) by the templates. + - *PRArenaPool\* arena* is a pointer to an NSPR arena pool. This is the arena pool from which + the decoder will allocate memory as needed. + + Decoder templates : + The SEC_ASN1Template structure tells the decoder what to do with the input data. This structure + contains four fields : + + - *kind* . This 32-bit field tells the decoder what to do with a particular component within the + input data. It is made of two parts : the lower byte, which can contain `ASN.1 + tags <#asn.1_tags>`__, and the upper 3 bytes, which can contain `decoder + modifiers <#decoder_modifiers>`__. If only an ASN.1 tag is specified without a modifier, then + the decoder will enforce the presence of a component of that type, and fail if it does not + match. If kind is an ASN.1 SEQUENCE tag (SEC_ASN1_SEQUENCE), then you must specify additional + templates in a NULL-terminated array to define the content of the of the ASN.1 SEQUENCE. If + kind is the SEC_ASN1_CHOICE modifier, you must also specify additional templates in a NULL + terminated array to list the various possible types that this component can have. In all other + cases, only the first template structure passed to the decoder will be considered, even if + additonal templates are passed in an array. When only one template is needed, you do not need + a NULL template to terminate the array. + - *offset*\ † . This field does not apply to all template types. It is only needed if the + template instructs the decoder to save some data, such as for primitive component types, or + for some modifiers where noted.When needed, it tells the decoder where in the target data to + save the current component. It is normally relative to the dest argument passed to the + decoder. If templates are nested, the offset applies to the location of the current component + within the target component, typically the decoded SEQUENCE. + - *sub*\ † . This field does not apply to all template types. If kind contains the + SEC_ASN1_INLINE or SEC_ASN1_POINTER modifiers, then it must point to the required subtemplate. + If kind contains the SEC_ASN1_XTRN or SEC_ASN1_DYNAMIC modifiers, this is a pointer to a + callback function that will dynamically return the required subtemplate. + - *size*\ † . This field does not apply to all template types. It is only required for + dynamically allocating memory for the structure if the template is being included from an + ASN.1 SEQUENCE or SEQUENCE OF, or if dynamic allocation was requested from the parent template + using the SEC_ASN1_POINTER modifier + + Here is a description of the various tags and modifiers that apply to the kind field. + *ASN.1 tags* + + | ASN.1 tags are specified in the lower byte of the kind field of the template, as noted above. + | The following is not an attempt to explain ASN.1 tags or their purposes. Rather, the goal here + is to explain what type of tags the decoder supports and which macros should be used when + defining tags in decoder templates. It should be noted that we only support an older + specification of ASN.1; multibyte tags are not currently supported. + + The 8-bit ASN.1 tags that we support are made of three parts : + + #. The ASN.1 component class type. It is specified in the upper 2 tag bits (number 6 and 7). + There are four classes of ASN.1 tags : universal, application-specific, context-specific, and + private. You can specify the class of the tag using the macros SEC_ASN1_UNIVERSAL, + SEC_ASN1_APPLICATION, SEC_ASN1_CONTEXT_SPECIFIC and SEC_ASN1_PRIVATE. Universal is the default + tag class and does not have to be specified, as the value of the class type is zero. + + #. The method type : whether the component type is constructed or primitive. This information is + stored in the next lowest tag bit (number 5). You can use the macro SEC_ASN1_CONSTRUCTED for a + constructed component type. A SEC_ASN1_PRIMITIVE macro is also provided, but does not need to + be included as it is zero. + + #. | The tag number. It is stored in the lower 5 tag bits (number 0 through 4). The ASN.1 + standard only defines tag numbers in the universal class. If you are using a tag of a + different classes, you can define your own tag number macros or specify the tag value within + the template definition. The following macros are provided for tag numbers within the + universal class : + | SEC_ASN1_BOOLEAN, SEC_ASN1_INTEGER, SEC_ASN1_BIT_STRING, SEC_ASN1_OCTET_STRING, + SEC_ASN1_NULL, SEC_ASN1_OBJECT_ID, SEC_ASN1_OBJECT_DESCRIPTOR,† SEC_ASN1_REAL, + SEC_ASN1_ENUMERATED, SEC_ASN1_EMBEDDED_PDV, SEC_ASN1_UTF8_STRING, SEC_ASN1_SEQUENCE, + SEC_ASN1_SET, SEC_ASN1_NUMERIC_STRING, SEC_ASN1_PRINTABLE_STRING, SEC_ASN1_T61_STRING, + SEC_ASN1_TELETEX_STRING, SEC_ASN1_T61_STRING, SEC_ASN1_VIDEOTEX_STRING, SEC_ASN1_IA5_STRING, + SEC_ASN1_UTC_TIME, SEC_ASN1_GENERALIZED_TIME, SEC_ASN1_GRAPHIC_STRING, + SEC_ASN1_VISIBLE_STRING, SEC_ASN1_GENERAL_STRING, SEC_ASN1_UNIVERSAL_STRING, + SEC_ASN1_BMP_STRING + + Note that for SEC_ASN1_SET and SEC_ASN1_SEQUENCE types, you must also include the method type + macro SEC_ASN1_CONSTRUCTED to construct a fully valid tag, as defined by the ASN.1 standard . + + *Decoder modifiers :* + These modifiers are also specified in the kind field of the template structure. All the values + are in the 9 - 31 bit range. + + - *SEC_ASN1_OPTIONAL*: tells the decoder that this component is optional. If the component in + the input data does not match this template, the decoder will continue processing the input + data using the next available template. + - *SEC_ASN1_EXPLICIT*: tells the decoder that explicit tagging is being used. This is always a + constructed type. It requires a subtemplate defining the types of the data within. + - *SEC_ASN1_ANY*: allows the decoder to match this template with any component type, regardless + of the tag in the input data. If used in conjunction with SEC_ASN1_OPTIONAL as part of a + sequence, this must be the last template in the template array. + - *SEC_ASN1_INLINE*: recurse into the specified subtemplate to continue processing. This is + typically used for SEC_ASN1_SEQUENCE or SEC_ASN1_CHOICE definitions, which always need to be + the first template in a template array of their own. + - *SEC_ASN1_POINTER*: similar to SEC_ASN1_INLINE, except that the memory in the target will be + allocated dynamically and a pointer to the dynamically allocated memory will be stored in the + *dest* struct at the *offset*. This requires that the subtemplate contains a non-zero size + field. + - *SEC_ASN1_GROUP*: can only be used in conjunction with a SEC_ASN1_SET or SEC_ASN1_SEQUENCE. It + tells the decoder that the component is an ASN.1 SET OF or SEQUENCE OF respectively. You can + also use the macros SEC_ASN1_SET_OF and SEC_ASN1_SEQUENCE_OF which define both the tag number + and this modifier (but still need the method type, this may be a bug). + - *SEC_ASN1_DYNAMIC* or *SEC_ASN1_XTRN* : specifies that the component format is defined in a + dynamic subtemplate. There is no difference between the two macros. The sub field of the + template points to a callback function of type SEC_ASN1TemplateChooser that returns the + subtemplate depending on the component data. + - *SEC_ASN1_SKIP*: specifies that the decoder should skip decoding of the component. + SEC_ASN1DecodeItem can only skip required components and will assert if you try to skip an + OPTIONAL component. SEC_QuickDERDecodeItem supports skipping the decoding of OPTIONAL + components if you define the tag of the component in the template + - *SEC_ASN1_INNER*: recurse into the component and saves its content, without the surrounding + ASN.1 tag and length + - *SEC_ASN1_SAVE*: saves the component data, but does not proceed to the next component if + within a SEQUENCE template array. This means the next template will reprocess the same + component. + - *SEC_ASN1_SKIP_REST*: abort the decoding. This is used in a template array within a SEQUENCE, + if you don't care about the fields at the end of it. SEC_ASN1DecodeItem only supports this + modifier in the top-level template. SEC_QuickDERDecodeItem allows it at any nested sublevel. + - *SEC_ASN1_CHOICE*: allows decoding of components that are of variable type. This must be the + first template in a NULL-terminated array. The offset parameter specifies where to store the + type identifier in the target data . Subsequent templates specify a custom identifier for each + possible component type in the size parameter . + - *SEC_ASN1_DEBUG_BREAK*: makes the decoder assert when processing the template. This option is + only supported with SEC_QuickDERDecodeItem . It is useful to debug your templates or when + writing new templates if they don't work. + + | + | *Differences between SEC_ASN1DecodeItem and SEC_QuickDERDecodeItem* + + #. The arena argument is required to be non-NULL for SEC_QuickDERDecodeItem . With + SEC_ASN1DecodeItem, it can be NULL, and if so, the decoder will allocate from the heap using + PR_Malloc . However, this usage is strongly discouraged and we recommend that you always use + an arena pool even with SEC_ASN1DecodeItem. See `bug + 175163 <http://bugzilla.mozilla.org/show_bug.cgi?id=175163>`__ for more information about the + reason for this recommendation. + #. SEC_ASN1DecodeItem will make a copy of the input data into the decoded target as needed, while + SEC_QuickDERDecodeItem will generate output with pointers into the input. This means that if + you use SEC_QuickDERDecodeItem, you must always be careful not to free the input as long as + you intend to use the decoded structure. Ideally, you should allocate the input data out of + the same arena that you are passing to the decoder. This will allow you to free both the input + data and the decoded data at once when freeing the arena. + #. SEC_ASN1DecodeItem can decode both BER and DER data, while SEC_QuickDERDecodeItem can only + decode DER data. + #. SEC_QuickDERDecodeItem does not support streaming data. This feature will most likely never be + added, as this decoder gets most of its extra speed from not making a copy of the input data, + which would be required when streaming. + #. SEC_QuickDERDecodeItem supports SEC_ASN1_OPTIONAL together with SEC_ASN1_SKIP + #. SEC_ASN1_DEBUG_BREAK is not supported by SEC_ASN1DecodeItem
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note2/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note2/index.rst new file mode 100644 index 0000000000..efc80ff3a4 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note2/index.rst @@ -0,0 +1,167 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note2: + +nss tech note2 +============== + +.. container:: + + .. rubric:: Using the PKCS #11 Module Logger + :name: Using_the_PKCS_11_Module_Logger + +.. _nss_technical_note_2: + +`NSS Technical Note: 2 <#nss_technical_note_2>`__ +------------------------------------------------- + +.. container:: + + - `Modes of Operation <#modes>`__ + - `Extracting Output from Log files <#extracting>`__ + + The logger displays all activity between NSS and a specified PKCS #11 module. It works by + inserting a special set of entry points between NSS and the module. + + To enable the module logger, you must set the environment variable NSS_DEBUG_PKCS11_MODULE to the + name of the target module. For example, to log the softoken, use: + + .. code:: + + NSS_DEBUG_PKCS11_MODULE="NSS Internal PKCS #11 Module" + + Note: In the Command Prompt on Windows, do not quote the name of the target module, otherwise the + quotes are considered part of the name. For example, to log the softoken on Windows, use: + + .. code:: + + set NSS_DEBUG_PKCS11_MODULE=NSS Internal PKCS #11 Module + + The logger is available by default in debug builds. For optimized builds, NSS must be built with + the variable DEBUG_PKCS11 set. + +.. _modes_of_operation: + +`Modes of Operation <#modes_of_operation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The logger has several modes of operation: + + **1. Only display the sequence of PKCS #11 calls.** To enable this mode, set: + + .. code:: + + NSPR_LOG_MODULES=nss_mod_log:1 + NSPR_LOG_FILE=<logfile> + + The output format is: + + .. code:: + + OSThreadID[NSPRThreadID]: C_XXX + OSThreadID[NSPRThreadID]: rv = 0xYYYYYYYY + + For example, + + .. code:: + + 1024[805ef10]: C_Initialize + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_GetInfo + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_GetSlotList + 1024[805ef10]: rv = 0x0 + + **2. Display the sequence of PKCS #11 calls, and the parameters given to them.** To enable this + mode, set: + + .. code:: + + NSPR_LOG_MODULES=nss_mod_log:3 + NSPR_LOG_FILE=<logfile> + + The output format is: + + .. code:: + + OSThreadID[NSPRThreadID]: C_XXX + OSThreadID[NSPRThreadID]: arg1 = 0xAAAAAAAA + ... + OSThreadID[NSPRThreadID]: argN = 0xAAAAAAAA + OSThreadID[NSPRThreadID]: rv = 0xYYYYYYYY + + For example, + + .. code:: + + 1024[805ef10]: C_Initialize + 1024[805ef10]: pInitArgs = 0x4010c938 + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_GetInfo + 1024[805ef10]: pInfo = 0xbffff340 + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_GetSlotList + 1024[805ef10]: tokenPresent = 0x0 + 1024[805ef10]: pSlotList = 0x0 + 1024[805ef10]: pulCount = 0xbffff33c + 1024[805ef10]: *pulCount = 0x2 + 1024[805ef10]: rv = 0x0 + + Note that when a PKCS #11 function takes a pointer argument for which it will set a value + (C_GetSlotList above), this mode will display the value upon return. + + **3. Display verbose information, including template values, array values, etc.** To enable this + mode, set: + + .. code:: + + NSPR_LOG_MODULES=nss_mod_log:4 + NSPR_LOG_FILE=<logfile> + + The output format is the same as above, but with more information. For example, + + .. code:: + + 1024[805ef10]: C_FindObjectsInit + 1024[805ef10]: hSession = 0x1000001 + 1024[805ef10]: pTemplate = 0xbffff410 + 1024[805ef10]: ulCount = 3 + 1024[805ef10]: CKA_LABEL = localhost.nyc.rr.com [20] + 1024[805ef10]: CKA_TOKEN = CK_TRUE [1] + 1024[805ef10]: CKA_CLASS = CKO_CERTIFICATE [4] + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_FindObjects + 1024[805ef10]: hSession = 0x1000001 + 1024[805ef10]: phObject = 0x806d810 + 1024[805ef10]: ulMaxObjectCount = 16 + 1024[805ef10]: pulObjectCount = 0xbffff38c + 1024[805ef10]: *pulObjectCount = 0x1 + 1024[805ef10]: phObject[0] = 0xf6457d04 + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_FindObjectsFinal + 1024[805ef10]: hSession = 0x1000001 + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_GetAttributeValue + 1024[805ef10]: hSession = 0x1000001 + 1024[805ef10]: hObject = 0xf6457d04 + 1024[805ef10]: pTemplate = 0xbffff2d0 + 1024[805ef10]: ulCount = 2 + 1024[805ef10]: CKA_TOKEN = 0 [1] + 1024[805ef10]: CKA_LABEL = 0 [20] + 1024[805ef10]: rv = 0x0 + 1024[805ef10]: C_GetAttributeValue + 1024[805ef10]: hSession = 0x1000001 + 1024[805ef10]: hObject = 0xf6457d04 + 1024[805ef10]: pTemplate = 0xbffff2d0 + 1024[805ef10]: ulCount = 2 + 1024[805ef10]: CKA_TOKEN = CK_TRUE [1] + 1024[805ef10]: CKA_LABEL = localhost.nyc.rr.com [20] + 1024[805ef10]: rv = 0x0 + + **4. Collect performance data.** This mode is most useful in optimized builds. The number of + calls to each PKCS #11 function will be counted, and the time spent in each function as well. A + summary of performance data is dumped during NSS shutdown. + + No additional environment variables are required for this mode. If the environment variable + NSS_OUTPUT_FILE is set, its value will be used as the path name of the file to which the final + output will be written. Otherwise, the output will be written to stdout.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note3/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note3/index.rst new file mode 100644 index 0000000000..2d72c870cc --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note3/index.rst @@ -0,0 +1,234 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note3: + +nss tech note3 +============== + +.. _all_about_certificate_extensions: + +`All About Certificate Extensions <#all_about_certificate_extensions>`__ +------------------------------------------------------------------------ + +.. container:: + +.. _nss_technical_note_3: + +`NSS Technical Note: 3 <#nss_technical_note_3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + 09 May 2002 + Nelson B. Bolyard + + This week at least 5 different people came to me with variants of the + same question: + + What certificate extensions do I have to put into my cert for NSS to + allow it to be used for purpose <x>?? + + This message attempts to answer that question, and to document NSS's + approach to validating certificates for certain purposes. + + When NSS is asked to verify the validity of a certificate chain, it + verifies the validity of that cert chain for a particular purpose, + known as a SECCertUsage, as of a specific date and time. + + The list of known SECCertUsages is short: + + certUsageSSLClient ........... An SSL client authentication cert + certUsageSSLServer ........... An ordinary SSL server cert + certUsageSSLServerWithStepUp.. An SSL server cert that allows export + clients to use strong crypto. + certUsageSSLCA ............... An intermediate or root CA cert allowed + to issue SSL client or SSL server certs + or other intermediate SSL CA certs. + certUsageEmailSigner ......... Used to verify S/MIME email signatures + certUsageEmailRecipient ...... Used to encrypt S/MIME emails. + certUsageObjectSigner ........ Used to verify signatures on files of + executable code, e.g. jar files. + certUsageStatusResponder ..... Used by an OCSP responder + certUsageVerifyCA ............ A CA of any kind. + + Each cert has a "type" and a "key usage", each of which may contain one + or more valid values. + + Each of the above SECCertUsages translates into a required set of + cert type and key usage for the certificate itself, and into another + set of required cert type and key usage for all the CA certs in the + cert chain. + + To determine if a cert is valid for a given cert usage, it must have the + the cert type and key usage required for that cert usage, and all the + CA certs in the cert chain must have the cert type and key usage required + for CA certs for that cert usage. + + There are 8 Key Usages: + CERT_SIGN + CRL_SIGN + DATA_ENCIPHERMENT + DIGITAL_SIGNATURE + GOVT_APPROVED + KEY_AGREEMENT + KEY_ENCIPHERMENT + NON_REPUDIATION + + There are 9 Cert types: + EMAIL + EMAIL_CA + OBJECT_SIGNING + OBJECT_SIGNING_CA + SSL_CA + SSL_CLIENT + SSL_SERVER + STATUS_RESPONDER + TIME_STAMP + + + For the cert being checked, the requirements are: + + Cert Usage Requried Key Usage Required Cert Type + -------------------- -------------------- ----------------------- + SSLClient: DIGITAL_SIGNATURE; SSL_CLIENT; + + SSLServer: KEY_AGREEMENT OR + KEY_ENCIPHERMENT; SSL_SERVER; + + SSLServerWithStepUp: GOVT_APPROVED AND SSL_SERVER + KEY_AGREEMENT or + KEY_ENCIPHERMENT + + SSLCA: CERT_SIGN; SSL_CA; + + EmailSigner: DIGITAL_SIGNATURE; EMAIL; + + EmailRecipient: KEY_AGREEMENT OR + KEY_ENCIPHERMENT; EMAIL; + + ObjectSigner: DIGITAL_SIGNATURE; OBJECT_SIGNING; + + StatusResponder: DIGITAL_SIGNATURE; STATUS_RESPONDER; + + VerifyCA CERT_SIGN SSL_CA OR + EMAIL_CA OR + OBJECT_SIGNING_CA OR + STATUS_RESPONDER + + For CA certs in the cert chain, the requirements are: + + Cert Usage Requried Key Usage Required Cert Type + -------------------- -------------------- ----------------------- + SSLServerWithStepUp: GOVT_APPROVED AND + CERT_SIGN; SSL_CA; + + SSLClient: CERT_SIGN; SSL_CA; + + SSLServer: CERT_SIGN; SSL_CA; + + SSLCA: CERT_SIGN; SSL_CA; + + EmailSigner: CERT_SIGN; EMAIL_CA or SSL_CA + + EmailRecipient: CERT_SIGN; EMAIL_CA or SSL_CA + + ObjectSigner: CERT_SIGN; OBJECT_SIGNING_CA; + + UsageAnyCA: CERT_SIGN; OBJECT_SIGNING_CA OR + EMAIL_CA OR + SSL_CA; + + StatusResponder: CERT_SIGN; OBJECT_SIGNING_CA OR + EMAIL_CA OR + SSL_CA; + + Note: When the required key usage is KEY_AGREEMENT OR KEY_ENCIPHERMENT, + the actual key usage required depends on the key's algorithm. For + RSA keys, the required usage is KEY_ENCIPHERMENT. For other types of + keys, it is KEY_AGREEMENT. + + + Cert Extensions: + + One vital Certificate extension is the "Basic Constraints" extension. + It tells NSS whether the cert is a CA cert, or not, and affects every + other aspect of how the cert is interpreted by NSS. The OID for this + extension is { 2 5 29 19 }, encoded in hex as 0x55, 0x1d, 0x13. + If the extension is present and has the value TRUE, then this cert is + taken to be a CA cert. Otherwise it is not (except that trust flags + may override this, see discussion of trust flags farther below). + + Netscape has its own openly defined Cert Type extension, which can be used + to explicitly set the Cert Type in any Cert. The Cert Type extension has + bits in it that correspond directly to the cert types named above. + The OID for this extension is { 2 16 840 1 113730 1 1 } + encoded in hex as 0x60, 0x86, 0x48, 0x01, 0x86, 0xf8, 0x42, 0x01, 0x01 + + In addition to Netscape's own Cert Type extension, NSS recognizes various + X.509 extensions. + + The X.509 key usage extension has OID { 2 5 29 0F } encoded in hex as + 0x55, 0x1d, 0x0f. If present, this extension directly determines the + values of the 8 key usages defined above. If absent, the cert is + assumed to be valid for all key usages. + + The X.509v3 extended Key usage extension as OID { 2 5 29 37 } encoded in + hex as 0x55, 0x1d, 0x25. That extension contains a sequence of OIDs, each + of which signifies one or more Cert Types, depending on the presence or + absence of of the True Basic Constraints extension; that is, the + interpretation of the extended Key Usage extension is controlled by + whether the cert is a CA cert, or not. + + The following table shows the OIDs recognized in the extended key usage + extension, and how they map to cert types and key usages for CA and non-CA + certs. + + extended key usage OID non-CA cert CA cert + ----------------------------------- -------------- ---------------- + SEC_OID_EXT_KEY_USAGE_EMAIL_PROTECT EMAIL_CA EMAIL_CA + SEC_OID_EXT_KEY_USAGE_SERVER_AUTH SSL_SERVER SSL_CA + SEC_OID_EXT_KEY_USAGE_CLIENT_AUTH SSL_CLIENT SSL_CA + SEC_OID_EXT_KEY_USAGE_CODE_SIGN OBJECT_SIGNING OBJECT_SIGNING_CA + SEC_OID_EXT_KEY_USAGE_TIME_STAMP TIME_STAMP TIME_STAMP + SEC_OID_OCSP_RESPONDER OCSP_RESPONDER OCSP_RESPONDER + + SEC_OID_NS_KEY_USAGE_GOVT_APPROVED GOVT_APPROVED GOVT_APPROVED + + If the extended key usage extension is absent, the cert is assumed to have + the cert types SSL_CLIENT, SSL_SERVER and EMAIL, and if the cert is a CA + cert (as indicated by the presence of a true basic constraints extension), + the cert is also assumed to have the cert types SSL_CA, EMAIL_CA and + STATUS_RESPONDER. If the basic constraints extension is missing, but the + user has trusted the cert as a CA cert, the cert also gets the + STATUS_RESPONDER cert type. If the cert has a Fortezza type public key + with the magic bits that signify that it is a CA, it is given cert types + SSL_CA and EMAIL_CA. + + A cert with the extended key usage extension and the Netscape cert type + extension that has the cert type SSL_CLIENT and also has an email address + in the subject is also given the cert type EMAIL. This allows all SSL + client authentication certs with email addresses to also be used as email + certs (provded they have adequate key usage). + + A cert with the extended key usage extension and the Netscape cert type + extension that as cert type SSL_CA is also always given cert type EMAIL_CA. + This allows all SSL intermediate CAs to also be used as email intermediate CAs. + + /* X.509 v3 Key Usage Extension flags */ + #define KU_DIGITAL_SIGNATURE (0x80) /* bit 0 */ + #define KU_NON_REPUDIATION (0x40) /* bit 1 */ + #define KU_KEY_ENCIPHERMENT (0x20) /* bit 2 */ + #define KU_DATA_ENCIPHERMENT (0x10) /* bit 3 */ + #define KU_KEY_AGREEMENT (0x08) /* bit 4 */ + #define KU_KEY_CERT_SIGN (0x04) /* bit 5 */ + #define KU_CRL_SIGN (0x02) /* bit 6 */ + + #define NS_CERT_TYPE_SSL_CLIENT (0x80) /* bit 0 */ + #define NS_CERT_TYPE_SSL_SERVER (0x40) /* bit 1 */ + #define NS_CERT_TYPE_EMAIL (0x20) /* bit 2 */ + #define NS_CERT_TYPE_OBJECT_SIGNING (0x10) /* bit 3 */ + #define NS_CERT_TYPE_RESERVED (0x08) /* bit 4 */ + #define NS_CERT_TYPE_SSL_CA (0x04) /* bit 5 */ + #define NS_CERT_TYPE_EMAIL_CA (0x02) /* bit 6 */ + #define NS_CERT_TYPE_OBJECT_SIGNING_CA (0x01) /* bit 7 */ + </x>
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note4/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note4/index.rst new file mode 100644 index 0000000000..7a7334bee2 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note4/index.rst @@ -0,0 +1,221 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note4: + +nss tech note4 +============== + +.. _pulling_certificate_extension_information_out_of_ssl_certificates: + +`Pulling certificate extension information out of SSL certificates <#pulling_certificate_extension_information_out_of_ssl_certificates>`__ +------------------------------------------------------------------------------------------------------------------------------------------ + +.. container:: + +.. _nss_technical_note_4: + +`NSS Technical Note: 4 <#nss_technical_note_4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + **Note:** This document contains code snippets that focus on essential aspects of the task and + often do not illustrate all the cleanup that needs to be done. Also, this document does not + attempt to be an exhaustive survey of all possible ways to do a certain task; it merely tries to + show a certain way. + .. rubric:: Include these files + :name: include_these_files + + #include "ssl.h" + #include "cert.h" + .. rubric:: Get the handle of the cert associated with an SSL connection + :name: get_the_handle_of_the_cert_associated_with_an_ssl_connection + + *CERTCertificate\* cert = SSL_PeerCertificate(PRFileDesc \*fd);* + If SSL client, this will get you the server's cert handle; + If SSL server, this will get you the client's cert handle IF client auth is enabled + *CERTCertificate\* cert = SSL_LocalCertificate(PRFileDesc \*fd);* + If SSL client, this will get you the client cert's handle, IF client auth happened + If SSL server, this will get you the server's cert handle + .. rubric:: Don't forget to clean up the cert handle when you're done with it + :name: don't_forget_to_clean_up_the_cert_handle_when_you're_done_with_it + + *void CERT_DestroyCertificate(CERTCertificate \*cert);* + .. rubric:: Some info is readily available + :name: some_info_is_readily_available + + cert->subjectName (char*) + cert->issuerName (char*) + cert->emailAddr (char*) + OR char \*CERT_GetCertificateEmailAddress(CERTCertificate \*cert); + cert->keyUsage (unsigned int) + .. rubric:: To break the issuer and subject names into components + :name: to_break_the_issuer_and_subject_names_into_components + + Pass &(cert->issuer) or &(cert->subject) to the following functions + *char \*CERT_GetCommonName(CERTName \*name); + char \*CERT_GetCertEmailAddress(CERTName \*name); + char \*CERT_GetCountryName(CERTName \*name); + char \*CERT_GetLocalityName(CERTName \*name); + char \*CERT_GetStateName(CERTName \*name); + char \*CERT_GetOrgName(CERTName \*name); + char \*CERT_GetOrgUnitName(CERTName \*name); + char \*CERT_GetDomainComponentName(CERTName \*name); + char \*CERT_GetCertUid(CERTName \*name);* + + Example code to illustrate access to the info is given below. + .. rubric:: Background on cert extensions + :name: background_on_cert_extensions + + An extension has the following attributes + + - Object Id (OID) : A unique OID represents an algorithm, a mechanism, a piece of information, + etc. Examples: X500 RSA Encryption, Certificate Basic Constraints, PKCS#7 Digested Data, etc. + There is a long list of pre-defined OIDs, and new ones can be *added dynamically by an + application.* + The OID data structure contains an array of identifier bytes (each byte is a "level" in a + hierarchical namespace), a text description, and some other things. + - Critical : indicates whether the extension is critical + - Value : The value of the extension + + .. rubric:: Looping through all extensions + :name: looping_through_all_extensions + + *CERTCertExtension*\* extensions =cert->extensions;* + *if (extensions)* + *{* + * while (*extensions)* + * {* + * SECItem \*ext_oid = &(*extensions)->id;* + * SECItem \*ext_critical = &(*extensions)->critical;* + * SECItem \*ext_value = &(*extensions)->value;* + * /\* id attribute of the extension \*/* + * SECOidData \*oiddata = SECOID_FindOID(ext_oid);* + * if (oiddata == NULL)* + * {* + */\* OID not found \*/* + */\* SECItem ext_oid has type (SECItemType), data (unsigned char \*) and len (unsigned int) + fields* + * - the application interprets these \*/* + *.......* + * }* + * else* + * {* + *char \*name = oiddata->desc; /\* name of the extension \*/* + *.......* + * }* + * /\* critical attribute of the extension \*/* + * if (ext_critical->len > 0)* + * {* + *if (ext_critical->data[0])* + * /\* the extension is critical \*/* + *else* + * /\* the extension is not critical \*/* + * }* + * /\* value attribute of the extension \*/* + * /\* SECItem ext_value has type (SECItemType), data (unsigned char \*) and len + (unsigned int) fields* + *- the application interprets these \*/* + * SECOidTag oidtag = SECOID_FindOIDTag(ext_oid);* + * switch (oidtag)* + * {* + *case a_tag_that_app_recognizes:* + * .....* + *case .....* + * ......* + * }* + * extensions++;* + * }* + *}* + + .. rubric:: An example custom cert extension + :name: an_example_custom_cert_extension + + *struct \_myCertExtData* + *{* + * SECItem version;* + * SECItem streetaddress;* + * SECItem phonenum;* + * SECItem rfc822name;* + * SECItem id;* + * SECItem maxusers;* + *};* + *typedef struct \_myCertExtData myCertExtData;* + */\* template used for decoding the extension \*/* + *const SEC_ASN1Template myCertExtTemplate[] = {* + * { SEC_ASN1_SEQUENCE, 0, NULL, sizeof( myCertExtData ) },* + * { SEC_ASN1_INTEGER, offsetof(myCertExtData, version) },* + * { SEC_ASN1_OCTET_STRING, offsetof( myCertExtData, streetaddress ) },* + * { SEC_ASN1_OCTET_STRING, offsetof( myCertExtData, phonenum ) },* + * { SEC_ASN1_OCTET_STRING, offsetof( myCertExtData, rfc822name ) },* + * { SEC_ASN1_OCTET_STRING, offsetof( myCertExtData, id ) },* + * { SEC_ASN1_INTEGER, offsetof(myCertExtData, maxusers ) },* + * { 0 }* + *};* + */\* OID for my cert extension - replace 0xff with appropriate values*/* + *static const unsigned char myoid[] = { 0xff, 0xff, 0xff, 0xff, .... };* + *static const SECItem myoidItem = { (SECItemType) 0, (unsigned char \*)myoid, sizeof(myoid) + };* + *SECItem myextvalue; + myCertExtData data;* + *SECStatus rv = CERT_FindCertExtensionByOID(cert, &myoidItem, &myextvalue); + if (rv == SECSuccess) + { + SEC_ASN1DecoderContext \* context = SEC_ASN1DecoderStart(NULL, &data, myCertExtTemplate); + rv = SEC_ASN1DecoderUpdate( context, (const char \*)(myextvalue.data), myextvalue.len); + if (rv == SECSuccess) + { + /\* Now you can extract info from SECItem fields of your extension data structure \*/ + /\* See "Misc helper functions" below \*/ + ....... + /\* free the SECItem fields \*/ + SECITEM_FreeItem(&data.version, PR_FALSE); + SECITEM_FreeItem(&data.streetaddress, PR_FALSE); + ...... + SECITEM_FreeItem(&data.maxusers, PR_FALSE); + } + }* + + .. rubric:: Some miscellaneous helper functions + :name: some_miscellaneous_helper_functions + + - Compare two SECItems (e.g., two OIDs) + *PRBool SECITEM_ItemsAreEqual(const SECItem \*a, const SECItem \*b);* + - Interpreting a SECItem value as an integer + If SECItem \*item->len <=4, then int value = *DER_GetInteger(item)*; + - Interpreting a SECItem value as a string + Use string copy functions to copy item->len bytes from item->data and null terminate + explicitly + + .. rubric:: Some higher level extension functions + :name: some_higher_level_extension_functions + + - Get a specific extension from the list of extensions, given the extension tag + *SECStatus CERT_FindCertExtension (CERTCertificate \*cert, int tag, SECItem \*value);* + - Get a specific extension from the ISSUER's cert\ * + SECStatus CERT_FindIssuerCertExtension (CERTCertificate \*cert, int tag, SECItem \*value);* + - Get the value of an extension with the given OID + *SECStatus CERT_FindCertExtensionByOID (CERTCertificate \*cert, SECItem \*oid, SECItem + \*value);* + - Get the decoded value of the "Basic Constraints" extension + *SECStatus CERT_FindBasicConstraintExten (CERTCertificate \*cert, CERTBasicConstraints + \*value);* + - Get value of the keyUsage extension. This uses PR_Alloc to allocate buffer for the decoded + value, The caller should free up the storage allocated in value->data. + *SECStatus CERT_FindKeyUsageExtension (CERTCertificate \*cert, SECItem \*value);* + - Get decoded value of the subjectKeyID extension. This uses PR_Alloc to allocate buffer for + the decoded value, The caller should free up the storage allocated in value->data. + *SECStatus CERT_FindSubjectKeyIDExten (CERTCertificate \*cert, SECItem \*retItem);* + + * + * + +.. _for_more_information: + +`For more information <#for_more_information>`__ +------------------------------------------------ + +.. container:: + + - Browse through the NSS source code online at + http://lxr.mozilla.org/mozilla/source/security/nss/ and http://lxr.mozilla.org/security/ + - documentation on some cert funcs + `http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt.html <https://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt.html>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note5/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note5/index.rst new file mode 100644 index 0000000000..d9b7b9ddf6 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note5/index.rst @@ -0,0 +1,659 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note5: + +nss tech note5 +============== + +.. _using_nss_to_perform_miscellaneous_cryptographic_operations: + +`Using NSS to perform miscellaneous cryptographic operations <#using_nss_to_perform_miscellaneous_cryptographic_operations>`__ +------------------------------------------------------------------------------------------------------------------------------ + +.. container:: + +.. _nss_technical_note_5: + +`NSS Technical Note: 5 <#nss_technical_note_5>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS Project Info is at + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__ + - You can browse the NSS source online at http://lxr.mozilla.org/mozilla/source/security/nss/ + and http://lxr.mozilla.org/security/ + - Be sure to look for :ref:`mozilla_projects_nss_sample_code` first for things you need to do. + - **Note:** This document contains code snippets that focus on essential aspects of the task and + often do not illustrate all the cleanup that needs to be done. Also, this document does not + attempt to be an exhaustive survey of all possible ways to do a certain task; it merely tries + to show a certain way. + + -------------- + +`Encrypt/Decrypt <#encryptdecrypt>`__ +------------------------------------- + +.. container:: + + #. Include headers + *#include "nss.h" + #include "pk11pub.h"* + #. Make sure NSS is initialized.The simplest Init function, in case you don't need a NSS database + is + *NSS_NoDB_Init(".")* + #. Choose a cipher mechanism. Note that some mechanisms (*_PAD) imply the padding is handled for + you by NSS. If you choose something else, then data padding is the application's + responsibility. You can find a list of cipher mechanisms in security/nss/lib/softoken/pkcs11.c + - grep for CKF_EN_DE_. + *CK_MECHANISM_TYPE cipherMech = CKM_DES_CBC_PAD* <big>(for example)</big> + #. Choose a slot on which to do the operation + *PK11SlotInfo\* slot = PK11_GetBestSlot(cipherMech, NULL); *\ **OR**\ * + PK11SlotInfo\* slot = PK11_GetInternalKeySlot(); /\* alwys returns internal slot, may not be + optimal \*/* + #. Prepare the Key + + - If using a raw key + */\* turn the raw key into a SECItem \*/ + SECItem keyItem; + keyItem.data = /\* ptr to an array of key bytes \*/ + keyItem.len = /\* length of the array of key bytes \*/ + /\* turn the SECItem into a key object \*/ + PK11SymKey\* SymKey = PK11_ImportSymKey(slot, cipherMech, PK11_OriginUnwrap, + + CKA_ENCRYPT, &keyItem, NULL)*; + - If generating the key - see section `Generate a Symmetric + Key <#generate_a_symmetric_key>`__ + + + #. <big>Prepare the parameter for crypto context. IV is relevant only when using CBC mode of + encryption. If not using CBC mode, just pass a NULL IV parm to PK11_ParamFromIV function + *SECItem ivItem; + ivItem.data = /\* ptr to an array of IV bytes \*/ + ivItem.len = /\* length of the array of IV bytes \*/ + SECItem \*SecParam = PK11_ParamFromIV(cipherMech, &ivItem);*\ </big> + #. <big>Now encrypt and decrypt using the key and parameter setup in above steps</big> + + - Create Encryption context + *PK11Context\* EncContext = PK11_CreateContextBySymKey(cipherMech, + + CKA_ENCRYPT or CKA_DECRYPT, + SymKey, + SecParam);* + - Do the Operation. If encrypting, outbuf len must be atleast (inbuflen + blocksize). If + decrypting, outbuflen must be atleast inbuflen. + *SECStatus s = PK11_CipherOp(EncContext, outbuf, &tmp1_outlen, sizeof outbuf, inbuf, + inbuflen); + s = PK11_DigestFinal(EncContext, outbuf+tmp1_outlen, &tmp2_outlen, + sizeof outbuf - tmp1_outlen); + result_len = tmp1_outlen + tmp2_outlen;* + - <big>Destroy the Context + *PK11_DestroyContext(EncContext, PR_TRUE);*\ </big> + + #. <big>Repeat Step 6 **any number of times**. When all done with encrypt/decrypt ops, clean + up</big> + <big>\ *PK11_FreeSymKey(SymKey); + SECITEM_FreeItem(SecParam, PR_TRUE); + PK11_FreeSlot(slot);*\ </big> + + | **Note:** AES encryption, a fixed blocksize of 16 bytes is used. The Rijndael algorithm permits + 3 blocksizes (16, 24, 32 bytes), but the AES standard requires the blocksize to be 16 bytes. + The keysize can vary and these keysizes are permitted: 16, 24, 32 bytes. + | You can also look at a `sample program <../sample-code/sample2.html>`__ illustrating encryption + + -------------- + +.. _hash_digest: + +`Hash / Digest <#hash_digest>`__ +-------------------------------- + +.. container:: + + #. Include headers + *#include "nss.h" + #include "pk11pub.h"* + #. Make sure NSS is initialized.The simplest Init function, in case you don't need a NSS database + is + *NSS_NoDB_Init(".")* + #. <big>Create Digest context</big>. Some of the digest algorithm identifiers are (without the + SEC_OID\_ prefix) : MD2, MD5, SHA1, SHA256, SHA384, SHA512. + *PK11Context\* DigestContext = PK11_CreateDigestContext(SEC_OID_MD5);* + #. <big>Digest the data</big> + <big>\ *SECStatus s = PK11_DigestBegin(DigestContext); + s = PK11_DigestOp(DigestContext, data, sizeof data); + s = PK11_DigestFinal(DigestContext, digest, &len, sizeof digest); + /\* now, digest contains the 'digest', and len contains the length of the digest \*/*\ </big> + #. Clean up + *PK11_DestroyContext(DigestContext, PR_TRUE);* + + | + | You can also look at a `sample program <../sample-code/sample3.html>`__ illustrating this + + -------------- + +.. _hash_digest_with_secret_key_included: + +`Hash / Digest with secret key included <#hash_digest_with_secret_key_included>`__ +---------------------------------------------------------------------------------- + +.. container:: + + #. Include headers + *#include "nss.h" + #include "pk11pub.h"* + #. Make sure NSS is initialized.The simplest Init function, in case you don't need a NSS database + is + *NSS_NoDB_Init(".")* + #. Choose a digest mechanism. You can find a list of digest mechanisms in + security/nss/lib/softoken/pkcs11.c - grep for CKF_DIGEST. + *CK_MECHANISM_TYPE digestMech = CKM_MD5* <big>(for example)</big> + #. Choose a slot on which to do the operation + *PK11SlotInfo\* slot = PK11_GetBestSlot(digestMech, NULL); *\ **OR**\ * + PK11SlotInfo\* slot = PK11_GetInternalKeySlot(); /\* always returns int slot, may not be + optimal \*/* + #. Prepare the Key + + - If using a raw key + */\* turn the raw key into a SECItem \*/ + SECItem keyItem; + keyItem.data = /\* ptr to an array of key bytes \*/ + keyItem.len = /\* length of the array of key bytes \*/ + /\* turn the SECItem into a key object \*/ + PK11SymKey\* SymKey = PK11_ImportSymKey(slot, digestMech, PK11_OriginUnwrap, + + CKA_DIGEST, &keyItem, NULL)*; + - If generating the key - see section `Generate a Symmetric + Key <#generate_a_symmetric_key>`__. Can use *CKM_GENERIC_SECRET_KEY_GEN* as the key gen + mechanism. + + + #. <big>Prepare the parameter for crypto context. The param must be provided, but can be empty. + *SECItem param; + param.data = 0; + param.len = 0;*\ </big> + #. <big>Create Crypto context</big> + *PK11Context\* DigestContext = PK11_CreateContextBySymKey(digestMech, CKA_DIGEST, SymKey, + + ¶m);* + #. <big>Digest the data</big>, providing the key + <big>\ *SECStatus s = PK11_DigestBegin(DigestContext); + s = PK11_DigestKey(DigestContext, SymKey); + s = PK11_DigestOp(DigestContext, data, sizeof data); + s = PK11_DigestFinal(DigestContext, digest, &len, sizeof digest); + /\* now, digest contains the 'digest', and len contains the length of the digest \*/*\ </big> + #. Clean up + *PK11_DestroyContext(DigestContext, PR_TRUE); + PK11_FreeSymKey(SymKey); + PK11_FreeSlot(slot);* + + You can also look at a `sample program <../sample-code/sample3.html>`__ illustrating this + + -------------- + +`HMAC <#hmac>`__ +---------------- + +.. container:: + + #. Include headers + *#include "nss.h" + #include "pk11pub.h"* + #. Make sure NSS is initialized.The simplest Init function, in case you don't need a NSS database + is + *NSS_NoDB_Init(".")* + #. Choose a HMAC mechanism. You can find a list of HMAC mechanisms in + security/nss/lib/softoken/pkcs11.c - grep for CKF_SN_VR, and choose the mechanisms that + contain HMAC in the name + *CK_MECHANISM_TYPE hmacMech = CKM_MD5_HMAC;* <big>(for example)</big> + #. Choose a slot on which to do the operation + *PK11SlotInfo\* slot = PK11_GetBestSlot(hmacMech, NULL); *\ **OR**\ * + PK11SlotInfo\* slot = PK11_GetInternalKeySlot(); /\* always returns int slot, may not be + optimal \*/* + #. Prepare the Key + + - If using a raw key + */\* turn the raw key into a SECItem \*/ + SECItem keyItem; + keyItem.type = siBuffer; + keyItem.data = /\* ptr to an array of key bytes \*/ + keyItem.len = /\* length of the array of key bytes \*/ + /\* turn the SECItem into a key object \*/ + PK11SymKey\* SymKey = PK11_ImportSymKey(slot, hmacMech, PK11_OriginUnwrap, + + CKA_SIGN, &keyItem, NULL)*; + - If generating the key - see section `Generate a Symmetric + Key <#generate_a_symmetric_key>`__. Can use *CKM_GENERIC_SECRET_KEY_GEN* as the key gen + mechanism. + + + #. <big>Prepare the parameter for crypto context. The param must be provided, but can be empty. + *SECItem param; + param.type = siBuffer; + param.data = NULL; + param.len = 0;*\ </big> + #. <big>Create Crypto context</big> + *PK11Context\* DigestContext = PK11_CreateContextBySymKey(hmacMech, CKA_SIGN, + + SymKey, ¶m);* + #. <big>Digest the data</big> + <big>\ *SECStatus s = PK11_DigestBegin(DigestContext); + s = PK11_DigestOp(DigestContext, data, sizeof data); + s = PK11_DigestFinal(DigestContext, digest, &len, sizeof digest); + /\* now, digest contains the 'signed digest', and len contains the length of the digest + \*/*\ </big> + #. Clean up + *PK11_DestroyContext(DigestContext, PR_TRUE);* + *PK11_FreeSymKey(SymKey); + PK11_FreeSlot(slot);* + + | + | You can also look at a `sample program <../sample-code/sample3.html>`__ illustrating this + + -------------- + +.. _symmetric_key_wrappingunwrapping_of_a_symmetric_key: + +`Symmetric Key Wrapping/Unwrapping of a Symmetric Key <#symmetric_key_wrappingunwrapping_of_a_symmetric_key>`__ +--------------------------------------------------------------------------------------------------------------- + +.. container:: + + #. Include headers + *#include "nss.h" + #include "pk11pub.h"* + #. Make sure NSS is initialized.The simplest Init function, in case you don't need a NSS database + is + *NSS_NoDB_Init(".")* + #. Choose a Wrapping mechanism. See wrapMechanismList in security/nss/lib/pk11wrap/pk11slot.c + and security/nss/lib/ssl/ssl3con.c for examples of wrapping mechanisms. Most of them are + cipher mechanisms. + *CK_MECHANISM_TYPE wrapMech = CKM_DES3_ECB;* <big>(for example)</big> + #. Choose a slot on which to do the operation + *PK11SlotInfo\* slot = PK11_GetBestSlot(wrapMech, NULL); *\ **OR**\ * + PK11SlotInfo\* slot = PK11_GetInternalKeySlot(); /\* always returns int slot, may not be + optimal \*/* + <big>Regarding the choice of slot and wrapMech, if you know one, you can derive the other. You + can get the best slot given a wrap mechanism (as shown above), or get the best wrap mechanism + given a slot using:</big> + *CK_MECHANISM_TYPE wrapMech = PK11_GetBestWrapMechanism(slot)* + #. Prepare the Wrapping Key + + - If using a raw key + */\* turn the raw key into a SECItem \*/ + SECItem keyItem; + keyItem.data = /\* ptr to an array of key bytes \*/ + keyItem.len = /\* length of the array of key bytes \*/ + /\* turn the SECItem into a key object \*/ + PK11SymKey\* WrappingSymKey = PK11_ImportSymKey(slot, wrapMech, + + PK11_OriginUnwrap, + + CKA_WRAP, &keyItem, NULL)* + + - If generating the key - see section `Generate a Symmetric + Key <#generate_a_symmetric_key>`__ + + + #. Prepare the To-be-Wrapped Key + + - If using a raw key + */\* turn the raw key into a SECItem \*/ + SECItem keyItem; + keyItem.data = /\* ptr to an array of key bytes \*/ + keyItem.len = /\* length of the array of key bytes \*/ + /\* turn the SECItem into a key object \*/ + PK11SymKey\* ToBeWrappedSymKey = PK11_ImportSymKey(slot, wrapMech,, + + PK11_OriginUnwrap, + + CKA_WRAP, &keyItem, NULL)*; + - If generating the key - see section `Generate a Symmetric + Key <#generate_a_symmetric_key>`__ + + + #. <big>Prepare the parameter for crypto context. IV is relevant only when using CBC cipher mode. + If not using CBC mode, just pass a NULL *SecParam* to *PK11_WrapSymKey* or *PK11_UnwrapSymKey* + function + *SECItem ivItem; + ivItem.data = /\* ptr to an array of IV bytes \*/ + ivItem.len = /\* length of the array of IV bytes \*/ + SECItem \*SecParam = PK11_ParamFromIV(wrapMech, &ivItem);*\ </big> + #. Allocate space for the wrapped key + *SECItem WrappedKey; + WrappedKey.len = SOME_LEN; + WrappedKey.data = allocate (SOME_LEN) bytes;* + #. <big>Do the Wrap</big>. Note that the WrappingSymKey and the ToBeWrappedSymKey must be on the + slot where the wrap is going to happen. To move keys to the desired slot, see section `Moving + a Key from one slot to another <#moving_a_key_from_one_slot_to_another>`__ + <big>\ *SECStatus s = PK11_WrapSymKey(wrapMech, SecParam, WrappingSymKey, + ToBeWrappedSymKey, + &WrappedKey);*\ </big> + #. <big><big>Transport/Store or do whatever with the Wrapped Key (WrappedKey.data, + WrappedKey.len)</big></big> + #. <big><big>Unwrapping. </big></big> + + - <big><big>Set up the args to the function *PK11_UnwrapSymKey*, most of which are + illustrated above. The *keyTypeMech* arg of type *CK_MECHANISM_TYPE *\ <big>indicates the + type of key that was wrapped and can be same as the *wrapMech* (e.g. + *wrapMech=CKM_SKIPJACK_WRAP, keyTypeMech=CKM_SKIPJACK_CBC64; wrapMech=CKM_SKIPJACK_CBC64, + keyTypeMech=CKM_SKIPJACK_CBC64*).</big>\ </big></big> + - Do the unwrap + <big><big>\ *PK11SymKey\* UnwrappedSymKey = PK11_UnwrapSymKey(WrappingSymKey, + + wrapMech*\ </big></big><big><big>\ *, SecParam, &WrappedKey, + + keyTypeMech,*\ </big></big> + <big><big>\ * + CKA_UNWRAP, /\* or CKA_DECRYPT? \*/ + + size_of_key_that_was_wrapped_bytes);*\ </big></big> + + #. Clean up + *PK11_FreeSymKey(WrappingSymKey);* + *PK11_FreeSymKey(ToBeWrappedSymKey); + PK11_FreeSymKey(UnwrappedSymKey); + if (SecParam) SECITEM_FreeItem(SecParam, PR_TRUE); + SECITEM_FreeItem(&WrappedKey, PR_TRUE); + PK11_FreeSlot(slot); * + + -------------- + +.. _symmetric_key_wrappingunwrapping_of_a_private_key: + +`Symmetric Key Wrapping/Unwrapping of a Private Key <#symmetric_key_wrappingunwrapping_of_a_private_key>`__ +----------------------------------------------------------------------------------------------------------- + +.. container:: + + #. Include headers + *#include "nss.h" + #include "pk11pub.h"* + #. Make sure NSS is initialized. + #. Choose a Wrapping mechanism. See wrapMechanismList in security/nss/lib/pk11wrap/pk11slot.c + and security/nss/lib/ssl/ssl3con.c for examples of wrapping mechanisms. Most of them are + cipher mechanisms. + *CK_MECHANISM_TYPE wrapMech = CKM_DES3_ECB;* <big>(for example).</big> + #. Slot on which to do the operation + *PK11SlotInfo\* slot = PK11_GetBestSlot(wrapMech, NULL); *\ **OR**\ * + PK11SlotInfo\* slot = PK11_GetInternalKeySlot(); /\* always returns int slot, may not be + optimal \*/* + This should be the slot that is best suited for the wrapping. This may or may not be the slot + that contains the private key or the slot that contains the Symmetric key. + <big>Regarding the choice of slot and wrapMech, if you know one, you can derive the other. You + can get the best slot given a wrap mechanism (as shown above), or get the best wrap mechanism + given a slot using:</big> + *CK_MECHANISM_TYPE wrapMech = PK11_GetBestWrapMechanism(slot)* + #. Prepare the Wrapping Key + + - If using a raw key + */\* turn the raw key into a SECItem \*/ + SECItem keyItem; + keyItem.data = /\* ptr to an array of key bytes \*/ + keyItem.len = /\* length of the array of key bytes \*/ + /\* turn the SECItem into a key object \*/ + PK11SymKey\* WrappingSymKey = PK11_ImportSymKey(slot, wrapMech, + + PK11_OriginUnwrap, + + CKA_WRAP, &keyItem, NULL)*; + - If generating the key - see section `Generate a Symmetric + Key <#generate_a_symmetric_key>`__ + + + #. Prepare the To-be-Wrapped Key + + - *SECKEYPrivateKey \*ToBeWrappedPrivKey * + + #. <big>Prepare the parameter for crypto context. IV is relevant only when using CBC cipher mode. + If not using CBC mode, just pass a NULL *SecParam* to *PK11_WrapPrivKey* function + *SECItem ivItem; + ivItem.data = /\* ptr to an array of IV bytes \*/ + ivItem.len = /\* length of the array of IV bytes \*/ + SECItem \*SecParam = PK11_ParamFromIV(wrapMech, &ivItem);*\ </big> + #. Allocate space for the wrapped key. Note that a 2048-bit *wrapped* RSA private key takes up + around 1200 bytes. + *SECItem WrappedKey; + WrappedKey.len = SOME_LEN; + WrappedKey.data = allocate (SOME_LEN) bytes;* + #. <big>Do the Wrap</big>. Note that the WrappingSymKey and the ToBeWrappedPvtKey must be on the + slot where the wrap is going to happen. To move keys to the desired slot, see section `Moving + a Key from one slot to another <#moving_a_key_from_one_slot_to_another>`__ + <big>\ *SECStatus s = PK11_WrapPrivKey(slot, WrappingSymKey, ToBeWrappedPvtKey, wrapMech, + SecParam, &WrappedKey, + NULL);*\ </big> + #. <big><big>Transport/Store or do whatever with the Wrapped Key (WrappedKey.data, + WrappedKey.len)</big></big> + #. <big><big>Unwrapping.</big></big> + + - Prepare the args for the unwrap function. Most of the args are illustrated above + *SECItem label; /\* empty, doesn't need to be freed \*/ + label.data = NULL; label.len = 0;* + *SECItem \*pubValue = NULL; + pubValue = /\* ?? \*/;* + *PRBool token = /\* PR_TRUE or PR_FALSE depending on?? \*/ + CK_MECHANISM_TYPE keyTypeMech = ??; + CK_KEY_TYPE keyType; + keyType = PK11_GetKeyType(keyTypeMech, 0); + CK_ATTRIBUTE_TYPE attribs[4]; + int numAttribs; + /\* figure out which operations to enable for this key \*/ + if( keyType == CKK_RSA ) { + attribs[0] = CKA_SIGN; + attribs[1] = CKA_DECRYPT; + attribs[2] = CKA_SIGN_RECOVER; + attribs[3] = CKA_UNWRAP; + numAttribs = 4; + } else if(keyType == CKK_DSA) { + attribs[0] = CKA_SIGN; + numAttribs = 1; + }* + - <big>Do the unwrap</big> + *SECKEYPrivateKey \*UnwrappedPvtKey = + PK11_UnwrapPrivKey(slot, WrappingSymKey, wrapMech, SecParam, &WrappedKey, + &label, pubValue, token, PR_TRUE + /\* sensitive \*/ + keyType, attribs, numAttribs, + NULL /*wincx*/);* + + #. Clean up + *PK11_FreeSymKey(WrappingSymKey);* + <big>\ *if (SecParam) SECITEM_FreeItem(SecParam, PR_TRUE);*\ </big> + <big>\ *SECITEM_FreeItem(&WrappedKey, PR_TRUE);*\ </big> + *if (pubValue) SECITEM_FreeItem(pubValue, PR_TRUE);* + *if (UnwrappedPvtKey) SECKEY_DestroyPrivateKey(UnwrappedPvtKey);* + *if (ToBeWrappedPvtKey) SECKEY_DestroyPrivateKey(ToBeWrappedPvtKey);* + *PK11_FreeSlot(slot);* + + -------------- + +.. _public_key_wrapping_private_key_unwrapping_of_a_symmetric_key_(pki_based_key_transport): + +`Public Key Wrapping & Private Key Unwrapping of a Symmetric Key (PKI based key transport) <#public_key_wrapping_private_key_unwrapping_of_a_symmetric_key_(pki_based_key_transport)>`__ +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + #. Include headers + *#include "nss.h" + #include "pk11pub.h"* + #. Make sure NSS is initialized. + #. Choose a Wrapping mechanism. See wrapMechanismList in security/nss/lib/pk11wrap/pk11slot.c + and security/nss/lib/ssl/ssl3con.c for examples of wrapping mechanisms. Most of them are + cipher mechanisms. + *CK_MECHANISM_TYPE wrapMech = CKM_DES3_ECB;* <big>(for example)</big> + #. Slot on which to do the operation + *PK11SlotInfo\* slot = PK11_GetBestSlot(wrapMech, NULL); *\ **OR**\ * + PK11SlotInfo\* slot = PK11_GetInternalKeySlot(); /\* always returns int slot, may not be + optimal \*/* + This should be the slot that is best suited for the wrapping. This may or may not be the slot + that contains the public/private key or the slot that contains the Symmetric key. + <big>Regarding the choice of slot and wrapMech, if you know one, you can derive the other. You + can get the best slot given a wrap mechanism (as shown above), or get the best wrap mechanism + given a slot using:</big> + *CK_MECHANISM_TYPE wrapMech = PK11_GetBestWrapMechanism(slot)* + #. Prepare the Wrapping Key + + - *SECKeyPublicKey \*WrappingPubKey* + + #. Prepare the To-be-Wrapped Key + + - If using a raw key + */\* turn the raw key into a SECItem \*/ + SECItem keyItem; + keyItem.data = /\* ptr to an array of key bytes \*/ + keyItem.len = /\* length of the array of key bytes \*/ + /\* turn the SECItem into a key object \*/ + PK11SymKey\* ToBeWrappedSymKey = PK11_ImportSymKey(slot, wrapMech,, + + PK11_OriginUnwrap, + + CKA_WRAP, &keyItem, NULL)*; + - If generating the key - see section `Generate a Symmetric + Key <#generate_a_symmetric_key>`__ + + #. Allocate space for the wrapped key + *SECItem WrappedKey; + WrappedKey.len = SOME_LEN; + WrappedKey.data = allocate (SOME_LEN) bytes;* + #. <big>Do the Wrap</big>. Note that the WrappingPubKey and the ToBeWrappedSymKey must be on the + slot where the wrap is going to happen. To move keys to the desired slot, see section `Moving + a Key from one slot to another <#moving_a_key_from_one_slot_to_another>`__ + <big>\ *SECStatus s = PK11_PubWrapSymKey(wrapMech, WrappingPubKey, + ToBeWrappedSymKey, + &WrappedKey);*\ </big> + #. <big><big>Transport/Store or do whatever with the Wrapped Key (WrappedKey.data, + WrappedKey.len)</big></big> + #. <big><big>Unwrapping. </big></big> + + - Prepare the args for the unwrap function. Most of the args are illustrated above + *SECKEYPrivateKey \*UnWrappingPvtKey; + CK_MECHANISM_TYPE keyTypeMech = ??;* + - <big>Do the unwrap</big> + *PK11SymKey \*UnwrappedSymKey = + PK11_PubUnwrapSymKey(UnWrappingPvtKey, WrappedKey, keyTypeMech, + *<big><big>\ *CKA_UNWRAP, /\* + or CKA_DECRYPT? \*/ + + *\ </big></big><big><big>\ *size_of_key_that_was_wrapped_bytes);*\ </big></big> + + #. Clean up + *PK11_FreeSymKey(ToBeWrappedSymKey);* + <big>\ *SECITEM_FreeItem(&WrappedKey, PR_TRUE);*\ </big> + *if (WrappingPubKey) SECKEY_DestroyPublicKey(WrappingPubKey);* + *if (UnwrappingPvtKey) SECKEY_DestroyPrivateKey(UnwrappingPvtKey);* + *PK11_FreeSlot(slot);* + + Also look at a `sample program <../sample-code/sample1.html>`__ that uses the above functions. + + -------------- + +.. _generate_a_symmetric_key_2: + +`Generate a Symmetric Key <#generate_a_symmetric_key_2>`__ +---------------------------------------------------------- + +.. container:: + + | Subsequent to the operation, the symmetric key may need to be transported/stored in wrapped or + raw form. You can find a list of key generation mechanisms in + security/nss/lib/softoken/pkcs11.c - grep for CKF_GENERATE. For some key gen mechanisms, the + keysize is in bytes, and for some it is in bits. + | + + #. <big>Choose a key generation mechanism</big> + *CK_MECHANISM_TYPE keygenMech = CKM_DES_KEY_GEN;* (for example) + #. <big>Generate the key</big> + *PK11SymKey\* SymKey = PK11_KeyGen(slot, keygenMech, NULL, keysize, NULL);* + + <big>You can also see an `sample program <../sample-code/sample1.html>`__ that does key + generation.</big> + + .. rubric:: Extract the raw key (This should not normally be used. Better to use wrapping + instead. See `method1 <#symmetric_key_wrappingunwrapping_sym_key>`__ and + `method2 <#pki_wrap_symkey>`__ ). + :name: extract_the_raw_key_(this_should_not_normally_be_used._better_to_use_wrapping_instead._see_method1_and_method2_). + + *SECStatus rv = PK11_ExtractKeyValue(SymKey); + SECItem \*keydata = PK11_GetKeyData(SymKey);* + + .. rubric:: Generating a persistent symmetric key + :name: generating_a_persistent_symmetric_key + + | *SECItem keyid; + CK_MECHANISM_TYPE cipherMech = CKM_AES_CBC_PAD; + keyid.data = /\* ptr to an array of bytes representing the id of the key to be generated \*/; + keyid.len = /\* length of the array of bytes \*/; + /\* keysize must be 0 for fixed key-length algorithms like DES... and appropriate value + \* for non fixed-key-length algorithms \*/ + PK11SymKey \*key = PK11_TokenKeyGen(slot, cipherMech, 0, 32 /\* keysize \*/, + &keyid, PR_TRUE, + 0);* + | *int keylen = PK11_GetKeyLength(key); + cipherMech = PK11_GetMechanism(key);* + | */\* find the symmetric key in the database \*/ + key = PK11_FindFixedKey(slot, cipherMech, &keyid, 0);* + + -------------- + +.. _moving_a_key_from_one_slot_to_another_2: + +`Moving a Key from one slot to another <#moving_a_key_from_one_slot_to_another_2>`__ +------------------------------------------------------------------------------------ + +.. container:: + + - To move a Private key from one slot to another, wrap the private key on the origin slot and + unwrap it into the destination slot. See section `Symmetric Key Wrapping/Unwrapping of a + Private Key <#symmetric_key_wrappingunwrapping_pvtkey>`__ + - To move a Symmetric key + *PK11SymKey \*destSymKey = pk11_CopyToSlot(destslot, wrapMech, CKA_UNWRAP?, origSymKey);* + + -------------- + +.. _generate_an_rsa_key_pair: + +`Generate an RSA Key Pair <#generate_an_rsa_key_pair>`__ +-------------------------------------------------------- + +.. container:: + + *PK11_GenerateKeyPair*\ <big> is the function to use</big>. See a `sample + program <../sample-code/sample1.html>`__ that uses this function. + + -------------- + +.. _<big>sign_verify_data<big>: + +`<big>Sign & Verify Data</big> <#%3Cbig%3Esign_verify_data%3Cbig%3E>`__ +----------------------------------------------------------------------- + +.. container:: + + | *SECKEYPrivateKey \*pvtkey; + SECItem signature; + SECItem data; + SECStatus s = PK11_Sign(pvtkey, &signature, &data);* + | *SECKeyPublicKey \*pubkey;* + | *SECStatus s = PK11_Verify(pubkey, &signature, &data, NULL);* + + -------------- + +.. _misc_useful_functions: + +`Misc Useful Functions <#misc_useful_functions>`__ +-------------------------------------------------- + +.. container:: + + #. Get the best wrapping mechanism supported by a slot + *CK_MECHANISM_TYPE mech = PK11_GetBestWrapMechanism(PK11SlotInfo \*slot);* + #. <big>Get the best slot for a certain mechanism</big> + *PK11SlotInfo\* slot = PK11_GetBestSlot(mechanism, NULL);* + #. <big>Get the best key length for a certain mechanism on a given slot</big> + *int keylen = PK11_GetBestKeyLength(PK11SlotInfo \*slot, mechanism);* + #. Get the key length of a symmetric key + *int keylen = PK11_GetKeyLength(PK11SymKey \*symkey);* + #. Get the mechanism given a symmetric key + *CK_MECHANISM_TYPE mech = PK11_GetMechanism(PK11SymKey \*key);* + + + --------------
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note6/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note6/index.rst new file mode 100644 index 0000000000..a55425c752 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note6/index.rst @@ -0,0 +1,104 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note6: + +nss tech note6 +============== + +.. _nss_.chk_files_for_the_fips_140_mode: + +`NSS .chk Files for the FIPS 140 Mode + <#nss_.chk_files_for_the_fips_140_mode>`__ +------------------------------------------- + +.. container:: + +.. _nss_technical_note_6: + +`NSS Technical Note: 6 <#nss_technical_note_6>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + In NSS 3.8, we added checksum files required for the NSS softoken to operate in FIPS 140 mode. + The new checksum file is called libsoftokn3.chk on Unix/Linux and softokn3.chk on Windows. It + must be put in the same directory as the NSS libraries. The libsoftokn3.chk/softokn3.chk file + contains a checksum for the softoken. When in FIPS 140 mode, the softoken is required to compute + its checksum and compare it with the value in libsoftokn3.chk/softokn3.chk. + + The following applies to NSS 3.8 through 3.10 : + + | On 32-bit Solaris SPARC (i.e., not x86, and not 64-bit SPARC) and 32-bit HP-UX PA-RISC (i.e., + not Itanium, and not 64-bit PA-RISC), there are two more .chk files: libfreebl_pure32_3.chk and + libfreebl_hybrid_3.chk. + | + + The following applies to NSS 3.11 : + + The low-level freebl cryptographic code has been separated from softoken on all platforms. Even + on platforms for which there is only one implementation of freebl, there is now a separate freebl + shared library. The freebl library implements a private interface internal to NSS. + + - On 32-bit Windows and 32-bit OS/2, this shared library is called freebl3.dll, and the + corresponding .chk file is called freebl3.chk . + - On 32-bit Solaris x86, 64-bit Solaris x64 (AMD64), 32-bit Linux x86, 64-bit Linux x86-64, + 32-bit AIX and 64-bit AIX, this shared library is called libfreebl3.so, and the corresponding + .chk file is called libfreebl3.chk . + - On the 32-bit Solaris SPARC architecture, there are 3 freebl libraries : + + - libfreebl_32int64_3.so for UltraSparc T1 CPUs, with a corresponding libfreebl_32int64_3.chk + - libfreebl_32fpu_3.so for other UltraSparc CPUs, with a corresponding libfreebl_32fpu_3.chk + - libfreebl_32int_3.so for SPARC V8 CPUs, with a corresponding libfreebl_32int_3.chk + + - On the 64-bit Solaris SPARC architecture, there are 2 freebl libraries : + + - libfreebl_64int_3.so for UltraSparc T1 CPUs, with a corresponding libfreebl_64int_3.chk + - libfreebl_64fpu_3.so for other UltraSparc CPUs, with a corresponding libfreebl_64fpu_3.chk + + - On the 32-bit HP-UX PA-RISC architecture, there are 2 freebl libraries : + + - libfreebl_32fpu_3.sl for CPUs that do multiply operations faster in floating point, with a + corresponding libfreebl_32fpu_3.chk + - libfreebl_32int_3.sl for other PA-RISC CPUs, with a corresponding libfreebl_32int_3.chk + + - On the 64-bit HP-UX PA-RISC architecture, there is only one freebl library, called + libfreebl3.sl, with a corresponding libfreebl3.chk + + Applications should always use NSS binaries that are the output of the regular NSS build process. + If your application modifies NSS binaries for any reason after they were built, then : + + - The FIPS 140 mode of operation will no longer work, because the chk files will no longer match + the softoken and freebl shared libraries . + - The softoken and freebl binaries won't match any NSS binaries that may have been submitted to + NIST for validation, and thus may not be verified as being the actual FIPS 140 validated + cryptographic module . The only way to meet this requirement is for your application never to + modify the NSS binaries. + - Any offer of binary support that may have been previously made to you by NSS developers is + null and void. + + If your build process modifies NSS libraries in any way (for example, to strip the symbols), it + should consider not doing so for the reasons cited above. If you still decide to make unsupported + changes, you can allow the softoken to come up in FIPS 140 mode of operation by regenerating the + .chk files yourself. The tool to do that is called shlibsign. It is released as part of the NSS + binary distributions. + If your build process does not modify NSS shared libraries, you can just use the .chk files in + the NSS binary distributions. + + So you have two options. + + 1. Do not modify NSS libraries in your build process. Specifically, do not modify libsoftokn3.so, + libsoftokn3.sl, softokn3.dll, libfreebl_pure32_3.so, libfreebl_pure32_3.sl, + libfreebl_hybrid_3.so,libfreebl_hybrid_3.sl, libfreebl3.so, libfreebl3.sl, freebl3.dll, + libfreebl_32int64_3.so, libfreebl_32int_3.so, libfreebl_32fpu_3.so, libfreebl_64int_3.so, + libfreebl_64fpu_3.so, libfreebl_32int_3.sl, libfreebl_32fpu_3.sl; or + + 2. Use shlibsign to regenerate the .chk files. For example, on 32-bit Solaris SPARC for NSS + 3.11, say + + shlibsign -v -i libsoftokn3.so + shlibsign -v -i libfreebl_32int64_3.so + shlibsign -v -i libfreebl_32fpu_3.so + shlibsign -v -i libfreebl_32int_3.so + + (You need to set LD_LIBRARY_PATH appropriately and specify the correct pathnames of the + libraries.) + + Option 1 is simpler and highly preferred.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note7/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note7/index.rst new file mode 100644 index 0000000000..f7fa00f6d9 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note7/index.rst @@ -0,0 +1,189 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note7: + +nss tech note7 +============== + +.. _rsa_signing_and_encryption_with_nss: + +`RSA Signing and Encryption with NSS <#rsa_signing_and_encryption_with_nss>`__ +------------------------------------------------------------------------------ + +.. container:: + +.. _nss_technical_note_7: + +`NSS Technical Note: 7 <#nss_technical_note_7>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This technical note explains how to use NSS to perform RSA signing and encryption. The industry + standard for RSA signing and encryption is `PKCS + #1 <http://www.rsasecurity.com/rsalabs/node.asp?id=2125>`__. NSS supports PKCS #1 v1.5. NSS + doesn't yet support PKCS #1 v2.0 and v2.1, in particular OAEP, but OAEP support is on our `to-do + list <https://bugzilla.mozilla.org/show_bug.cgi?id=158747>`__. Your contribution is welcome. + +.. _data_types: + +`Data Types <#data_types>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS uses the following data types to represent keys: + + - ``SECKEYPublicKey``: a public key, defined in "keythi.h". + - ``SECKEYPrivateKey``: a private key, defined in "keythi.h". + - ``PK11SymKey``: a symmetric key (often called a session key), defined in "secmodt.h". + + | These data types should be used as if they were opaque structures, that is, they should only be + created by some NSS functions and you always pass pointers to these data types to NSS functions + and never examine the members of these structures. + | The strength of an RSA key pair is measured by the size of its modulus because given the + modulus and public exponent, the best known algorithm for computing the private exponent is to + factor the modulus. At present 1024 bit and 2048 bit RSA keys are the most common and + recommended. To prevent denial-of-service attacks with huge public keys, NSS disallows modulus + size greater than 8192 bits. + | How are these keys created in NSS? There are a few possibilities. + + - RSA key pairs may be generated inside a crypto module (also known as a token). Use + ``PK11_GenerateKeyPair()`` to generate a key pair in a crypto module. + + - Key pairs may be generated elsewhere, exported in encrypted form, and imported into a crypto + module. + + - | Public keys may be imported into NSS. Call ``SECKEY_ImportDERPublicKey()`` with + ``type=CKK_RSA`` to import a DER-encoded RSA public key. If you have the modulus and public + exponent, you need to first encode them into an RSA public key and then import the public + key into NSS. + | PKCS #1 defines an RSA public key as a ``SEQUENCE`` of modulus and public exponent, both of + which are ``INTEGER``\ s. Here is the ASN.1 type definition: + + .. code:: + + RSAPublicKey ::= SEQUENCE { + modulus INTEGER, -- n + publicExponent INTEGER -- e } + + The following sample code (error handling omitted for brevity) encodes a ``RSAPublicKey`` from + a modulus and a public exponent and imports the public key into NSS. + + .. code:: + + struct MyRSAPublicKey { + SECItem m_modulus; + SECItem m_exponent; + } inPubKey; + + SECItem derPubKey; + + SECKEYPublicKey *pubKey; + + const SEC_ASN1Template MyRSAPublicKeyTemplate[] = { + { SEC_ASN1_SEQUENCE, 0, NULL, sizeof(MyRSAPublicKey) }, + { SEC_ASN1_INTEGER, offsetof(MyRSAPublicKey,m_modulus), }, + { SEC_ASN1_INTEGER, offsetof(MyRSAPublicKey,m_exponent), }, + { 0, } + }; + + PRArenaPool *arena; + + /* + * Point inPubKey.m_modulus and m_exponent at the data, and + * then set their types to unsigned integers. + */ + inPubKey.m_modulus.type = siUnsignedInteger; + inPubKey.m_exponent.type = siUnsignedInteger; + + arena = PORT_NewArena(DER_DEFAULT_CHUNKSIZE); + SEC_ASN1EncodeItem(arena, &derPubKey, &inPubKey, + MyRSAPublicKeyTemplate); + pubKey = SECKEY_ImportDERPublicKey(&derPubKey, CKK_RSA); + PORT_FreeArena(arena, PR_FALSE); + + - Public keys may be extracted from certificates. Given a certficate (``CERTCertificate *``), + use ``CERT_ExtractPublicKey()`` to extract its public key. The returned public key may be used + after the certificate is destroyed. + + When the keys are no longer needed, they need to be destroyed. + + - Use ``SECKEY_DestroyPublicKey()`` to destroy a public key (``SECKEYPublicKey *``). + - Use ``SECKEY_DestroyPrivateKey()`` to destroy a private key (``SECKEYPrivateKey *``). + - Unlike ``SECKEYPublicKey`` and ``SECKEYPrivateKey``, ``PK11SymKey`` objects are reference + counted. Use ``PK11_ReferenceSymKey()`` to acquire a reference to a symmetric key + (``PK11SymKey *``). Use ``PK11_FreeSymKey()`` to release a reference to a symmetric key + (``PK11SymKey *``); the symmetric key is destroyed when its reference count becomes zero. + +`Functions <#functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | RSA signing and encryption functions are provided by two layers of NSS function: the ``SGN_`` + and ``VFY_`` functions in cryptohi.h, and the ``PK11_`` functions in pk11pub.h. As a general + principle, you should use the highest layer of NSS you can possibly use for what you are trying + to accomplish. + | For example, if you just need to generate or verify a signature, you can use the ``SGN_`` and + ``VFY_`` functions in cryptohi.h. + | If you need to interoperate with a protocol that isn't implemented by NSS, then you may need to + use the ``PK11_`` functions. (This API pretty much consists of what was needed to implement SSL + and S/MIME, plus a few enhancements over the years to support JSS.) When using the ``PK11_`` + interfaces, the same principal applies: use the highest available function. + | If you are really trying to send a key, you should use ``PK11_PubWrapSymKey()``. For a low + level signature, use ``PK11_Sign()``. Both of these functions do the PKCS #1 wrapping of the + data. ``PK11_Sign`` does not do the BER encoding of the hash (as is done in ``SGN_`` + functions). + | If you are trying to just send data, use ``PK11_PubEncryptPKCS1``. + | ``PK11_PubEncryptRaw`` is the lowest level function. It takes a modulus size data and does a + raw RSA operation on the data. It's used to support SSL2, which modifies the key encoding to + include the SSL version number. + +.. _pkcs_1_v1.5_block_formatting: + +`PKCS #1 v1.5 Block Formatting <#pkcs_1_v1.5_block_formatting>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | Question: + | In PKCS #1 v1.5 (Section 8.1 Encryption-block formatting) and v2.1 (Section 7.2.1 Encryption + operation), PKCS1 v1.5 padding is described like this: + | ``00 || 02 || PS || 00 || M`` + | but in PKCS #1 v2.0 (Section 9.1.2.1 Encoding operation, Step 3) and on the W3C web site + (http://www.w3.org/TR/xmlenc-core/#rsa-1_5), PKCS1 v1.5 padding is described like this: + | ``02 || PS || 00 || M`` + | 00 at the beginning is missing. Why? + | Answer: + | The version without the initial 00 says : + + .. container:: + + "PS is a string of strong pseudo-random octets [RANDOM] [...] long enough that the value of + the quantity being CRYPTed is one octet shorter than the RSA modulus" + + | + | The version with the initial 00 instead says to pad to the same length as the RSA modulus. + | "The same length as the RSA modulus with an initial octet of 0" and "one octet shorter without + that initial octet" are exactly the same thing because the formatted block is treated as a + big-endian big integer by the RSA algorithm. The leading 00 octet is simply eight most + significant 0 bits. For example, 0x00123456 is equal to 0x123456. + | Perhaps this change made in PKCS #1 v2.0 confused many people, so it was reversed in v2.1. + +.. _sample_code: + +`Sample Code <#sample_code>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_nss_sample_code_nss_sample_code_sample4` + +`References <#references>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `RSA Labs PKCS #1 web site <http://www.rsasecurity.com/rsalabs/node.asp?id=2125>`__ + - `RFC 3447 <http://www.ietf.org/rfc/rfc3447.txt>`__: RSA PKCS #1 v2.1 + - `Poupou's Blog: Common question: How to encrypt using + RSA <http://www.dotnet247.com/247reference/a.aspx?u=http://pages.infinit.net/ctech/20031101-0151.html>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note8/index.rst b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note8/index.rst new file mode 100644 index 0000000000..efbb737d82 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tech_notes/nss_tech_note8/index.rst @@ -0,0 +1,130 @@ +.. _mozilla_projects_nss_nss_tech_notes_nss_tech_note8: + +nss tech note8 +============== + +.. _background_information_on_libssl's_cache_functions_and_sids: + +`Background Information on libSSL's Cache Functions and SIDs <#background_information_on_libssl's_cache_functions_and_sids>`__ +------------------------------------------------------------------------------------------------------------------------------ + +.. container:: + +.. _nss_technical_note_8: + +`NSS Technical Note: 8 <#nss_technical_note_8>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + 27 February 2006 + Nelson B. Bolyard + + Here is some background information on libSSL's cache functions and SIDs. + + A SID (or sslSessionID struct) contains all the info needed to restart + the ssl session at a later time on another socket. The protocol code + builds such a structure, and then asks the cache code (client or server) + to save the info. The protocol code can also ask to remove a SID from + the cache. + + Every SSL socket has two function pointers, ss->sec.cache and ss->sec.uncache, + which have the following types: + typedef void (*sslSessionIDCacheFunc) (sslSessionID *sid); + typedef void (*sslSessionIDUncacheFunc)(sslSessionID *sid); + + There are two separate implementations of each function, one for clients + and one for servers. The client implementation caches or uncaches the + SID in the client session cache. The server implementation caches or + uncaches the SID in the server session cache. + + For servers these pointers point to + sec->cache = ssl_sid_cache; + sec->uncache = ssl_sid_uncache; + which are functions defined in sslsnce.c, the server session cache source file. + + For clients these pointers point to + sec->cache = CacheSID; + sec->uncache = LockAndUncacheSID; + which are functions defined in sslnonce.c, the client session cache source file. + + The same cache/uncache API is used by both client and server code. + As originally designed, before calling the cache function, the caller was + responsible to fill in the session creation time (which might not be the + same as the time of insertion into the cache) and the session expiration + time, among other things. + + Since NSS 1.0, up until NSS 3.4, there were two global variables that + contained the expected session lifetimes for ssl2 and ssl3 sessions. + + extern PRUint32 ssl_sid_timeout; (the ssl2 session lifetime) + extern PRUint32 ssl3_sid_timeout; (the ssl3 session lifetime) + + Each of these variables applied to both client and server sessions. + That is, the client session lifetime was NOT separately settable from the + server session lifetime. + + These two variables were private, declared in a private header file. + There was no API function by which client programs could set these values. + However since NSS was delivered as archive libraries, client programs + merely declared these two variables for themselves, and then were able to + alter those variables directly. + + For server programs, the function for initializing the server session cache + would set these two variables according to two of the arguments to that + function. + + So, SSL protocol code that wanted to cache a SID would do these steps, + whether for client or for server: + + For ssl2: + sid->lastAccessTime = sid->creationTime = ssl_Time(); + sid->expirationTime = sid->creationTime + ssl_sid_timeout; + (*ss->sec.cache)(sid); + for ssl3: + sid->lastAccessTime = sid->creationTime = ssl_Time(); + sid->expirationTime = sid->creationTime + ssl3_sid_timeout; + (*ss->sec.cache)(sid); + + The cache API was defined such that the caller MUST set creationTime + properly, and may set expirationTime to the desired value or to zero. + If zero, then the called cache function would compute the correct + expiration time by adding the chosen timeout (from one of those two + global variables) to the SID's creationTime, giving the expirationTime. + + However, none of the callers relied on the ability of the respective + cache functions to be able to compute the expiration time. All callers + computed the expiration times explicitly, as shown above. + + The server side of the session cache code was largely rewritten for + NSS 3.4. The objectives were to make the server session cache faster, + and to fix bugs that caused corruption in multi-process servers, and also + to allow separate virtual servers to have their own session caches. + + The new approach was to use shared memory for the server session cache, + and to allow multiple different server session caches to coexist. + As part of that work, I decided that each cache would have its own + variables containing the SSL2 and SSL3 session durations. + This means that client cache session lifetimes are separate from server + session cache lifetimes, and that each server session cache may have its + own lifetimes. + + So, in NSS 3.4, the global variables ssl3_sid_timeout and ssl_sid_timeout + were intended to become the definitions for the client cache only, and + each server cache had its own new pair of variables for ssl2 and ssl3 + session lifetimes, i.e., cache->ssl2Timeout and cache->ssl3Timeout. + The server cache initialization function was intended to no longer alter + the variables ssl3_sid_timeout and ssl_sid_timeout, but rather to set the + server cache's variables. + + Since all the callers of the socket's cache function always initialized + both their creationTime and expirationTime using the client's session + lifetime variables, I changed the server's caching function to IGNORE the + expirationTime computed by the caller, and compute its own expiration + time, using the cache's own timeout values, or that was the intent. + + But an implementation flaw caused the caching code to continue to use the + client's timeout time values, not the server cache's own timeout values. + That is the subject of bug 223242.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_third-party_code/index.rst b/security/nss/doc/rst/legacy/nss_third-party_code/index.rst new file mode 100644 index 0000000000..499d4b0985 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_third-party_code/index.rst @@ -0,0 +1,45 @@ +.. _mozilla_projects_nss_nss_third-party_code: + +NSS Third-Party Code +==================== + +.. container:: + + This is a list of third-party code included in the NSS repository, broken into two lists: Code + that can be compiled into the NSS libraries, and code that is only used for testing. + + Note that not all code that can be compiled into the NSS libraries necessarily *is*. Often this + is configurable at build time, with various trade-offs. + +.. _compiled_in: + +`Compiled In <#compiled_in>`__ +------------------------------ + +.. container:: + + - sqlite [/lib/sqlite] + - BerkleyDB [/lib/dbm] + - zlib [/lib/zlib] + - libjar [/lib/jar] + - Fiat-Crypto, Ring [lib/freebl/ecl] + +.. _used_for_tests: + +`Used for Tests <#used_for_tests>`__ +------------------------------------ + +.. container:: + + - GTest [/gtests] + +.. _downloaded_by_certain_test_tooling: + +`Downloaded by certain test tooling <#downloaded_by_certain_test_tooling>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - TLSFuzzer [/tests/tlsfuzzer] + - BoGo tests [/tests/bogo] + - BoringSSL, OpenSSL [/tests/interop]
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/nss_tools_sslstrength/index.rst b/security/nss/doc/rst/legacy/nss_tools_sslstrength/index.rst new file mode 100644 index 0000000000..3a53baa606 --- /dev/null +++ b/security/nss/doc/rst/legacy/nss_tools_sslstrength/index.rst @@ -0,0 +1,81 @@ +.. _mozilla_projects_nss_nss_tools_sslstrength: + +NSS Tools sslstrength +===================== + +`sslstrength <#sslstrength>`__ +------------------------------ + +.. container:: + +`Summary <#summary>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A simple command-line client which connects to an SSL-server, and reports back the encryption + cipher and strength used. + +`Synopsis <#synopsis>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + 1) sslstrength ciphers + 2) sslstrength hostname[:port] [ciphers=xyz] [debug] [verbose] [policy=export|domestic] + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The first form simple lists out the possible ciphers. The letter in the first column of the + output is used to identify the cipher preferences in the ciphers= command. + The second form attempts to connect to the named ssl host. The hostname argument must be present. + However, the port number is an optional argument, and if not given, will default to the https + port (443). + + .. rubric:: Restricting Ciphers + :name: restricting_ciphers + + By default, sslstrength assumes that all the preferences are on, so it will use any preferences + in your policy. The enabled ciphersuites will always be printed out before the connection is + made. If you want to test out a particular cipher, there are two ways to affect which ciphers are + available. Firstly, you can set **policy** to be either domestic or export. This restricts the + available ciphers to the same set used by Communicator. In addition to this, the **ciphers** + command can be used to further restrict the ciphers available. The argument to the ciphers + command is a string of characters, where each single character represents a cipher. You can + obtain this list of character->cipher mappings by doing 'sslstrength ciphers'. For example, + ** ciphers=bfi** will turn on these cipher preferences and turn off all others. + + ** policy=export** or **policy=domestic** will set your policies appropriately. + + | ** policy** will default to domestic if not specified. + + .. rubric:: Step-up + :name: step-up + + Step up is a mode where the connection starts out with 40-bit encryption, but due to a + 'change-cipher-spec' handshake, changes to 128-bit encryption. This is only done in 'export + mode', with servers with a special certificate. You can tell if you stepped-up, because the + output will says 'using export policy', and you'll find the secret key size was 128-bits. + +`Prerequisites <#prerequisites>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + You should have a cert7.db in the directory in which you run sslstrength. + +`Other <#other>`__ +~~~~~~~~~~~~~~~~~~ + +.. container:: + + For references, here is a table of well-known SSL port numbers: + + ===== === + HTTPS 443 + IMAPS 993 + NNTPS 563 + ===== ===
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/overview/index.rst b/security/nss/doc/rst/legacy/overview/index.rst new file mode 100644 index 0000000000..287226fac0 --- /dev/null +++ b/security/nss/doc/rst/legacy/overview/index.rst @@ -0,0 +1,167 @@ +.. _mozilla_projects_nss_overview: + +Overview of NSS +=============== + +.. container:: + + .. rubric:: Open Source Crypto Libraries + :name: Open_Source_Crypto_Libraries + +.. _proven_application_security_architecture: + +`Proven Application Security Architecture <#proven_application_security_architecture>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + If you want to add support for SSL, S/MIME, or other Internet security standards to your + application, you can use Network Security Services (NSS) to implement all your security features. + NSS provides a complete open-source implementation of the crypto libraries used by AOL, Red Hat, + Google, and other companies in a variety of products, including the following: + + - `Mozilla products <https://www.mozilla.org/products/>`__, including + `Firefox <https://www.mozilla.com/firefox/>`__, + `Thunderbird <https://www.mozilla.com/thunderbird/>`__, + `SeaMonkey <https://seamonkey-project.org/>`__, and `Firefox + OS <https://support.mozilla.org/en-US/products/firefox-os>`__. + - AOL Instant Messenger (AIM) + - Open source client applications such as `Evolution <https://wiki.gnome.org/Apps/Evolution>`__, + `Pidgin <https://pidgin.im/>`__, `Apache OpenOffice <https://www.openoffice.org/>`__, and + `LibreOffice <https://www.libreoffice.org>`__. + - Server products from `Red Hat <https://www.redhat.com/en/technologies>`__: `Red Hat Directory + Server <https://www.redhat.com/en/technologies/cloud-computing/directory-server>`__, `Red Hat + Certificate + System <https://www.redhat.com/en/technologies/cloud-computing/certificate-system>`__, and the + `mod_nss <https://directory.fedoraproject.org/docs/389ds/administration/mod-nss.html>`__ SSL + module for the Apache web server. + - Server products from Oracle (formerly Sun Java Enterprise System), including `Oracle + Communications Messaging + Server <https://www.oracle.com/industries/communications/enterprise/products/messaging-server/index.html>`__ + and `Oracle Directory Server Enterprise + Edition <http://www.oracle.com/technetwork/middleware/id-mgmt/overview/index-085178.html>`__. + - `SUSE Linux Enterprise Server <https://www.suse.com/products/server/>`__ supports NSS and the + `mod_nss <https://documentation.suse.com/sles/11-SP4/html/SLES-all/cha-apache2.html#sec-apache2-nss>`__ + SSL module for the Apache web server. + + NSS includes a framework to which developers and OEMs can contribute patches, such as assembler + code, to optimize performance on their platforms. NSS 3.x has been certified on 18 platforms. + + For more detailed information about NSS, see `wiki.mozilla.org <https://wiki.mozilla.org/NSS>`__ + and `NSS FAQ <NSS_FAQ>`__. + + Source code for a Java interface to NSS is available in the Mozilla CVS tree. For details, see + `Network Security Services for Java <JSS>`__. + + NSS makes use of Netscape Portable Runtime + (`NSPR <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR>`__), a platform-neutral + open-source API for system functions designed to facilitate cross-platform development. Like NSS, + NSPR has been battle-tested in multiple products. For more information, see the `NSPR Project + Page <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR>`__. + +.. _interoperability_and_open_standards: + +`Interoperability and Open Standards <#interoperability_and_open_standards>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + You can use NSS to support a range of security standards in your application, including the + following: + + - `SSL v3 </en-US/Glossary#SSL>`__. The Secure Sockets Layer (SSL) protocol allows mutual + authentication between a client and server and the establishment of an authenticated and + encrypted connection. + - TLS v1.3 (`RFC 8446 <https://datatracker.ietf.org/doc/html/rfc8446>`__), `TLS v1.2 (RFC + 5246 <https://datatracker.ietf.org/doc/html/rfc5246>`__), `TLS v1.1 (RFC + 4346 <https://datatracker.ietf.org/doc/html/rfc4346>`__), `TLS v1 + ( <https://www.ietf.org/rfc/rfc2246.txt>`__\ `RFC + 2246 <https://datatracker.ietf.org/doc/html/rfc2246>`__). The Transport Layer Security (TLS) + protocol from the IETF that supersedes SSL. + - `PKCS #1 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-1/index.html>`__. RSA standard that + governs implementation of public-key cryptography based on the RSA algorithm. + - `PKCS #3 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-3/index.html>`__. RSA standard that + governs implementation of Diffie-Hellman key agreement. + - `PKCS #5 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-5/index.html>`__. RSA standard that + governs password-based cryptography, for example to encrypt private keys for storage. + - `PKCS #7 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-7/index.html>`__. RSA standard that + governs the application of cryptography to data, for example digital signatures and digital + envelopes. + - `PKCS #8 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-8/index.html>`__. RSA standard that + governs the storage and encryption of private keys. + - `PKCS #9 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-9/index.html>`__. RSA standard that + governs selected attribute types, including those used with PKCS #7, PKCS #8, and PKCS #10. + - `PKCS #10 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-10/index.html>`__. RSA standard that + governs the syntax for certificate requests. + - `PKCS #11 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-11/index.html>`__. RSA standard that + governs communication with cryptographic tokens (such as hardware accelerators and smart + cards) and permits application independence from specific algorithms and implementations. + - `PKCS #12 <https://www.rsasecurity.com/rsalabs/pkcs/pkcs-12/index.html>`__. RSA standard that + governs the format used to store or transport private keys, certificates, and other secret + material. + - `S/MIME (RFC 2311 and RFC 2633) </en-US/Glossary#S.2FMIME>`__. IETF message specification + (based on the popular Internet MIME standard) that provides a consistent way to send and + receive signed and encrypted MIME data. + - `X.509 v3 <https://developer.mozilla.org/en-US/docs/Mozilla/Security/x509_Certificates>`__. + ITU standard that governs the format of certificates used for authentication in public-key + cryptography. + - `OCSP (RFC 2560) </en-US/Glossary#OCSP>`__. The Online Certificate Status Protocol (OCSP) + governs real-time confirmation of certificate validity. + - `PKIX Certificate and CRL Profile ( <https://www.ietf.org/rfc/rfc3280.txt>`__\ `RFC + 3280 <https://datatracker.ietf.org/doc/html/rfc3280>`__). The first part of the four-part + standard under development by the Public-Key Infrastructure (X.509) working group of the IETF + (known at PKIX) for a public-key infrastructure for the Internet. + - RSA, DSA, ECDSA, Diffie-Hellman, EC Diffie-Hellman, + `AES <https://en.wikipedia.org/wiki/Advanced_Encryption_Standard>`__, Triple DES, DES, RC2, + RC4, SHA-1, SHA-256, SHA-384, SHA-512, MD2, MD5, HMAC: Common cryptographic algorithms used in + public-key and symmetric-key cryptography. + - FIPS 186-2 pseudorandom number generator. + + For complete details, see `Encryption + Technologies <https://www.mozilla.org/projects/security/pki/nss/nss-3.11/nss-3.11-algorithms.html>`__. + +.. _fips_140_validation_and_niscc_testing: + +`FIPS 140 Validation and NISCC Testing <#fips_140_validation_and_niscc_testing>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The NSS software crypto module has been validated three times for conformance to FIPS 140 at + Security Levels 1 and 2. For more information, see the `NSS FIPS <FIPS_Mode_-_an_explanation>`__ + page (`Or this one <https://wiki.mozilla.org/FIPS_Validation>`__). + + The NSS libraries passed the NISCC + `TLS/SSL <https://www.niscc.gov.uk/niscc/docs/re-20030930-00749.pdf?lang=en>`__ and + `S/MIME <https://www.uniras.gov.uk/niscc/docs/re-20031104-00752.pdf?lang=en>`__ test suites (1.6 + million test cases of invalid input data). + +.. _complete_software_development_kit: + +`Complete Software Development Kit <#complete_software_development_kit>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + In addition to libraries and APIs, NSS provides :ref:`mozilla_projects_nss_tools` required for + debugging, diagnostics, certificate and key management, cryptography module management, and other + development tasks. + + NSS comes with an extensive and growing set of :ref:`mozilla_projects_nss#documentation`, + including introductory material, API references, man pages for command-line tools, and + :ref:`mozilla_projects_nss_nss_sample_code`. + + NSS is available as source and shared (dynamic) libraries. Every NSS release is backward + compatible with previous releases, allowing NSS users to upgrade to the new NSS shared libraries + without recompiling or relinking their applications. + +.. _open-source_licensing_and_distribution: + +`Open-Source Licensing and Distribution <#open-source_licensing_and_distribution>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS is available under the `Mozilla Public License <https://www.mozilla.org/MPL/>`__, version 2. + The latest source code is available for free worldwide from https://www.mozilla.org and its + mirror sites.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs11/faq/index.rst b/security/nss/doc/rst/legacy/pkcs11/faq/index.rst new file mode 100644 index 0000000000..81fe124736 --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs11/faq/index.rst @@ -0,0 +1,390 @@ +.. _mozilla_projects_nss_pkcs11_faq: + +PKCS11 FAQ +========== + +.. _pkcs11_faq: + +`PKCS11 FAQ <#pkcs11_faq>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: QUESTIONS AND ANSWERS + :name: questions_and_answers + + .. rubric:: GENERAL QUESTIONS + :name: general_questions + + .. rubric:: After plugging in an external PKCS #11 module, how do you use the certificate + available on the token? Does the certificate need to be imported into NSS's internal + certificate database? If so, is there a way to get the certificate from an external token into + NSS's internal certificate database? + :name: after_plugging_in_an_external_pkcs_.2311_module.2c_how_do_you_use_the_certificate_available_on_the_token.3f_does_the_certificate_need_to_be_imported_into_nss.27s_internal_certificate_database.3f_if_so.2c_is_there_a_way_to_get_the_certificate_from_an_external_token_into_nss.27s_internal_certificate_database.3f + + NSS searches all the installed PKCS #11 modules when looking for certificates. Once you've + installed the module, the module's certificates simply appear in the list of certificates + displayed in the Certificate window. + + .. rubric:: What version of PKCS #11 does NSS support? + :name: what_version_of_pkcs_.2311_does_nss_support.3f + + NSS requires at least PKCS #11 version 2.0, but can support some features of later versions of + NSS, including NSS 2.20. NSS does not use all the features of later versions of PKCS #11. + + .. rubric:: What are the expectations in terms of session manipulation? Will NSS potentially open + more than one session at a time? Read-only sessions, read/write sessions, serial, parallel? + :name: what_are_the_expectations_in_terms_of_session_manipulation.3f_will_nss_potentially_open_more_than_one_session_at_a_time.3f_read-only_sessions.2c_read.2fwrite_sessions.2c_serial.2c_parallel.3f + + NSS typically holds one session read-only session per slot, in which some of the non-multipart + functions are handled. Multipart functions, such as bulk encryption, hashing, and mac functions + (for example, C_Digest and C_Sign) and those that require overlapped operation (C_Unwrap, + C_Decrypt) are handled by creating new sessions. If no new sessions are available, the one + read-only session is used, and the state is saved and restored after each multipart operation. + + NSS never uses Parallel mode. + + NSS opens new read/write sessions for key generation, some password management, and storage of + new certificates. + + If your token is read/write and has only one session, NSS will open that one initial session + read/write. + + .. rubric:: What permanent PKCS #11 objects are used by NSS or read from the token? Example: RSA + private key, CA certificate, user's own certificate, user's name. + :name: what_permanent_pkcs_.2311_objects_are_used_by_nss_or_read_from_the_token.3f_example:_rsa_private_key.2c_ca_certificate.2c_user.27s_own_certificate.2c_user.27s_name. + + Private keys (RSA and DSA) and the corresponding certificates are read from the token. Other + certificates on the token are also loaded (to allow building certificate chains), but it's not + necessary to include the full chain, as long as the full chain is available in the regular + certificate database. For the sake of completeness, it's also a good idea to expose public key + objects. NSS falls back to looking for the existance of public keys to determine if the token may + have the corresponding private key while the token is not logged in. + + .. rubric:: How are permanent PKCS #11 objects found by NSS? That is, which PKCS #11 attributes + are used in the object searches? Labels? Key IDs? Key types? + :name: how_are_permanent_pkcs_.2311_objects_found_by_nss.3f_that_is.2c_which_pkcs_.2311_attributes_are_used_in_the_object_searches.3f_labels.3f_key_ids.3f_key_types.3f + + These are the general guidelines: + + - User certificates are identified by their labels. + - Certificates and keys are often looked up by the following methods: + + - By looking up all private keys. + - By looking up all certificates. + - Certificates may be looked up by label. By convention, all certificates making up a single + personality should have the same label (that is, a pair of certificates, one for signing + and one for key exchange, should have the same label). + - S/MIME-capable certificates are also looked up by issuer/serial number. + - Certificates may be looked up by their DER value. + - Certificates may also be looked up by subject. More than one certificate can match, but + each certificate with the same subject should be part of the same personality. + - NSS may enumerate all the permanment certificates in a token (CKA_TOKEN set to true). + - Private keys must have the same CKA_ID value as their corresponding certificate, and this + value must be unique on the token. + - Orphaned keys have a CKA_ID generated from some part of the public key. This value is set + when the key is generated, so that NSS will be able to find the key when the certificate + for that key is loaded. This case is interesting only for read/write tokens. + + .. rubric:: What labels does NSS use to identify certificates? + :name: what_labels_does_nss_use_to_identify_certificates.3f + + NSS can use the CKA_LABEL attribute to identify user certificates (see previous question) and + presents this label to the user. Therefore, each user certificate must have some label associated + with it. The label for a token certificate is presented to the user as follows:*token label* + **:**\ *certificate label* . This implies that each\ *token label* should be unique and + meaningful to the user, and that each\ *certificate label* should be unique to the token. + + NSS gets the value of the CKA_LABEL attribute from the token. Labels should not have any trailing + blank characters. + + .. rubric:: Will NSS use the random number generation features of PKCS #11? + :name: will_nss_use_the_random_number_generation_features_of__pkcs_.2311.3f + + Only if you identify your token as the default random number generator. If you do, your token + must be able to generate random numbers even when it is not logged in. NSS uses installed random + number generators if PKCS11_MECH_RANDOM_FLAG is set in the installer script. For information on + how to do this, see Using the JAR Installation Manager to Install a PKCS #11 Cryptographic + Module. + + .. rubric:: Can Mozilla provide a list of all PKCS #11 functions that NSS will use? + :name: can_mozilla_provide_a_list_of_all_pkcs_.2311_functions_that_nss_will_use.3f + + Your token should expect to implement all the PKCS #11 functions that make sense for your token. + NSS continues to evolve, and periodically enhances it's functionality by using a more complete + list of PKCS #11 functions. You should have implementations for all the functions specified in + the version of the PKCS #11 spec your token implements. If you do not actually do the operation + specified by that function, you can return CKR_FUNCTION_NOT_SUPPORTED. + + .. rubric:: Will NSS get the user's CA certificate via PKCS #11 and push it into the CA + certificate database or is the CA certificate database expected to obtain the CA certificate + by some other means? + :name: will_nss_get_the_user.27s_ca_certificate_via_pkcs_.2311_and_push_it_into_the_ca_certificate_database_or_is_the_ca_certificate_database_expected_to_obtain_the_ca_certificate_by_some_other_means.3f + + PKCS #11 certificates that have private keys associated with them are loaded into the temporary + database (in memory) and marked as user certificates. All other certificates in the module are + loaded into the temporary database with no special trust bits associated with them. NSS is + perfectly capable of using token certificates in place. + + .. rubric:: Which function does NSS use to get login state information? + :name: which_function_does_nss_use_to_get_login_state_information.3f + + NSS calls C_GetSessionInfo to get the login/logout state. NSS never attempts to cache this + information, because login state can change instantly without NSS knowing about it (for example, + when the user removes the card). You must update all sessions correctly when the state changes. + Not doing so is a common source of problems. + + .. rubric:: I have noticed that NSS sometimes use a session handle value of 0. Is this an invalid + session handle? + :name: i_have_noticed_that_nss_sometimes_use__a_session_handle_value_of_0._is_this_an_invalid_session_handle.3f + + A session handle of 0 is indeed invalid. In the past, NSS uses the invalid session handle to mark + problems with acquiring or using a session. There have been cases where NSS would then use this + handle to try to do some operation. PKCS #11 modules should fail with CKR_INVALID_SESSION. We are + working to remove these cases as we find them. + + .. rubric:: What are "Generic Crypto Svcs" (the first item listed when you click the View/Edit + button for the NSS Internal PKCS #11 Module under Security Devices under Options/Security in + Firefox)? + :name: what_are_.22generic_crypto_svcs.22_.28the_first_item_listed_when_you_click_the_view.2fedit_button_for_the_nss_internal_pkcs_.2311_module__under_security_devices_under_options.2fsecurity_in_firefox.29.3f + + Generic Crypto Svcs are the services that NSS uses to do its basic cryptography (RSA encryption + with public keys, hashing, AES, DES, RC4, RC2, and so on).Other PKCS #11 modules can supply + implementations of these functions, and NSS uses those versions under certain conditions. + However, these are not the services NSS calls to get to other PKCS #11 modules, which show up + separately under Cryptographic Modules. + + .. rubric:: Our plugin provides several slots with different capabilities. For example, one does + all the hashing/symmetric operations, while another does only asymmetric RSA operations. Can + this kind of division lead to problems? + :name: our_plugin_provides_several_slots_with_different_capabilities._for_example.2c_one_does_all_the_hashing.2fsymmetric_operations.2c_while_another_does_only_asymmetric_rsa_operations._can_this_kind_of_division_lead_to_problems.3f + + The only issue is dealing with keys. For example, if the RSA slot unwraps a key, NSS needs to + move that key to a slot that can do the symmetric operations. NSS itself uses two tokens + internally--one that provides generic cryptographic services without authentication, and one that + provides operations based on the keys stored in the user's database and do need authentication. + NSS does this to avoid having to prompt for a password when performing an RSA verify operation, + DES encryption, and so on. Therefore, NSS can move keys around when necessary and possible. When + operating in FIPS mode, moving keys is significantly harder. In this case NSS uses a single token + to handle both key and cert storage and crypto operations. + + In general, you not should use different slots unless you have a good reason. Much of NSS's token + selection is based on where the key involved is currently stored. If the token that has your + private keys doesn't also do symmetric operations, for example, it's likely that the internal + token will end up doing the symmetric operations. + + .. rubric:: Is the PKCS #11 module supplied with NSS accessible through a shared library? + :name: is_the_pkcs_.2311_module_supplied_with_nss_accessible_through_a_shared_library.3f + + Yes, the token is call softokn3 (softokn3.dll on windows, libsoftokn3.so on most unix platforms). + The NSS softokn3 is not a complete PKCS #11 module, it was implemented only to support NSS, + though other products have managed to get it to work in their environment. There are a number of + bugs against softoken's non-compliance, but these bugs have lower priority than fixing NSS's + non-complient uses of PKCS #11 or adding new features to NSS. + + .. rubric:: If multiple PKCS #11 modules are loaded, how does NSS determine which ones to use for + the mechanisms required by SSL? + :name: if_multiple_pkcs_.2311_modules_are_loaded.2c_how_does_nss_determine_which_ones_to_use_for_the_mechanisms_required_by_ssl.3f + + NSS uses the first slot it finds that can perform all the required operations. On servers, it's + almost always the slot that contains the server's private key. + + .. rubric:: Does NSS support the use of PKCS #11 callbacks specified in the pNotify and + pApplication parameters for C_OpenSession? + :name: does_nss_support_the_use_of_pkcs_.2311_callbacks_specified_in_the_pnotify_and_papplication_parameters_for_c_opensession.3f + + NSS does not currently use any of the callbacks. + + NSS applications detect card insertion and deletion by means of polling to determine whether the + card is still in the slot and whether the open session associated with that card is still valid, + or by waiting on the C_WaitForSlotEvent call. + + .. rubric:: What must an X.509 certificate include to allow it to be recognized as an email + certificate for use with S/MIME? + :name: what_must_an_x.509_certificate_include_to_allow_it_to_be_recognized_as_an_email_certificate_for_use_with_s.2fmime.3f + + An email address must be included in the attribute of the subject DN or the mail attribute of the + subject DN. If the subject DN does not include an email address, the certificate extension + subjectAltName must include an email address. The subjectAltName extension is part of the X.509 + v3 and PKIX specifications. + + .. rubric:: If I have a multipurpose token that supports all required PKCS #11 functions and + provides RSA_PKCS and DSA mechanisms but not AES, DES or RC4, will NSS use the token for the + RSA_PKCS mechanisms and the NSS Internal PKCS #11 module for AES, DES or RC4 when making an + SSL connection? + :name: if_i_have_a_multipurpose_token_that_supports_all_required_pkcs_.2311_functions_and_provides_rsa_pkcs_and_dsa_mechanisms_but_but_not_aes.2c_des_or_rc4.2c_will_nss_use_the_token_for_the_rsa_pkcs_mechanisms_and_the_nss_internal_pkcs_.2311_module_for_aes.2c_des_or_rc4_when_making_an_ssl_connection.3f + + Once NSS starts using a token for a given operation (like S/MIME or SSL), it works hard to keep + using that same token (so keys don't get moved around). Symmetric operations supported by NSS + include the following: CKM_AES_XXX, CKM_DES3_XXX, CKM_DES_XXX, CKM_RC2_XXX, and CKM_RC4_XXX. NSS + knows about all the mechanisms defined in PKCS #11 version 2.01, but will not perform those that + aren't defined by NSS's policy mechanism. + + .. rubric:: When do NSS Applications spawn threads off the main thread, which in turn opens up a + new PKCS #11 session? + :name: when_do_nss_applications_spawn_threads_off_the_main_thread.2c_which_in_turn_opens_up_a_new_pkcs_.2311_session.3f + + This depends on the application. PKCS #11 sessions are cryptographic session states, independent + of threads. In NSS based servers, multiple threads may call the same session, but two threads + will not call the same session at the same time. + + .. rubric:: QUESTIONS ABOUT KEYS AND TOKENS + :name: questions_about_keys_and_tokens + + .. rubric:: Is the PKCS #11 token treated in a read-only manner? That is, no token init, no key + gens, no data puts, no cert puts, etc.? + :name: is_the_pkcs_.2311_token_treated_in_a_read-only_manner.3f_that_is.2c_no_token_init.2c_no_key_gens.2c_no_data_puts.2c_no_cert_puts.2c_etc..3f + + If the token is marked read-only, then it will be treated as such. If the token is marked + read/write and advertises that it can generate keys, NSS uses the token (through PKCS #11) to + generate the key and loads the user's certificate into the token. If the token is marked + read/write and does not advertise that it can generate keys, NSS generates the keys and loads + them into the token. + + .. rubric:: How is private key handled when an external PKCS #11 module is loaded? Is it picked + up from the token when securing, or does NSS expect it to be added in its private key database + to use it? + :name: how_is_private_key_handled_when_an_external_pkcs_.2311_module_is_loaded.3f_is_it_picked_up_from_the_token_when_securing.2c_or_does_nss_expect_it_to_be_added_in_its_private_key_database_to_use_it.3f + + While certificates may be read into the temporary database, private keys are never extracted from + the PKCS #11 module unless the user is trying to back up the key. NSS represents each private key + and a pointer to its PKCS #11 slot as a CK_OBJECT_HANDLE. When NSS needs to do anything with a + private key, it calls the PCKS #11 module that holds the key. + + .. rubric:: If a PKCS #11 library reports that, for example, it does not support RSA signing + operations, does NSS expect to be able to pull an RSA private key off the token using the + C_GetAttributeValue call and then do the operation in software? + :name: if_a_pkcs_.2311_library_reports_that.2c_for_example.2c_it_does_not_support_rsa_signing_operations.2c_does_nss_expect_to_be_able_to_pull_an_rsa_private_key_off_the_token_using_the_c_getattributevalue_call_and_then_do_the_operation_in_software.3f + + No. NSS will never try to pull private keys out of tokens (except as wrapped objects for PKCS + #12). Operations the token does not support are considered impossible for the key to support. + + NSS may try to pull and load symmetric keys, usually if the key exchange happens in a token that + does not support the symmetric algorithm. NSS works very hard not to have to pull any key out of + a token (since that operation does not always work on all tokens). + + .. rubric:: If so, by what means does NSS attempt to retrieve the data? By searching for some + fixed label attribute? Must the token store any temporary (session) objects? + :name: if_so.2c_by_what_means_does_nss_attempt_to_retrieve_the_data.3f_by_searching_for_some_fixed_label_attribute.3f_must_the_token_store_any_temporary_.28session.29_objects.3f + + In general, yes, the token should store temporary session objects. This may not be necessary for + "private key op only" tokens, but this is not guaranteed. You should be prepared to handle + temporary objects. (Many NSS based server products will use temporary session objects, even for + "private key op only" tokens.) + + .. rubric:: If a session key is unwrapped and stays on a hardware token, is it sufficient to + support just the usual decryption mechanisms for it, or is it assumed that such a symmetric + key will always be extractable from the token into the browser? The motivation for this is + that some hardware tokens will prevent extraction of symmetric keys by design. + :name: if_a_session_key_is_unwrapped_and_stays_on_a_hardware_token.2c_is_it_sufficient_to_support_just_the_usual_decryption_mechanisms_for_it.2c_or_is_it_assumed_that_such_a_symmetric_key_will_always_be_extractable_from_the_token_into_the_browser.3f_the_motivation_for_this_is_that_some_hardware_tokens_will_prevent_extraction_of_symmetric_keys_by_design. + + NSS attempts to extract an unwrapped key from a token only if the token cannot provide the + necessary service with that key. For instance if you are decrypting an S/MIME message and you + have unwrapped the DES key with the private key provided by a given token, NSS attempts to use + that token to provide the DES encryption. Only if that token cannot do DES will NSS try to + extract the key. + + .. rubric:: If the smartcard can't do key generation, will NSS do the key generation + automatically? + :name: if_the_smartcard_can.27t_do_key_generation.2c_will_nss_do_the_key_generation_automatically.3f + + Yes. If your token can do CKM_RSA_PKCS, and is writable, NSS displays it as one of the options to + do key generation with. If the token cannot do CKM_RSA_PKCS_GEN_KEYPAIR, NSS uses its software + key generation code and writes the private and public keys into the token using C_CreateObject. + The RSA private key will contain all the attributes specified by PKCS #11 version 2.0. This is + also true for CKM_DSA and CKM_DSA_GEN_KEYPAIR. + + .. rubric:: What is the C_GenerateKeyPair process? For example, what happens when an application + in the a server asks an NSS based client to do a keypair generation while a smartCard is + attached? How is the private key stored to the smartCard, and how is the public key sent to + the server (with wrapping?). + :name: what_is_the_c_generatekeypair_process.3f_for_example.2c_what_happens_when_an_application_in_the_a_server_asks_an_nss_based_client_to_do_a_keypair_generation_while_a_smartcard_is_attached.3f_how_is_the_private_key_stored_to_the_smartcard.2c_and_how_is_the_public_key_sent_to_the_server_.28with_wrapping.3f.29. + + The private key is created using C_GenerateKeyPair or stored using C_CreateObject (depending on + who generates the key). NSS does not keep a copy of the generated key if it generates the key + itself. Key generation in Mozilla clients is triggered either by the standard <KEYGEN> tag, or by + the keygen functions off the window.crypto object. This is the same method used for generating + software keys and certificates and is used by certificate authorities like VeriSign and Thawte. + (Red Hat Certificate Server also uses this method). The public key is sent to the server + base-64-DER-encoded with an (optional) signed challenge. + + .. rubric:: Are persistent objects that are stored on the token, such as private keys and + certificates, created by the PKCS #11 module? Is it safe to assume that NSS never calls + C_CreateObject for those persistent objects? + :name: are_persistent_objects_that_are_stored_on_the_token.2c_such_as_private_keys_and_certificates.2c_created_by_the_pkcs_.2311_module.3f_is_it_safe_to_assume_that_nss_never_calls_c_createobject_for_those_persistent_objects.3f + + No. As stated in the answer to the preceding question, when NSS does a keygen it uses + C_GenerateKeyPair if the token supports the keygen method. If the token does not support keygen, + NSS generates the key internally and uses C_CreateObject to load the private key into the token. + When the certificate is received after the keygen, NSS loads it into the token with + C_CreateObject. NSS also does a similar operation for importing private keys and certificates + through pkcs12. + + The above statement is true for read-write tokens only. + + .. rubric:: When and how does NSS generate private keys on the token? + :name: when_and_how_does_nss_generate_private_keys_on_the_token.3f + + As stated above, NSS uses C_GenerateKeyPair if the token supports the keygen method. If an RSA + key is being generated, the NSS application will present a list of all writable RSA devices asks + the user to select which one to use, if a DSA key is being generated, it will present a list of + all the writable DSA devices, if an EC key is being generated, it will present a list of all + writable EC devices. + + .. rubric:: Does NSS ever use C_CopyObject to copy symmetric keys if it needs to reference the + same key for different sessions? + :name: does_nss_ever_use_c_copyobject_to_copy_symmetric_keys_if_it_needs_to_reference_the_same_key_for_different_sessions.3f + + No. This is never necessary. The PKCS #11 specification explicitly requires that symmetric keys + must be visible to all sessions of the same application. NSS explicitly depends on this semantic + without the use of C_CopyObject. If your module does not support this semantic, it will not work + with NSS. + + .. rubric:: QUESTIONS ABOUT PINS + :name: questions_about_pins + + .. rubric:: Will a password change ever be done on the token? + :name: will_a_password_change_ever_be_done_on_the_token.3f + + Yes, NSS attempts to change the password in user mode only. (It goes to SSO mode only if your + token identifies itself as CKF_LOGIN_REQUIRED, but not CKF_USER_INITIALIZED). + + It's perfectly valid to reject the password change request with a return value such as + CKR_FUNCTION_NOT_SUPPORTED. If you do this, NSS applications display an appropriate error message + for the user. + + .. rubric:: If I have my smart card which has initial PIN set at '9999', I insert it into my + reader and download with my certificate (keygen completed), can I issue 'Change Password' from + the Firefox to set a new PIN to the smart card? Any scenario that you can give me similar to + this process (a way to issue a certificate on an initialized new card)? + :name: if_i_have_my_smart_card_which_has_initial_pin_set_at__.279999.27.2c_i_insert_it_into_my_reader_and_download_with_my_certificate_.28keygen_completed.29.2c_can_i_issue_.27change_password.27_from_the_firefox_to_set_a_new_pin_to_the_smart_card.3f_any_scenario_that_you_can_give_me_similar_to_this_process_.28a_way_to_issue_a_certificate_on_an_initialized_new_card.29.3f + + Yes. First open the Tools/Options/Advanced/Security window in Mozilla and click Security Devices. + Then select your PKCS #11 module, click View/Edit, select the token, and click Change Password. + For this to work, you must supply a C_SetPIN function that operates as CKU_USER. Mozilla, + Thunderbird, and Netscape products that use NSS have different UI to get the Security Devices + dialog. + + To get a key into an initialized token, go to your local Certificate Authority and initiate a + certificate request. Somewhere along the way you will be prompted with a keygen dialog. Normally + this dialog does not have any options and just provides information; however, if you have more + than one token that can be used in this key generation process (for example, your smartcard and + the NSS internal PKCS#11 module), you will see a selection of "cards and databases" that can be + used to generate your new key info. + + In the key generation process, NSS arranges for the key to have it's CKA_ID set to some value + derived from the public key, and the public key will be extracted using C_GetAttributes. This key + will be sent to the CA. + + At some later point, the CA presents the certificate to you (as part of this keygen, or in an + e-mail, or you go back and fetch it from a web page once the CA notifies you of the arrival of + the new certificate). NSS uses the public key to search all its tokens for the private key that + matches that certificate. The certificate is then written to the token where that private key + resides, and the certificate's CKA_ID is set to match the private key. + + .. rubric:: Why does Firefox require users to authenticate themselves by entering a PIN at the + keyboard? Why not use a PIN pad or a fingerprint reader located on the token or reader? + :name: why_does_firefox_require_users_to_authenticate_themselves_by_entering_a_pin_at_the_keyboard.3f_why_not_use_a_pin_pad_or_a_fingerprint_reader_located_on_the_token_or_reader.3f + + PKCS #11 defines how these kinds of devices work. There is an outstanding bug in Firefox to + implement this support.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs11/index.rst b/security/nss/doc/rst/legacy/pkcs11/index.rst new file mode 100644 index 0000000000..957080266d --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs11/index.rst @@ -0,0 +1,14 @@ +.. _mozilla_projects_nss_pkcs11: + +PKCS11 +====== + +.. container:: + + PKCS #11 information for implementors of cryptographic modules: + + - `Implementing PKCS11 for NSS <PKCS11_Implement>`__ + - :ref:`mozilla_projects_nss_pkcs11_faq` + - `Using the JAR Installation Manager to Install a PKCS #11 Cryptographic + Module <PKCS11_Jar_Install>`__ + - `PKCS #11 Conformance Testing <PKCS11_Conformance>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs11/module_installation/index.rst b/security/nss/doc/rst/legacy/pkcs11/module_installation/index.rst new file mode 100644 index 0000000000..bd3502e4b6 --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs11/module_installation/index.rst @@ -0,0 +1,56 @@ +.. _mozilla_projects_nss_pkcs11_module_installation: + +PKCS11 module installation +========================== + +.. container:: + + `PKCS #11 </en-US/PKCS11>`__ modules are external modules which add to Firefox support for + smartcard readers, biometric security devices, and external certificate stores. This article + covers the two methods for installing PKCS #11 modules into Firefox. Users can use the + preferences dialog to install or remove PKCS #11 module. Extensions can programmatically manage + PKCS #11 modules using the nsIPKCS11 programming interface. + + .. note:: + + **Note:** The information in this article is specific to Firefox 3.5 and newer. Older versions + of Firefox may support the + `window.pkcs11 <https://developer.mozilla.org/en-US/docs/Web/API/Window/pkcs11>`__ property + for installing PKCS #11 modules. + +.. _using_the_firefox_preferences_to_install_pkcs_11_modules: + +`Using the Firefox preferences to install PKCS #11 modules <#using_the_firefox_preferences_to_install_pkcs_11_modules>`__ +------------------------------------------------------------------------------------------------------------------------- + +.. container:: + + #. Save the PKCS #11 module to a permanent location on your local computer + #. Open the Firefox preferences dialog. Choose "Advanced" > "Encryption" > "Security Devices" + #. Choose "Load" + #. Enter a name for the security module, such as "My Client Database". NOTE: there is currently a + bug in Firefox where international characters may cause problems. + #. Choose "Browse..." to find the location of the PKCS #11 module on your local computer, and + choose "OK" when done. + +.. _provisioning_pkcs_11_modules_using_the_pkcs11_api: + +`Provisioning PKCS #11 modules using the pkcs11 API <#provisioning_pkcs_11_modules_using_the_pkcs11_api>`__ +----------------------------------------------------------------------------------------------------------- + +.. container:: + + Starting with Firefox 58, extensions can use the ``pkcs11`` browser extension API to enumerate + PKCS #11 modules and make them accessible to the browser as sources of keys and certificates. + +.. _see_also: + +`See also <#see_also>`__ +------------------------ + +.. container:: + + - `Web security <https://developer.mozilla.org/en-US/docs/Web/Security>`__ + - :ref:`mozilla_projects_nss_pkcs11` + - ``pkcs11.installModule()`` + - ``pkcs11.isModuleInstalled()``
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs11/module_specs/index.rst b/security/nss/doc/rst/legacy/pkcs11/module_specs/index.rst new file mode 100644 index 0000000000..cb8729161e --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs11/module_specs/index.rst @@ -0,0 +1,365 @@ +.. _mozilla_projects_nss_pkcs11_module_specs: + +PKCS #11 Module Specs +===================== + +.. _pkcs_.2311_module_specs: + +`PKCS #11 Module Specs <#pkcs_.2311_module_specs>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following is a proposal to the `PKCS <https://en.wikipedia.org/wiki/PKCS>`__ #11 working + group made in August 2001 for configuring PKCS #11 modules. NSS currently implements this + proposal internally. + + The file format consists of name/value pairs of the form ``name=value``. Each name/value pair is + separated by a blank value. A single line, terminated by a '\n', '\r\n', or '\r' represents a + single pkcs #11 library. + + Names can be any alpha/numeric combination, and are parsed case-insensitive. + + Values can contain any printable ASCII value, including UTF8 characters. Values can contain + embedded blanks either through quoting the entire value, or by escaping the embedded blanks with + '\'. The value is considered quoted if the first character after the '=' is ', ", {, [, or <. If + the value is quoted, then the value is terminated with and ending quote of the form ', ", ), ], + }, or > matching the respective starting quote. Ending quotes can be escaped. Embedded '\' + characters are considered escape characters for the next character in the stream. Note that case + must be preserved in the values. + + These modules specs can be passed by the application directly to NSS via the + ``SECMOD_LoadUserModule()`` call. To initialize a PKCS #11 module 'on-the-fly'. + + .. rubric:: Recognized Names + :name: recognized_names + + All applications/libraries must be able recognize the following name values: + + library + This specifies the path to the pkcs #11 library. + name + This specifies the name of the pkcs #11 library. + parameter + This specifies a pkcs #11 library parameter with the application must pass to the pkcs #11 + library at ``C_Initialize()`` time (see below). + + In additions applications/libraries should be able to ignore additional name value pairs which + are used to specify configuration for other applications. Of course these application/libraries + should be able to parse their own name/value pairs. + + Each of these name/value pairs are optional. + + If the library is not specified, the line represents some application specific meta configuration + data. Other applications and libraries can safely ignore this line. + + If the name is not specified, the application can use the library path to describe the PKCS #11 + library in any UI it may have. + + If the parameter is not specified, no parameters are passed to the PKCS #11 module. + + If the application/library does not find its application/library specific data, it should use + it's defaults for this pkcs #11 library. + + .. rubric:: Parameter Passing + :name: parameter_passing + + If the parameter is specified, the application/library will strip the value out, processing any + outter quotes and escapes appropriately, and pass the parameter to the pkcs #11 library when it + calls ``C_Initialize()``. + + A new ``CK_C_INITIALIZE_ARGS`` structure is defined as + + .. code:: + + typedef struct CK_C_INITIALIZE_ARGS { + CK_CREATEMUTEX CreateMutex; + CK_DESTROYMUTEX DestroyMutex; + CK_LOCKMUTEX LockMutex; + CK_UNLOCKMUTEX UnlockMutex; + CK_FLAGS flags; + CK_VOID_PTR LibraryParameters; + CK_VOID_PTR pReserved; + } CK_C_INITIALIZE_ARGS; + + Applications/libraries must set LibraryParameters to ``NULL`` if no parameter value is specified. + PKCS #11 libraries which accept parameters must check if the 'new' ``pReserved`` field is + ``NULL`` if and only if ``LibraryParameters`` field is not ``NULL``. + +.. _nss_specific_parameters_in_module_specs: + +`NSS Specific Parameters in Module Specs <#nss_specific_parameters_in_module_specs>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Here are the NSS Application specific parameters in use. This data is currently stored in + ``secmod.db`` or pkcs11.txt. This isn't part of the generic spec (that is other applications need + not parse it, nor pkcs #11 modules need supply them or use them). + + .. code:: + + NSS="nss_params" + + ``nss_params`` are themselves name/value pairs, parsed with the same rules described above. Valid + names inside ``nss_params`` are: + + flags + comma separated list of flag values, parsed case-insensitive. + Valid flag values are: + + internal + this library is actually the Netscape internal library + fips + this library is the Netscape internal fips library. + critical + if this library cannot be loaded, completely fail initialization. + moduleDB + this library includes NSS specific functions to supply additional module specs for loading. + **moduleDBOnly** - this library has no PKCS #11 functions and is only used for loading + additional modules. + trustOrder + integer value specifying the order in which the trust information for certificates specified + by tokens on this PKCS #11 library should be rolled up. A value of 0 means that tokens on this + library should not supply trust information. The default trust order value is 50. The relative + order of two pkcs#11 libraries which have the same trustOrder value is undefined. + cipherOrder + integer value specifiying the order in which tokens are searched when looking for a token to + do a generic operation (DES/Hashing, etc). + ciphers + comma separated list of ciphers this token will enable that isn't already enabled by the + library (currently only **FORTEZZA** is defined) (case-insensitive). + slotParams + space separated list of name/value pairs where the name is a slotID and the value is a space + separated list of parameters related to that slotID. Valid slotParams values are: + + slotFlags + comma separated list of cipher groups which this slot is expected to be the default + implementation for (case-insensitive). + Valid flags are: + + RSA + This token should be used for all RSA operations (other than Private key operations + where the key lives in another token). + DSA + This token should be used for all DSA operations (other than Private key operations + where the key lives in another token). + RC4 + This token should be used for all RC4 operations which are not constrained by an + existing key in another token. + RC2 + This token should be used for all RC2 operations which are not constrained by an + existing key in another token. + DES + This token should be used for all DES, DES2, and DES3 operations which are not + constrained by an existing key in another token. + DH + This token should be used for all DH operations (other than Private key operations where + the key lives in another token). + FORTEZZA + This token should be used for all KEA operations (other than Private key operations + where the key lives in another token), as well as SKIPJACK operations which are not + constrained by an existing key in another token. + RC5 + This token should be used for all RC5 operations which are not constrained by an + existing key in another token. + SHA1 + This token should be used for all basic SHA1 hashing. + MD5 + This token should be used for all basic MD5 hashing. + MD2 + This token should be used for all basic MD2 hashing. + SSL + This token should be used for SSL key derivation which are not constrained by an + existing key in another token. + TLS + This token should be used for TLS key derivation which are not constrained by an + existing key in another token. + AES + This token should be used for all AES operations which are not constrained by an + existing key in another token. + RANDOM + This token should be used to generate random numbers when the application call + 'PK11_GenerateRandom'. + PublicCerts + The certificates on this token can be read without authenticating to this token, and any + user certs on this token have a matching public key which is also readable without + authenticating. Setting this flags means NSS will not try to authenticate to the token + when searching for Certificates. This removes spurious password prompts, but if + incorrectly set it can also cause NSS to miss certificates in a token until that token + is explicitly logged in. + rootFlags + comma separated of flags describing any root certs that may be stored (case-insensitive). + Valid flags are: + + hasRootCerts + claims that this token has the default root certs and trust values. At init time NSS, + will try to look for a default root cert device if one has not already been loaded. + hasRootTrust + parsed but ignored. + timeout + time in minutes before the current authentication should be rechecked. This value is only + used if askpwd is set to 'timeout'. (default = 0). + askpwd + case-insensitive flag describing how password prompts should be manages. Only one of the + following can be specified. + + every + prompt whenever the a private key on this token needs to be access (this is on the + entire token, not on a key-by-key basis. + timeout + whenever the last explicit login was longer than 'timeout' minutes ago. + only + authenticate to the token only when necessary (default). + + Sample file: + + .. code:: + + library= name="Netscape Internal Crypto Module" parameters="configdir=/u/relyea/.netscape certprefix= secmod=secmod.db" NSS="Flags=internal,pkcs11module TrustOrder=1 CipherOrder=-1 ciphers= slotParams={0x1=[slotFlags='RSA,DSA,DH,RC4,RC2,DES,MD2,MD5,SHA1,SSL,TLS,PublicCerts,Random'] 0x2=[slotFlags='RSA' askpw=only]}" + library=dkck32.dll name="DataKey SignaSURE 3600" NSS="TrustOrder=50 ciphers= " + library=swft32.dll name="Netscape Software Fortezza" parameters="keyfile=/u/relyea/keyfile" NSS="TrustOrder=50 ciphers=FORTEZZA slotParams=0x1=[slotFlags='FORTEZZA']" + library=core32.dll name="Litronic Netsign" + +.. _softoken_specific_parameters: + +`Softoken Specific Parameters <#softoken_specific_parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The internal NSS PKCS #11 implementation (softoken) requires Applications parameters. It will not + initialize if the **parameters**\ = is not specified. If another application wishes to load the + softoken, that application must supply a non-``NULL`` ``libraryParameters`` value in the + ``CK_C_INITIALIZE_ARGS`` structure passed at ``C_INITIALIZE`` time. The parameter passed to + softoken is a space separated list of name/value pairs exactly like those specified in the PKCS + #11 module spec. + + Valid values are: + + configDir + Configuration Directory where NSS can store persistant state information (typically + databases). + secmod + Name of the secmod database (default = secmod.db). + certPrefix + Prefix for the cert database. + keyPrefix + Prefix for the key database. + minPWLen + Minimum password length in bytes. + manufacturerID + Override the default ``manufactureID`` value for the module returned in the ``CK_INFO``, + ``CK_SLOT_INFO``, and ``CK_TOKEN_INFO`` structures with an internationalize string (UTF8). + This value will be truncated at 32 bytes (no NULL, partial UTF8 characters dropped). + libraryDescription + Override the default ``libraryDescription`` value for the module returned in the ``CK_INFO`` + structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no + ``NULL``, partial UTF8 characters dropped). + cryptoTokenDescription + Override the default label value for the internal crypto token returned in the + ``CK_TOKEN_INFO`` structure with an internationalize string (UTF8). This value will be + truncated at 32 bytes (no NULL, partial UTF8 characters dropped). + dbTokenDescription + Override the default label value for the internal DB token returned in the ``CK_TOKEN_INFO`` + structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no + NULL, partial UTF8 characters dropped). + FIPSTokenDescription + Override the default label value for the internal FIPS token returned in the ``CK_TOKEN_INFO`` + structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no + NULL, partial UTF8 characters dropped). + cryptoSlotDescription + Override the default ``slotDescription`` value for the internal crypto token returned in the + ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be + truncated at 64 bytes (no NULL, partial UTF8 characters dropped). + dbSlotDescription + Override the default ``slotDescription`` value for the internal DB token returned in the + ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be + truncated at 64 bytes (no NULL, partial UTF8 characters dropped). + FIPSSlotDescription + Override the default ``slotDescription`` value for the internal FIPS token returned in the + ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be + truncated at 64 bytes (no NULL, partial UTF8 characters dropped). + flags + comma separated list of flag values, parsed case-insensitive. + + .. rubric:: Flags + :name: flags + + Valid flags are: + + noModDB + Don't open ``secmod.db`` and try to supply the strings. The MOD DB function is not through + standard PKCS #11 interfaces. + readOnly + Databases should be opened read only. + noCertDB + Don't try to open a certificate database. + noKeyDB + Don't try to open a key database. + forceOpen + Don't fail to initialize the token if the databases could not be opened. + passwordRequired + Zero length passwords are not acceptable (valid only if there is a keyDB). + optimizeSpace + allocate smaller hash tables and lock tables. When this flag is not specified, Softoken will + allocate large tables to prevent lock contention. + tokens + configure 'tokens' by hand. The tokens parameter specifies a space separated list of slotIDS, + each of which specify their own set of parameters affecting that token. Typically 'tokens' + would not be specified unless additional databases are to be opened as additional tokens. If + tokens is specified, then all tokens (including the default tokens) need to be specified. If + tokens is not specified, then softoken would default to the following specs: + + In non-FIPS mode: + + .. code:: + + tokens=<0x01=[configDir=configDir tokenDescription=cryptoTokenDescription slotDescription=cryptoSlotDescription flags=noCertDB,noKeyDB,optimizeSpace] 0x02=[configDir=configDir tokenDescription=dbTokenDescription slotDescription=dbSlotDescription certPrefix=certPrefix keyPrefix=keyPrefix flags=flags minPWLen=minPWLen]> + + In FIPS mode: + + .. code:: + + tokens=<0x03=[configDir=configDir tokenDescription=FIPSTokenDescription slotDescription=FIPSSlotDescription certPrefix=certPrefix keyPrefix=keyPrefix flags=flags minPWLen=minPWLen]> + + where *configDir*, *cryptoTokenDescription*, *cryptoSlotDescription*, *dbTokenDescription*, + *dbSlotDescription*, *FIPSTokenDescription*, *FIPSSlotDescription*, *optimizeSpace*, + *certPrefix*, *keyPrefix*, *flags*, and *minPWLen* are copied from the parameters above. + + Parameters: + + configDir + The location of the databases for this token. If ``configDir`` is not specified, the default + ``configDir`` specified earlier will be used. + certPrefix + Cert prefix for this token. + keyPrefix + Prefix for the key database for this token. + tokenDescription + The label value for this token returned in the ``CK_TOKEN_INFO`` structure with an + internationalize string (UTF8). This value will be truncated at 32 bytes (no NULL, partial + UTF8 characters dropped). + slotDescription + The ``slotDescription`` value for this token returned in the ``CK_SLOT_INFO`` structure with + an internationalize string (UTF8). This value will be truncated at 64 bytes (no NULL, partial + UTF8 characters dropped). + minPWLen + minimum password length for this token. + flags + comma separated list of flag values, parsed case-insensitive. + Valid flags are: + + readOnly + Databases should be opened read only. + noCertDB + Don't try to open a certificate database. + noKeyDB + Don't try to open a key database. + forceOpen + Don't fail to initialize the token if the databases could not be opened. + passwordRequired + Zero length passwords are not acceptable (valid only if there is a ``keyDB``). + optimizeSpace + allocate smaller hash tables and lock tables. When this flag is not specified, Softoken + will allocate large tables to prevent lock contention.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs11_functions/index.rst b/security/nss/doc/rst/legacy/pkcs11_functions/index.rst new file mode 100644 index 0000000000..13b9301c08 --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs11_functions/index.rst @@ -0,0 +1,554 @@ +.. _mozilla_projects_nss_pkcs11_functions: + +NSS PKCS11 Functions +==================== + +.. _pkcs_.2311_functions: + +`PKCS #11 Functions <#pkcs_.2311_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This chapter describes the core PKCS #11 functions that an application needs for communicating + with cryptographic modules. In particular, these functions are used for obtaining certificates, + keys, and passwords. This was converted from `"Chapter 7: PKCS #11 + Functions" <https://www.mozilla.org/projects/security/pki/nss/ref/ssl/pkfnc.html>`__. + + - :ref:`mozilla_projects_nss_reference` + - `SECMOD_LoadUserModule <#secmod_loadusermodule>`__ + - `SECMOD_UnloadUserModule <#secmod_unloadusermodule>`__ + - `SECMOD_OpenUserDB <#secmod_openuserdb>`__ + - `SECMOD_CloseUserDB <#secmod_closeuserdb>`__ + - `PK11_FindCertFromNickname <#pk11_findcertfromnickname>`__ + - `PK11_FindKeyByAnyCert <#pk11_findkeybyanycert>`__ + - `PK11_GetSlotName <#pk11_getslotname>`__ + - `PK11_GetTokenName <#pk11_gettokenname>`__ + - `PK11_IsHW <#pk11_ishw>`__ + - `PK11_IsPresent <#pk11_ispresent>`__ + - `PK11_IsReadOnly <#pk11_isreadonly>`__ + - `PK11_SetPasswordFunc <#pk11_setpasswordfunc>`__ + + .. rubric:: SECMOD_LoadUserModule + :name: secmod_loadusermodule + + Load a new PKCS #11 module based on a moduleSpec. + + .. rubric:: Syntax + :name: syntax + + .. code:: + + #include "secmod.h" + + extern SECMODModule *SECMOD_LoadUserModule(char *moduleSpec, SECMODModule *parent, PRBool recurse); + + .. rubric:: Parameters + :name: parameters + + This function has the following parameters: + + *moduleSpec* is a pkcs #11 moduleSpec. *parent* is the moduleDB that presented this module spec. + For applications this value should be NULL. *recurse* is a boolean indicates whether or not the + module should also launch additional pkcs #11 modules. This is only applicable if the loaded + module is actually a moduleDB rather than a PKCS #11 module (see + :ref:`mozilla_projects_nss_pkcs11_module_specs`). + + .. rubric:: Returns + :name: returns + + The function returns one of these values: + + - If successful, a pointer to a SECMODModule. Caller owns the reference + - If unsuccessful, NULL. + + .. rubric:: Description + :name: description + + SECMOD_LoadUserModule loads a new PKCS #11 module into NSS and connects it to the current NSS + trust infrastructure. Once the module has been successfully loaded, other NSS calls will use it + in the normal course of searching. + + *modulespec* specifies how the module should be loaded. More information about module spec is + available at :ref:`mozilla_projects_nss_pkcs11_module_specs`. NSS parameters may be specified in + module specs used by SECMOD_LoadUserModule. + + Module will continue to function in the NSS infrastructure until unloaded with + SECMOD_UnloadUserModule. + + .. rubric:: SECMOD_UnloadUserModule + :name: secmod_unloadusermodule + + Unload a PKCS #11 module. + + .. rubric:: Syntax + :name: syntax_2 + + .. code:: + + #include "secmod.h" + + extern SECStatus SECMOD_UnloadUserModule(SECMODModule *module); + + .. rubric:: Parameters + :name: parameters_2 + + This function has the following parameters: + + *module* is the module to be unloaded. + + .. rubric:: Returns + :name: returns_2 + + The function returns one of these values: + + - If successful, SECSuccess. + - If unsuccessful, SECFailure. + + .. rubric:: Description + :name: description_2 + + SECMOD_UnloadUserModule detaches a module from the nss trust domain and unloads it. The module + should have previously been loaded by SECMOD_LoadUserModule. + + .. rubric:: SECMOD_CloseUserDB + :name: secmod_closeuserdb + + Close an already opened user database. NOTE: the database must be in the internal token, and must + be one created with SECMOD_OpenUserDB(). Once the database is closed, the slot will remain as an + empty slot until it's used again with SECMOD_OpenUserDB(). + + .. rubric:: Syntax + :name: syntax_3 + + .. code:: + + #include <pk11pub.h> + + SECStatus SECMOD_CloseUserDB(PK11SlotInfo *slot) + + .. rubric:: Parameters + :name: parameters_3 + + This function has the following parameter: + + *slot* A pointer to a slot info structure. This slot must a slot created by SECMOD_OpenUserDB() + at some point in the past. + + .. rubric:: Returns + :name: returns_3 + + The function returns one of these values: + + - If successful, SECSuccess). + - If unsuccessful, SECFailure. + + .. rubric:: SECMOD_OpenUserDB + :name: secmod_openuserdb + + Open a new database using the softoken. + + .. rubric:: Syntax + :name: syntax_4 + + .. code:: + + #include "pk11pub.h" + + PK11SlotInfo *SECMOD_OpenUserDB(const char *moduleSpec) + + .. rubric:: Parameters + :name: parameters_4 + + This function has the following parameters: + + *moduleSpec* is the same data that you would pass to softoken at initialization time under the + 'tokens' options. + + .. rubric:: Returns + :name: returns_4 + + The function returns one of these values: + + - If successful, a pointer to a slot. + - If unsuccessful, NULL. + + .. rubric:: Description + :name: description_3 + + Open a new database using the softoken. The caller is responsible for making sure the module spec + is correct and usable. The caller should ask for one new database per call if the caller wants to + get meaningful information about the new database. + + moduleSpec is the same data that you would pass to softoken at initialization time under the + 'tokens' options. For example, if you would normally specify *tokens=<0x4=[configdir='./mybackup' + tokenDescription='Backup']>* to softoken if you at init time, then you could specify + "*configdir='./mybackup' tokenDescription='Backup'*" as your module spec here to open the + database ./mybackup on the fly. The slot ID will be calculated for you by SECMOD_OpenUserDB(). + + Typical parameters here are configdir, tokenDescription and flags. a Full list is below: + + *configDir* The location of the databases for this token. If configDir is not specified, and + noCertDB and noKeyDB is not specified, the load will fail. + + *certPrefix* Cert prefix for this token. + + *keyPrefix* Prefix for the key database for this token. (if not specified, certPrefix will be + used). + + *tokenDescription* The label value for this token returned in the CK_TOKEN_INFO structure with an + internationalize string (UTF8). This value will be truncated at 32 bytes (no NULL, partial UTF8 + characters dropped). You should specify a user friendly name here as this is the value the token + will be referred to in most application UI's. You should make sure tokenDescription is unique. + + *slotDescription* The slotDescription value for this token returned in the CK_SLOT_INFO structure + with an internationalize string (UTF8). This value will be truncated at 64 bytes (no NULL, + partialUTF8 characters dropped). This name will not change after thedatabase is closed. It should + have some number to make this unique. + + *minPWLen* Then minimum password length for this token. + + | *flags* A comma separated list of flag values, parsed case-insensitive. + | Valid flags are: + + - *readOnly* - Databases should be opened read only. + - *noCertDB* - Don't try to open a certificate database. + - *noKeyDB* - Don't try to open a key database. + - *forceOpen* - Don't fail to initialize the token if thedatabases could not be opened. + - *passwordRequired* - zero length passwords are not acceptable(valid only if there is a keyDB). + - *optimizeSpace* - allocate smaller hash tables and lock tables.When this flag is not + specified, Softoken will allocatelarge tables to prevent lock contention. + + For more info on module strings see :ref:`mozilla_projects_nss_pkcs11_module_specs`. + + This function will return a reference to a slot. The caller is responsible for freeing the slot + reference when it is through. Freeing the slot reference will not unload the slot. That happens + with the corresponding SECMOD_CloseUserDB() function. Until the SECMOD_CloseUserDB function is + called, the newly opened database will be visible to any NSS calls search for keys or certs. + + .. rubric:: PK11_FindCertFromNickname + :name: pk11_findcertfromnickname + + Finds a certificate from its nickname. + + .. rubric:: Syntax + :name: syntax_5 + + .. code:: + + #include <pk11pub.h> + #include <certt.h> + + CERTCertificate *PK11_FindCertFromNickname( + char *nickname, + void *passwordArg); + + .. rubric:: Parameters + :name: parameters_5 + + This function has the following parameters: + + *nickname* A pointer to the nickname in the certificate database or to the nickname in the token. + + *passwordArg* A pointer to application data for the password callback function. This pointer is + set with SSL_SetPKCS11PinArg during SSL configuration. To retrieve its current value, use + SSL_RevealPinArg. + + .. rubric:: Returns + :name: returns_5 + + The function returns one of these values: + + - If successful, a pointer to a certificate structure. + - If unsuccessful, NULL. + + .. rubric:: Description + :name: description_4 + + When you are finished with the certificate structure returned by PK11_FindCertFromNickname, you + must free it by calling CERT_DestroyCertificate. + + The PK11_FindCertFromNickname function calls the password callback function set with + PK11_SetPasswordFunc and passes it the pointer specified by the wincx parameter. + + .. rubric:: PK11_FindKeyByAnyCert + :name: pk11_findkeybyanycert + + Finds the private key associated with a specified certificate in any available slot. + + .. rubric:: Syntax + :name: syntax_6 + + .. code:: + + #include <pk11pub.h> + #include <certt.h> + #include <keyt.h> + + SECKEYPrivateKey *PK11_FindKeyByAnyCert( + CERTCertificate *cert, + void *passwordArg); + + .. rubric:: Parameters + :name: parameters_6 + + This function has the following parameters: + + *cert* A pointer to a certificate structure in the certificate database. + + *passwordArg* A pointer to application data for the password callback function. This pointer is + set with SSL_SetPKCS11PinArg during SSL configuration. To retrieve its current value, use + SSL_RevealPinArg. + + .. rubric:: Returns + :name: returns_6 + + The function returns one of these values: + + - If successful, a pointer to a private key structure. + - If unsuccessful, NULL. + + .. rubric:: Description + :name: description_5 + + When you are finished with the private key structure returned by PK11_FindKeyByAnyCert, you must + free it by calling SECKEY_DestroyPrivateKey. + + The PK11_FindKeyByAnyCert function calls the password callback function set with + PK11_SetPasswordFunc and passes it the pointer specified by the wincx parameter. + + .. rubric:: PK11_GetSlotName + :name: pk11_getslotname + + Gets the name of a slot. + + .. rubric:: Syntax + :name: syntax_7 + + .. code:: + + #include <pk11pub.h> + + char *PK11_GetSlotName(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_7 + + This function has the following parameter: + + *slot* A pointer to a slot info structure. + + .. rubric:: Returns + :name: returns_7 + + The function returns one of these values: + + - If successful, a pointer to the name of the slot (a string). + - If unsuccessful, NULL. + + .. rubric:: Description + :name: description_6 + + If the slot is freed, the string with the slot name may also be freed. If you want to preserve + it, copy the string before freeing the slot. Do not try to free the string yourself. + + .. rubric:: PK11_GetTokenName + :name: pk11_gettokenname + + Gets the name of the token. + + .. rubric:: Syntax + :name: syntax_8 + + .. code:: + + #include <pk11pub.h> + + char *PK11_GetTokenName(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_8 + + This function has the following parameter: + + *slot* A pointer to a slot info structure. + + .. rubric:: Returns + :name: returns_8 + + The function returns one of these values: + + - If successful, a pointer to the name of the token (a string). + - If unsuccessful, NULL. + + .. rubric:: Description + :name: description_7 + + If the slot is freed, the string with the token name may also be freed. If you want to preserve + it, copy the string before freeing the slot. Do not try to free the string yourself. + + .. rubric:: PK11_IsHW + :name: pk11_ishw + + Finds out whether a slot is implemented in hardware or software. + + .. rubric:: Syntax + :name: syntax_9 + + .. code:: + + #include <pk11pub.h> + #include <prtypes.h> + + PRBool PK11_IsHW(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_9 + + This function has the following parameter: + + *slot* A pointer to a slot info structure. + + .. rubric:: Returns + :name: returns_9 + + The function returns one of these values: + + - If the slot is implemented in hardware, PR_TRUE. + - If the slot is implemented in software, PR_FALSE. + + .. rubric:: PK11_IsPresent + :name: pk11_ispresent + + Finds out whether the token for a slot is available. + + .. rubric:: Syntax + :name: syntax_10 + + .. code:: + + #include <pk11pub.h> + #include <prtypes.h> + + PRBool PK11_IsPresent(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_10 + + This function has the following parameter: + + *slot* A pointer to a slot info structure. + + .. rubric:: Returns + :name: returns_10 + + The function returns one of these values: + + - If token is available, PR_TRUE. + - If token is disabled or missing, PR_FALSE. + + .. rubric:: PK11_IsReadOnly + :name: pk11_isreadonly + + Finds out whether a slot is read-only. + + .. rubric:: Syntax + :name: syntax_11 + + .. code:: + + #include <pk11pub.h> + #include <prtypes.h> + + PRBool PK11_IsReadOnly(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_11 + + This function has the following parameter: + + *slot* A pointer to a slot info structure. + + .. rubric:: Returns + :name: returns_11 + + The function returns one of these values: + + - If slot is read-only, PR_TRUE. + - Otherwise, PR_FALSE. + + .. rubric:: PK11_SetPasswordFunc + :name: pk11_setpasswordfunc + + Defines a callback function used by the NSS libraries whenever information protected by a + password needs to be retrieved from the key or certificate databases. + + .. rubric:: Syntax + :name: syntax_12 + + .. code:: + + #include <pk11pub.h> + #include <prtypes.h> + + void PK11_SetPasswordFunc(PK11PasswordFunc func); + + .. rubric:: Parameter + :name: parameter + + This function has the following parameter: + + *func* A pointer to the callback function to set. + + .. rubric:: Description + :name: description_8 + + During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11 + token (either a smart card or soft token) to access protected information, such as a private key. + Such information is protected with a password that can be retrieved by calling an + application-supplied callback function. The callback function is identified in a call to + PK11_SetPasswordFunc that takes place during NSS initialization. + + The callback function set up by PK11_SetPasswordFunc has the following prototype: + + .. code:: + + typedef char *(*PK11PasswordFunc)( + PK11SlotInfo *slot, + PRBool retry, + void *arg); + + This callback function has the following parameters: + + *slot* A pointer to a slot info structure. + + *retry* Set to PR_TRUE if this is a retry. This implies that the callback has previously returned + the wrong password. + + *arg* A pointer supplied by the application that can be used to pass state information. Can be + NULL. + + This callback function returns one of these values: + + - If successful, a pointer to the password. This memory must have been allocated with PR_Malloc + or PL_strdup. + - If unsuccessful, returns NULL. + + Many tokens keep track of the number of attempts to enter a password and do not allow further + attempts after a certain point. Therefore, if the retry argument is PR_TRUE, indicating that the + password was tried and is wrong, the callback function should return NULL to indicate that it is + unsuccessful, rather than attempting to return the same password again. Failing to terminate when + the retry argument is PR_TRUE can result in an endless loop. + + Several functions in the NSS libraries use the password callback function to obtain the password + before performing operations that involve the protected information. The third parameter to the + password callback function is application-defined and can be used for any purpose. For example, + Mozilla uses the parameter to pass information about which window is associated with the modal + dialog box requesting the password from the user. When NSS SSL libraries call the password + callback function, the value they pass in the third parameter is determined by + SSL_SetPKCS11PinArg. + + .. rubric:: See Also + :name: see_also + + For examples of password callback functions, see the samples in the Samples directory.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs11_implement/index.rst b/security/nss/doc/rst/legacy/pkcs11_implement/index.rst new file mode 100644 index 0000000000..2bf635d433 --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs11_implement/index.rst @@ -0,0 +1,477 @@ +.. _mozilla_projects_nss_pkcs11_implement: + +PKCS11 Implement +================ + +.. _implementing_pkcs_.2311_for_nss: + +`Implementing PKCS #11 for NSS <#implementing_pkcs_.2311_for_nss>`__ +-------------------------------------------------------------------- + +.. container:: + + **NOTE:** This document was originally for the Netscape Security Library that came with Netscape + Communicator 4.0. This note will be removed once the document is updated for the current version + of NSS. + + This document supplements the information in PKCS #11: Cryptographic Token Interface Standard, + version 2.0 with guidelines for implementors of cryptographic modules who want their products to + work with Mozilla client software: + + - How NSS Calls PKCS #11 Functions. Function-specific information organized in the same + categories as the PKCS #11 specification. + - Functions for Different Kinds of Tokens. Summarizes the support NSS expects from different + kinds of tokens. + - Installation. Installing modules and informing the user of changes in the Cryptographic + Modules settings. + - Semantics Unique to NSS. Miscellaneous NSS semantics that affect module implementation. + + Future versions of Netscape server products will also support of PKCS #11 version 2.0. + + How NSS Calls PKCS #11 Functions This section is organized according to the categories used in + PKCS #11: Cryptographic Token Interface Standard, version 2.0. To understand this section, you + should be familiar with the standard specification. + +.. _general-purpose_functions: + +`General-Purpose Functions <#general-purpose_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: C_Initialize + :name: c_initialize + + The NSS calls C_Initialize on startup or when it loads a new module. The NSS always passes NULL, + as required by the PKCS #11 specification, in the single C_Initialize parameter pReserved. + + .. rubric:: C_Finalize + :name: c_finalize + + The NSS calls C_Finalize on shutdown and whenever it unloads a module. + + .. rubric:: C_GetFunctionList + :name: c_getfunctionlist + + The NSS calls C_GetFunctionList on startup or when it loads a new module. The function list + returned should include all the PKCS 2.0 function calls. If you don't implement a function, you + should still provide a stub that returns CKR_FUNCTION_NOT_SUPPORTED. + + .. rubric:: C_GetInfo + :name: c_getinfo + + The NSS calls C_GetInfo on startup or when it loads a new module. The version numbers, + manufacturer IDs, and so on are displayed when the user views the information. The supplied + library names are used as the default library names; currently, these names should not include + any double quotation marks. (This is more restrictive than PKCS 2.0 and may change in future + versions of NSS.). + +.. _slot_and_token_management: + +`Slot and Token Management <#slot_and_token_management>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: C_GetSlotList + :name: c_getslotlist + + The NSS calls C_GetSlotList on startup or when it loads a new module, requests all the module's + slots, and keeps track of the list from that point on. The slots are expected to remain static: + that is, the module never has more slots or fewer slots than the number on the original list. + + .. rubric:: C_GetSlotInfo + :name: c_getslotinfo + + The NSS calls C_GetSlotInfo on startup or when it loads a new module and reads in the information + that can be viewed on the slot information page. If the CKF_REMOVABLE_DEVICE flag is set, NSS + also calls C_GetSlotInfo whenever it looks up slots to make sure the token is present. If the + CKF_REMOVABLE_DEVICE flag is not set, NSS uses that token information without checking again. + + If the CKF_REMOVABLE_DEVICE flag is not set, the CKF_TOKEN_PRESENT flag must be set, or else NSS + marks the slot as bad and will never use it. + + The NSS doesn't currently use the CKF_HW_SLOT flag. + + .. rubric:: C_GetTokenInfo + :name: c_gettokeninfo + + If a token is a permanent device (that is, if the CKF_REMOVABLE_DEVICE flag is not set), NSS + calls C_GetTokenInfo only on startup or when it loads a new module. If the token is a removable + device, NSS may call C_GetTokenInfo anytime it's looking for a new token to check whether the + token is write protected, whether it can generate random numbers, and so on. + + The NSS expects CK_TOKEN_INFO.label to contain the name of the token. + + If the CKF_WRITE_PROTECTED flag is set, NSS won't use the token to generate keys. + + The NSS interprets the combination of the CKF_LOGIN_REQUIRED and CKF_USER_PIN_INITIALIZED flags + as shown in Table 1.1. + + +-----------------------------------+--------------------------+-----------------------------------+ + | NSS's interpretation of the | | | + | CKF_LOGIN_REQUIRED and | | | + | CKF_USER_PIN_INITIALIZED flags | | | + +-----------------------------------+--------------------------+-----------------------------------+ + | CFK_LOGIN_REQUIRED | CFK_USER_PIN_INITIALIZED | NSS assumes that: | + +-----------------------------------+--------------------------+-----------------------------------+ + | FALSE | FALSE | This is a general access device. | + | | | The NSS will use it without | + | | | prompting the user for a PIN. | + +-----------------------------------+--------------------------+-----------------------------------+ + | TRUE | FALSE | The device is uninitialized. The | + | | | NSS attempts to initialize the | + | | | device only if it needs to | + | | | generate a key or needs to set | + | | | the user PIN. The NSS calls | + | | | C_InitPIN to initialize the | + | | | device and set the user PIN; if | + | | | these calls are successful, the | + | | | key is generated and at that | + | | | point the | + | | | CFK_USER_PIN_INITIALIZED flag | + | | | should change from FALSE to TRUE. | + +-----------------------------------+--------------------------+-----------------------------------+ + | FALSE | TRUE | This is a general access device | + | | | that can have a PIN set on it. | + | | | Because it's a general access | + | | | device, NSS never prompts for the | + | | | PIN, even though it's possible to | + | | | set a PIN with C_SetPIN. If the | + | | | PIN is set successfully, the | + | | | CFK_LOGIN_REQUIRED flag should | + | | | change to TRUE. The NSS uses this | + | | | combination of flags for its | + | | | internal token when the key | + | | | database password is NULL. These | + | | | are not standard PKCS #11 | + | | | semantics; they are intended for | + | | | NSS's internal use only. | + +-----------------------------------+--------------------------+-----------------------------------+ + | TRUE | TRUE | The device has been initialized | + | | | and requires authentication. The | + | | | NSS checks whether the user is | + | | | logged on, and if not prompts the | + | | | user for a PIN. | + +-----------------------------------+--------------------------+-----------------------------------+ + + .. rubric:: C_GetMechanismList + :name: c_getmechanismlist + + The NSS calls C_GetMechanismList fairly frequently to identify the mechanisms supported by a + token. + + .. rubric:: C_GetMechanismInfo + :name: c_getmechanisminfo + + The NSS currently doesn't call C_GetMechanismInfo. This function may be called in the future, so + you should implement it anyway. + + .. rubric:: C_InitToken + :name: c_inittoken + + The NSS never calls C_InitToken. + + .. rubric:: C_InitPIN + :name: c_initpin + + The NSS calls C_InitPIN only in the key generation case, as noted in this document under + C_GetTokenInfo, when CFK_LOGIN_REQUIRED = TRUE and CFK_USER_PIN_INITIALIZED = FALSE. + + .. rubric:: C_SetPIN + :name: c_setpin + + Called only in the key generation case, as noted in this document under C_GetTokenInfo, when + CFK_LOGIN_REQUIRED = TRUE and CFK_USER_PIN_INITIALIZED = FALSE. + +.. _session_management: + +`Session Management <#session_management>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: C_OpenSession + :name: c_opensession + + The NSS calls C_OpenSession whenever it initializes a token and keeps the session open as long as + possible. The NSS almost never closes a session after it finishes doing something with a token. + It uses a single session for all single-part RSA operations such as logging in, logging out, + signing, verifying, generating keys, wrapping keys, and so on. + + The NSS opens a separate session for each part of a multipart encryption (bulk encryption). If it + runs out of sessions, it uses the initial session for saves and restores. + + .. rubric:: C_CloseSession + :name: c_closesession + + The NSS calls C_CloseSession to close sessions created for bulk encryption. + + .. rubric:: C_CloseAllSessions + :name: c_closeallsessions + + The NSS may call C_CloseAllSessions when it closes down a slot. + + .. rubric:: C_GetSessionInfo + :name: c_getsessioninfo + + The NSS calls C_GetSessionInfo frequently. + + If a token has been removed during a session, C_GetSessionInfo should return either + CKR_SESSION_CLOSED or CKR_SESSION_HANDLE_INVALID. If a token has been removed and then the same + or another token is inserted, C_GetSessionInfo should return CKR_SESSION_HANDLE_INVALID. + + .. rubric:: C_Login + :name: c_login + + The NSS calls C_Login on a token's initial session whenever CKF_LOGIN_REQUIRED is TRUE and the + user state indicates that the user isn't logged in. + + .. rubric:: C_Logout + :name: c_logout + + The NSS calls C_Logout on a token's initial session + + - when the password is timed out + - when performing any kind of private key operation if "ask always" is turned on + - when changing a password + - when the user logs out + +.. _object_management: + +`Object Management <#object_management>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: C_CreateObject + :name: c_createobject + + The NSS calls C_CreateObject when loading new private keys and new certificates into a token. + Typically, NSS uses C_CreateObject for creating a new private key if PKCS #12 is operating or if + your writable token doesn't support C_GenerateKeyPair. Currently PKCS #12 isn't allowed to import + onto a token. + + The NSS also uses C_CreateObject to create new session keys. The NSS sometimes loads raw key data + and builds a key from that. + + The NSS will be doing more and more session key generation on tokens in the future. It's also + possible for NSS to load a key if the private key that decrypted the key is located on a + different slot. For example, if a particular token can't do DES encryption, NSS decrypts the key, + then copies it over to the token that can do DES encryption. + + The NSS creates certificates as token objects. It loads the token object only if the private key + for that certificate exists on the token and was generated by NSS. All the fields defined by PKCS + #11 for certificates are set. + + The NSS also sets the CKA_ID and CKA_LABEL attributes for the token. Currently, the CKA_ID + attribute is set to the modulus for RSA or to the public value on DSA. The NSS may hash this + value in the future. In either case, NSS does set the CKA_ID attribute and expects it to remain + the same. If a certificate is loaded, the value of the certificate's CKA_ID attribute must match + the value of the CKA_ID attribute for the corresponding private key, and the value of the + certificate's CKA_LABEL attribute must also match the value of the CKA_LABEL attribute for the + private key. For private keys that don't include certificates, NSS doesn't set the CKA_LABEL + attribute, or sets it to NULL, until it receives the certificate. + + .. rubric:: C_CopyObject + :name: c_copyobject + + The NSS rarely calls C_CopyObject but may sometimes do so for non-token private keys. + + .. rubric:: C_DestroyObject + :name: c_destroyobject + + The NSS calls C_DestroyObject to destroy certificates and keys on tokens. + + .. rubric:: C_GetObjectSize + :name: c_getobjectsize + + The NSS never calls C_GetObjectSize. + + .. rubric:: C_GetAttributeValue + :name: c_getattributevalue + + The NSS calls C_GetAttributeValue to get the value of attributes for both single objects and + multiple objects. This is useful for extracting public keys, nonsecret bulk keys, and so on. + + .. rubric:: C_SetAttributeValue + :name: c_setattributevalue + + The NSS uses C_SetAttributeValue to change labels on private keys. + + .. rubric:: C_FindObjectsInit, C_FindObjects, C_FindFinal + :name: c_findobjectsinit.2c_c_findobjects.2c_c_findfinal + + The NSS calls these functions frequently to look up objects by CKA_ID or CKA_LABEL. These values + must match the equivalent values for related keys and certificates and must be unique among key + pairs on a given token. + + The NSS also looks up certificates by CK_ISSUER and CK_SERIAL. If those fields aren't set on the + token, S/MIME won't work. + + Functions for Different Kinds of Tokens The NSS expects different kinds of PKCS #11 support from + four different kinds of tokens: + + - External key distribution tokens are used with corresponding plug-ins to distribute private + keys. + - Signing tokens include a signing certificate and are used to sign objects or messages or to + perform SSL authentication. They cannot be used for encrypted S/MIME, because they can't + decrypt messages. + - Signing and decryption tokens can be used for S/MIME and for encrypted transactions over + unsecured networks such as the Internet. + - Multipurpose tokens provide the full range of cryptographic services. They can be thought of + as cryptographic accelerator cards. Future releases of NSS will also support multipurpose + tokens that are FIPS-140 compliant. + + Table 1.2 summarizes the PKCS #11 functions (in addition to the other functions described in this + document) that NSS expects each type of token to support. + + +------------------------+------------------------+------------------------+------------------------+ + | PKCS #11 functions | | | | + | required for different | | | | + | kinds of tokens | | | | + +------------------------+------------------------+------------------------+------------------------+ + | External key | Signing tokens | Signing and decryption | Multipurpose tokens | + | distribution tokens | | tokens | | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_Encrypt | + +------------------------+------------------------+------------------------+------------------------+ + | C_Decrypt | | C_Decrypt | C_Decrypt | + | | | | | + | - CKM_RSA_PKCS | | - CKM_RSA_PKCS | | + | - CKM_RSA_X_509 (SSL | | - CKM_RSA_X_509 (SSL | | + | 2.0 server only) | | 2.0 server only) | | + +------------------------+------------------------+------------------------+------------------------+ + | C_Sign | C_Sign | C_Sign | C_Sign | + | | | | | + | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | + | - CKM_DSA | - CKM_DSA | - CKM_DSA | - CKM_DSA | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_Verify | + | | | | | + | | | | - CKM_RSA_PKCS | + | | | | - CKM_DSA | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_VerifyRecover | + | | | | | + | | | | - CKM_RSA_PKCS | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_GenerateKey | + +------------------------+------------------------+------------------------+------------------------+ + | C_GenerateKeyPair (if | C_GenerateKeyPair (if | C_GenerateKeyPair (if | C_GenerateKeyPair (if | + | token is read/write) | token is read/write) | token is read/write) | token is read/write) | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_WrapKey | + +------------------------+------------------------+------------------------+------------------------+ + | C_UnwrapKey | C_UnwrapKey | C_UnwrapKey | C_UnwrapKey | + | | | | | + | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_GenerateRandom | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_Save (when token | + | | | | runs out of sessions) | + +------------------------+------------------------+------------------------+------------------------+ + | | | | C_Restore (when token | + | | | | runs out of sessions) | + +------------------------+------------------------+------------------------+------------------------+ + + External key tokens need to support C_Decrypt and C_Sign. If they have a read/write value and + can't generate a key pair, NSS uses its own C_GenerateKeyPair and loads the key with + C_CreateObject. + + Signing tokens just need to support C_Sign and possibly C_GenerateKeyPair. + + In addition to C_Sign and C_GenerateKeyPair, signing and decryption tokens should also support + C_Decrypt and, optionally, C_UnwrapKey. + + Multipurpose tokens should support all the functions listed in Table 1.2, except that C_WrapKey + and C_UnwrapKey are optional. The NSS always attempts to use these two functions but uses + C_Encrypt and C_Decrypt instead if C_WrapKey and C_UnwrapKey aren't implemented. + +`Installation <#installation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + You can install your module in any convenient location on the user's hard disk, but you must tell + the user to type the module name and location in the Cryptographic Modules portion of the + Communicator Security Info window. To do so, the user should follow these steps: + + #. Click the Security icon near the top of any Communicator window. + #. In the Security Info window, click Cryptographic Modules. + #. In the Cryptographic Modules frame, click Add. + #. In the Create a New Security Module dialog box, add the Security Module Name for your module + and the full pathname for the Security Module File. + + To avoid requiring the user to type long pathnames, make sure your module is not buried too + deeply. + +.. _semantics_unique_to_nss: + +`Semantics Unique to NSS <#semantics_unique_to_nss>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These sections describe semantics required by NSS but not specified by PKCS #11. + + .. rubric:: Supporting Multiple Sessions + :name: supporting_multiple_sessions + + If you support multiple sessions simultaneously and if you wish to support C_InitPIN, C_SetPIN, + or C_GenerateKeyPair, you must support simultaneous read-only and read/write sessions. + + .. rubric:: Random-Number Generation and Simple Digesting + :name: random-number_generation_and_simple_digesting + + The NSS requires that the following functions operate without authenticating to the token: + C_SeedRandom, C_GenerateRandom, and C_Digest (for SHA, MD5, and MD2). If your token requires + authentication before executing these functions, your token cannot provide the default + implementation for them. (You can still use your token for other default functions.) NSS does not + support replacement of default functions. Later versions will provide such support. + + .. rubric:: Read/Write and Read-Only Requirements + :name: read.2fwrite_and_read-only_requirements + + The NSS assumes that the following operations always require a read/write session: + + - creating a token object, such as with C_CreateObject (token) or C_DestroyObject (token) + - changing a password + - initializing a token + + Creating session objects must work with a read-only session. + + .. rubric:: Creating an RSA Private Key + :name: creating_an_rsa_private_key + + When NSS creates an RSA private key with C_CreateObject, it writes the entire set of RSA + components. It expects to be able to read back the modulus and the value of the CKA_ID attribute. + It also expects to be able to set the label and the subject on the key after creating it. + + .. rubric:: Encrypting Email + :name: encrypting_email + + If you wish to support encrypted email, your token must be able to look up a certificate by the + issuer and serial number attributes. When NSS loads a certificate, it sets these attributes + correctly. Token initialization software that you supply should also set these fields. + + .. rubric:: Use of Key IDs + :name: use_of_key_ids + + The NSS associates a key with its certificates by its key ID (CKA-ID). It doesn't matter how the + key ID is generated, as long as it is unique for the token and maps to a certificate to it + associated private key. More than one certificate can point to the same private key. + + The only exception to this requirement involves key generation for a new certificate, during + which an orphan key waits for a brief time for a matching certificate. The NSS uses part of the + public key (modulus for RSA, value for DSA) as the key ID during this time. + + NSS doesn't require token public keys, but if they exist, NSS expects the value of the CKA_ID + attribute to be associated with private key and any related certificates. + + .. rubric:: Sessions and Session Objects + :name: sessions_and_session_objects + + The NSS depends on a PKCS #11 v. 2.0 semantic requiring all session objects to be visible in all + of a token's sessions.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs_12_functions/index.rst b/security/nss/doc/rst/legacy/pkcs_12_functions/index.rst new file mode 100644 index 0000000000..fa2dba95d7 --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs_12_functions/index.rst @@ -0,0 +1,37 @@ +.. _mozilla_projects_nss_pkcs_12_functions: + +PKCS 12 functions +================= + +.. container:: + + The public functions listed here perform PKCS #12 operations required by some of the NSS tools + and other applications. + + The `Mozilla Cross Reference <http://mxr.mozilla.org/>`__ (MXR) link for each function provides + access to the function definition, prototype definition, and source code references. The NSS + version column indicates which versions of NSS support the function. + + ====================================== =========== ============== + Function name/documentation Source code NSS versions + ``SEC_PKCS12AddCertAndKey`` MXR 3.2 and later + ``SEC_PKCS12AddPasswordIntegrity`` MXR 3.2 and later + ``SEC_PKCS12CreateExportContext`` MXR 3.2 and later + ``SEC_PKCS12CreatePasswordPrivSafe`` MXR 3.2 and later + ``SEC_PKCS12CreateUnencryptedSafe`` MXR 3.2 and later + ``SEC_PKCS12DecoderFinish`` MXR 3.2 and later + ``SEC_PKCS12DecoderGetCerts`` MXR 3.4 and later + ``SEC_PKCS12DecoderImportBags`` MXR 3.2 and later + ``SEC_PKCS12DecoderIterateInit`` MXR 3.10 and later + ``SEC_PKCS12DecoderIterateNext`` MXR 3.10 and later + ``SEC_PKCS12DecoderSetTargetTokenCAs`` MXR 3.8 and later + ``SEC_PKCS12DecoderStart`` MXR 3.2 and later + ``SEC_PKCS12DecoderUpdate`` MXR 3.2 and later + ``SEC_PKCS12DecoderValidateBags`` MXR 3.2 and later + ``SEC_PKCS12DecoderVerify`` MXR 3.2 and later + ``SEC_PKCS12DestroyExportContext`` MXR 3.2 and later + ``SEC_PKCS12EnableCipher`` MXR 3.2 and later + ``SEC_PKCS12Encode`` MXR 3.2 and later + ``SEC_PKCS12IsEncryptionAllowed`` MXR 3.2 and later + ``SEC_PKCS12SetPreferredCipher`` MXR 3.2 and later + ====================================== =========== ==============
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/pkcs_7_functions/index.rst b/security/nss/doc/rst/legacy/pkcs_7_functions/index.rst new file mode 100644 index 0000000000..ea5732721e --- /dev/null +++ b/security/nss/doc/rst/legacy/pkcs_7_functions/index.rst @@ -0,0 +1,55 @@ +.. _mozilla_projects_nss_pkcs_7_functions: + +PKCS 7 functions +================ + +.. container:: + + The public functions listed here perform PKCS #7 operations required by mail and news + applications and by some of the NSS tools. + + The `Mozilla Cross Reference <http://mxr.mozilla.org/>`__ (MXR) link for each function provides + access to the function definition, prototype definition, and source code references. The NSS + version column indicates which versions of NSS support the function. + + ==================================== =========== =============== + Function name/documentation Source code NSS versions + ``SEC_PKCS7AddCertificate`` MXR 3.3 and later + ``SEC_PKCS7AddRecipient`` MXR 3.2 and later + ``SEC_PKCS7AddSigningTime`` MXR 3.2 and later + ``SEC_PKCS7ContainsCertsOrCrls`` MXR 3.4 and later + ``SEC_PKCS7ContentIsEncrypted`` MXR 3.4 and later + ``SEC_PKCS7ContentIsSigned`` MXR 3.4 and later + ``SEC_PKCS7ContentType`` MXR 3.2 and later + ``SEC_PKCS7CopyContentInfo`` MXR 3.4 and later + ``SEC_PKCS7CreateCertsOnly`` MXR 3.3 and later + ``SEC_PKCS7CreateData`` MXR 3.2 and later + ``SEC_PKCS7CreateEncryptedData`` MXR 3.2 and later + ``SEC_PKCS7CreateEnvelopedData`` MXR 3.2 and later + ``SEC_PKCS7CreateSignedData`` MXR 3.2 and later + ``SEC_PKCS7DecodeItem`` MXR 3.2 and later + ``SEC_PKCS7DecoderAbort`` MXR 3.9 and later + ``SEC_PKCS7DecoderFinish`` MXR 3.2 and later + ``SEC_PKCS7DecoderStart`` MXR 3.2 and later + ``SEC_PKCS7DecoderUpdate`` MXR 3.2 and later + ``SEC_PKCS7DecryptContents`` MXR 3.2 and later + ``SEC_PKCS7DestroyContentInfo`` MXR 3.2 and later + ``SEC_PKCS7Encode`` MXR 3.3 and later + ``SEC_PKCS7EncodeItem`` MXR 3.9.3 and later + ``SEC_PKCS7EncoderAbort`` MXR 3.9 and later + ``SEC_PKCS7EncoderFinish`` MXR 3.2 and later + ``SEC_PKCS7EncoderStart`` MXR 3.2 and later + ``SEC_PKCS7EncoderUpdate`` MXR 3.2 and later + ``SEC_PKCS7GetCertificateList`` MXR 3.2 and later + ``SEC_PKCS7GetContent`` MXR 3.2 and later + ``SEC_PKCS7GetEncryptionAlgorithm`` MXR 3.2 and later + ``SEC_PKCS7GetSignerCommonName`` MXR 3.4 and later + ``SEC_PKCS7GetSignerEmailAddress`` MXR 3.4 and later + ``SEC_PKCS7GetSigningTime`` MXR 3.4 and later + ``SEC_PKCS7IncludeCertChain`` MXR 3.2 and later + ``SEC_PKCS7IsContentEmpty`` MXR 3.2 and later + ``SEC_PKCS7SetContent`` MXR 3.4 and later + ``SEC_PKCS7VerifyDetachedSignature`` MXR 3.4 and later + ``SEC_PKCS7VerifySignature`` MXR 3.2 and later + ``SECMIME_DecryptionAllowed`` MXR 3.4 and later + ==================================== =========== ===============
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/python_binding_for_nss/index.rst b/security/nss/doc/rst/legacy/python_binding_for_nss/index.rst new file mode 100644 index 0000000000..c3bf61d806 --- /dev/null +++ b/security/nss/doc/rst/legacy/python_binding_for_nss/index.rst @@ -0,0 +1,1795 @@ +.. _mozilla_projects_nss_python_binding_for_nss: + +Python binding for NSS +====================== + +.. _project_information: + +`Project Information <#project_information>`__ +---------------------------------------------- + +.. container:: + + python-nss is a Python binding for NSS (Network Security Services) and NSPR (Netscape Portable + Runtime). NSS provides cryptography services supporting SSL, TLS, PKI, PKIX, X509, PKCS*, etc. + NSS is an alternative to OpenSSL and used extensively by major software projects. NSS is FIPS-140 + certified. + + NSS is built upon NSPR because NSPR provides an abstraction of common operating system services, + particularly in the areas of networking and process management. Python also provides an + abstraction of common operating system services but because NSS and NSPR are tightly bound + python-nss exposes elements of NSPR. + + For information on NSS and NSPR, see the following: + + - :ref:`mozilla_projects_nss`. NSS project page. + - `Netscape Portable Runtime </docs/NSPR>`__. NSPR project page. + - `NSPR Reference </docs/NSPR_API_Reference>`__. NSPR API documentation. + +.. _design_goals: + +`Design Goals <#design_goals>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS and NSPR are C language API's which python-nss "wraps" and exposes to Python programs. The + design of python-nss follows these basic guiding principles: + + - Be a thin layer with almost a one-to-one mapping of NSS/NSPR calls to python methods and + functions. Programmers already familiar with NSS/NSPR will be quite comfortable with + python-nss. + - Be "Pythonic". The term Pythonic means to follow accepted Python paradigms and idoms in the + Python language and libraries. Thus when deciding if the NSS/NSPR API should be rigidly + followed or a more Pythonic API provided the Pythonic implementation wins because Python + programmers do not want to write C programs in Python, rather they want their Python code to + feel like Python code with the richness of full Python. + - Identifer names follow the preferred Python style instead of the style in the NSS/NSPR C + header files. + + - Classes are camel-case. Class names always begin with a upper case letter and are then + followed by a mix of lower and upper case letters, a upper case letter is used to separate + words. Acronyms always appear as a contiguous string of upper case letters. + - Method, function and property names are always lower case with words separated by + underscores. + - Constants are all upper case with words separated by underscores, they match the NSS/NSPR C + API. + + - Every module, class, function, and method has associated documentation and is exposed via the + standard Python methodology. This documentation is available via the numerous Python + documentation extraction tools. Also see the `generated HTML + documentation <https://mozilla.github.io/python-nss-docs/>`__ provided with each release. + - NSS/NSPR structs are exposed as Python objects. + - NSS/NSPR functions which operate on a NSS/NSPR object (i.e. struct) become methods of that + object. + - NSS/NSPR objects which are collections support the Python iteration protocol. In other words + they can be iterated over, indexed by position, or used as slices. + - NSS/NSPR objects whose collection elements can be referenced by name support associative + indexing. + - NSS/NSPR objects which have "get" and "set" API function calls are exposed as Python + properties. + - All NSS/NSPR Python objects can print their current value by evaluting the Python object in a + string context or by using the Python str() function. + - Support threading. The Python Global Interpreter Lock (GIL) is released prior to calling + NSS/NSPR C functions and reaquired after the NSS/NSPR C function returns. This allows other + Python threads to execute during the time a NSS/NSPR function is progress in another thread. + Also, any "global" values which are set in python-nss are actually thread-local. Examples of + this are the various callbacks which can be set and their parameters. Thus each thread gets it + own set of callbacks. + - Many methods/functions provide sane default (keyword) parameters freeing the Python programmer + from having to specify all parameters yet allowing them to be overriden when necessary. + - Error codes are *never* returned from methods/functions. python-nss follows the existing + Python exception mechanism. Any error reported by NSS/NSPR is converted into a Python + exception and raised. The exact error code, error description, and often contextual error + information will be present in the exception object. + - Enumerated constants used in the NSS/NSPR API's are available in the Python module under the + *exact* same name as they appear in the C header files of NSS/NSPR. + - Convenience functions are provided to translate between the numeric value of an enumerated + constant and it's string representation and visa versa. + - python-nss internally supports UTF-8. Strings may be Python str objects or Python unicode + objects. If a Python unicode object is passed to a NSS/NSPR function it will be encoded as + UTF-8 first before being passed to NSS/NSPR. + - python-nss tries to be flexible when generating a print representation of complex objects. For + simplicity you can receive a block of formatted text but if you need more control, such as + when building GUI elments you can access a list of "lines", each line is paired with an + indentation level value. The (indent, text) pairs allow you to insert the item into a GUI tree + structure or simply change the indentation formatting. + - Deprecated elements of the python-nss API are marked with Python deprecation warnings as well + as being documented in the nss module documentation. As of Python 2.7 deprecation warnings are + no longer reported by default. It is suggested Python developers using python-nss periodically + run their code with deprecation warnings enabled. Depercated elements will persist for a least + two releases before being removed from the API entirely. + +.. _project_history: + +`Project History <#project_history>`__ +-------------------------------------- + +.. container:: + + Red Hat utilizes both NSS and Python in many of it's projects, however it was not previously + possible to call NSS directly from Python. To solve this problem Red Hat generously funded the + initial development of python-nss as well as it's continued maintenance. Red Hat following it's + open source philosophy has contributed the source to the Mozilla security project. Red Hat + welcomes all interested contributors who would like to contribute the python-nss project as part + of an open source community. The initial release of python-nss occurred in September 2008 with + it's inclusion in the Fedora distribution. The source code to python-nss was first imported into + the Mozilla CVS repository on June 9th 2009. python-nss is currently available in: + + - Fedora + - RHEL 6 + + The principal developer of python-nss is John Dennis jdennis@redhat.com. Additional contributors + are: + + - Miloslav Trmač mitr@redhat.com + - Bohuslav Kabrda slavek@redhat.com + + The python-nss binding is still young despite having been utilized in several major software + projects. Thus it's major version number is still at zero. This is primarily so the developers + can make changes to the API as experiece grows with it. For example it is already known there are + some naming inconsistencies. Elments of the API are probably not ideally partitioned into proper + namespaces via Python modules. Some functionality and interface have already been deprecated due + to lessons learned. Thus at some point in the future when it is felt the API has solidified and + been further proven in the field a 1.0 release will be made. At that point in time existing users + of the python-nss API will need to some elements of their code. A migration script will be + provided to assist them. + +.. _licensing_information: + +`Licensing Information <#licensing_information>`__ +-------------------------------------------------- + +.. container:: + + python-nss is available under the Mozilla Public License, the GNU General Public License, and the + GNU Lesser General Public License. For information on downloading python-nss releases as tar + files, see `Source Download <#sourcedownload>`__. + +`Documentation <#documentation>`__ +---------------------------------- + +.. container:: + + .. rubric:: python-nss API documentation + :name: python-nss_api_documentation + + The python-nss API documentation for the current release can be viewed at `python-nss API + documentation <https://mozilla.github.io/python-nss-docs/>`__. + + The API documentation is generated from the python-nss source code and compiled modules. You can + build it yourself via ``./setup.py build_doc``. Most distributions include the python-nss API + documentation in the python-nss packaging. Consult your distribution for more information. + + .. rubric:: Example Code + :name: example_code + + The doc/examples directory contains numerous examples of python-nss programs and libraries you + may wish to consult. They illustrate suggested usage and best practice. + + .. rubric:: Test Code + :name: test_code + + In addition the test directory contains unit tests that also illustrate python-nss usage, however + unlike the examples the unit tests are geared towards testing rather than expository + illustration. + + .. rubric:: Other Documentation + :name: other_documentation + + The doc directory contains other files you may wish to review. + +.. _how_to_report_a_bug: + +`How to Report a Bug <#how_to_report_a_bug>`__ +---------------------------------------------- + +.. container:: + + python-nss bugs are currently being tracked in the Red Hat bugzilla system for Fedora. You can + enter a bug report + `here <https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora;component=python-nss>`__. + +.. _source_download_area: + +`Source Download Area <#source_download_area>`__ +------------------------------------------------ + +.. container:: + + Source downloads are maintained + `here <https://ftp.mozilla.org/pub/mozilla.org/security/python-nss/releases/>`__. Links to + download URL for a specific release can be found in the `Release Information <#release_info>`__ + section. + +.. _mozilla_source_code_management_(scm)_information: + +`Mozilla Source Code Management (SCM) Information <#mozilla_source_code_management_(scm)_information>`__ +-------------------------------------------------------------------------------------------------------- + +.. container:: + + On March 21, 2013 the NSS project switched from using CVS as it's source code manager (SCM) to + Mercurial, also known as ``hg``. All prior CVS information (including release tags) were imported + into the new Mercurial repositories, as such there is no need to utilize the deprecated CVS + repositories, use Mercurial instead. + + To check out python-nss source code from Mercurial do this: + + ``hg clone https://hg.mozilla.org/projects/python-nss`` + + The SCM tags for various python-nss releases can be found in the `Release + Information <#release_info>`__. + + You may want to review the `Getting Mozilla Source Code Using + Mercurial <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code/Mercurial>`__ + documentation for more information with working with Mercurial. + + The old deprecated CVS documentation can be found here: `Getting Mozilla Source Code Using + CVS <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Source_Code/CVS>`__. + + The old deprecated python-nss CVS source code location is ``mozilla/security/python/nss``. + +.. _release_information: + +`Release Information <#release_information>`__ +---------------------------------------------- + +.. container:: + +.. _release_1.0.1: + +`Release 1.0.1 <#release_1.0.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2017-02-28 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_1_0_1 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securi | + | | ty/python-nss/releases/PYNSS_RELEASE_1_0_1/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | - Add TLS 1.3 cipher suites | + | | - ssl_cipher_info.py now attempts to enable | + | | TLS 1.3 | + | | - Fix build issue in setup.py. python-nss can | + | | now be build as Python wheel, e.g. \`pip | + | | wheel -w dist .\` | + | | - The following constants were added: | + | | | + | | - ssl.TLS_AES_128_GCM_SHA256 | + | | - ssl.TLS_AES_256_GCM_SHA384 | + | | - ssl.TLS_CHACHA20_POLY1305_SHA256 | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_1.0.0: + +`Release 1.0.0 <#release_1.0.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2016-09-01 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_1_0_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securi | + | | ty/python-nss/releases/PYNSS_RELEASE_1_0_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | Official 1.0.0 release, only minor tweaks from | + | | the 1.0.0beta1 release. | + | | | + | | - Allow custom include root in setup.py as | + | | command line arg. | + | | - Add TLS chacha20 poly1305 constants. | + | | - Remove checks for whether a socket is open | + | | for reading. It's not possible for the | + | | binding to know in all cases, especially if | + | | the socket is created from an xternal socket | + | | passed in. | + | | - The following module functions were added: | + | | | + | | - nss.get_all_tokens | + | | | + | | - The following constants were added: | + | | | + | | - | + | | ssl.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | + | | - ss | + | | l.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | + | | - | + | | ssl.TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | + | | - | + | | ssl.TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 | + | | - | + | | ssl.TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_1.0.0beta1: + +`Release 1.0.0beta1 <#release_1.0.0beta1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2016-02-16 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_1_0_0beta1 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | http | + | | s://ftp.mozilla.org/pub/mozilla.org/security/py | + | | thon-nss/releases/PYNSS_RELEASE_1_0_0beta1/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | The primary enhancement in this version is | + | | support for Python3. A single code base | + | | supports both Py2 (minimum version 2.7) and Py3 | + | | | + | | - When built for Py2: | + | | | + | | - text will be a Unicode object | + | | - binary data will be a str object | + | | - ints will be Python long object | + | | | + | | - When built for Py3: | + | | | + | | - text will be a str object | + | | - binary data will be a bytes object | + | | - ints will be a Python int object | + | | | + | | - All pure Python tests and examples have been | + | | ported to Py3 syntax but should continue to | + | | run under Py2. | + | | - The following class methods were added: | + | | | + | | - PK11Slot.check_security_officer_passwd | + | | - PK11Slot.check_user_passwd | + | | - PK11Slot.change_passwd | + | | - PK11Slot.init_pin | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.17.0: + +`Release 0.17.0 <#release_0.17.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2014-11-07 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_17_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_17_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | The primary enhancement in this version is | + | | adding support for PBKDF2 | + | | | + | | - The following module functions were added: | + | | | + | | - nss.create_pbev2_algorithm_id | + | | | + | | - The following class methods were added: | + | | | + | | - nss.AlgorithmID.get_pbe_crypto_mechanism | + | | - nss.AlgorithmID.get_pbe_iv | + | | - nss.PK11Slot.pbe_key_gen | + | | - nss.PK11Slot.format_lines | + | | - nss.PK11Slot.format | + | | - nss.Pk11SymKey.format_lines | + | | - nss.Pk11SymKey.format | + | | - nss.SecItem.to_base64 | + | | - nss.SecItem.format_lines | + | | - nss.SecItem.format | + | | | + | | - The following files were added: | + | | | + | | - doc/examples/pbkdf2_example.py | + | | | + | | - The SecItem constructor added 'ascii' | + | | parameter to permit initialization from | + | | base64 and/or PEM textual data. | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.16.0: + +`Release 0.16.0 <#release_0.16.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2014-10-29 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_16_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_16_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | The primary enhancements in this version is | + | | adding support for the setting trust attributes | + | | on a Certificate, the SSL version range API, | + | | information on the SSL cipher suites and | + | | information on the SSL connection. | + | | | + | | - The following module functions were added: | + | | | + | | - ssl.get_ssl_version_from_major_minor | + | | - ssl.get_default_ssl_version_range | + | | - ssl.get_supported_ssl_version_range | + | | - ssl.set_default_ssl_version_range | + | | - ssl.ssl_library_version_from_name | + | | - ssl.ssl_library_version_name | + | | - ssl.get_cipher_suite_info | + | | - ssl.ssl_cipher_suite_name | + | | - ssl.ssl_cipher_suite_from_name | + | | | + | | - The following deprecated module functions | + | | were removed: | + | | | + | | - ssl.nssinit | + | | - ssl.nss_ini | + | | - ssl.nss_shutdown | + | | | + | | - The following classes were added: | + | | | + | | - SSLCipherSuiteInfo | + | | - SSLChannelInfo | + | | | + | | - The following class methods were added: | + | | | + | | - Certificate.trust_flags | + | | - Certificate.set_trust_attributes | + | | - SSLSocket.set_ssl_version_range | + | | - SSLSocket.get_ssl_version_range | + | | - SSLSocket.get_ssl_channel_info | + | | - SSLSocket.get_negotiated_host | + | | - SSLSocket.connection_info_format_lines | + | | - SSLSocket.connection_info_format | + | | - SSLSocket.connection_info_str | + | | - SSLCipherSuiteInfo.format_lines | + | | - SSLCipherSuiteInfo.format | + | | - SSLChannelInfo.format_lines | + | | - SSLChannelInfo.format | + | | | + | | - The following class properties were added: | + | | | + | | - Certificate.ssl_trust_flags | + | | - Certificate.email_trust_flags | + | | - Certificate.signing_trust_flags | + | | - SSLCipherSuiteInfo.cipher_suite | + | | - SSLCipherSuiteInfo.cipher_suite_name | + | | - SSLCipherSuiteInfo.auth_algorithm | + | | - SSLCipherSuiteInfo.auth_algorithm_name | + | | - SSLCipherSuiteInfo.kea_type | + | | - SSLCipherSuiteInfo.kea_type_name | + | | - SSLCipherSuiteInfo.symmetric_cipher | + | | - SSLCipherSuiteInfo.symmetric_cipher_name | + | | - SSLCipherSuiteInfo.symmetric_key_bits | + | | - SSLCipherSuiteInfo.symmetric_key_space | + | | - SSLCipherSuiteInfo.effective_key_bits | + | | - SSLCipherSuiteInfo.mac_algorithm | + | | - SSLCipherSuiteInfo.mac_algorithm_name | + | | - SSLCipherSuiteInfo.mac_bits | + | | - SSLCipherSuiteInfo.is_fips | + | | - SSLCipherSuiteInfo.is_exportable | + | | - SSLCipherSuiteInfo.is_nonstandard | + | | - SSLChannelInfo.protocol_version | + | | - SSLChannelInfo.protocol_version_str | + | | - SSLChannelInfo.protocol_version_enum | + | | - SSLChannelInfo.major_protocol_version | + | | - SSLChannelInfo.minor_protocol_version | + | | - SSLChannelInfo.cipher_suite | + | | - SSLChannelInfo.auth_key_bits | + | | - SSLChannelInfo.kea_key_bits | + | | - SSLChannelInfo.creation_time | + | | - SSLChannelInfo.creation_time_utc | + | | - SSLChannelInfo.last_access_time | + | | - SSLChannelInfo.last_access_time_utc | + | | - SSLChannelInfo.expiration_time | + | | - SSLChannelInfo.expiration_time_utc | + | | - SSLChannelInfo.compression_method | + | | - SSLChannelInfo.compression_method_name | + | | - SSLChannelInfo.session_id | + | | | + | | - The following files were added: | + | | | + | | - doc/examples/cert_trust.py | + | | - doc/examples/ssl_version_range.py | + | | | + | | - The following constants were added: | + | | | + | | - nss.CERTDB_TERMINAL_RECORD | + | | - nss.CERTDB_VALID_PEER | + | | - nss.CERTDB_TRUSTED | + | | - nss.CERTDB_SEND_WARN | + | | - nss.CERTDB_VALID_CA | + | | - nss.CERTDB_TRUSTED_CA | + | | - nss.CERTDB_NS_TRUSTED_CA | + | | - nss.CERTDB_USER | + | | - nss.CERTDB_TRUSTED_CLIENT_CA | + | | - nss.CERTDB_GOVT_APPROVED_CA | + | | - ssl.SRTP_AES128_CM_HMAC_SHA1_32 | + | | - ssl.SRTP_AES128_CM_HMAC_SHA1_80 | + | | - ssl.SRTP_NULL_HMAC_SHA1_32 | + | | - ssl.SRTP_NULL_HMAC_SHA1_80 | + | | - ssl.SSL_CK_DES_192_EDE3_CBC_WITH_MD5 | + | | - ssl.SSL_CK_DES_64_CBC_WITH_MD5 | + | | - ssl.SSL_CK_IDEA_128_CBC_WITH_MD5 | + | | - ssl.SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 | + | | - ssl.SSL_CK_RC2_128_CBC_WITH_MD5 | + | | - ssl.SSL_CK_RC4_128_EXPORT40_WITH_MD5 | + | | - ssl.SSL_CK_RC4_128_WITH_MD5 | + | | | + | | - ssl.SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA | + | | - ssl.SSL_FORTEZZA_DMS_WITH_NULL_SHA | + | | - ssl.SSL_FORTEZZA_DMS_WITH_RC4_128_SHA | + | | - ssl.SSL_RSA_OLDFIPS_WITH_3DES_EDE_CBC_SHA | + | | - ssl.SSL_RSA_OLDFIPS_WITH_DES_CBC_SHA | + | | - ssl.TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA | + | | - ssl.TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA | + | | - ssl.TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 | + | | - ssl.TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA | + | | - ssl.TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA | + | | - ssl.TLS_DHE_DSS_WITH_DES_CBC_SHA | + | | - ssl.TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA | + | | - ssl.TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA | + | | - ssl.TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 | + | | - ssl.TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | + | | - ssl.TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 | + | | - ssl.TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA | + | | - ssl.TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA | + | | - ssl.TLS_DHE_RSA_WITH_DES_CBC_SHA | + | | - ssl.TLS_DH_ANON_WITH_CAMELLIA_128_CBC_SHA | + | | - ssl.TLS_DH_ANON_WITH_CAMELLIA_256_CBC_SHA | + | | - ssl.TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA | + | | - ssl.TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA | + | | - ssl.TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA | + | | - ssl.TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA | + | | - ssl.TLS_DH_DSS_WITH_DES_CBC_SHA | + | | - ssl.TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA | + | | - ssl.TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA | + | | - ssl.TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA | + | | - ssl.TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA | + | | - ssl.TLS_DH_RSA_WITH_DES_CBC_SHA | + | | - ssl.TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA | + | | - ssl.TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 | + | | - ssl.TLS_DH_anon_WITH_3DES_EDE_CBC_SHA | + | | - ssl.TLS_DH_anon_WITH_AES_128_CBC_SHA | + | | - ssl.TLS_DH_anon_WITH_AES_256_CBC_SHA | + | | - ssl.TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA | + | | - ssl.TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA | + | | - ssl.TLS_DH_anon_WITH_DES_CBC_SHA | + | | - ssl.TLS_DH_anon_WITH_RC4_128_MD5 | + | | | + | | - ssl.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | + | | | + | | - ssl.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | + | | - ssl.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | + | | - ssl.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | + | | | + | | - ssl.TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 | + | | - ssl.TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 | + | | - ssl.TLS_EMPTY_RENEGOTIATION_INFO_SCSV | + | | - ssl.TLS_FALLBACK_SCSV | + | | - ssl.TLS_NULL_WITH_NULL_NULL | + | | - ssl.TLS_RSA_EXPORT_WITH_DES40_CBC_SHA | + | | - ssl.TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 | + | | - ssl.TLS_RSA_EXPORT_WITH_RC4_40_MD5 | + | | - ssl.TLS_RSA_WITH_3DES_EDE_CBC_SHA | + | | - ssl.TLS_RSA_WITH_AES_128_CBC_SHA256 | + | | - ssl.TLS_RSA_WITH_AES_128_GCM_SHA256 | + | | - ssl.TLS_RSA_WITH_AES_256_CBC_SHA256 | + | | - ssl.TLS_RSA_WITH_CAMELLIA_128_CBC_SHA | + | | - ssl.TLS_RSA_WITH_CAMELLIA_256_CBC_SHA | + | | - ssl.TLS_RSA_WITH_DES_CBC_SHA | + | | - ssl.TLS_RSA_WITH_IDEA_CBC_SHA | + | | - ssl.TLS_RSA_WITH_NULL_MD5 | + | | - ssl.TLS_RSA_WITH_NULL_SHA | + | | - ssl.TLS_RSA_WITH_NULL_SHA256 | + | | - ssl.TLS_RSA_WITH_RC4_128_MD5 | + | | - ssl.TLS_RSA_WITH_RC4_128_SHA | + | | - ssl.TLS_RSA_WITH_SEED_CBC_SHA | + | | - ssl.SSL_VARIANT_DATAGRAM | + | | - ssl.SSL_VARIANT_STREAM | + | | - ssl.SSL_LIBRARY_VERSION_2 | + | | - ssl.SSL_LIBRARY_VERSION_3_0 | + | | - ssl.SSL_LIBRARY_VERSION_TLS_1_0 | + | | - ssl.SSL_LIBRARY_VERSION_TLS_1_1 | + | | - ssl.SSL_LIBRARY_VERSION_TLS_1_2 | + | | - ssl.SSL_LIBRARY_VERSION_TLS_1_3 | + | | - ssl.ssl2 | + | | - ssl.ssl3 | + | | - ssl.tls1.0 | + | | - ssl.tls1.1 | + | | - ssl.tls1.2 | + | | - ssl.tls1.3 | + | | | + | | - The following methods were missing thread | + | | locks, this has been fixed. | + | | | + | | - nss.nss_initialize | + | | - nss.nss_init_context | + | | - nss.nss_shutdown_context | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.15.0: + +`Release 0.15.0 <#release_0.15.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2014-09-09 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_15_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_15_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | The primary enhancements in this version was | + | | fixing access to extensions in a | + | | CertificateRequest and giving access to | + | | CertificateRequest attributes. There is a bug | + | | in NSS which hides the existence of extensions | + | | in a CSR if the extensions are not contained in | + | | the first CSR attribute. This was fixable in | + | | python-nss without requiring a patch to NSS. | + | | Formerly python-nss did not provide access to | + | | the attributes in a CSR only the extensions, | + | | with this release all components of a CSR can | + | | be accessed. See test/test_cert_request.py for | + | | examples. | + | | | + | | - Add ability to read PEM data from a string. | + | | - Add more build instructions to README. | + | | Source README into package long description. | + | | - A SecItem now converts almost all DER | + | | encoded data to a string when it's str | + | | method is invoked, formerly it was limited | + | | to only a few objects. | + | | - The following classes were added: | + | | | + | | - CERTAttribute | + | | | + | | - The following class methods were added: | + | | | + | | - CertAttribute.format_lines | + | | - CertAttribute.format | + | | - nss.SecItem.get_integer | + | | | + | | - The following class properties were added: | + | | | + | | - CertificateRequest.attributes | + | | - CertAttribute.type_oid | + | | - CertAttribute.type_tag | + | | - CertAttribute.type_str | + | | - CertAttribute.values | + | | | + | | - The following module functions were added: | + | | | + | | - base64_to_binary | + | | | + | | - The following files were added: | + | | | + | | - test_cert_request | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.14.1: + +`Release 0.14.1 <#release_0.14.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2013-10-28 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_14_1 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_14_1/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | Release 0.14.1 contains only modifications to | + | | tests and examples, otherwise functionally it | + | | is the same as release 0.14.0 | + | | | + | | - Fix bug in ssl_example.py and | + | | test_client_server.py where complete data | + | | was not read from socket. The Beast CVE fix | + | | in NSS causes only one octet to be sent in | + | | the first socket packet and then the | + | | remaining data is sent normally, this is | + | | known as 1/n-1 record splitting. The example | + | | and test SSL code sent short messages and | + | | then did a sock.recv(1024). We had always | + | | received the entire message in one | + | | sock.recv() call because it was so short. | + | | But sock.recv() does not guarantee how much | + | | data will be received, thus this was a | + | | coding mistake. The solution is straight | + | | forward, use newlines as a record separator | + | | and call sock.readline() instead of | + | | sock.recv(). sock.readline() calls | + | | sock.recv() internally until a complete line | + | | is read or the socket is closed. | + | | | + | | - Rewrite setup_certs.py, it was written like | + | | an expect script reacting to prompts read | + | | from a pseudo terminal but it was fragile | + | | and would hang on some systems. New version | + | | uses temporary password file and writes | + | | hardcoded responses to the stdin of certuil | + | | and modutil. | + | | | + | | - setup_certs now creates a new sql sytle NSS | + | | database (sql:pki) | + | | | + | | - All tests and examples now load the sql:pki | + | | database. Command line arg and variable | + | | changed from dbdir to db_name to reflect the | + | | database specification is no longer just a | + | | directory. | + | | | + | | - All command line process in test and | + | | examples now uses modern argparse module | + | | instead of deprecated getopt and optparse. | + | | Some command line args were tweaked. | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.14.0: + +`Release 0.14.0 <#release_0.14.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Release Date + +2013-05-10 + +SCM Tag + +PYNSS_RELEASE_0_14_0 + +Source Download + +https://ftp.mozilla.org/pub/mozilla.org/security/python-nss/releases/PYNSS_RELEASE_0_14_0/src/ + +Change Log + +The primary enhancements in this version is support of certifcate validation, OCSP support, and +support for the certificate "Authority Information Access" extension. + +Enhanced certifcate validation including CA certs can be done via Certificate.verify() or +Certificate.is_ca_cert(). When cert validation fails you can now obtain diagnostic information as to +why the cert failed to validate. This is encapsulated in the CertVerifyLog class which is a iterable +collection of CertVerifyLogNode objects. Most people will probablby just print the string +representation of the returned CertVerifyLog object. Cert validation logging is handled by the +Certificate.verify() method. Support has also been added for the various key usage and cert type +entities which feature prominently during cert validation. + +- Certificate() constructor signature changed from + + Certificate(data=None, der_is_signed=True) + + to + + Certificate(data, certdb=cert_get_default_certdb(), perm=False, nickname=None) + + This change was necessary because all certs should be added to the NSS temporary database when + they are loaded, but earlier code failed to do that. It's is not likely that an previous code was + failing to pass initialization data or the der_is_signed flag so this change should be backwards + compatible. + +- Fix bug #922247, PKCS12Decoder.database_import() method. Importing into a NSS database would + sometimes fail or segfault. + +- Error codes and descriptions were updated from upstream NSPR & NSS. + +- The password callback did not allow for breaking out of a password prompting loop, now if None is + returned from the password callback the password prompting is terminated. + +- nss.nss_shutdown_context now called from InitContext destructor, this assures the context is + shutdown even if the programmer forgot to. It's still best to explicitly shut it down, this is + just failsafe. + +- Support was added for shutdown callbacks. + +- cert_dump.py extended to print NS_CERT_TYPE_EXTENSION + +- cert_usage_flags, nss_init_flags now support optional repr_kind parameter + +- The following classes were added: + + - nss.CertVerifyLogNode + - nss.CertVerifyLog + - error.CertVerifyError (exception) + - nss.AuthorityInfoAccess + - nss.AuthorityInfoAccesses + +- The following class methods were added: + + - nss.Certificate.is_ca_cert + - nss.Certificate.verify + - nss.Certificate.verify_with_log + - nss.Certificate.get_cert_chain + - nss.Certificate.check_ocsp_status + - nss.PK11Slot.list_certs + - nss.CertVerifyLogNode.format_lines + - nss.CertVerifyLog.format_lines + - nss.CRLDistributionPts.format_lines + +- The following class properties were added: + + - nss.CertVerifyLogNode.certificate + - nss.CertVerifyLogNode.error + - nss.CertVerifyLogNode.depth + - nss.CertVerifyLog.count + +- The following module functions were added: + + - nss.x509_cert_type + - nss.key_usage_flags + - nss.list_certs + - nss.find_certs_from_email_addr + - nss.find_certs_from_nickname + - nss.nss_get_version + - nss.nss_version_check + - nss.set_shutdown_callback + - nss.get_use_pkix_for_validation + - nss.set_use_pkix_for_validation + - nss.enable_ocsp_checking + - nss.disable_ocsp_checking + - nss.set_ocsp_cache_settings + - nss.set_ocsp_failure_mode + - nss.set_ocsp_timeout + - nss.clear_ocsp_cache + - nss.set_ocsp_default_responder + - nss.enable_ocsp_default_responder + - nss.disable_ocsp_default_responder + +- The following files were added: + + - src/py_traceback.h + - doc/examples/verify_cert.py + - test/test_misc.py + +- The following constants were added: + + - nss.KU_DIGITAL_SIGNATURE + - nss.KU_NON_REPUDIATION + - nss.KU_KEY_ENCIPHERMENT + - nss.KU_DATA_ENCIPHERMENT + - nss.KU_KEY_AGREEMENT + - nss.KU_KEY_CERT_SIGN + - nss.KU_CRL_SIGN + - nss.KU_ENCIPHER_ONLY + - nss.KU_ALL + - nss.KU_DIGITAL_SIGNATURE_OR_NON_REPUDIATION + - nss.KU_KEY_AGREEMENT_OR_ENCIPHERMENT + - nss.KU_NS_GOVT_APPROVED + - nss.PK11CertListUnique + - nss.PK11CertListUser + - nss.PK11CertListRootUnique + - nss.PK11CertListCA + - nss.PK11CertListCAUnique + - nss.PK11CertListUserUnique + - nss.PK11CertListAll + - nss.certUsageSSLClient + - nss.certUsageSSLServer + - nss.certUsageSSLServerWithStepUp + - nss.certUsageSSLCA + - nss.certUsageEmailSigner + - nss.certUsageEmailRecipient + - nss.certUsageObjectSigner + - nss.certUsageUserCertImport + - nss.certUsageVerifyCA + - nss.certUsageProtectedObjectSigner + - nss.certUsageStatusResponder + - nss.certUsageAnyCA + - nss.ocspMode_FailureIsVerificationFailure + - nss.ocspMode_FailureIsNotAVerificationFailure + +Internal Changes + +- Reimplement exception handling + + - NSPRError is now derived from StandardException instead of EnvironmentError. It was never + correct to derive from EnvironmentError but was difficult to implement a new subclassed + exception with it's own attributes, using EnvironmentError had been expedient. + - NSPRError now derived from StandardException, provides: + + - errno (numeric error code) + - strerror (error description associated with error code) + - error_message (optional detailed message) + - error_code (alias for errno) + - error_desc (alias for strerror) + + - CertVerifyError derived from NSPRError, extends with: + + - usages (bitmask of returned usages) + - log (CertVerifyLog object) + +- Expose error lookup to sibling modules + +- Use macros for bitmask_to_list functions to reduce code duplication and centralize logic. + +- Add repr_kind parameter to cert_trust_flags_str() + +- Add support for repr_kind AsEnumName to bitstring table lookup. + +- Add cert_type_bitstr_to_tuple() lookup function + +- Add PRTimeConvert(), used to convert Python time values to PRTime, centralizes conversion logic, + reduces duplication + +- Add UTF8OrNoneConvert to better handle unicode parameters which are optional. + +- Add Certificate_summary_format_lines() utility to generate concise certificate identification + info for output. + +- Certificate_new_from_CERTCertificate now takes add_reference parameter to properly reference + count certs, should fix shutdown busy problems. + +- Add print_traceback(), print_cert() debugging support. + +.. _release_0.13.0: + +`Release 0.13.0 <#release_0.13.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2012-10-09 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_13_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_13_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | - Fix NSS SECITEM_CompareItem bug via | + | | workaround. | + | | - Fix incorrect format strings in | + | | PyArg_ParseTuple\* for: | + | | | + | | - GeneralName | + | | - BasicConstraints | + | | - cert_x509_key_usage | + | | | + | | - Fix bug when decoding certificate | + | | BasicConstraints extension | + | | - Fix hang in setup_certs. | + | | - For NSS >= 3.13 support | + | | CERTDB_TERMINAL_RECORD | + | | - You can now query for a specific certificate | + | | extension Certficate.get_extension() | + | | - The PublicKey formatting (i.e. format_lines) | + | | was augmented to format DSA keys (formerly | + | | it only recognized RSA keys). | + | | - Allow labels and values to be justified when | + | | printing objects | + | | | + | | .. rubric:: The following classes were added | + | | :name: the_following_classes_were_added | + | | | + | | - RSAGenParams | + | | | + | | .. rubric:: The following class methods were | + | | added | + | | | + | | :name: the_following_class_methods_were_added | + | | | + | | - nss.nss.Certificate.get_extension | + | | - nss.nss.PK11Slot.generate_key_pair | + | | - nss.nss.DSAPublicKey.format | + | | - nss.nss.DSAPublicKey.format_lines | + | | | + | | .. rubric:: The following module functions were | + | | added | + | | : | + | | name: the_following_module_functions_were_added | + | | | + | | - nss.nss.pub_wrap_sym_key | + | | | + | | .. rubric:: The following internal utilities | + | | were added | + | | :na | + | | me: the_following_internal_utilities_were_added | + | | | + | | - PyString_UTF8 | + | | - SecItem_new_alloc() | + | | | + | | .. rubric:: The following class constructors | + | | were modified to accept intialization | + | | parameters | + | | :name: the_following_class_constructors_w | + | | ere_modified_to_accept_intialization_parameters | + | | | + | | - KEYPQGParams (DSA generation parameters) | + | | | + | | .. rubric:: The following were deprecated | + | | :name: the_following_were_deprecated | + | | | + | | - nss.nss.make_line_pairs (replaced by | + | | nss.nss.make_line_fmt_tuples) | + | | | + | | .. rubric:: Deprecated Functionality | + | | :name: deprecated_functionality | + | | | + | | make_line_pairs() has been replaced by | + | | make_line_fmt_tuples() because 2-valued tuples | + | | were not sufficently general. It is expected | + | | very few programs will have used this function, | + | | it's mostly used internally but provided as a | + | | support utility. | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.12.0: + +`Release 0.12.0 <#release_0.12.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2011-06-06 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_12_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_12_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | - Major new enhancement is additon of PKCS12 | + | | support and AlgorithmID's. | + | | - setup.py build enhancements | + | | | + | | - Now searches for the NSS and NSPR header | + | | files rather than hardcoding their | + | | location. This makes building friendlier | + | | on other systems (i.e. debian) | + | | - Now takes optional command line | + | | arguments, -d or --debug will turn on | + | | debug options during the build. | + | | | + | | - Fix reference counting bug in | + | | PK11_password_callback() which contributed | + | | to NSS not being able to shutdown due to | + | | resources still in use. | + | | - Add UTF-8 support to | + | | ssl.config_server_session_id_cache() | + | | - Added unit tests for cipher, digest, | + | | client_server. | + | | - All unittests now run, added test/run_tests | + | | to invoke full test suite. | + | | - Fix bug in test/setup_certs.py, hardcoded | + | | full path to libnssckbi.so was causing | + | | failures on 64-bit systems, just use the | + | | libnssckbi.so basename, modutil will find it | + | | on the standard search path. | + | | - doc/examples/cert_dump.py uses new | + | | AlgorithmID class to dump Signature | + | | Algorithm | + | | - doc/examples/ssl_example.py now can cleanly | + | | shutdown NSS. | + | | - Exception error messages now include PR | + | | error text if available. | + | | | + | | .. rubric:: The following classes were replaced | + | | :name: the_following_classes_were_replaced | + | | | + | | - SignatureAlgorithm replaced by new class | + | | AlgorithmID | + | | | + | | .. rubric:: The following classes were added | + | | :name: the_following_classes_were_added_2 | + | | | + | | - AlgorithmID | + | | - PKCS12DecodeItem | + | | - PKCS12Decoder | + | | | + | | .. rubric:: The following class methods were | + | | added | + | | | + | | :name: the_following_class_methods_were_added_2 | + | | | + | | - PK11Slot.authenticate() | + | | - PK11Slot.get_disabled_reason() | + | | - PK11Slot.has_protected_authentication_path() | + | | - PK11Slot.has_root_certs() | + | | - PK11Slot.is_disabled() | + | | - PK11Slot.is_friendly() | + | | - PK11Slot.is_internal() | + | | - PK11Slot.is_logged_in() | + | | - PK11Slot.is_removable() | + | | - PK11Slot.logout() | + | | - PK11Slot.need_login() | + | | - PK11Slot.need_user_init() | + | | - PK11Slot.user_disable() | + | | - PK11Slot.user_enable() | + | | - PKCS12DecodeItem.format() | + | | - PKCS12DecodeItem.format_lines() | + | | - PKCS12Decoder.database_import() | + | | - PKCS12Decoder.format() | + | | - PKCS12Decoder.format_lines() | + | | | + | | .. rubric:: The following class properties were | + | | added | + | | : | + | | name: the_following_class_properties_were_added | + | | | + | | - AlgorithmID.id_oid | + | | - AlgorithmID.id_str | + | | - AlgorithmID.id_tag | + | | - AlgorithmID.parameters | + | | - PKCS12DecodeItem.certificate | + | | - PKCS12DecodeItem.friendly_name | + | | - PKCS12DecodeItem.has_key | + | | - PKCS12DecodeItem.shroud_algorithm_id | + | | - PKCS12DecodeItem.signed_cert_der | + | | - PKCS12DecodeItem.type | + | | - SignedData.data | + | | - SignedData.der | + | | | + | | .. rubric:: The following module functions were | + | | added | + | | :na | + | | me: the_following_module_functions_were_added_2 | + | | | + | | - nss.nss.dump_certificate_cache_info() | + | | - nss.nss.find_slot_by_name() | + | | - nss.nss.fingerprint_format_lines() | + | | - nss.nss.get_internal_slot() | + | | - nss.nss.is_fips() | + | | - nss.nss.need_pw_init() | + | | - nss.nss.nss_init_read_write() | + | | - nss.nss.pk11_disabled_reason_name() | + | | - nss.nss.pk11_disabled_reason_str() | + | | - nss.nss.pk11_logout_all() | + | | - nss.nss.pkcs12_cipher_from_name() | + | | - nss.nss.pkcs12_cipher_name() | + | | - nss.nss.pkcs12_enable_all_ciphers() | + | | - nss.nss.pkcs12_enable_cipher() | + | | - nss.nss.pkcs12_export() | + | | - nss.nss.pkcs12_map_cipher() | + | | - n | + | | ss.nss.pkcs12_set_nickname_collision_callback() | + | | - nss.nss.pkcs12_set_preferred_cipher() | + | | - nss.nss.token_exists() | + | | - nss.ssl.config_mp_server_sid_cache() | + | | - ns | + | | s.ssl.config_server_session_id_cache_with_opt() | + | | - nss.ssl.get_max_server_cache_locks() | + | | - nss.ssl.set_max_server_cache_locks() | + | | - nss.ssl.shutdown_server_session_id_cache() | + | | | + | | .. rubric:: The following constants were added | + | | :name: the_following_constants_were_added | + | | | + | | - nss.nss.int.PK11_DIS_COULD_NOT_INIT_TOKEN | + | | - nss.nss.int.PK11_DIS_NONE | + | | - nss.nss.int.PK11_DIS_TOKEN_NOT_PRESENT | + | | - nss.nss.int.PK11_DIS_TOKEN_VERIFY_FAILED | + | | - nss.nss.int.PK11_DIS_USER_SELECTED | + | | - nss.nss.int.PKCS12_DES_56 | + | | - nss.nss.int.PKCS12_DES_EDE3_168 | + | | - nss.nss.int.PKCS12_RC2_CBC_128 | + | | - nss.nss.int.PKCS12_RC2_CBC_40 | + | | - nss.nss.int.PKCS12_RC4_128 | + | | - nss.nss.int.PKCS12_RC4_40 | + | | | + | | .. rubric:: The following files were added | + | | :name: the_following_files_were_added | + | | | + | | - test/run_tests | + | | - test/test_cipher.py (replaces | + | | cipher_test.py) | + | | - test/test_client_server.py | + | | - test/test_digest.py (replaces | + | | digest_test.py) | + | | - test/test_pkcs12.py | + | | | + | | .. rubric:: Deprecated Functionality | + | | :name: deprecated_functionality_2 | + | | | + | | - SignatureAlgorithm | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.11.0: + +`Release 0.11.0 <#release_0.11.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2011-02-21 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_11_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_11_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: External Changes | + | | :name: external_changes | + | | | + | | - Add AddrInfo class to support IPv6 address | + | | resolution. Supports iteration over it's set | + | | of NetworkAddress objects and provides | + | | hostname, canonical_name object properties. | + | | - Add PR_AI_\* constants. | + | | - NetworkAddress constructor and | + | | NetworkAddress.set_from_string() added | + | | optional family parameter. This is necessary | + | | for utilizing PR_GetAddrInfoByName(). | + | | - NetworkAddress initialized via a string | + | | parameter are now initialized via | + | | PR_GetAddrInfoByName using family. | + | | - Add NetworkAddress.address property to | + | | return the address sans the port as a | + | | string. NetworkAddress.str() includes the | + | | port. For IPv6 the a hex string must be | + | | enclosed in brackets if a port is appended | + | | to it, the bracketed hex address with | + | | appended with a port is unappropriate in | + | | some circumstances, hence the new address | + | | property to permit either the address string | + | | with a port or without a port. | + | | - Fix the implementation of the | + | | NetworkAddress.family property, it was | + | | returning bogus data due to wrong native | + | | data size. | + | | - HostEntry objects now support iteration and | + | | indexing of their NetworkAddress members. | + | | - Add io.addr_family_name() function to return | + | | string representation of PR_AF_\* constants. | + | | - Modify example and test code to utilize | + | | AddrInfo instead of deprecated | + | | NetworkAddress functionality. Add address | + | | family command argument to ssl_example. | + | | - Fix pty import statement in | + | | test/setup_certs.py | + | | | + | | .. rubric:: Deprecated Functionality | + | | :name: deprecated_functionality_3 | + | | | + | | - NetworkAddress initialized via a string | + | | parameter is now deprecated. AddrInfo should | + | | be used instead. | + | | - NetworkAddress.set_from_string is now | + | | deprecated. AddrInfo should be used instead. | + | | - NetworkAddress.hostentry is deprecated. It | + | | was a bad idea, NetworkAddress objects can | + | | support both IPv4 and IPv6, but a HostEntry | + | | object can only support IPv4. Plus the | + | | implementation depdended on being able to | + | | perform a reverse DNS lookup which is not | + | | always possible. | + | | - HostEntry.get_network_addresses() and | + | | HostEntry.get_network_address() are now | + | | deprecated. In addition their port parameter | + | | is now no longer respected. HostEntry | + | | objects now support iteration and indexing | + | | of their NetworkAddress and that should be | + | | used to access their NetworkAddress objects | + | | instead. | + | | | + | | .. rubric:: Internal Changes | + | | :name: internal_changes | + | | | + | | - Utilize PR_NetAddrFamily() access macro | + | | instead of explict access. | + | | - Add PRNetAddr_port() utility to hide host | + | | vs. network byte order requirements when | + | | accessing the port inside a PRNetAddr and | + | | simplify accessing the IPv4 vs. IPv6 port | + | | variants. | + | | - Replace the use of PR_InitializeNetAddr() | + | | with PR_SetNetAddr(), the later properly | + | | handles IPv6, the former did not. | + | | - Rename NetworkAddress.addr to | + | | NetworkAddress.pr_netaddr for naming | + | | consistency. | + | | - Update HostEntry documentation to indicate | + | | it's deprecated status. | + | | - Remove redundant implementation of | + | | NetworkAddress_new_from_PRNetAddr from | + | | py_ssl.c and properly import the | + | | implementation from py_nspr_io.c. | + | | - The following other non-IPv6 fixes were also | + | | made because they were discovered while | + | | doing the IPv6 work: | + | | - Move definition of TYPE_READY to | + | | py_nspr_common.h so it can be shared. Update | + | | all modules to utilize it. | + | | - Replace incorrect use of free() with | + | | PyMem_Free for string data returned by | + | | Python's utf-8 encoder. | + | | - Add header dependency information to | + | | setup.py so modules will be rebuilt when | + | | header files change. | + | | - Add utility tuple_str() to convert a tuple | + | | to a string representation by calling str() | + | | on each object in the tuple. Tuple.str() in | + | | CPython only calls repr() on each member. | + | | - HostEntry objects now store their aliases | + | | and NetworkAddress's in internal tuples. | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.10.0: + +`Release 0.10.0 <#release_0.10.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2010-07-25 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_10_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | https://ftp.mozilla.org/pub/mozilla.org/securit | + | | y/python-nss/releases/PYNSS_RELEASE_0_10_0/src/ | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: The following classes were added: | + | | :name: the_following_classes_were_added_3 | + | | | + | | - InitParameters | + | | - InitContext | + | | | + | | .. rubric:: The following module functions were | + | | added: | + | | :na | + | | me: the_following_module_functions_were_added_3 | + | | | + | | - nss.nss.nss_initialize() | + | | - nss.nss.nss_init_context() | + | | - nss.nss.nss_shutdown_context() | + | | - nss.nss.nss_init_flags() | + | | | + | | .. rubric:: The following constants were added: | + | | :name: the_following_constants_were_added_2 | + | | | + | | - NSS_INIT_READONLY | + | | - NSS_INIT_NOCERTDB | + | | - NSS_INIT_NOMODDB | + | | - NSS_INIT_FORCEOPEN | + | | - NSS_INIT_NOROOTINIT | + | | - NSS_INIT_OPTIMIZESPACE | + | | - NSS_INIT_PK11THREADSAFE | + | | - NSS_INIT_PK11RELOAD | + | | - NSS_INIT_NOPK11FINALIZE | + | | - NSS_INIT_RESERVED | + | | - NSS_INIT_COOPERATE | + | | | + | | .. rubric:: The following file was added: | + | | :name: the_following_file_was_added | + | | | + | | - test/setup_certs.py | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.9.0: + +`Release 0.9.0 <#release_0.9.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2010-05-28 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_9_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications | + | | | + | | - Correct definciencies in | + | | auth_certificate_callback found in several | + | | of the example files and documentation. If | + | | you've copied that code you should merge | + | | those changes in. | + | | - Unicode objects now accepted as well as str | + | | objects for interfaces expecting a string. | + | | - Sockets were enhanced thusly: | + | | | + | | - Threads will now yield during blocking | + | | IO. | + | | - Socket.makefile() reimplemented | + | | | + | | - file object methods that had been | + | | missing (readlines(), sendall(), and | + | | iteration) were implemented | + | | - makefile now just returns the same | + | | - Socket object but increments an "open" | + | | ref count. Thus a Socket object | + | | behaves like a file object and must be | + | | closed once for each makefile() call | + | | before it's actually closed. | + | | | + | | - Sockets now support the iter protocol | + | | - Added methods: | + | | | + | | - Socket.readlines() | + | | - Socket.sendall() | + | | | + | | - Apply patches from Miloslav Trmač | + | | <mitr@redhat.com> for ref counting and | + | | threading support. Thanks Miloslav! | + | | - Review all ref counting, numerous ref | + | | counting fixes | + | | - Implement cyclic garbage collection support | + | | by adding object traversal and clear methods | + | | - Identify static variables, move to thread | + | | local storage | + | | - Remove python-nss specific httplib.py, no | + | | longer needed python-nss now compatible with | + | | standard library | + | | - Rewrite httplib_example.py to use standard | + | | library and illustrate ssl, non-ssl, | + | | connection class, http class usage | + | | | + | | .. rubric:: The following classes were added: | + | | :name: the_following_classes_were_added_4 | + | | | + | | - AuthKeyID | + | | - BasicConstraints | + | | - CRLDistributionPoint | + | | - CRLDistributionPts | + | | - CertificateExtension | + | | - GeneralName | + | | - SignedCRL | + | | - DN | + | | - RDN | + | | - AVA | + | | - CertificateRequest | + | | | + | | .. rubric:: The following module functions were | + | | added: | + | | :na | + | | me: the_following_module_functions_were_added_4 | + | | | + | | - nss.nss.nss_is_initialized() | + | | - nss.nss.cert_crl_reason_from_name() | + | | - nss.nss.cert_crl_reason_name() | + | | - nss.nss.cert_general_name_type_from_name() | + | | - nss.nss.cert_general_name_type_name() | + | | - nss.nss.cert_usage_flags() | + | | - nss.nss.decode_der_crl() | + | | - nss.nss.der_universal_secitem_fmt_lines() | + | | - nss.nss.import_crl() | + | | - nss.nss.make_line_pairs() | + | | - nss.nss.oid_dotted_decimal() | + | | - nss.nss.oid_str() | + | | - nss.nss.oid_tag() | + | | - nss.nss.oid_tag_name() | + | | - nss.nss.read_der_from_file() | + | | - nss.nss.x509_alt_name() | + | | - nss.nss.x509_ext_key_usage() | + | | - nss.nss.x509_key_usage() | + | | | + | | .. rubric:: The following class methods and | + | | properties were added: | + | | :name: the_fo | + | | llowing_class_methods_and_properties_were_added | + | | | + | | Note: it's a method if the name is suffixed | + | | with (), a propety otherwise | + | | | + | | - Socket.next() | + | | - Socket.readlines() | + | | - Socket.sendall() | + | | - SSLSocket.next() | + | | - SSLSocket.readlines() | + | | - SSLSocket.sendall() | + | | - AuthKeyID.key_id | + | | - AuthKeyID.serial_number | + | | - AuthKeyID.get_general_names() | + | | - CRLDistributionPoint.issuer | + | | - CRLDistributionPoint.get_general_names() | + | | - CRLDistributionPoint.get_reasons() | + | | - CertDB.find_crl_by_cert() | + | | - CertDB.find_crl_by_name() | + | | - Certificate.extensions | + | | - CertificateExtension.critical | + | | - CertificateExtension.name | + | | - CertificateExtension.oid | + | | - CertificateExtension.oid_tag | + | | - CertificateExtension.value | + | | - GeneralName.type_enum | + | | - GeneralName.type_name | + | | - GeneralName.type_string | + | | - SecItem.der_to_hex() | + | | - SecItem.get_oid_sequence() | + | | - SecItem.to_hex() | + | | - SignedCRL.delete_permanently() | + | | - AVA.oid | + | | - AVA.oid_tag | + | | - AVA.value | + | | - AVA.value_str | + | | - DN.cert_uid | + | | - DN.common_name | + | | - DN.country_name | + | | - DN.dc_name | + | | - DN.email_address | + | | - DN.locality_name | + | | - DN.org_name | + | | - DN.org_unit_name | + | | - DN.state_name | + | | - DN.add_rdn() | + | | - DN.has_key() | + | | - RDN.has_key() | + | | | + | | .. rubric:: The following module functions were | + | | removed: | + | | :na | + | | me: the_following_module_functions_were_removed | + | | | + | | Note: use nss.nss.oid_tag() instead | + | | | + | | - nss.nss.sec_oid_tag_from_name() | + | | - nss.nss.sec_oid_tag_name() | + | | - nss.nss.sec_oid_tag_str() | + | | | + | | .. rubric:: The following files were added: | + | | :name: the_following_files_were_added_2 | + | | | + | | - doc/examples/cert_dump.py | + | | - test/test_cert_components.py | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.8.0: + +`Release 0.8.0 <#release_0.8.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2009-09-21 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | PYNSS_RELEASE_0_8_0 | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications_2 | + | | | + | | - SecItem's now support indexing and slicing | + | | on their data | + | | - Clean up parsing and parameter validation of | + | | variable arg functions | + | | | + | | .. rubric:: The following were added: | + | | :name: the_following_were_added | + | | | + | | - SecItem.type SecItem.len | + | | - SecItem.data | + | | - PK11SymKey.key_data | + | | - PK11SymKey.key_length | + | | - PK11SymKey.slot | + | | - create_context_by_sym_key | + | | - param_from_iv | + | | - generate_new_param | + | | - get_iv_length | + | | - get_block_size | + | | - get_pad_mechanism | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.7.0: + +`Release 0.7.0 <#release_0.7.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2009-09-18 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications_3 | + | | | + | | - add support for symmetric | + | | encryption/decryption | + | | - more support for digests (hashes) | + | | | + | | .. rubric:: The following classes added: | + | | :name: the_following_classes_added | + | | | + | | - PK11SymKey | + | | - PK11Context | + | | | + | | .. rubric:: The following methods and functions | + | | added: | + | | : | + | | name: the_following_methods_and_functions_added | + | | | + | | - get_best_wrap_mechanism | + | | - get_best_key_length | + | | - key_gen | + | | - derive | + | | - get_key_length | + | | - digest_key | + | | - clone_context | + | | - digest_begin | + | | - digest_op | + | | - cipher_op | + | | - finalize | + | | - digest_final | + | | - read_hex | + | | - hash_buf | + | | - sec_oid_tag_str | + | | - sec_oid_tag_name | + | | - sec_oid_tag_from_name | + | | - key_mechanism_type_name | + | | - key_mechanism_type_from_name | + | | - pk11_attribute_type_name | + | | - pk11_attribute_type_from_name | + | | - get_best_slot | + | | - get_internal_key_slot | + | | - create_context_by_sym_key | + | | - import_sym_key | + | | - create_digest_context | + | | - param_from_iv | + | | - param_from_algid | + | | - generate_new_param | + | | - algtag_to_mechanism | + | | - mechanism_to_algtag | + | | | + | | .. rubric:: The following files added: | + | | :name: the_following_files_added | + | | | + | | - test/cipher_test.py | + | | - test/digest_test.py | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.6.0: + +`Release 0.6.0 <#release_0.6.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2009-07-08 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications_4 | + | | | + | | - fix Red Hat bug #510343 | + | | client_auth_data_callback seg faults if | + | | False is returned from callback | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.5.0: + +`Release 0.5.0 <#release_0.5.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2009-07-01 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications_5 | + | | | + | | - restore ssl.nss_init and ssl.nss_shutdown | + | | but make them deprecated | + | | - add \__version_\_ string to nss module | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.4.0: + +`Release 0.4.0 <#release_0.4.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2009-06-30 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications_6 | + | | | + | | - add binding for NSS_NoDB_Init(), Red Hat bug | + | | #509002 | + | | - move nss_init and nss_shutdown from ssl | + | | module to nss module | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.3.0: + +`Release 0.3.0 <#release_0.3.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2009-06-04 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications_7 | + | | | + | | - import to Mozilla CVS, tweak directory | + | | layout | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.2.0: + +`Release 0.2.0 <#release_0.2.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +-------------------------------------------------+-------------------------------------------------+ + | Release Date | 2009-05-21 | + +-------------------------------------------------+-------------------------------------------------+ + | SCM Tag | | + +-------------------------------------------------+-------------------------------------------------+ + | Source Download | | + +-------------------------------------------------+-------------------------------------------------+ + | Change Log | .. rubric:: General Modifications: | + | | :name: general_modifications_8 | + | | | + | | - apply patch from Red Hat bug #472805, | + | | (Miloslav Trmač) | + | | - Don't allow closing a socket twice, that | + | | causes crashes. | + | | - Fix return value creation in | + | | SSLSocket.get_security_status | + | | - Convert licensing to MPL tri-license | + | | | + | | .. rubric:: The following were added: | + | | :name: the_following_were_added_2 | + | | | + | | - nss.io.Socket.new_socket_pair() | + | | - nss.io.Socket.poll() | + | | - nss.io.Socket.import_tcp_socket() | + | | - | + | | nss.nss.Certificate.get_subject_common_name() | + | | - nss.nss.generate_random() | + | | - nss.ssl.SSLSocket.import_tcp_socket() | + +-------------------------------------------------+-------------------------------------------------+ + +.. _release_0.1.0: + +`Release 0.1.0 <#release_0.1.0>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + =============== =============== + Release Date 2008-07-09 + SCM Tag + Source Download + Change Log Initial release + =============== ===============
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/building_and_installing_nss/build_instructions/index.rst b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/build_instructions/index.rst new file mode 100644 index 0000000000..265d507a14 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/build_instructions/index.rst @@ -0,0 +1,152 @@ +.. _mozilla_projects_nss_reference_building_and_installing_nss_build_instructions: + +Build instructions +================== + +.. container:: + + .. note:: + + These instructions are outdated. Use the :ref:`mozilla_projects_nss_building` page for more + recent information. + + Numerous optional features of NSS builds are controlled through make variables. + + gmake is GNU make, usually your Linux-distro-regular "make" binary file, unless maybe it is a BSD + make. Make variables may be set on the gmake command line, e.g., + + .. code:: + + gmake variable=value variable=value target1 target2 + + or defined in the environment, e.g. (for POSIX shells), + + .. code:: + + variable=value; export variable + gmake target1 target2 + + Here are some (not all) of the make variables that affect NSS builds: + + - BUILD_OPT: If set to 1, means do optimized non-DEBUG build. Default is DEBUG, non-optimized + build. + - USE_DEBUG_RTL: If set to 1, on Windows, causes build with debug version of the C run-time + library. + - NS_USE_GCC: On platforms where gcc is not the native compiler, tells NSS to build with gcc + instead of the native compiler. Default is to build with the native compiler. + - USE_64: On platforms that support both 32-bit and 64-bit ABIs, tells NSS to build for the + 64-bit ABI. Default is 32-bit ABI, except on platforms that do not support a 32-bit ABI. + - MOZ_DEBUG_SYMBOLS: tells NSS to build with debug symbols, even in an optimized build. On + windows, in both DEBUG and optimized builds, when using MSVC, tells NSS to put symbols in a + .pdb file. Required to build with MSVC 8 (2005 Express). Default is not to put debug symbols + into optimized builds, and for MSVC, is to put symbols into the .exe or .dll file. + - NSDISTMODE: If set to 'copy', mozilla/dist/<OBJ_STUFF>/bin/\* real files instead of symbolic + links. + + These variables should be either undefined, or set to "1". Results are undefined for variables + set to "0". + + For Windows, install + the `MozillaBuild <https://firefox-source-docs.mozilla.org/setup/windows_build.html#install-mozillabuild>`__ environment + and Microsoft Visual Studio 2010. (The free edition works, and other versions like Visual Studio + 2008 and Visual Studio 2012 may also work.) Use start-shell-msvc2010.bat from MozillaBuild to get + a bash shell with the PATH already configured, and execute these instructions from within that + bash shell. + + For RHEL-5, you need to use the new assembler. You can install the new assembler as root as + follows: + + .. code:: + + yum install binutils220 + + You can then use the new assembler by adding /usr/libexec/binutils220 to the beginning of your + build path. This can be done in sh or bash as follows: + + .. code:: + + export PATH=/usr/libexec/binutils220:$PATH + + The following build instructions should work for all platforms (with some platform-specific + changes as noted). + +.. _build_instructions_for_recent_versions_(mercurial): + +`Build Instructions for Recent Versions (Mercurial) <#build_instructions_for_recent_versions_(mercurial)>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Clone the NSPR and NSS repositories. + + .. code:: + + hg clone https://hg.mozilla.org/projects/nspr + hg clone https://hg.mozilla.org/projects/nss + + #. If you want to build a releases other than the tips of these repositories, then switch to the + release tags: + + .. code:: + + cd nspr + hg update NSPR_4_9_5_RTM + cd ../nss + hg update NSS_3_14_2_RTM + cd .. + + #. Set environment variables: + + #. If you want a non-debug optimized build, set ``BUILD_OPT=1`` in your environment. + Otherwise, you get a debug build. On Windows, if you want a debug build with the system's + debug RTL libraries, set ``USE_DEBUG_RTL=1`` in your environment. + #. On Unix platforms, except Alpha/OSF1, if you want a build for the system's 64-bit ABI, set + ``USE_64=1`` in your environment. By default, NSS builds for the 32-bit environment on all + platforms except Alpha/OSF1. + #. To build with ``gcc`` on platforms other than Linux and Windows, you need to set two more + environment variables: + + - ``NS_USE_GCC=1`` + ``NO_MDUPDATE=1`` + + #. For HP-UX, you must set the environment variable ``USE_PTHREADS`` to 1. + + #. ``cd nss`` + + #. ``gmake nss_build_all`` + + The output of the build will be in the ``dist`` directory alongside the ``nspr`` and ``nss`` + directories. + + For information on troubleshooting the build system, see + :ref:`mozilla_projects_nss_reference_troubleshoot`. + +.. _build_instructions_for_older_versions_(cvs): + +`Build Instructions for Older Versions (CVS) <#build_instructions_for_older_versions_(cvs)>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Set the environment variable ``CVSROOT`` to + ``:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot`` + + #. ``cvs login`` (if you haven't before). + + #. Check out NSPR and NSS: + + .. code:: + + cvs co -r NSPR_4_9_5_RTM NSPR + cvs co -r NSS_3_14_2_RTM NSS + + #. Set environment variables as described in the Mercurial-based instructions. + + #. ``cd mozilla/security/nss`` + + #. ``gmake nss_build_all`` + + The output of the build will be in ``mozilla/dist`` subdirectory. + + For information on troubleshooting the build system, see + :ref:`mozilla_projects_nss_reference_troubleshoot`. diff --git a/security/nss/doc/rst/legacy/reference/building_and_installing_nss/index.rst b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/index.rst new file mode 100644 index 0000000000..c51a681b8a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/index.rst @@ -0,0 +1,12 @@ +.. _mozilla_projects_nss_reference_building_and_installing_nss: + +Building and installing NSS +=========================== + +.. container:: + + This chapter describes how to build and install NSS. + + - :ref:`mozilla_projects_nss_reference_building_and_installing_nss_build_instructions` + - :ref:`mozilla_projects_nss_reference_building_and_installing_nss_installation_guide` + - :ref:`mozilla_projects_nss_reference_building_and_installing_nss_sample_manual_installation`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/building_and_installing_nss/installation_guide/index.rst b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/installation_guide/index.rst new file mode 100644 index 0000000000..0a2f382e4b --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/installation_guide/index.rst @@ -0,0 +1,50 @@ +.. _mozilla_projects_nss_reference_building_and_installing_nss_installation_guide: + +Installation guide +================== + +.. container:: + + The build system of NSS originated from Netscape's build system, which predated the "configure; + make; make test; make install" sequence that we're familiar with now. Our makefiles also have an + "install" target, but it has a different meaning: our "install" means installing the headers, + libraries, and programs in the appropriate directories under mozilla/dist. + + So right now you need to manually install the headers, libraries, and programs in the directories + you want. If you install the libraries in a directory other than /usr/lib, you usually need to + set the LD_LIBRARY_PATH environment variable. You can avoid that by installing the libraries in a + directory that is $ORIGIN/../lib, where $ORIGIN is the directory where the programs are + installed. This is done here: + `http://lxr.mozilla.org/security/sour...platlibs.mk#53 <http://lxr.mozilla.org/security/source/security/nss/cmd/platlibs.mk#53>`__ + + .. code:: + + 53 ifeq ($(OS_ARCH), Linux) + 54 ifeq ($(USE_64), 1) + 55 EXTRA_SHARED_LIBS += -Wl,-rpath,'$$ORIGIN/../lib64:$$ORIGIN/../lib' + 56 else + 57 EXTRA_SHARED_LIBS += -Wl,-rpath,'$$ORIGIN/../lib' + 58 endif + 59 endif + + For example, if you install certutil in /foo/bar/nss/bin and the .so's in /foo/bar/nss/lib, then + you only need to add /foo/bar/nss/bin to your PATH; you don't need to set LD_LIBRARY_PATH. + + The libraries you need to install are listed below. + + NSPR: + + - libnspr4.so + - libplds4.so + - libplc4.so + + NSS: (Note the use of \* for libfreebl -- some platforms have multiple ones) + + - libfreebl*3.so + - libfreebl*3.chk + - libsoftokn3.so + - libsoftokn3.chk + - libnss3.so + - libsmime3.so + - libssl3.so + - libnssckbi.so
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/building_and_installing_nss/migration_to_hg/index.rst b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/migration_to_hg/index.rst new file mode 100644 index 0000000000..11bd04eabe --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/migration_to_hg/index.rst @@ -0,0 +1,49 @@ +.. _mozilla_projects_nss_reference_building_and_installing_nss_migration_to_hg: + +Migration to HG +=============== + +.. container:: + + | The NSPR, NSS and related projects have stopped using Mozilla'a CVS server, but have migrated + to + | Mozilla's HG (Mercurial) server. + | Each project now lives in its own separate space, they can be found at: + | https://hg.mozilla.org/projects/nspr/ + | https://hg.mozilla.org/projects/nss/ + | https://hg.mozilla.org/projects/jss/ + | https://hg.mozilla.org/projects/python-nss/ + + | This migration has been used as an opportunity to change the layout of the + | source directories. + | For NSPR, "mozilla/nsprpub" has been removed from the directory + | hierarchy, all files now live in the top directory of the NSPR + | repository. + | Likewise for NSS and JSS, "mozilla/security" has been removed and files + | now live at the top level. In addition for NSS, we have merged the + | contents of directories mozilla/dbm and mozilla/security/dbm into the + | new directory lib/dbm. + | Besides the new layout, the build system hasn't changed. Most parts of + | the NSS build instructions remain valid, especially the instructions + | about setting environment variables. + | Updated instructions for building NSS with NSPR can be found at: + | :ref:`mozilla_projects_nss_reference_building_and_installing_nss_build_instructions` + | It's best to refer to the above document to learn about the various + | environment variables that you might have to set to build on your + | platform (this part hasn't changed). + | However, below is a brief summary that shows how to checkout the + | source code and build both NSPR and NSS: + | mkdir workarea + | cd workarea + | hg clone https://hg.mozilla.org/projects/nspr + | hg clone https://hg.mozilla.org/projects/nss + | cd nss + | # set USE_64=1 on 64 bit architectures + | # set BUILD_OPT=1 to get an optimized build + | make nss_build_all + | Note that the JSS project has been given a private copy of the former + | mozilla/security/coreconf directory, allowing it to remain stable, + | and only update its build system as necessary. + | Because of the changes described above, we have decided to use a new + | series of (minor) version numbers. The first releases using the new code + | layout will be NSPR 4.10 and NSS 3.15
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/building_and_installing_nss/sample_manual_installation/index.rst b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/sample_manual_installation/index.rst new file mode 100644 index 0000000000..bc570c2e13 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/building_and_installing_nss/sample_manual_installation/index.rst @@ -0,0 +1,27 @@ +.. _mozilla_projects_nss_reference_building_and_installing_nss_sample_manual_installation: + +Sample manual installation +========================== + +.. container:: + + | + | The NSS build system does not include a target to install header files and shared libraries in + the system directories, so this needs to be done manually. + + After building NSS with *"gmake nss_build_all"*, the resulting build can be found in the NSS + source tree as follows: + + - NSS header files: *mozilla/dist/public/nss* + - NSPR header files: *mozilla/dist/*\ **<OBJ-DIR>**\ */include* + - NSPR/NSS shared libs: *mozilla/dist/*\ **<OBJ-DIR>**\ */lib* + - NSS binary executables: *mozilla/dist/*\ **<OBJ-DIR>**\ */bin*. + + where **<OBJ-DIR>** would vary according to the type of build and the platform. For example, + **<OBJ-DIR>** for a debug build of NSS on the x86 platform with a Linux kernel version 2.6 with + glibc would be: Linux2.6_x86_glibc_PTH_DBG.OBJ + + From these directories, you can copy the files to any system (or other) directory. If the + destination directories are not what's standard for the system (e.g. /usr/include, /usr/lib and + /usr/bin for a Linux system), you need to edit the corresponding environment variables or + compiler/linker arguments.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_cancelfunction/index.rst b/security/nss/doc/rst/legacy/reference/fc_cancelfunction/index.rst new file mode 100644 index 0000000000..8923feba1d --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_cancelfunction/index.rst @@ -0,0 +1,61 @@ +.. _mozilla_projects_nss_reference_fc_cancelfunction: + +FC_CancelFunction +================= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_CancelFunction - cancel a function running in parallel + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_CancelFunction( + CK_SESSION_HANDLE hSession + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Parallel functions are not implemented. ``FC_CancelFunction`` is a legacy function that simply + returns ``CKR_FUNCTION_NOT_PARALLEL``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_CancelFunction`` always returns ``CKR_FUNCTION_NOT_PARALLEL``. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_CancelFunction </en-US/NSC_CancelFunction>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_closeallsessions/index.rst b/security/nss/doc/rst/legacy/reference/fc_closeallsessions/index.rst new file mode 100644 index 0000000000..bbfa703fcb --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_closeallsessions/index.rst @@ -0,0 +1,66 @@ +.. _mozilla_projects_nss_reference_fc_closeallsessions: + +FC_CloseAllSessions +=================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_CloseAllSessions - close all sessions between an application and a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_CloseAllSessions( + CK_SLOT_ID slotID + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``slotID`` + [in] the ID of the token's slot. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_CloseAllSessions`` closes all sessions between an application and the token in the slot with + the ID ``slotID``. + + The NSS cryptographic module currently doesn't call the surrender callback function ``Notify``. + (See PKCS #11 v2.20 section 11.17.1.) + + A user may call ``FC_CloseAllSessions`` without logging into the token (to assume the NSS User + role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_closesession`, + `NSC_CloseAllSessions </en-US/NSC_CloseAllSessions>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_closesession/index.rst b/security/nss/doc/rst/legacy/reference/fc_closesession/index.rst new file mode 100644 index 0000000000..ef3d9c6992 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_closesession/index.rst @@ -0,0 +1,60 @@ +.. _mozilla_projects_nss_reference_fc_closesession: + +FC_CloseSession +=============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_CloseSession - close a session opened between an application and a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_CloseSession( + CK_SESSION_HANDLE hSession + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] the session handle to be closed. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_CloseSession`` closes a session between an application and a token. + + A user may call ``FC_CloseSession`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_opensession`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_copyobject/index.rst b/security/nss/doc/rst/legacy/reference/fc_copyobject/index.rst new file mode 100644 index 0000000000..11cbb9574a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_copyobject/index.rst @@ -0,0 +1,74 @@ +.. _mozilla_projects_nss_reference_fc_copyobject: + +FC_CopyObject +============= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_CopyObject - create a copy of an object. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_CopyObject( + CK_SESSION_HANDLE hSession, + CK_OBJECT_HANDLE hObject, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG usCount, + CK_OBJECT_HANDLE_PTR phNewObject + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``hObject`` + [in] object handle. + ``pTemplate`` + [in] object template. + ``usCount`` + [in] number of attributes in the template. + ``phnewObject`` + [out] pointer to location to receive the new object's handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_CopyObject`` creates a copy of an object using the attributes specified in the template. + + A user must log into the token (to assume the NSS User role) before copying a secret or private + key object. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_destroyobject`, + `NSC_CopyObject </en-US/NSC_CopyObject>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_createobject/index.rst b/security/nss/doc/rst/legacy/reference/fc_createobject/index.rst new file mode 100644 index 0000000000..c4157db64c --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_createobject/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_createobject: + +FC_CreateObject +=============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_CreateObject - create a new object. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_CreateObject( + CK_SESSION_HANDLE hSession, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG ulCount, + CK_OBJECT_HANDLE_PTR phObject + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pTemplate`` + [in] object template. + ``ulCount`` + [in] number of attributes in the template. + ``phObject`` + [out] pointer to location to receive the new objects handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_CreateObject`` creates an object using the attributes specified in the template. + + A user must log into the token (to assume the NSS User role) before calling ``FC_CreateObject``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_destroyobject`, + `NSC_CreateObject </en-US/NSC_CreateObject>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_decrypt/index.rst b/security/nss/doc/rst/legacy/reference/fc_decrypt/index.rst new file mode 100644 index 0000000000..5984a546f4 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_decrypt/index.rst @@ -0,0 +1,73 @@ +.. _mozilla_projects_nss_reference_fc_decrypt: + +FC_Decrypt +========== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_Decrypt - Decrypt a block of data. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Decrypt( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pEncryptedData, + CK_ULONG usEncryptedDataLen, + CK_BYTE_PTR pData, + CK_ULONG_PTR pusDataLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pEncryptedData`` + [in] pointer to encrypted data block. + ``usEncryptedDataLen`` + [in] length of the data in bytes. + ``pData`` + [out] pointer to location where recovered data is to be stored. + ``pusDataLen`` + [in,out] pointer to location where the length of recovered data is to be stored. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Decrypt`` decrypts a block of data according to the attributes of the previous call to + ``FC_DecryptInit``. + + A user must log into the token (to assume the NSS User role) before calling ``FC_Decrypt``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_decryptinit`, `NSC_Decrypt </en-US/NSC_Decrypt>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_decryptdigestupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_decryptdigestupdate/index.rst new file mode 100644 index 0000000000..4eae1c7f37 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_decryptdigestupdate/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_reference_fc_decryptdigestupdate: + +FC_DecryptDigestUpdate +====================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DecryptDigestUpdate - continue a multi-part decrypt and digest operation + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DecryptDigestUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pEncryptedPart, + CK_ULONG ulEncryptedPartLen, + CK_BYTE_PTR pPart, + CK_ULONG_PTR pulPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pEncryptedPart`` + [in] pointer to the encrypted data part. + ``ulEncryptedPartLen`` + [in] length of encrypted data in bytes. + ``pPart`` + [in] pointer to the location which receives the recovered data part or NULL. + ``pulPartLen`` + [in] pointer to the length of the recovered part buffer. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DecryptDigestUpdate`` continues a multi-part decrypt and digest operation. After calling + both ``FC_DecryptInit`` and ``FC_DigestInit`` to set up the operations this function may be + called multiple times. The operation is finished by calls to ``FC_DigestFinal`` and + ``FC_DecryptFinal``. + + A user must log into the token (to assume the NSS User role) before calling + ``FC_DecryptDigestUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_DecryptDigestUpdate </en-US/NSC_DecryptDigestUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_decryptfinal/index.rst b/security/nss/doc/rst/legacy/reference/fc_decryptfinal/index.rst new file mode 100644 index 0000000000..63ec6f575d --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_decryptfinal/index.rst @@ -0,0 +1,67 @@ +.. _mozilla_projects_nss_reference_fc_decryptfinal: + +FC_DecryptFinal +=============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DecryptFinal - finish a multi-part decryption operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DecryptFinal( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pLastPart, + CK_ULONG_PTR pusLastPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pLastPart`` + [out] pointer to the location where the last block of recovered data, if any, is to be stored. + ``pusLastPartLen`` + [in,out] pointer to location where the number of bytes of recovered data is to be stored. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DecryptFinal`` returns the last block of data of a multi-part decryption operation. + + A user must log into the token (to assume the NSS User role) before calling ``FC_DecryptFinal``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_decryptinit`, + `NSC_DecryptFinal </en-US/NSC_DecryptFinal>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_decryptinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_decryptinit/index.rst new file mode 100644 index 0000000000..05540da07b --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_decryptinit/index.rst @@ -0,0 +1,66 @@ +.. _mozilla_projects_nss_reference_fc_decryptinit: + +FC_DecryptInit +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DecryptInit - initialize a decryption operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DecryptInit( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] mechanism to be used for the subsequent decryption operation. + ``hKey`` + [in] handle of the key to be used. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DecryptInit`` initializes a decryption operation. + + A user must log into the token (to assume the NSS User role) before calling ``FC_DecryptInit``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_DecryptInit </en-US/NSC_DecryptInit>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_decryptupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_decryptupdate/index.rst new file mode 100644 index 0000000000..75d39b379c --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_decryptupdate/index.rst @@ -0,0 +1,74 @@ +.. _mozilla_projects_nss_reference_fc_decryptupdate: + +FC_DecryptUpdate +================ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DecryptUpdate - decrypt a block of a multi-part encryption operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DecryptUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pEncryptedPart, + CK_ULONG usEncryptedPartLen, + CK_BYTE_PTR pPart, + CK_ULONG_PTR pusPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pEncryptedPart`` + [in] pointer to the next block of data to be decrypted. + ``usEncryptedPartLen`` + [in] length of data block in bytes. + ``pPart`` + [out] pointer to location where recovered block is to be stored. + ``pusPartLen`` + [in,out] pointer the location where the number of bytes of recovered data is to be stored. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DecryptUpdate`` decrypts a block of data according to the attributes of the previous call to + ``FC_DecryptInit``. The block may be part of a multi-part decryption operation. + + A user must log into the token (to assume the NSS User role) before calling ``FC_DecryptUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_decryptinit`, + `NSC_DecryptUpdate </en-US/NSC_DecryptUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_decryptverifyupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_decryptverifyupdate/index.rst new file mode 100644 index 0000000000..1e8818be26 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_decryptverifyupdate/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_reference_fc_decryptverifyupdate: + +FC_DecryptVerifyUpdate +====================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DecryptVerifyUpdate - continue a multi-part decrypt and verify operation + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DecryptVerifyUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pEncryptedData, + CK_ULONG ulEncryptedDataLen, + CK_BYTE_PTR pData, + CK_ULONG_PTR pulDataLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pEncryptedData`` + [in] pointer to the encrypted data part. + ``ulEncryptedDataLen`` + [in] length of encrypted data in bytes. + ``pData`` + [in] pointer to the location which receives the recovered data part or NULL. + ``pulDataLen`` + [in] pointer to the length of the recovered part buffer. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DecryptVerifyUpdate`` continues a multi-part decryption and signature verification + operation. After calling both ``FC_DecryptInit`` and ``FC_VerifyInit`` to set up the operations + this function may be called multiple times. The operation is finished by calls to + ``FC_DecryptFinal`` and ``FC_VerifyFinal``. + + A user must log into the token (to assume the NSS User role) before calling + ``FC_DecryptVerifyUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_DecryptVerifyUpdate </en-US/NSC_DecryptVerifyUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_derivekey/index.rst b/security/nss/doc/rst/legacy/reference/fc_derivekey/index.rst new file mode 100644 index 0000000000..85166ef998 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_derivekey/index.rst @@ -0,0 +1,77 @@ +.. _mozilla_projects_nss_reference_fc_derivekey: + +FC_DeriveKey +============ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DeriveKey - derive a key from a base key + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DeriveKey( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hBaseKey, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG usAttributeCount, + CK_OBJECT_HANDLE_PTR phKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] pointer to the mechanism to use. + ``hBaseKey`` + [in] handle of the base key. + ``pWrappedKey`` + [in] pointer to the wrapped key. + ``pTemplate`` + [in] pointer to the list of attributes for the new key. + ``usAttributeCount`` + [in] number of attributes in the template. + ``phKey`` + [out] pointer to the location to receive the handle of the new key. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DeriveKey`` derives (decrypts) a key and creates a new key object. + + A user must log into the token (to assume the NSS User role) before calling ``FC_DeriveKey``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_DeriveKey </en-US/NSC_DeriveKey>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_destroyobject/index.rst b/security/nss/doc/rst/legacy/reference/fc_destroyobject/index.rst new file mode 100644 index 0000000000..e1e2de10a8 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_destroyobject/index.rst @@ -0,0 +1,64 @@ +.. _mozilla_projects_nss_reference_fc_destroyobject: + +FC_DestroyObject +================ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DestroyObject - destroy an object. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DestroyObject( + CK_SESSION_HANDLE hSession, + CK_OBJECT_HANDLE hObject + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``hObject`` + [in] object handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DestroyObject`` destroys an object. + + A user must log into the token (to assume the NSS User role) before destroying a secret or + private key object. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_DestroyObject </en-US/NSC_DestroyObject>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_digest/index.rst b/security/nss/doc/rst/legacy/reference/fc_digest/index.rst new file mode 100644 index 0000000000..8017f4958b --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_digest/index.rst @@ -0,0 +1,74 @@ +.. _mozilla_projects_nss_reference_fc_digest: + +FC_Digest +========= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_Digest - digest a block of data. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Digest( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pData, + CK_ULONG usDataLen, + CK_BYTE_PTR pDigest, + CK_ULONG_PTR pusDigestLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pData`` + [in] pointer to data block. + ``usDataLen`` + [in] length of the data in bytes. + ``pDigest`` + [out] pointer to location where recovered data is to be stored. + ``pusDigestLen`` + [in, out] pointer to the maximum size of the output buffer, replaced by the length of the + message digest if the operation is successful. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Digest`` digests a message in a single operation according to the attributes of the previous + call to ``FC_DigestInit``. + + A user may call ``FC_Digest`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_digestinit`, `NSC_Digest </en-US/NSC_Digest>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_digestencryptupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_digestencryptupdate/index.rst new file mode 100644 index 0000000000..0fa553f525 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_digestencryptupdate/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_reference_fc_digestencryptupdate: + +FC_DigestEncryptUpdate +====================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DigestEncryptUpdate - continue a multi-part digest and encryption operation + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DigestEncryptUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pPart, + CK_ULONG ulPartLen, + CK_BYTE_PTR pEncryptedPart, + CK_ULONG_PTR pulEncryptedPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pPart`` + [in] pointer to the data part. + ``ulPartLen`` + [in] length of data in bytes. + ``pEncryptedPart`` + [in] pointer to the location which receives the digested and encrypted part or NULL. + ``pulEncryptedPartLen`` + [in] pointer to the length of the encrypted part buffer. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DigestEncryptUpdate`` continues a multi-part digest and encryption operation. After calling + both ``FC_DigestInit`` and ``FC_EncryptInit`` to set up the operations this function may be + called multiple times. The operation is finished by calls to ``FC_DigestFinal`` and + ``FC_EncryptFinal`` in that order. + + A user must log into the token (to assume the NSS User role) before calling + ``FC_DigestEncryptUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_DigestEncryptUpdate </en-US/NSC_DigestEncryptUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_digestfinal/index.rst b/security/nss/doc/rst/legacy/reference/fc_digestfinal/index.rst new file mode 100644 index 0000000000..695865f686 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_digestfinal/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_reference_fc_digestfinal: + +FC_DigestFinal +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DigestFinal - finish a multi-part digest operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DigestFinal( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pDigest, + CK_ULONG_PTR pulDigestLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pDigest`` + [out] pointer to the buffer which will receive the digest or NULL. + ``pulDigestLen`` + [in, out] pointer to location containing the maximum buffer size. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DigestFinal`` finishes a multi-part digest operation by returning the complete digest and + clearing the operation context. If ``pDigest`` is NULL the length of the digest is returned and + ``FC_DigestFinal`` may be called again with ``pDigest`` set to retrieve the digest. + + A user may call ``FC_DigestFinal`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_digestinit`, + `NSC_DigestFinal </en-US/NSC_DigestFinal>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_digestinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_digestinit/index.rst new file mode 100644 index 0000000000..012643d57f --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_digestinit/index.rst @@ -0,0 +1,63 @@ +.. _mozilla_projects_nss_reference_fc_digestinit: + +FC_DigestInit +============= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DigestInit - initialize a message-digest operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DigestInit( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] mechanism to be used for the subsequent digest operation. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DigestInit`` initializes a message-digest operation. + + A user may call ``FC_DigestInit`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_DigestInit </en-US/NSC_DigestInit>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_digestkey/index.rst b/security/nss/doc/rst/legacy/reference/fc_digestkey/index.rst new file mode 100644 index 0000000000..4b558bb238 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_digestkey/index.rst @@ -0,0 +1,66 @@ +.. _mozilla_projects_nss_reference_fc_digestkey: + +FC_DigestKey +============ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DigestKey - add the digest of a key to a multi-part digest operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DigestKey( + CK_SESSION_HANDLE hSession, + CK_OBJECT_HANDLE hKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``hKey`` + [in] handle of the key to be digested. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DigestKey`` continues a multi-part digest operation by digesting the value of a secret key. + The digest for the entire message is returned by a call to + :ref:`mozilla_projects_nss_reference_fc_digestfinal`. + + A user must log into the token (to assume the NSS User role) before calling ``FC_DigestKey``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_digestinit`, + :ref:`mozilla_projects_nss_reference_fc_digestfinal`, `NSC_DigestKey </en-US/NSC_DigestKey>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_digestupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_digestupdate/index.rst new file mode 100644 index 0000000000..9650600465 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_digestupdate/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_digestupdate: + +FC_DigestUpdate +=============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_DigestUpdate - process the next block of a multi-part digest operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_DigestUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pPart, + CK_ULONG usPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pPart`` + [in] pointer to the next block of data to be digested. + ``usPartLen`` + [in] length of data block in bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_DigestUpdate`` starts or continues a multi-part digest operation. One or more blocks may be + part of the message digest operation. The digest for the entire message is returned by a call to + :ref:`mozilla_projects_nss_reference_fc_digestfinal`. + + A user may call ``FC_DigestUpdate`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_digestinit`, + :ref:`mozilla_projects_nss_reference_fc_digestfinal`, + `NSC_DigestUpdate </en-US/NSC_DigestUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_encrypt/index.rst b/security/nss/doc/rst/legacy/reference/fc_encrypt/index.rst new file mode 100644 index 0000000000..33e61612a7 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_encrypt/index.rst @@ -0,0 +1,73 @@ +.. _mozilla_projects_nss_reference_fc_encrypt: + +FC_Encrypt +========== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_Encrypt - Encrypt a block of data. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Encrypt( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pData, + CK_ULONG usDataLen, + CK_BYTE_PTR pEncryptedData, + CK_ULONG_PTR pusEncryptedDataLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pData`` + [in] pointer to the data buffer + ``usDataLen`` + [in] length of the data buffer in bytes. + ``pEncryptedData`` + [out] pointer to location where encrypted data is to be stored. + ``pusEncryptedDataLen`` + [in/out] number of bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Encrypt`` encrypts a block of data according to the attributes of the previous call to + ``FC_EncryptInit``. + + A user must log into the token (to assume the NSS User role) before calling ``FC_Encrypt``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_encryptinit`, `NSC_Encrypt </en-US/NSC_Encrypt>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_encryptfinal/index.rst b/security/nss/doc/rst/legacy/reference/fc_encryptfinal/index.rst new file mode 100644 index 0000000000..05bab1f646 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_encryptfinal/index.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_reference_fc_encryptfinal: + +FC_EncryptFinal +=============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_EncryptFinal - finish a multi-part encryption operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_EncryptFinal( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pLastEncryptedPart, + CK_ULONG_PTR pusLastEncryptedPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pLastEncryptedPart`` + [out] pointer to the location that receives the last encrypted data part, if any + ``pusLastEncryptedPartLen`` + [in,out] pointer to location where the number of bytes of the last encrypted data part is to + be stored. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_EncryptFinal`` returns the last block of data of a multi-part encryption operation. + + A user must log into the token (to assume the NSS User role) before calling ``FC_EncryptFinal``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_encryptinit`, + `NSC_EncryptFinal </en-US/NSC_EncryptFinal>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_encryptinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_encryptinit/index.rst new file mode 100644 index 0000000000..6ca0b8dee4 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_encryptinit/index.rst @@ -0,0 +1,71 @@ +.. _mozilla_projects_nss_reference_fc_encryptinit: + +FC_EncryptInit +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_EncryptInit - initialize an encryption operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_EncryptInit( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] handle to the session. + ``pMechanism`` + [in] pointer to the mechanism to be used for subsequent encryption. + ``hKey`` + [in] handle of the encryption key. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_EncryptInit`` initializes an encryption operation with the mechanism and key to be used. + + A user must log into the token (to assume the NSS User role) before calling ``FC_EncryptInit``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` + Slot information was successfully copied. + ``CKR_SLOT_ID_INVALID`` + The specified slot number is out of the defined range of values. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_EncryptInit </en-US/NSC_EncryptInit>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_encryptupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_encryptupdate/index.rst new file mode 100644 index 0000000000..0cc9a7eafd --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_encryptupdate/index.rst @@ -0,0 +1,74 @@ +.. _mozilla_projects_nss_reference_fc_encryptupdate: + +FC_EncryptUpdate +================ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_EncryptUpdate - encrypt a block of a multi-part encryption operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_EncryptUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pPart, + CK_ULONG usPartLen, + CK_BYTE_PTR pEncryptedPart, + CK_ULONG_PTR pusEncryptedPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pPart`` + [in] pointer to the next block of data to be encrypted. + ``usPartLen`` + [in] length of data block in bytes. + ``pEncryptedPart`` + [out] pointer to location where encrypted block is to be stored. + ``pusEncryptedPartaLen`` + [out] pointer the location where the number of bytes of encrypted data is to be stored. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_EncryptUpdate`` encrypts a block of data according to the attributes of the previous call to + ``FC_EncryptInit``. The block may be part of a multi-part encryption operation. + + A user must log into the token (to assume the NSS User role) before calling ``FC_EncryptUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_encryptinit`, + `NSC_EncryptUpdate </en-US/NSC_EncryptUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_finalize/index.rst b/security/nss/doc/rst/legacy/reference/fc_finalize/index.rst new file mode 100644 index 0000000000..a6bf07b87f --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_finalize/index.rst @@ -0,0 +1,88 @@ +.. _mozilla_projects_nss_reference_fc_finalize: + +FC_Finalize +=========== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_Finalize - indicate that an application is done with the PKCS #11 library. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Finalize (CK_VOID_PTR pReserved); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Finalize`` has one parameter: + + ``pReserved`` + must be ``NULL`` + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Finalize`` shuts down the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module` in + the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module_fips_mode_of_operation`. If the + library is not initialized, it does nothing. + + The ``pReserved`` argument is not used and must be ``NULL``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Finalize`` always returns ``CKR_OK``. + + .. note:: + + ``FC_Finalize`` should check the ``pReserved`` argument and return ``CKR_ARGUMENTS_BAD`` if + ``pReserved`` is not ``NULL``. + + ``FC_Finalize`` should return ``CKR_CRYPTOKI_NOT_INITIALIZED`` if the library is not + initialized. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <assert.h> + + CK_FUNCTION_LIST_PTR pFunctionList; + CK_RV crv; + + crv = FC_GetFunctionList(&pFunctionList); + assert(crv == CKR_OK); + + ... + + /* invoke FC_Finalize as pFunctionList->C_Finalize */ + crv = pFunctionList->C_Finalize(NULL); + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_initialize`, + `NSC_Initialize </en-US/NSC_Initialize>`__, `NSC_Finalize </en-US/NSC_Finalize>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_findobjects/index.rst b/security/nss/doc/rst/legacy/reference/fc_findobjects/index.rst new file mode 100644 index 0000000000..09298c4b94 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_findobjects/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_findobjects: + +FC_FindObjects +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_FindObjects - Search for one or more objects + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_FindObjects( + CK_SESSION_HANDLE hSession, + CK_OBJECT_HANDLE_PTR phObject, + CK_ULONG usMaxObjectCount, + CK_ULONG_PTR pusObjectCount + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pTemplate`` + [out] pointer to location to receive the object handles. + ``usMaxObjectCount`` + [in] maximum number of handles to retrieve. + ``pusObjectCount`` + [out] pointer to location to receive the number of returned handles. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_FindObjects`` returns the next set of object handles matching the criteria set up by the + previous call to ``FC_FindObjectsInit`` and sets the object count variable to their number or to + zero if there are none. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_findobjectsinit`, + `NSC_FindObjects </en-US/NSC_FindObjects>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_findobjectsfinal/index.rst b/security/nss/doc/rst/legacy/reference/fc_findobjectsfinal/index.rst new file mode 100644 index 0000000000..0d6ed54df6 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_findobjectsfinal/index.rst @@ -0,0 +1,59 @@ +.. _mozilla_projects_nss_reference_fc_findobjectsfinal: + +FC_FindObjectsFinal +=================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_FindObjectsFinal - terminate an object search. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_FindObjectsFinal( + CK_SESSION_HANDLE hSession, + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Clears the object search criteria for a session. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_findobjects`, + `NSC_FindObjectsFinal </en-US/NSC_FindObjectsFinal>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_findobjectsinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_findobjectsinit/index.rst new file mode 100644 index 0000000000..cbd9a59fa3 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_findobjectsinit/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_findobjectsinit: + +FC_FindObjectsInit +================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_FindObjectsInit - initialize the parameters for an object search. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_FindObjectsInit( + CK_SESSION_HANDLE hSession, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG usCount + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pTemplate`` + [in] pointer to template. + ``usCount`` + [in] number of attributes in the template. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_FindObjectsInit`` sets the attribute list for an object search. If ``FC_FindObjectsInit`` is + successful ``FC_FindObjects`` may be called one or more times to retrieve handles of matching + objects. + + A user must log into the token (to assume the NSS User role) before searching for secret or + private key objects. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_findobjects`, + `NSC_FindObjectsInit </en-US/NSC_FindObjectsInit>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_generatekey/index.rst b/security/nss/doc/rst/legacy/reference/fc_generatekey/index.rst new file mode 100644 index 0000000000..47a45816e8 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_generatekey/index.rst @@ -0,0 +1,73 @@ +.. _mozilla_projects_nss_reference_fc_generatekey: + +FC_GenerateKey +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GenerateKey - generate a new key + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GenerateKey( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG ulCount, + CK_OBJECT_HANDLE_PTR phKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] pointer to the mechanism to use. + ``pTemplate`` + [in] pointer to the template for the new key. + ``ulCount`` + [in] number of attributes in the template. + ``phKey`` + [out] pointer to the location to receive the handle of the new key. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GenerateKey`` generates a secret key, creating a new key object. The handle of new key is + returned. + + A user must log into the token (to assume the NSS User role) before calling ``FC_GenerateKey``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GenerateKey </en-US/NSC_GenerateKey>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_generatekeypair/index.rst b/security/nss/doc/rst/legacy/reference/fc_generatekeypair/index.rst new file mode 100644 index 0000000000..75e2e166f7 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_generatekeypair/index.rst @@ -0,0 +1,83 @@ +.. _mozilla_projects_nss_reference_fc_generatekeypair: + +FC_GenerateKeyPair +================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GenerateKeyPair - generate a new public/private key pair + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GenerateKeyPair( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_ATTRIBUTE_PTR pPublicKeyTemplate, + CK_ULONG usPublicKeyAttributeCount, + CK_ATTRIBUTE_PTR pPrivateKeyTemplate, + CK_ULONG usPrivateKeyAttributeCount, + CK_OBJECT_HANDLE_PTR phPublicKey, + CK_OBJECT_HANDLE_PTR phPrivateKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] pointer to the mechanism to use. + ``pPublicKeyTemplate`` + [in] pointer to the public key template. + ``usPublicKeyAttributeCount`` + [in] number of attributes in the public key template. + ``pPrivateKeyTemplate`` + [in] pointer to the private key template. + ``usPrivateKeyAttributeCount`` + [in] number of attributes in the private key template. + ``phPublicKey`` + [out] pointer to the location to receive the handle of the new public key. + ``phPrivateKey`` + [out] pointer to the location to receive the handle of the new private key. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GenerateKeyPair`` generates a public/private key pair, creating new key objects. The handles + of new keys are returned. + + A user must log into the token (to assume the NSS User role) before calling + ``FC_GenerateKeyPair``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GenerateKeyPair </en-US/NSC_GenerateKeyPair>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_generaterandom/index.rst b/security/nss/doc/rst/legacy/reference/fc_generaterandom/index.rst new file mode 100644 index 0000000000..156ad25dca --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_generaterandom/index.rst @@ -0,0 +1,67 @@ +.. _mozilla_projects_nss_reference_fc_generaterandom: + +FC_GenerateRandom +================= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GenerateRandom - generate a random number. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GenerateRandom( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pRandomData, + CK_ULONG ulRandomLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pRandomData`` + [out] pointer to the location to receive the random data. + ``ulRandomLen`` + [in] length of the buffer in bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GenerateRandom`` generates random data of the specified length. + + A user may call ``FC_GenerateRandom`` without logging into the token (to assume the NSS User + role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GenerateRandom </en-US/NSC_GenerateRandom>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getattributevalue/index.rst b/security/nss/doc/rst/legacy/reference/fc_getattributevalue/index.rst new file mode 100644 index 0000000000..79471b5b1a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getattributevalue/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_getattributevalue: + +FC_GetAttributeValue +==================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetAttributeValue - get the value of attributes of an object. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetAttributeValue( + CK_SESSION_HANDLE hSession, + CK_OBJECT_HANDLE hObject, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG usCount + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``hObject`` + [in] object handle. + ``pTemplate`` + [in, out] pointer to template. + ``usCount`` + [in] number of attributes in the template. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetAttributeValue`` gets the value of one or more attributes of an object. + + A user must log into the token (to assume the NSS User role) before getting the attribute values + of a secret or private key object. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetAttributeValue </en-US/NSC_GetAttributeValue>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getfunctionlist/index.rst b/security/nss/doc/rst/legacy/reference/fc_getfunctionlist/index.rst new file mode 100644 index 0000000000..d2b44ebc1f --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getfunctionlist/index.rst @@ -0,0 +1,79 @@ +.. _mozilla_projects_nss_reference_fc_getfunctionlist: + +FC_GetFunctionList +================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetFunctionList - get a pointer to the list of function pointers in the FIPS mode of + operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetFunctionList(CK_FUNCTION_LIST_PTR *ppFunctionList); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetFunctionList`` has one parameter: + + ``ppFunctionList`` + [Output] The address of a variable that will receive a pointer to the list of function + pointers. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetFunctionList`` stores in ``*ppFunctionList`` a pointer to the + :ref:`mozilla_projects_nss_reference_nss_cryptographic_module`'s list of function pointers in the + :ref:`mozilla_projects_nss_reference_nss_cryptographic_module_fips_mode_of_operation`. + + A user may call ``FC_GetFunctionList`` without logging into the token (to assume the NSS User + role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetFunctionList`` always returns ``CKR_OK``. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <assert.h> + + CK_FUNCTION_LIST_PTR pFunctionList; + CK_RV crv; + + crv = FC_GetFunctionList(&pFunctionList); + assert(crv == CKR_OK); + + /* invoke the FC_XXX function as pFunctionList->C_XXX */ + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetFunctionList </en-US/NSC_GetFunctionList>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getfunctionstatus/index.rst b/security/nss/doc/rst/legacy/reference/fc_getfunctionstatus/index.rst new file mode 100644 index 0000000000..468e398dd7 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getfunctionstatus/index.rst @@ -0,0 +1,60 @@ +.. _mozilla_projects_nss_reference_fc_getfunctionstatus: + +FC_GetFunctionStatus +==================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetFunctionStatus - get the status of a function running in parallel + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetFunctionStatus( + CK_SESSION_HANDLE hSession + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetFunctionStatus`` is a legacy function that simply returns ``CKR_FUNCTION_NOT_PARALLEL``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetFunctionStatus`` always returns ``CKR_FUNCTION_NOT_PARALLEL``. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetFunctionStatus </en-US/NSC_GetFunctionStatus>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getinfo/index.rst b/security/nss/doc/rst/legacy/reference/fc_getinfo/index.rst new file mode 100644 index 0000000000..1b73f25082 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getinfo/index.rst @@ -0,0 +1,110 @@ +.. _mozilla_projects_nss_reference_fc_getinfo: + +FC_GetInfo +========== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetInfo - return general information about the PKCS #11 library. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetInfo(CK_INFO_PTR pInfo); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetInfo`` has one parameter: + + ``pInfo`` + points to a `CK_INFO </en-US/CK_INFO>`__ structure + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetInfo`` returns general information about the PKCS #11 library. On return, the ``CK_INFO`` + structure that ``pInfo`` points to has the following information: + + - ``cryptokiVersion``: PKCS #11 interface version number implemented by the PKCS #11 library. + The version is 2.20 (``major=0x02, minor=0x14``). + - ``manufacturerID``: the PKCS #11 library manufacturer, "Mozilla Foundation", padded with + spaces to 32 characters and not null-terminated. + - ``flags``: should be 0. + - ``libraryDescription``: description of the library, "NSS Internal Crypto Services", padded + with spaces to 32 characters and not null-terminated. + - ``libraryVersion``: PKCS #11 library version number, for example, 3.11 + (``major=0x03, minor=0x0b``). + + A user may call ``FC_GetInfo`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetInfo`` always returns ``CKR_OK``. + + .. note:: + + ``FC_GetInfo`` should return ``CKR_ARGUMENTS_BAD`` if ``pInfo`` is ``NULL``. + + ``FC_GetInfo`` should return ``CKR_CRYPTOKI_NOT_INITIALIZED`` if the library is not + initialized. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Note the use of the ``%.32s`` format string to print the ``manufacturerID`` and + ``libraryDescription`` members of the ``CK_INFO`` structure. + + .. code:: + + #include <assert.h> + #include <stdio.h> + + CK_FUNCTION_LIST_PTR pFunctionList; + CK_RV crv; + CK_INFO info; + + crv = FC_GetFunctionList(&pFunctionList); + assert(crv == CKR_OK); + + ... + + /* invoke FC_GetInfo as pFunctionList->C_GetInfo */ + crv = pFunctionList->C_GetInfo(&info); + assert(crv == CKR_OK); + printf("General information about the PKCS #11 library:\n"); + printf(" PKCS #11 version: %d.%d\n", + (int)info.cryptokiVersion.major, (int)info.cryptokiVersion.minor); + printf(" manufacturer ID: %.32s\n", info.manufacturerID); + printf(" flags: 0x%08lx\n", info.flags); + printf(" library description: %.32s\n", info.libraryDescription); + printf(" library version: %d.%d\n", + (int)info.libraryVersion.major, (int)info.libraryVersion.minor); + printf("\n"); + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetInfo </en-US/NSC_GetInfo>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getmechanisminfo/index.rst b/security/nss/doc/rst/legacy/reference/fc_getmechanisminfo/index.rst new file mode 100644 index 0000000000..559179c309 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getmechanisminfo/index.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_reference_fc_getmechanisminfo: + +FC_GetMechanismInfo +=================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetMechanismInfo - get information on a particular mechanism. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetMechanismInfo( + CK_SLOT_ID slotID, + CK_MECHANISM_TYPE type, + CK_MECHANISM_INFO_PTR pInfo + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetMechanismInfo`` takes three parameters: + + ``slotID`` + [Input] + ``type`` + [Input] . + ``pInfo`` + [Output] . + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetMechanismInfo`` obtains information about a particular mechanism possibly supported by a + token. + + A user may call ``FC_GetMechanismInfo`` without logging into the token (to assume the NSS User + role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetMechanismInfo </en-US/NSC_GetMechanismInfo>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getmechanismlist/index.rst b/security/nss/doc/rst/legacy/reference/fc_getmechanismlist/index.rst new file mode 100644 index 0000000000..11003f9831 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getmechanismlist/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_getmechanismlist: + +FC_GetMechanismList +=================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetMechanismList - get a list of mechanism types supported by a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetMechanismList( + CK_SLOT_ID slotID, + CK_MECHANISM_TYPE_PTR pMechanismList, + CK_ULONG_PTR pusCount + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetMechanismList`` takes three parameters: + + ``slotID`` + [Input] + ``pInfo`` + [Output] The address of a variable that will receive a pointer to the list of function + pointers. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetMechanismList`` obtains a list of mechanism types supported by a token. + + A user may call ``FC_GetMechanismList`` without logging into the token (to assume the NSS User + role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetMechanismList </en-US/NSC_GetMechanismList>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getobjectsize/index.rst b/security/nss/doc/rst/legacy/reference/fc_getobjectsize/index.rst new file mode 100644 index 0000000000..c2bf40cc51 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getobjectsize/index.rst @@ -0,0 +1,67 @@ +.. _mozilla_projects_nss_reference_fc_getobjectsize: + +FC_GetObjectSize +================ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetObjectSize - create a copy of an object. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetObjectSize( + CK_SESSION_HANDLE hSession, + CK_OBJECT_HANDLE hObject, + CK_ULONG_PTR pusSize + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``hObject`` + [in] object handle. + ``pusSize`` + [out] pointer to location to receive the object's size. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetObjectSize`` gets the size of an object in bytes. + + A user must log into the token (to assume the NSS User role) before getting the size of a secret + or private key object. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetObjectSize </en-US/NSC_GetObjectSize>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getoperationstate/index.rst b/security/nss/doc/rst/legacy/reference/fc_getoperationstate/index.rst new file mode 100644 index 0000000000..1ec38bd7de --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getoperationstate/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_reference_fc_getoperationstate: + +FC_GetOperationState +==================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetOperationState - get the cryptographic operation state of a session. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetOperationState( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pOperationState, + CK_ULONG_PTR pulOperationStateLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] handle of the open session. + ``pOperationState`` + [out] pointer to a byte array of a length sufficient for containing the operation state or + NULL. + ``pulOperationStateLen`` + [out] pointer to `CK_ULONG </en-US/CK_ULONG>`__ which receives the total length (in bytes) of + the operation state. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetOperationState`` saves the state of the cryptographic operation in a session. This + function only works for digest operations for now. Therefore, a user may call + ``FC_GetOperationState`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_setoperationstate`, + `NSC_GetOperationState </en-US/NSC_GetOperationState>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getsessioninfo/index.rst b/security/nss/doc/rst/legacy/reference/fc_getsessioninfo/index.rst new file mode 100644 index 0000000000..358c06eba9 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getsessioninfo/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_reference_fc_getsessioninfo: + +FC_GetSessionInfo +================= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetSessionInfo - obtain information about a session. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetSessionInfo( + CK_SESSION_HANDLE hSession, + CK_SESSION_INFO_PTR pInfo + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] the open session handle. + ``pInfo`` + [out] pointer to the `CK_SESSION_INFO </en-US/CK_SESSION_INFO>`__ structure to be returned. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetSessionInfo`` obtains information about a session. A user may call ``FC_GetSessionInfo`` + without logging into the token (to assume the NSS User role). + + If the NSS cryptographic module is in the error state, ``FC_GetSessionInfo`` returns + ``CKR_DEVICE_ERROR``. Otherwise, it fills in the ``CK_SESSION_INFO`` structure with the following + information: + + - ``state``: the state of the session, i.e., no role is assumed, the User role is assumed, or + the Crypto Officer role is assumed + - ``flags``: bit flags that define the type of session + + - ``CKF_RW_SESSION (0x00000002)``: true if the session is read/write; false if the session is + read-only. + - ``CKF_SERIAL_SESSION (0x00000004)``: this flag is provided for backward compatibility and + is always set to true. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_closesession`, + `NSC_OpenSession </en-US/NSC_OpenSession>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getslotinfo/index.rst b/security/nss/doc/rst/legacy/reference/fc_getslotinfo/index.rst new file mode 100644 index 0000000000..09877920a4 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getslotinfo/index.rst @@ -0,0 +1,71 @@ +.. _mozilla_projects_nss_reference_fc_getslotinfo: + +FC_GetSlotInfo +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetSlotInfo - get information about a particular slot in the system. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetSlotInfo( + CK_SLOT_ID slotID, + CK_SLOT_INFO_PTR pInfo + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetSlotInfo`` takes two parameters: + + ``slotID`` + [in] + ``pInfo`` + [out] The address of a ``CK_SLOT_INFO`` structure. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetSlotInfo`` stores the information about the slot in the ``CK_SLOT_INFO`` structure that + ``pInfo`` points to. + + A user may call ``FC_GetSlotInfo`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` + Slot information was successfully copied. + ``CKR_SLOT_ID_INVALID`` + The specified slot number is out of the defined range of values. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetSlotInfo </en-US/NSC_GetSlotInfo>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_getslotlist/index.rst b/security/nss/doc/rst/legacy/reference/fc_getslotlist/index.rst new file mode 100644 index 0000000000..a655ae24a6 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_getslotlist/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_reference_fc_getslotlist: + +FC_GetSlotList +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetSlotList - Obtain a list of slots in the system. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetSlotList( + CK_BBOOL tokenPresent, + CK_SLOT_ID_PTR pSlotList, + CK_ULONG_PTR pulCount + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``tokenPresent`` + [in] If true only slots with a token present are included in the list, otherwise all slots are + included. + ``pSlotList`` + [out] Either null or a pointer to an existing array of ``CK_SLOT_ID`` objects. + ``pulCount`` + [out] Pointer to a ``CK_ULONG`` variable which receives the slot count.; + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetSlotList`` obtains a list of slots in the system. + + A user may call ``FC_GetSlotList`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_GetSlotList </en-US/NSC_GetSlotList>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_gettokeninfo/index.rst b/security/nss/doc/rst/legacy/reference/fc_gettokeninfo/index.rst new file mode 100644 index 0000000000..7b5a5b8db7 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_gettokeninfo/index.rst @@ -0,0 +1,106 @@ +.. _mozilla_projects_nss_reference_fc_gettokeninfo: + +FC_GetTokenInfo +=============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_GetTokenInfo - obtain information about a particular token in the system. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_GetTokenInfo(CK_SLOT_ID slotID, CK_TOKEN_INFO_PTR pInfo); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetTokenInfo`` has two parameters: + + ``slotID`` + the ID of the token's slot + ``pInfo`` + points to a `CK_TOKEN_INFO </en-US/CK_TOKEN_INFO>`__ structure + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_GetTokenInfo`` returns information about the token in the specified slot. On return, the + ``CK_TOKEN_INFO`` structure that ``pInfo`` points to has the following information: + + - ``label``: the label of the token, assigned during token initialization, padded with spaces to + 32 bytes and not null-terminated. + - ``manufacturerID``: ID of the device manufacturer, "Mozilla Foundation", padded with spaces to + 32 characters and not null-terminated. + - ``model``: model of the device, "NSS 3", padded with spaces to 16 characters and not + null-terminated. + - ``serialNumber``: the device's serial number as a string, "0000000000000000", 16 characters + and not null-terminated. + - ``flags``: bit flags indicating capabilities and status of the device. + + - ``CKF_RNG (0x00000001)``: this device has a random number generator + - ``CKF_WRITE_PROTECTED (0x00000002)``: this device is read-only + - ``CKF_LOGIN_REQUIRED (0x00000004)``: this device requires the user to log in to use some of + its services + - ``CKF_USER_PIN_INITIALIZED (0x00000008)``: the user's password has been initialized + - ``CKF_DUAL_CRYPTO_OPERATIONS (0x00000200)``: a single session with the token can perform + dual cryptographic operations + - ``CKF_TOKEN_INITIALIZED (0x00000400)``: the token has been initialized. If login is + required (which is true for the FIPS mode of operation), this flag means the user's + password has been initialized. + + - ``ulSessionCount``: number of sessions that this application currently has open with the token + - ``ulRwSessionCount``: number of read/write sessions that this application currently has open + with the token + - ``hardwareVersion``: hardware version number, for example, 8.3 (``major=0x08, minor=0x03``), + which are the version numbers of the certificate and key databases, respectively. + - ``firmwareVersion``: firmware version number, 0.0 (``major=0x00, minor=0x00``). + + A user may call ``FC_GetTokenInfo`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` + Token information was successfully copied. + ``CKR_CRYPTOKI_NOT_INITIALIZED`` + The PKCS #11 module library is not initialized. + ``CKR_SLOT_ID_INVALID`` + The specified slot number is out of the defined range of values. + + .. note:: + + FC_GetTokenInfo should return CKR_ARGUMENTS_BAD if pInfo is NULL. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Note the use of the ``%.32s`` format string to print the ``label`` and ``manufacturerID`` members + of the ``CK_TOKEN_INFO`` structure. + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_getslotinfo`, + `NSC_GetTokenInfo </en-US/NSC_GetTokenInfo>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_initialize/index.rst b/security/nss/doc/rst/legacy/reference/fc_initialize/index.rst new file mode 100644 index 0000000000..5cc8d2f3f8 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_initialize/index.rst @@ -0,0 +1,131 @@ +.. _mozilla_projects_nss_reference_fc_initialize: + +FC_Initialize +============= + +.. _name: + +`Summary <#name>`__ +------------------- + +.. container:: + + FC_Initialize - initialize the PKCS #11 library. + +`Syntax <#syntax>`__ +-------------------- + +.. container:: + + .. code:: + + CK_RV FC_Initialize(CK_VOID_PTR pInitArgs); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``pInitArgs`` + Points to a ``CK_C_INITIALIZE_ARGS`` structure. + +`Description <#description>`__ +------------------------------ + +.. container:: + + ``FC_Initialize`` initializes the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module` + for the :ref:`mozilla_projects_nss_reference_nss_cryptographic_module_fips_mode_of_operation`. In + addition to creating the internal data structures, it performs the FIPS software integrity test + and power-up self-tests. + + The ``pInitArgs`` argument must point to a ``CK_C_INITIALIZE_ARGS`` structure whose members + should have the following values: + + - ``CreateMutex`` should be ``NULL``. + - ``DestroyMutex`` should be ``NULL``. + - ``LockMutex`` should be ``NULL``. + - ``UnlockMutex`` should be ``NULL``. + - ``flags`` should be ``CKF_OS_LOCKING_OK``. + - ``LibraryParameters`` should point to a string that contains the library parameters. + - ``pReserved`` should be ``NULL``. + + The library parameters string has this format: + + .. code:: + + "configdir='dir' certPrefix='prefix1' keyPrefix='prefix2' secmod='file' flags= " + + Here are some examples. + + ``NSS_NoDB_Init("")``, which initializes NSS with no databases: + + .. code:: + + "configdir='' certPrefix='' keyPrefix='' secmod='' flags=readOnly,noCertDB,noMod + DB,forceOpen,optimizeSpace " + + Mozilla Firefox initializes NSS with this string (on Windows): + + .. code:: + + "configdir='C:\\Documents and Settings\\wtc\\Application Data\\Mozilla\\Firefox\\Profiles\\default.7tt' certPrefix='' keyPrefix='' secmod='secmod.db' flags=optimizeSpace manufacturerID='Mozilla.org' libraryDescription='PSM Internal Crypto Services' cryptoTokenDescription='Generic Crypto Services' dbTokenDescription='Software Security Device' cryptoSlotDescription='PSM Internal Cryptographic Services' dbSlotDescription='PSM Private Keys' FIPSSlotDescription='PSM Internal FIPS-140-1 Cryptographic Services' FIPSTokenDescription='PSM FIPS-140-1 User Private Key Services' minPS=0" + + See :ref:`mozilla_projects_nss_pkcs11_module_specs` for complete documentation of the library + parameters string. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Initialize`` returns the following return codes. + + - ``CKR_OK``: library initialization succeeded. + - ``CKR_ARGUMENTS_BAD`` + + - ``pInitArgs`` is ``NULL``. + - ``pInitArgs->LibraryParameters`` is ``NULL``. + - only some of the lock functions were provided by the application. + + - ``CKR_CANT_LOCK``: the ``CKF_OS_LOCKING_OK`` flag is not set in ``pInitArgs->flags``. The NSS + cryptographic module always uses OS locking and doesn't know how to use the lock functions + provided by the application. + - ``CKR_CRYPTOKI_ALREADY_INITIALIZED``: the library is already initialized. + - ``CKR_DEVICE_ERROR`` + + - We failed to create the OID tables, random number generator, or internal locks. (Note: we + probably should return ``CKR_HOST_MEMORY`` instead.) + - The software integrity test or power-up self-tests failed. The NSS cryptographic module is + in a fatal error state. + + - ``CKR_HOST_MEMORY``: we ran out of memory. + +`Examples <#examples>`__ +------------------------ + +.. container:: + + .. code:: + + #include <assert.h> + + CK_FUNCTION_LIST_PTR pFunctionList; + CK_RV crv; + CK_C_INITIALIZE_ARGS initArgs; + + crv = FC_GetFunctionList(&pFunctionList); + assert(crv == CKR_OK); + + initArgs.CreateMutex = NULL; + initArgs.DestroyMutex = NULL; + initArgs.LockMutex = NULL; + initArgs.UnlockMutex = NULL; + initArgs.flags = CKF_OS_LOCKING_OK; + initArgs.LibraryParameters = "..."; + initArgs.pReserved = NULL; + + /* invoke FC_Initialize as pFunctionList->C_Initialize */ + crv = pFunctionList->C_Initialize(&initArgs); diff --git a/security/nss/doc/rst/legacy/reference/fc_initpin/index.rst b/security/nss/doc/rst/legacy/reference/fc_initpin/index.rst new file mode 100644 index 0000000000..fc083b9e0a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_initpin/index.rst @@ -0,0 +1,78 @@ +.. _mozilla_projects_nss_reference_fc_initpin: + +FC_InitPIN +========== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitPIN()`` - Initialize the user's PIN. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_InitPIN( + CK_SESSION_HANDLE hSession, + CK_CHAR_PTR pPin, + CK_ULONG ulPinLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitPIN()`` takes three parameters: + + ``hSession`` + [Input] Session handle. + ``pPin`` + [Input] Pointer to the PIN being set. + ``ulPinLen`` + [Input] Length of the PIN. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitPIN()`` initializes the normal user's PIN. + + ``FC_InitPIN()`` must be called when the PKCS #11 Security Officer (SO) is logged into the token + and the session is read/write, that is, the session must be in the "R/W SO Functions" state + (``CKS_RW_SO_FUNCTIONS``). The role of the PKCS #11 SO is to initialize a token and to initialize + the normal user's PIN. In the NSS cryptographic module, one uses the empty string password ("") + to log in as the PKCS #11 SO. The module only allows the PKCS #11 SO to log in if the normal + user's PIN has not yet been set or has been reset. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitPIN()`` returns the following return codes. + + - ``CKR_OK``: normal user's PIN initialization succeeded. + - ``CKR_SESSION_HANDLE_INVALID``: the session handle is invalid. + - ``CKR_USER_NOT_LOGGED_IN``: the session is not in the "R/W SO Functions" state. + - ``CKR_PIN_INVALID``: the PIN has an invalid UTF-8 character. + - ``CKR_PIN_LEN_RANGE``: the PIN is too short, too long, or too weak (doesn't have enough + character types). + - ``CKR_DEVICE_ERROR``: normal user's PIN is already initialized. + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_InitPIN </en-US/NSC_InitPIN>`__, :ref:`mozilla_projects_nss_reference_fc_setpin`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_inittoken/index.rst b/security/nss/doc/rst/legacy/reference/fc_inittoken/index.rst new file mode 100644 index 0000000000..900e91c5e3 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_inittoken/index.rst @@ -0,0 +1,110 @@ +.. _mozilla_projects_nss_reference_fc_inittoken: + +FC_InitToken +============ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitToken()`` - initialize or re-initialize a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_InitToken( + CK_SLOT_ID slotID, + CK_CHAR_PTR pPin, + CK_ULONG ulPinLen, + CK_CHAR_PTR pLabel + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitToken()`` has the following parameters: + + ``slotID`` + the ID of the token's slot + ``pPin`` + the password of the security officer (SO) + ``ulPinLen`` + the length in bytes of the SO password + ``pLabel`` + points to the label of the token, which must be padded with spaces to 32 bytes and not be + null-terminated + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitToken()`` initializes a brand new token or re-initializes a token that was initialized + before. + + Specifically, ``FC_InitToken()`` initializes or clears the key database, removes the password, + and then marks all the *user certs* in the certificate database as *non-user certs*. (User certs + are the certificates that have their associated private keys in the key database.) + + A user must be able to call ``FC_InitToken()`` without logging into the token (to assume the NSS + User role) because either the user's password hasn't been set yet or the user forgets the + password and needs to blow away the password-encrypted private key database and start over. + + .. note:: + + **Note:** The SO password should be the empty string, i.e., ``ulPinLen`` argument should be 0. + ``FC_InitToken()`` ignores the ``pLabel`` argument. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitToken()`` returns the following return codes. + + - ``CKR_OK``: token initialization succeeded. + - ``CKR_SLOT_ID_INVALID``: slot ID is invalid. + - ``CKR_TOKEN_WRITE_PROTECTED`` + + - we don't have a reference to the key database (we failed to open the key database or we + have released our reference). + + - ``CKR_DEVICE_ERROR``: failed to reset the key database. + +.. _application_usage: + +`Application usage <#application_usage>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_InitToken()`` is used to reset the password for the key database when the user forgets the + password. + + - The "Reset Password" button of the Mozilla Application Suite and SeaMonkey (in + Preferences->Privacy & Security->Master Passwords) calls ``FC_InitToken()``. + - The "-T" (token reset) command of ``certutil`` calls ``FC_InitToken()``. + + .. note:: + + **Note:** Resetting the password clears all permanent secret and private keys. You won't be + able to decrypt the data, such as Mozilla's stored passwords, that were encrypted using any of + those keys. + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_initpin`, `NSC_InitToken </en-US/NSC_InitToken>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_login/index.rst b/security/nss/doc/rst/legacy/reference/fc_login/index.rst new file mode 100644 index 0000000000..2a429ab6ba --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_login/index.rst @@ -0,0 +1,88 @@ +.. _mozilla_projects_nss_reference_fc_login: + +FC_Login +======== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Login()`` - log a user into a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Login( + CK_SESSION_HANDLE hSession, + CK_USER_TYPE userType, + CK_CHAR_PTR pPin, + CK_ULONG ulPinLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Login()`` takes four parameters: + + ``hSession`` + [in] a session handle + ``userType`` + [in] the user type (``CKU_SO`` or ``CKU_USER``) + ``pPin`` + [in] a pointer that points to the user's PIN + ``ulPinLen`` + [in] the length of the PIN + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Login()`` logs a user into a token. + + The Security Officer (``CKU_SO``) only logs in to initialize the normal user's PIN. The SO PIN is + the empty string. The NSS cryptographic module doesn't allow the SO to log in if the normal + user's PIN is already initialized. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Login()`` returns the following return codes. + + - ``CKR_OK``: the user logged in successfully. + - ``CKR_DEVICE_ERROR``: the token is in the Error state. + - ``CKR_HOST_MEMORY``: memory allocation failed. + - ``CKR_PIN_INCORRECT``: the PIN is incorrect. + - ``CKR_PIN_LEN_RANGE``: the PIN is too long (``ulPinLen`` is greater than 255). + + .. note:: + + The function should return ``CKR_PIN_INCORRECT`` in this case. + + - ``CKR_SESSION_HANDLE_INVALID``: the session handle is invalid. + - ``CKR_USER_ALREADY_LOGGED_IN``: the user is already logged in. + - ``CKR_USER_TYPE_INVALID`` + + - The token can't authenticate the user because there is no key database or the user's + password isn't initialized. + - ``userType`` is ``CKU_SO`` and the normal user's PIN is already initialized. + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_Login </en-US/NSC_Login>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_logout/index.rst b/security/nss/doc/rst/legacy/reference/fc_logout/index.rst new file mode 100644 index 0000000000..2eaa2d065c --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_logout/index.rst @@ -0,0 +1,58 @@ +.. _mozilla_projects_nss_reference_fc_logout: + +FC_Logout +========= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_Logout - log a user out from a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Logout( + CK_SESSION_HANDLE hSession + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Logs the current user out of a USER_FUNCTIONS session. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_closesession`, `NSC_Logout </en-US/NSC_Logout>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_opensession/index.rst b/security/nss/doc/rst/legacy/reference/fc_opensession/index.rst new file mode 100644 index 0000000000..23c6927ed8 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_opensession/index.rst @@ -0,0 +1,78 @@ +.. _mozilla_projects_nss_reference_fc_opensession: + +FC_OpenSession +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_OpenSession - open a session between an application and a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_OpenSession( + CK_SLOT_ID slotID, + CK_FLAGS flags, + CK_VOID_PTR pApplication, + CK_NOTIFY Notify, + CK_SESSION_HANDLE_PTR phSession + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_OpenSession`` has the following parameters: + + ``slotID`` + [in] the ID of the token's slot. + ``flags`` + [in] + ``pApplication`` + ``Notify`` + [in] pointer to a notification callback function. Not currently supported. + ``phSession`` + [out] pointer to a session handle. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_OpenSession`` opens a session between an application and the token in the slot with the ID + ``slotID``. + + The NSS cryptographic module currently doesn't call the surrender callback function ``Notify``. + (See PKCS #11 v2.20 section 11.17.1.) + + A user may call ``FC_OpenSession`` without logging into the token (to assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_closesession`, + `NSC_OpenSession </en-US/NSC_OpenSession>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_seedrandom/index.rst b/security/nss/doc/rst/legacy/reference/fc_seedrandom/index.rst new file mode 100644 index 0000000000..175dd8d2b7 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_seedrandom/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_seedrandom: + +FC_SeedRandom +============= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SeedRandom()`` - mix additional seed material into the random number generator. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SeedRandom( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pSeed, + CK_ULONG usSeedLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pSeed`` + [in] pointer to the seed material + ``usSeedLen`` + [in] length of the seed material in bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SeedRandom()`` mixes additional seed material into the token's random number generator. Note + that ``FC_SeedRandom()`` doesn't provide the initial seed material for the random number + generator. The initial seed material is provided by the NSS cryptographic module itself. + + | + | A user may call ``FC_SeedRandom()`` without logging into the token (to assume the NSS User + role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_SeedRandom </en-US/NSC_SeedRandom>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_setattributevalue/index.rst b/security/nss/doc/rst/legacy/reference/fc_setattributevalue/index.rst new file mode 100644 index 0000000000..38da0d539a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_setattributevalue/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_setattributevalue: + +FC_SetAttributeValue +==================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SetAttributeValue - set the values of attributes of an object. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SetAttributeValue( + CK_SESSION_HANDLE hSession, + CK_OBJECT_HANDLE hObject, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG usCount + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``hObject`` + [in] object handle. + ``pTemplate`` + [in, out] pointer to template. + ``usCount`` + [in] number of attributes in the template. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SetAttributeValue`` sets the value of one or more attributes of an object. + + A user must log into the token before setting the attribute values of a secret or private key + object. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_SetAttributeValue </en-US/NSC_SetAttributeValue>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_setoperationstate/index.rst b/security/nss/doc/rst/legacy/reference/fc_setoperationstate/index.rst new file mode 100644 index 0000000000..c45b254892 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_setoperationstate/index.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_reference_fc_setoperationstate: + +FC_SetOperationState +==================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SetOperationState - restore the cryptographic operation state of a session. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SetOperationState( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pOperationState, + CK_ULONG ulOperationStateLen, + CK_OBJECT_HANDLE hEncryptionKey, + CK_OBJECT_HANDLE hAuthenticationKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] handle of the open session. + ``pOperationState`` + [in] pointer to a byte array containing the operation state. + ``ulOperationStateLen`` + [in] contains the total length (in bytes) of the operation state. + ``hEncryptionKey`` + [in] handle of the encryption or decryption key to be used in a stored session or zero if no + key is needed. + ``hAuthenticationKey`` + [in] handle of the authentication key to be used in the stored session or zero if none is + needed. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SetOperationState`` restores the cryptographic operations state of a session from an array + of bytes obtained with ``FC_GetOperationState``. This function only works for digest operations + for now. Therefore, a user may call ``FC_SetOperationState`` without logging into the token (to + assume the NSS User role). + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_getoperationstate`, + `NSC_SetOperationState </en-US/NSC_SetOperationState>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_setpin/index.rst b/security/nss/doc/rst/legacy/reference/fc_setpin/index.rst new file mode 100644 index 0000000000..83ef6f17db --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_setpin/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_reference_fc_setpin: + +FC_SetPIN +========= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SetPIN - Modify the user's PIN. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SetPIN( + CK_SESSION_HANDLE hSession, + CK_CHAR_PTR pOldPin, + CK_ULONG ulOldLen, + CK_CHAR_PTR pNewPin, + CK_ULONG ulNewLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SetPIN`` takes five parameters: + + ``hSession`` + [Input] the session's handle + ``pOldPin`` + [Input] points to the old PIN. + ``ulOldLen`` + [Input] the length in bytes of the old PIN. + ``pNewPin`` + [Input] points to the new PIN. + ``ulNewLen`` + [Input] the length in bytes of the new PIN. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SetPIN`` modifies the PIN of the user. The user must log into the token (to assume the NSS + User role) before calling ``FC_SetPIN``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_SetPIN </en-US/NSC_SetPIN>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_sign/index.rst b/security/nss/doc/rst/legacy/reference/fc_sign/index.rst new file mode 100644 index 0000000000..f1bc786587 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_sign/index.rst @@ -0,0 +1,74 @@ +.. _mozilla_projects_nss_reference_fc_sign: + +FC_Sign +======= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_Sign - sign a block of data. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Sign( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pData, + CK_ULONG usDataLen, + CK_BYTE_PTR pSignature, + CK_ULONG_PTR pusSignatureLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pData`` + [in] pointer to data block. + ``usDataLen`` + [in] length of the data in bytes. + ``pSignature`` + [out] pointer to location where recovered data is to be stored. + ``pusSignatureLen`` + [in, out] pointer to the maximum size of the output buffer, replaced by the length of the + signature if the operation is successful. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Sign`` signs a message in a single operation according to the attributes of the previous + call to ``FC_SignInit``. + + A user must log into the token (to assume the NSS User role) before calling ``FC_Sign``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_signinit`, `NSC_Sign </en-US/NSC_Sign>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_signencryptupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_signencryptupdate/index.rst new file mode 100644 index 0000000000..5064bbfe3f --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_signencryptupdate/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_reference_fc_signencryptupdate: + +FC_SignEncryptUpdate +==================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SignEncryptUpdate - continue a multi-part signing and encryption operation + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SignEncryptUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pPart, + CK_ULONG ulPartLen, + CK_BYTE_PTR pEncryptedPart, + CK_ULONG_PTR pulEncryptedPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pPart`` + [in] pointer to the data part. + ``ulPartLen`` + [in] length of data in bytes. + ``pEncryptedPart`` + [in] pointer to the location which receives the signed and encrypted data part or NULL. + ``pulEncryptedPartLen`` + [in] pointer to the length of the encrypted part buffer. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SignEncryptUpdate`` continues a multi-part signature and encryption operation. After calling + both ``FC_SignInit`` and ``FC_EncryptInit`` to set up the operations this function may be called + multiple times. The operation is finished by calls to ``FC_SignFinal`` and ``FC_EncryptFinal``. + + A user must log into the token (to assume the NSS User role) before calling + ``FC_SignEncryptUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_SignEncryptUpdate </en-US/NSC_SignEncryptUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_signfinal/index.rst b/security/nss/doc/rst/legacy/reference/fc_signfinal/index.rst new file mode 100644 index 0000000000..295ec3b47f --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_signfinal/index.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_reference_fc_signfinal: + +FC_SignFinal +============ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SignFinal - finish a multi-part signing operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SignFinal( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pSignature, + CK_ULONG_PTR pusSignatureLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pSignature`` + [out] pointer to the buffer which will receive the digest or NULL. + ``pusSignatureLen`` + [in, out] pointer to location containing the maximum buffer size. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SignFinal`` finishes a multi-part signing operation by returning the complete signature and + clearing the operation context. If ``pSignature`` is NULL the length of the signature is returned + and ``FC_SignFinal`` may be called again with ``pSignature`` set to retrieve the signature. + + A user must log into the token (to assume the NSS User role) before calling ``FC_SignFinal``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_signupdate`, `NSC_SignFinal </en-US/NSC_SignFinal>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_signinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_signinit/index.rst new file mode 100644 index 0000000000..0c6fc6ab67 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_signinit/index.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_reference_fc_signinit: + +FC_SignInit +=========== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SignInit - initialize a signing operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SignInit( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] mechanism to be used for the subsequent signing operation. + ``hKey`` + [in] handle of the key to be used . + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SignInit`` initializes a signature operation. + + A user must log into the token (to assume the NSS User role) before calling ``FC_SignInit``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_SignInit </en-US/NSC_SignInit>`__ :ref:`mozilla_projects_nss_reference_fc_sign` + :ref:`mozilla_projects_nss_reference_fc_signupdate` + :ref:`mozilla_projects_nss_reference_fc_signfinal`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_signrecover/index.rst b/security/nss/doc/rst/legacy/reference/fc_signrecover/index.rst new file mode 100644 index 0000000000..b20e4cd9cb --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_signrecover/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_reference_fc_signrecover: + +FC_SignRecover +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SignRecover - Sign data in a single recoverable operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SignRecover( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pData, + CK_ULONG usDataLen, + CK_BYTE_PTR pSignature, + CK_ULONG_PTR pusSignatureLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pData`` + [in] mechanism to be used for the signing operation. + ``usDataLen`` + [in] handle of the key to be usedn. + ``pSignature`` + [out] pointer to the buffer or NULL. + ``pusSignatureLen`` + [in, out] pointer to the size of the output buffer, replaced by the length of the signature if + the operation is successful. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SignRecover`` signs data in a single operation where the (digest) data can be recovered from + the signature. If ``pSignature`` is NULL only the length of the signature is returned in + ``*pusSignatureLen``. + + A user must log into the token (to assume the NSS User role) before calling ``FC_SignRecover``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_SignRecover </en-US/NSC_SignRecover>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_signrecoverinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_signrecoverinit/index.rst new file mode 100644 index 0000000000..8fd7a9027a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_signrecoverinit/index.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_reference_fc_signrecoverinit: + +FC_SignRecoverInit +================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SignRecoverInit - initialize a sign recover operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SignRecoverInit( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] mechanism to be used for the signing operation. + ``hKey`` + [in] handle of the key to be used. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SignRecoverInit`` initializes a initializes a signature operation where the (digest) data + can be recovered from the signature. + + A user must log into the token (to assume the NSS User role) before calling + ``FC_SignRecoverInit``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_SignRecoverInit </en-US/NSC_SignRecoverInit>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_signupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_signupdate/index.rst new file mode 100644 index 0000000000..08eedda2c6 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_signupdate/index.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_reference_fc_signupdate: + +FC_SignUpdate +============= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_SignUpdate - process the next block of a multi-part signing operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_SignUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pPart, + CK_ULONG usPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pPart`` + [in] pointer to the next block of the data to be signed. + ``usPartLen`` + [in] length of data block in bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_SignUpdate`` starts or continues a multi-part signature operation. One or more blocks may be + part of the signature. The signature for the entire message is returned by a call to + :ref:`mozilla_projects_nss_reference_fc_signfinal`. + + A user must log into the token (to assume the NSS User role) before calling ``FC_SignUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_signinit`, + :ref:`mozilla_projects_nss_reference_fc_signfinal`, `NSC_SignUpdate </en-US/NSC_SignUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_unwrapkey/index.rst b/security/nss/doc/rst/legacy/reference/fc_unwrapkey/index.rst new file mode 100644 index 0000000000..afec622775 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_unwrapkey/index.rst @@ -0,0 +1,83 @@ +.. _mozilla_projects_nss_reference_fc_unwrapkey: + +FC_UnwrapKey +============ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_UnwrapKey - unwrap a key + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_UnwrapKey( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hUnwrappingKey, + CK_BYTE_PTR pWrappedKey, + CK_ULONG usWrappedKeyLen, + CK_ATTRIBUTE_PTR pTemplate, + CK_ULONG usAttributeCount, + CK_OBJECT_HANDLE_PTR phKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] pointer to the mechanism to use. + ``hUnwrappingKey`` + [in] handle of the ket to use for unwrapping. + ``pWrappedKey`` + [in] pointer to the wrapped key. + ``usWrappedKeyLen`` + [in] length of the wrapped key. + ``pTemplate`` + [in] pointer to the list of attributes for the unwrapped key. + ``usAttributeCount`` + [in] number of attributes in the template. + ``phKey`` + [out] pointer to the location to receive the handle of the unwrapped key. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_UnwrapKey`` unwraps (decrypts) a key and creates a new key opbject. If ``pWrappedKey`` is + NULL the length of the wrapped key is returned in ``pusWrappedKeyLen`` and FC_UnwrapKey may be + called again with ``pWrappedKey`` set to retrieve the wrapped key. + + A user must log into the token (to assume the NSS User role) before calling ``FC_UnwrapKey``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_UnwrapKey </en-US/NSC_UnwrapKey>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_verify/index.rst b/security/nss/doc/rst/legacy/reference/fc_verify/index.rst new file mode 100644 index 0000000000..23ee0c7615 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_verify/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_reference_fc_verify: + +FC_Verify +========= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_Verify - sign a block of data. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_Verify( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pData, + CK_ULONG usDataLen, + CK_BYTE_PTR pSignature, + CK_ULONG usSignatureLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pData`` + [in] pointer to data block. + ``usDataLen`` + [in] length of the data in bytes. + ``pSignature`` + [in] pointer to the signature. + ``usSignatureLen`` + [in] length of the signature in bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_Verify`` verifies a signature in a single-part operation, where the signature is an appendix + to the data. + + A user must log into the token (to assume the NSS User role) before calling ``FC_Verify``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``CKR_OK`` is returned on success. ``CKR_SIGNATURE_INVALID`` is returned for signature mismatch. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_verifyinit`, `NSC_Verify </en-US/NSC_Verify>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_verifyfinal/index.rst b/security/nss/doc/rst/legacy/reference/fc_verifyfinal/index.rst new file mode 100644 index 0000000000..0dcf1804ad --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_verifyfinal/index.rst @@ -0,0 +1,67 @@ +.. _mozilla_projects_nss_reference_fc_verifyfinal: + +FC_VerifyFinal +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_VerifyFinal - finish a multi-part verify operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_VerifyFinal( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pSignature, + CK_ULONG usSignatureLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pSignature`` + [in] pointer to the buffer which will receive the digest or NULL. + ``usSignatureLen`` + [in] length of the signature in bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_VerifyFinal`` finishes a multi-part signature verification operation. + + A user must log into the token (to assume the NSS User role) before calling ``FC_VerifyFinal``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_verifyupdate`, + `NSC_VerifyFinal </en-US/NSC_VerifyFinal>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_verifyinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_verifyinit/index.rst new file mode 100644 index 0000000000..706d5a1ed9 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_verifyinit/index.rst @@ -0,0 +1,67 @@ +.. _mozilla_projects_nss_reference_fc_verifyinit: + +FC_VerifyInit +============= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_VerifyInit - initialize a verification operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_VerifyInit( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] mechanism to be used for the verification operation. + ``hKey`` + [in] handle of the key to be used. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_VerifyInit`` initializes a verification operation where the signature is an appendix to the + data. + + A user must log into the token (to assume the NSS User role) before calling ``FC_VerifyInit``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_VerifyInit </en-US/NSC_VerifyInit>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_verifyrecover/index.rst b/security/nss/doc/rst/legacy/reference/fc_verifyrecover/index.rst new file mode 100644 index 0000000000..4615eac8af --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_verifyrecover/index.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_reference_fc_verifyrecover: + +FC_VerifyRecover +================ + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_VerifyRecover - Verify data in a single recoverable operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_VerifyRecover( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pSignature, + CK_ULONG usSignatureLen, + CK_BYTE_PTR pData, + CK_ULONG_PTR pusDataLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pSignature`` + [in] mechanism to be used for the signing operation. + ``usSignatureLen`` + [in] handle of the key to be usedn. + ``pData`` + [out] pointer to the buffer or NULL. + ``pusDataLen`` + [in, out] pointer to the size of the output buffer, replaced by the length of the signature if + the operation is successful. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_VerifyRecover`` verifies data in a single operation where the (digest) data can be recovered + from the signature. If ``pSignature`` is NULL only the length of the signature is returned in + ``*pusSignatureLen``. + + A user must log into the token (to assume the NSS User role) before calling ``FC_VerifyRecover``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_VerifyRecover </en-US/NSC_VerifyRecover>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_verifyrecoverinit/index.rst b/security/nss/doc/rst/legacy/reference/fc_verifyrecoverinit/index.rst new file mode 100644 index 0000000000..aa17391253 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_verifyrecoverinit/index.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_reference_fc_verifyrecoverinit: + +FC_VerifyRecoverInit +==================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_VerifyRecoverInit - initialize a verification operation where data is recoverable. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_VerifyRecoverInit( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hKey + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] mechanism to be used for verification. + ``hKey`` + [in] handle of the key to be used. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_VerifyRecoverInit`` initializes a signature verification operation where the (digest) data + can be recovered from the signature. + + A user must log into the token (to assume the NSS User role) before calling + ``FC_VerifyRecoverInit``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_VerifyRecoverInit </en-US/NSC_VerifyRecoverInit>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_verifyupdate/index.rst b/security/nss/doc/rst/legacy/reference/fc_verifyupdate/index.rst new file mode 100644 index 0000000000..5cac472cb1 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_verifyupdate/index.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_reference_fc_verifyupdate: + +FC_VerifyUpdate +=============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_VerifyUpdate - process the next block of a multi-part verify operation. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_VerifyUpdate( + CK_SESSION_HANDLE hSession, + CK_BYTE_PTR pPart, + CK_ULONG usPartLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pPart`` + [in] pointer to the next block of the data to be verified. + ``usPartLen`` + [in] length of data block in bytes. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_VerifyUpdate`` starts or continues a multi-part signature verification operation where the + signature is an appendix to the data. One or more blocks may be part of the signature. The result + for the entire message is returned by a call to + :ref:`mozilla_projects_nss_reference_fc_verifyfinal`. + + A user must log into the token (to assume the NSS User role) before calling ``FC_VerifyUpdate``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_verifyfinal`, + `NSC_VerifyUpdate </en-US/NSC_VerifyUpdate>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_waitforslotevent/index.rst b/security/nss/doc/rst/legacy/reference/fc_waitforslotevent/index.rst new file mode 100644 index 0000000000..08faff6974 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_waitforslotevent/index.rst @@ -0,0 +1,61 @@ +.. _mozilla_projects_nss_reference_fc_waitforslotevent: + +FC_WaitForSlotEvent +=================== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_WaitForSlotEvent - waits for a slot event, such as token insertion or token removal, to occur. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_WaitForSlotEvent(CK_FLAGS flags, CK_SLOT_ID_PTR pSlot CK_VOID_PTR pReserved); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_WaitForSlotEvent`` takes three parameters: + + ``flags`` + ``pSlot``. + ``pReserved``. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This function is not supported by the NSS cryptographic module. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_WaitForSlotEvent`` always returns ``CKR_FUNCTION_NOT_SUPPORTED``. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_waitforslotevent`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/fc_wrapkey/index.rst b/security/nss/doc/rst/legacy/reference/fc_wrapkey/index.rst new file mode 100644 index 0000000000..6837c6f5ef --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/fc_wrapkey/index.rst @@ -0,0 +1,77 @@ +.. _mozilla_projects_nss_reference_fc_wrapkey: + +FC_WrapKey +========== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + FC_WrapKey - wrap a key + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV FC_WrapKey( + CK_SESSION_HANDLE hSession, + CK_MECHANISM_PTR pMechanism, + CK_OBJECT_HANDLE hWrappingKey, + CK_OBJECT_HANDLE hKey, + CK_BYTE_PTR pWrappedKey, + CK_ULONG_PTR pusWrappedKeyLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``hSession`` + [in] session handle. + ``pMechanism`` + [in] pointer to the mechanism to use. + ``hWrappingKey`` + [in] pointer to the public key template. + ``hKey`` + [in] number of attributes in the public key template. + ``pWrappedKey`` + [out] pointer to the location to receive the wrapped key or NULL. + ``pusWrappedKeyLen`` + [in, out] pointer to length of wrapped key buffer. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``FC_WrapKey`` wraps (encrypts) a key. If ``pWrappedKey`` is NULL the length of the wrapped key + is returned in ``pusWrappedKeyLen`` and FC_WrapKey may be called again with ``pWrappedKey`` set + to retrieve the wrapped key. + + A user must log into the token (to assume the NSS User role) before calling ``FC_WrapKey``. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_WrapKey </en-US/NSC_WrapKey>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/index.rst b/security/nss/doc/rst/legacy/reference/index.rst new file mode 100644 index 0000000000..a5cbc957a7 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/index.rst @@ -0,0 +1,340 @@ +.. _mozilla_projects_nss_reference: + +NSS reference +============= + +.. _initial_notes: + +`Initial Notes <#initial_notes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. container:: notecard note + + - We are migrating the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` into the + format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to + help with this migration, your help would be very much appreciated. + + - The proposed chapters below are based on the chapters of the + :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` and the categories of functions + in :ref:`mozilla_projects_nss_reference_nss_functions`. + + - Should a particular page require the use of an underscore, please see the documentation for + the `Title Override Extension </Project:En/MDC_style_guide#Title_Override_Extension>`__. + +.. _building_and_installing_nss: + +`Building and installing NSS <#building_and_installing_nss>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + :ref:`mozilla_projects_nss_reference_building_and_installing_nss` + +.. _overview_of_an_nss_application: + +`Overview of an NSS application <#overview_of_an_nss_application>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_ssl_functions_sslintro` in the SSL Reference. + +.. _getting_started_with_nss: + +`Getting started with NSS <#getting_started_with_nss>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_ssl_functions_gtstd` in the SSL Reference. + +.. _data_types: + +`Data types <#data_types>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_ssl_functions_ssltyp` in the SSL Reference. + +.. _nss_initialization_and_shutdown: + +`NSS initialization and shutdown <#nss_initialization_and_shutdown>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS_Init + - NSS_InitReadWrite + - NSS_NoDB_Init + - :ref:`mozilla_projects_nss_reference_nss_initialize` + - NSS_Shutdown + +.. _utility_functions: + +`Utility functions <#utility_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_reference_nss_functions#utility_functions` in NSS Public + Functions. + +.. _certificate_functions: + +`Certificate functions <#certificate_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_ssl_functions_sslcrt` in the SSL Reference and + :ref:`mozilla_projects_nss_reference_nss_functions#certificate_functions` in NSS Public + Functions. + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#validating_certificates` + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_verifycertnow` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_verifycert` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_verifycertname` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_checkcertvalidtimes` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#nss_cmpcertchainwcanames` + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#manipulating_certificates` + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_dupcertificate` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_destroycertificate` + - SEC_DeletePermCertificate + - \__CERT_ClosePermCertDB + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#getting_certificate_information` + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_findcertbyname` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_getcertnicknames` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_freenicknames` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#cert_getdefaultcertdb` + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#nss_findcertkeatype` + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#comparing_secitem_objects` + + - :ref:`mozilla_projects_nss_reference_nss_certificate_functions#secitem_compareitem` + +.. _key_functions: + +`Key functions <#key_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + :ref:`mozilla_projects_nss_reference_nss_key_functions` + + - :ref:`mozilla_projects_nss_ssl_functions_sslkey#seckey_getdefaultkeydb` + - :ref:`mozilla_projects_nss_ssl_functions_sslkey#seckey_destroyprivatekey` + +.. _digital_signatures: + +`Digital signatures <#digital_signatures>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This API consists of the routines used to perform signature generation and the routines used to + perform signature verification. + +.. _encryption.2fdecryption: + +`Encryption/decryption <#encryption.2fdecryption>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +`Hashing <#hashing>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _key_generation: + +`Key generation <#key_generation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Generate keys, key pairs, and domain parameters. + +.. _random_number_generation: + +`Random number generation <#random_number_generation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This API consists of the two routines used for pseudorandom number generation -- + PK11_GenerateRandomOnSlot and PK11_GenerateRandom -- and the two routines used for seeding + pseudorandom number generation -- PK11_SeedRandom and PK11_RandomUpdate. + +.. _pkcs_.2311_functions: + +`PKCS #11 functions <#pkcs_.2311_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_ssl_functions_pkfnc` in the SSL Reference and + :ref:`mozilla_projects_nss_reference_nss_functions#cryptography_functions` in NSS Public + Functions. + + - :ref:`mozilla_projects_nss_pkcs11_functions#secmod_loadusermodule` + - :ref:`mozilla_projects_nss_pkcs11_functions#secmod_unloadusermodule` + - :ref:`mozilla_projects_nss_pkcs11_functions#secmod_closeuserdb` + - :ref:`mozilla_projects_nss_pkcs11_functions#secmod_openuserdb` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_findcertfromnickname` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_findkeybyanycert` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_getslotname` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_gettokenname` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_ishw` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_ispresent` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_isreadonly` + - :ref:`mozilla_projects_nss_pkcs11_functions#pk11_setpasswordfunc` + +.. _ssl_functions: + +`SSL Functions <#ssl_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_ssl_functions_sslfnc` in the SSL Reference and + :ref:`mozilla_projects_nss_reference_nss_functions#ssl_functions` and + :ref:`mozilla_projects_nss_reference_nss_functions#deprecated_ssl_functions` in NSS Public + Functions. + + - SSL_ConfigServerSessionIDCache + - SSL_ClearSessionCache + +.. _s.2fmime: + +`S/MIME <#s.2fmime>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on the `S/MIME + Reference <https://www-archive.mozilla.org/projects/security/pki/nss/ref/smime/>`__ (which only + has one written chapter) and + :ref:`mozilla_projects_nss_reference_nss_functions#s_2fmime_functions` in NSS Public Functions. + +.. _pkcs_.237_functions: + +`PKCS #7 functions <#pkcs_.237_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on `"Archived PKCS #7 Functions + documentation." <https://www-archive.mozilla.org/projects/security/pki/nss/ref/nssfunctions.html#pkcs7>`__ + +.. _pkcs_.235_functions: + +`PKCS #5 functions <#pkcs_.235_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Password-based encryption + + - SEC_PKCS5GetIV + - SEC_PKCS5CreateAlgorithmID + - SEC_PKCS5GetCryptoAlgorithm + - SEC_PKCS5GetKeyLength + - SEC_PKCS5GetPBEAlgorithm + - SEC_PKCS5IsAlgorithmPBEAlg + +.. _pkcs_.2312_functions: + +`PKCS #12 functions <#pkcs_.2312_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on `"Archived PKCS #12 Functions + documentation." <https://www-archive.mozilla.org/projects/security/pki/nss/ref/nssfunctions.html#pkcs12>`__ + Used to exchange data such as private keys and certificates between two parties. + + - SEC_PKCS12CreateExportContext + - SEC_PKCS12CreatePasswordPrivSafe + - SEC_PKCS12CreateUnencryptedSafe + - SEC_PKCS12AddCertAndKey + - SEC_PKCS12AddPasswordIntegrity + - SEC_PKCS12EnableCipher + - SEC_PKCS12Encode + - SEC_PKCS12DestroyExportContext + - SEC_PKCS12DecoderStart + - SEC_PKCS12DecoderImportBags + - SEC_PKCS12DecoderUpdate + - SEC_PKCS12DecoderFinish + - SEC_PKCS12DecoderValidateBags + - SEC_PKCS12DecoderVerify + - SEC_PKCS12DecoderGetCerts + - SEC_PKCS12DecoderSetTargetTokenCAs + - SEC_PKCS12DecoderIterateInit + - SEC_PKCS12DecoderIterateNext + - SEC_PKCS12IsEncryptionAllowed + - SEC_PKCS12SetPreferredCipher + +.. _nspr_functions: + +`NSPR functions <#nspr_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A small number of :ref:`mozilla_projects_nss_reference_nspr_functions` are required for using the + certificate verification and SSL functions in NSS. These functions are listed in this section. + +.. _error_codes: + +`Error codes <#error_codes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_ssl_functions_sslerr` in the SSL Reference. + +.. _nss_environment_variables: + +`NSS Environment variables <#nss_environment_variables>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + :ref:`mozilla_projects_nss_reference_nss_environment_variables` + +.. _nss_cryptographic_module: + +`NSS cryptographic module <#nss_cryptographic_module>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + :ref:`mozilla_projects_nss_reference_nss_cryptographic_module` + +.. _nss_tech_notes: + +`NSS Tech Notes <#nss_tech_notes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + :ref:`mozilla_projects_nss_nss_tech_notes` :ref:`mozilla_projects_nss_memory_allocation` + +`Tools <#tools>`__ +~~~~~~~~~~~~~~~~~~ + +.. container:: + + Based on :ref:`mozilla_projects_nss_tools` documentation. + + Based on :ref:`mozilla_projects_nss_tools`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nsc_inittoken/index.rst b/security/nss/doc/rst/legacy/reference/nsc_inittoken/index.rst new file mode 100644 index 0000000000..8f5b91ffe6 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nsc_inittoken/index.rst @@ -0,0 +1,113 @@ +.. _mozilla_projects_nss_reference_nsc_inittoken: + +NSC_InitToken +============= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_InitToken()`` - initialize or re-initialize a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV NSC_InitToken( + CK_SLOT_ID slotID, + CK_CHAR_PTR pPin, + CK_ULONG ulPinLen, + CK_CHAR_PTR pLabel + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_InitToken()`` has the following parameters: + + ``slotID`` + the ID of the token's slot + ``pPin`` + the password of the security officer (SO) + ``ulPinLen`` + the length in bytes of the SO password + ``pLabel`` + points to the label of the token, which must be padded with spaces to 32 bytes and not be + null-terminated + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_InitToken()`` initializes a brand new token or re-initializes a token that was initialized + before. + + Specifically, ``NSC_InitToken()`` initializes or clears the key database, removes the password, + and then marks all the *user certs* in the certificate database as *non-user certs*. (User certs + are the certificates that have their associated private keys in the key database.) + + .. note:: + + **Note:** The SO password should be the empty string, i.e., ``ulPinLen`` argument should be 0. + ``NSC_InitToken()`` ignores the ``pLabel`` argument. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_InitToken()`` returns the following return codes. + + - ``CKR_OK``: token initialization succeeded. + - ``CKR_SLOT_ID_INVALID``: slot ID is invalid. + - ``CKR_TOKEN_WRITE_PROTECTED`` + + - slot ID is 1. (The non-FIPS mode has two slots: 1 and 2. The key database is in slot 2. + Slot 1 doesn't have a key database.) + - we don't have a reference to the key database (we failed to open the key database or we + have released our reference). + + - ``CKR_DEVICE_ERROR``: failed to reset the key database. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + +.. _application_usage: + +`Application usage <#application_usage>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_InitToken()`` is used to reset the password for the key database when the user forgets the + password. + + - The "Reset Password" button of the Mozilla Application Suite and SeaMonkey (in + **Preferences->Privacy & Security->Master Passwords**) calls ``NSC_InitToken()``. + - The "-T" (token reset) command of ``certutil`` calls ``NSC_InitToken()``. + + .. note:: + + **Note:** Resetting the password clears all permanent secret and private keys. You won't be + able to decrypt the data, such as Mozilla's stored passwords, that were encrypted using any of + those keys. + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `NSC_InitPIN </en-US/NSC_InitPIN>`__, :ref:`mozilla_projects_nss_reference_fc_inittoken`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nsc_login/index.rst b/security/nss/doc/rst/legacy/reference/nsc_login/index.rst new file mode 100644 index 0000000000..54ae57f212 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nsc_login/index.rst @@ -0,0 +1,88 @@ +.. _mozilla_projects_nss_reference_nsc_login: + +NSC_Login +========= + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_Login()`` - log a user into a token. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + CK_RV NSC_Login( + CK_SESSION_HANDLE hSession, + CK_USER_TYPE userType, + CK_CHAR_PTR pPin, + CK_ULONG ulPinLen + ); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_Login()`` takes four parameters: + + ``hSession`` + [in] a session handle + ``userType`` + [in] the user type (``CKU_SO`` or ``CKU_USER``) + ``pPin`` + [in] a pointer that points to the user's PIN + ``ulPinLen`` + [in] the length of the PIN + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_Login()`` logs a user into a token. + + The Security Officer (``CKU_SO``) only logs in to initialize the normal user's PIN. The SO PIN is + the empty string. The NSS cryptographic module doesn't allow the SO to log in if the normal + user's PIN is already initialized. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSC_Login()`` returns the following return codes. + + - ``CKR_OK``: the user logged in successfully. + - ``CKR_DEVICE_ERROR``: the token is in the Error state. + - ``CKR_HOST_MEMORY``: memory allocation failed. + - ``CKR_PIN_INCORRECT``: the PIN is incorrect. + - ``CKR_PIN_LEN_RANGE``: the PIN is too long (``ulPinLen`` is greater than 255). + + .. note:: + + The function should return ``CKR_PIN_INCORRECT`` in this case. + + - ``CKR_SESSION_HANDLE_INVALID``: the session handle is invalid. + - ``CKR_USER_ALREADY_LOGGED_IN``: the user is already logged in. + - ``CKR_USER_TYPE_INVALID`` + + - The token can't authenticate the user because there is no key database or the user's + password isn't initialized. + - ``userType`` is ``CKU_SO`` and the normal user's PIN is already initialized. + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_login`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nspr_functions/index.rst b/security/nss/doc/rst/legacy/reference/nspr_functions/index.rst new file mode 100644 index 0000000000..55d33200ec --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nspr_functions/index.rst @@ -0,0 +1,126 @@ +.. _mozilla_projects_nss_reference_nspr_functions: + +NSPR functions +============== + +.. container:: + + `NSPR <https://www.mozilla.org/projects/nspr/>`__ is a platform abstraction library that provides + a cross-platform API to common OS services. NSS uses NSPR internally as the porting layer. + However, a small number of NSPR functions are required for using the certificate verification and + SSL functions in NSS. These NSPR functions are listed in this section. + +.. _nspr_initialization_and_shutdown: + +`NSPR initialization and shutdown <#nspr_initialization_and_shutdown>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSPR is automatically initialized by the first NSPR function called by the application. Call + ```PR_Cleanup`` </en-US/PR_Cleanup>`__ to shut down NSPR and clean up its resources.\ ` + </en-US/PR_Init>`__ + + - `PR_Cleanup </en-US/PR_Cleanup>`__ + +.. _error_reporting: + +`Error reporting <#error_reporting>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS uses NSPR's thread-specific error code to report errors. Call + ```PR_GetError`` </en-US/PR_GetError>`__ to get the error code of the last failed NSS or NSPR + function. Call ```PR_SetError`` </en-US/PR_SetError>`__ to set the error code, which can be + retrieved with ``PR_GetError`` later. + + The NSS functions ``PORT_GetError`` and ``PORT_SetError`` are simply wrappers of ``PR_GetError`` + and ``PR_SetError``. + + - `PR_GetError </en-US/PR_GetError>`__ + - `PR_SetError </en-US/PR_SetError>`__ + +.. _calendar_time: + +`Calendar time <#calendar_time>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSS certificate verification functions take a ``PRTime`` parameter that specifies the time + instant at which the validity of the certificate should verified. The NSPR function + ```PR_Now`` </en-US/PR_Now>`__ returns the current time in ``PRTime``. + + - `PR_Now </en-US/PR_Now>`__ + +.. _interval_time: + +`Interval time <#interval_time>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The NSPR socket I/O functions ```PR_Recv`` </en-US/PR_Recv>`__ and + ```PR_Send`` </en-US/PR_Send>`__ (used by the NSS SSL functions) take a ``PRIntervalTime`` + timeout parameter. ``PRIntervalTime`` has an abstract, platform-dependent time unit. Call + ```PR_SecondsToInterval`` </en-US/PR_SecondsToInterval>`__ or ``PR_MillisecondsToInterval`` to + convert a time interval in seconds or milliseconds to ``PRIntervalTime``. + + - `PR_SecondsToInterval </en-US/PR_SecondsToInterval>`__ + - `PR_MillisecondsToInterval </en-US/PR_MillisecondsToInterval>`__ + +.. _nspr_io_layering: + +`NSPR I/O layering <#nspr_io_layering>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + NSPR file descriptors can be layered, corresponding to the layers in the network stack. The SSL + library in NSS implements the SSL protocol as an NSPR I/O layer, which sits on top of another + NSPR I/O layer that represents TCP. + + You can implement an NSPR I/O layer that wraps your own TCP socket code. The following NSPR + functions allow you to create your own NSPR I/O layer and manipulate it. + + - `PR_GetUniqueIdentity </en-US/PR_GetUniqueIdentity>`__ + - `PR_CreateIOLayerStub </en-US/PR_CreateIOLayerStub>`__ + - `PR_GetDefaultIOMethods </en-US/PR_GetDefaultIOMethods>`__ + - `PR_GetIdentitiesLayer </en-US/PR_GetIdentitiesLayer>`__ + - `PR_GetLayersIdentity </en-US/PR_GetLayersIdentity>`__ + - `PR_PushIOLayer </en-US/PR_PushIOLayer>`__ + - `PR_PopIOLayer </en-US/PR_PopIOLayer>`__ + +.. _wrapping_a_native_file_descriptor: + +`Wrapping a native file descriptor <#wrapping_a_native_file_descriptor>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + If your current TCP socket code uses the standard BSD socket API, a lighter-weight method than + creating your own NSPR I/O layer is to simply import a native file descriptor into NSPR. This + method is convenient and works for most applications. + + - `PR_ImportTCPSocket </en-US/PR_ImportTCPSocket>`__ + +.. _socket_io_functions: + +`Socket I/O functions <#socket_io_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + As mentioned above, the SSL library in NSS implements the SSL protocol as an NSPR I/O layer. + Users call NSPR socket I/O functions to read from, write to, and shut down an SSL connection, and + to close an NSPR file descriptor. + + - `PR_Read </en-US/PR_Read>`__ + - `PR_Write </en-US/PR_Write>`__ + - `PR_Recv </en-US/PR_Recv>`__ + - `PR_Send </en-US/PR_Send>`__ + - `PR_GetSocketOption </en-US/PR_GetSocketOption>`__ + - `PR_SetSocketOption </en-US/PR_SetSocketOption>`__ + - `PR_Shutdown </en-US/PR_Shutdown>`__ + - `PR_Close </en-US/PR_Close>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_certificate_functions/index.rst b/security/nss/doc/rst/legacy/reference/nss_certificate_functions/index.rst new file mode 100644 index 0000000000..01d694d49b --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_certificate_functions/index.rst @@ -0,0 +1,609 @@ +.. _mozilla_projects_nss_reference_nss_certificate_functions: + +NSS Certificate Functions +========================= + +.. _certificate_functions: + +`Certificate Functions <#certificate_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This chapter describes the functions and related types used to work with a certificate database + such as the cert8.db database provided with NSS. This was converted from `"Chapter 5: Certificate + Functions" <https://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt.html>`__. + + - :ref:`mozilla_projects_nss_reference` + - `Validating Certificates <NSS_Certificate_Functions#Validating_Certificates>`__ + - `Manipulating Certificates <NSS_Certificate_Functions#Manipulating_Certificates>`__ + - `Getting Certificate + Information <NSS_Certificate_Functions#Getting_Certificate_Information>`__ + - `Comparing SecItem Objects <NSS_Certificate_Functions#Comparing_SecItem_Objects>`__ + + .. rubric:: Validating Certificates + :name: validating_certificates + + - `CERT_VerifyCertNow <NSS_Certificate_Functions#CERT_VerifyCertNow>`__ + - `CERT_VerifyCert <NSS_Certificate_Functions#CERT_VerifyCert>`__ + - `CERT_VerifyCertName <NSS_Certificate_Functions#CERT_VerifyCertName>`__ + - `CERT_CheckCertValidTimes <NSS_Certificate_Functions#CERT_CheckCertValidTimes>`__ + - `NSS_CmpCertChainWCANames <NSS_Certificate_Functions#NSS_CmpCertChainWCANames>`__ + + .. rubric:: CERT_VerifyCertNow + :name: cert_verifycertnow + + Checks that the current date is within the certificate's validity period and that the CA + signature on the certificate is valid. + + .. rubric:: Syntax + :name: syntax + + .. code:: + + #include <cert.h> + + .. code:: + + SECStatus CERT_VerifyCertNow( + CERTCertDBHandle *handle, + CERTCertificate *cert, + PRBool checkSig, + SECCertUsage certUsage, + void *wincx); + + .. rubric:: Parameters + :name: parameters + + This function has the following parameters: + + *handle*\ A pointer to the certificate database handle. + + *cert*\ A pointer to the certificate to be checked. + + *checkSig*\ Indicates whether certificate signatures are to be checked. + + - PR_TRUE means certificate signatures are to be checked. + - PR_FALSE means certificate signatures will not be checked. + + *certUsage*\ One of these values: + + - certUsageSSLClient + - certUsageSSLServer + - certUsageSSLServerWithStepUp + - certUsageSSLCA + - certUsageEmailSigner + - certUsageEmailRecipient + - certUsageObjectSigner + - certUsageUserCertImport + - certUsageVerifyCA + - certUsageProtectedObjectSigner + + *wincx*\ The PIN argument value to pass to PK11 functions. See description below for more + information. + + .. rubric:: Returns + :name: returns + + The function returns one of these values: + + - If successful, SECSuccess. + - If unsuccessful, SECFailure. Use PR_GetError to obtain the error code. + + .. rubric:: Description + :name: description + + The CERT_VerifyCertNow function must call one or more PK11 functions to obtain the services of a + PKCS #11 module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for + details), which must be specified in the wincx parameter. To obtain the value to pass in the + wincx parameter, call SSL_RevealPinArg. + + .. rubric:: CERT_VerifyCert + :name: cert_verifycert + + Checks that the a given aribrary date is within the certificate's validity period and that the CA + signature on the certificate is valid. It also optionally returns a log of all the problems with + the chain. Calling CERT_VerifyCert with the parameters: CERT_VerifyCert(handle, cert, checkSig, + certUsage, PR_Now(), wincx, NULL) is equivalent to calling CERT_VerifyNow(handle, cert, checkSig, + certUsage, wincx). + + .. rubric:: Syntax + :name: syntax_2 + + .. code:: + + #include <cert.h> + + .. code:: + + SECStatus CERT_VerifyCert( + CERTCertDBHandle *handle, + CERTCertificate *cert, + PRBool checkSig, + SECCertUsage certUsage, + int 64 t, + void *wincx + CERTVerifyLog *log); + + .. rubric:: Parameters + :name: parameters_2 + + This function has the following parameters: + + *handle*\ A pointer to the certificate database handle. + + *cert*\ A pointer to the certificate to be checked. + + *checkSig*\ Indicates whether certificate signatures are to be checked. + + - PR_TRUE means certificate signatures are to be checked. + - PR_FALSE means certificate signatures will not be checked. + + *certUsage*\ One of these values: + + - certUsageSSLClient + - certUsageSSLServer + - certUsageSSLServerWithStepUp + - certUsageSSLCA + - certUsageEmailSigner + - certUsageEmailRecipient + - certUsageObjectSigner + - certUsageUserCertImport + - certUsageVerifyCA + - certUsageProtectedObjectSigner + + *t*\ Time in which to validate the certificate. + + *wincx*\ The PIN argument value to pass to PK11 functions. See description below for more + information. + + *log*\ Optional certificate log which returns all the errors in processing a given certificate + chain. See :ref:`mozilla_projects_nss_certverify_log` for more information. + + .. rubric:: Returns + :name: returns_2 + + The function returns one of these values: + + - If successful, SECSuccess. + - If unsuccessful, SECFailure. Use PR_GetError to obtain the error code. + + .. rubric:: Description + :name: description_2 + + The CERT_VerifyCert function must call one or more PK11 functions to obtain the services of a + PKCS #11 module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for + details), which must be specified in the wincx parameter. To obtain the value to pass in the + wincx parameter, call SSL_RevealPinArg. + + .. rubric:: CERT_VerifyCertName + :name: cert_verifycertname + + Compares the common name specified in the subject DN for a certificate with a specified hostname. + + .. rubric:: Syntax + :name: syntax_3 + + .. code:: + + #include <cert.h> + + .. code:: + + SECStatus CERT_VerifyCertName( + CERTCertificate *cert, + char *hostname); + + .. rubric:: Parameters + :name: parameters_3 + + This function has the following parameters: + + *cert*\ A pointer to the certificate against which to check the hostname referenced by hostname. + + *hostname*\ The hostname to be checked. + + .. rubric:: Returns + :name: returns_3 + + The function returns one of these values: + + - If the common name in the subject DN for the certificate matches the domain name passed in the + hostname parameter, SECSuccess. + - If the common name in the subject DN for the certificate is not identical to the domain name + passed in the hostname parameter, SECFailure. Use PR_GetError to obtain the error code. + + .. rubric:: Description + :name: description_3 + + The comparison performed by CERT_VerifyCertName is not a simple string comparison. Instead, it + takes account of the following rules governing the construction of common names in SSL server + certificates: + + - \* matches anything + - ? matches one character + - \\ escapes a special character + - $ matches the end of the string + - [abc] matches one occurrence of a, b, or c. The only character that needs to be escaped in + this is ], all others are not special. + - [a-z] matches any character between a and z + - [^az] matches any character except a or z + - ~ followed by another shell expression removes any pattern matching the shell expression from + the match list + - (foo|bar) matches either the substring foo or the substring bar. These can be shell + expressions as well. + + .. rubric:: CERT_CheckCertValidTimes + :name: cert_checkcertvalidtimes + + Checks whether a specified time is within a certificate's validity period. + + .. rubric:: Syntax + :name: syntax_4 + + .. code:: + + #include <cert.h> + #include <certt.h> + + .. code:: + + SECCertTimeValidity CERT_CheckCertValidTimes( + CERTCertificate *cert, + int64 t); + + .. rubric:: Parameters + :name: parameters_4 + + This function has the following parameters: + + *cert*\ A pointer to the certificate whose validity period you want to check against. + + *t*\ The time to check against the certificate's validity period. For more information, see the + NSPR header pr_time.h. + + .. rubric:: Returns + :name: returns_4 + + The function returns an enumerator of type SECCertTimeValidity: + + .. code:: + + typedef enum { + secCertTimeValid, + secCertTimeExpired, + secCertTimeNotValidYet + } SECCertTimeValidity; + + .. rubric:: NSS_CmpCertChainWCANames + :name: nss_cmpcertchainwcanames + + Determines whether any of the signers in the certificate chain for a specified certificate are on + a specified list of CA names. + + .. rubric:: Syntax + :name: syntax_5 + + .. code:: + + #include <nss.h> + + SECStatus NSS_CmpCertChainWCANames( + CERTCertificate *cert, + CERTDistNames *caNames); + + .. rubric:: Parameters + :name: parameters_5 + + This function has the following parameters: + + *cert*\ A pointer to the certificate structure for the certificate whose certificate chain is to + be checked. + + *caNames*\ A pointer to a structure that contains a list of distinguished names (DNs) against + which to check the DNs for the signers in the certificate chain. + + .. rubric:: Returns + :name: returns_5 + + The function returns one of these values: + + - If successful, SECSuccess. + - If unsuccessful, SECFailure. Use PR_GetError to obtain the error code. + + .. rubric:: Manipulating Certificates + :name: manipulating_certificates + + - `CERT_DupCertificate <#cert_dupcertificate>`__ + - `CERT_DestroyCertificate <#cert_destroycertificate>`__ + + .. rubric:: CERT_DupCertificate + :name: cert_dupcertificate + + Makes a shallow copy of a specified certificate. + + .. rubric:: Syntax + :name: syntax_6 + + .. code:: + + #include <cert.h> + + .. code:: + + CERTCertificate *CERT_DupCertificate(CERTCertificate *c) + + .. rubric:: Parameter + :name: parameter + + This function has the following parameter: + + *c*\ A pointer to the certificate object to be duplicated. + + .. rubric:: Returns + :name: returns_6 + + If successful, the function returns a pointer to a certificate object of type CERTCertificate. + + .. rubric:: Description + :name: description_4 + + The CERT_DupCertificate function increments the reference count for the certificate passed in the + c parameter. + + .. rubric:: CERT_DestroyCertificate + :name: cert_destroycertificate + + Destroys a certificate object. + + .. rubric:: Syntax + :name: syntax_7 + + .. code:: + + #include <cert.h> + #include <certt.h> + + .. code:: + + void CERT_DestroyCertificate(CERTCertificate *cert); + + .. rubric:: Parameters + :name: parameters_6 + + This function has the following parameter: + + *cert*\ A pointer to the certificate to destroy. + + .. rubric:: Description + :name: description_5 + + Certificate and key structures are shared objects. When an application makes a copy of a + particular certificate or key structure that already exists in memory, SSL makes a shallow + copy--that is, it increments the reference count for that object rather than making a whole new + copy. When you call CERT_DestroyCertificate or SECKEY_DestroyPrivateKey, the function decrements + the reference count and, if the reference count reaches zero as a result, both frees the memory + and sets all the bits to zero. The use of the word "destroy" in function names or in the + description of a function implies reference counting. + + Never alter the contents of a certificate or key structure. If you attempt to do so, the change + affects all the shallow copies of that structure and can cause severe problems. + + .. rubric:: Getting Certificate Information + :name: getting_certificate_information + + - `CERT_FindCertByName <#cert_findcertbyname>`__ + - `CERT_GetCertNicknames <#cert_getcertnicknames>`__ + - `CERT_FreeNicknames <#cert_freenicknames>`__ + - `CERT_GetDefaultCertDB <#cert_getdefaultcertdb>`__ + - `NSS_FindCertKEAType <#nss_findcertkeatype>`__ + + .. rubric:: CERT_FindCertByName + :name: cert_findcertbyname + + Finds the certificate in the certificate database with a specified DN. + + .. rubric:: Syntax + :name: syntax_8 + + .. code:: + + #include <cert.h> + + .. code:: + + CERTCertificate *CERT_FindCertByName ( + CERTCertDBHandle *handle, + SECItem *name); + + .. rubric:: Parameters + :name: parameters_7 + + This function has the following parameters: + + *handle*\ A pointer to the certificate database handle. + + *name*\ The subject DN of the certificate you wish to find. + + .. rubric:: Returns + :name: returns_7 + + If successful, the function returns a certificate object of type CERTCertificate. + + .. rubric:: CERT_GetCertNicknames + :name: cert_getcertnicknames + + Returns the nicknames of the certificates in a specified certificate database. + + .. rubric:: Syntax + :name: syntax_9 + + .. code:: + + #include <cert.h> + #include <certt.h> + + .. code:: + + CERTCertNicknames *CERT_GetCertNicknames ( + CERTCertDBHandle *handle, + int what, + void *wincx); + + .. rubric:: Parameters + :name: parameters_8 + + This function has the following parameters: + + *handle*\ A pointer to the certificate database handle. + + *what*\ One of these values: + + - SEC_CERT_NICKNAMES_ALL + - SEC_CERT_NICKNAMES_USER + - SEC_CERT_NICKNAMES_SERVER + - SEC_CERT_NICKNAMES_CA + + *wincx*\ The PIN argument value to pass to PK11 functions. See description below for more + information. + + .. rubric:: Returns + :name: returns_8 + + The function returns a CERTCertNicknames object containing the requested nicknames. + + .. rubric:: Description + :name: description_6 + + CERT_GetCertNicknames must call one or more PK11 functions to obtain the services of a PKCS #11 + module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for details), + which must be specified in the wincx parameter. To obtain the value to pass in the wincx + parameter, call SSL_RevealPinArg. + + .. rubric:: CERT_FreeNicknames + :name: cert_freenicknames + + Frees a CERTCertNicknames structure. This structure is returned by CERT_GetCertNicknames. + + .. rubric:: Syntax + :name: syntax_10 + + .. code:: + + #include <cert.h> + + .. code:: + + void CERT_FreeNicknames(CERTCertNicknames *nicknames); + + .. rubric:: Parameters + :name: parameters_9 + + This function has the following parameter: + + *nicknames*\ A pointer to the CERTCertNicknames structure to be freed. + + .. rubric:: CERT_GetDefaultCertDB + :name: cert_getdefaultcertdb + + Returns a handle to the default certificate database. + + .. rubric:: Syntax + :name: syntax_11 + + .. code:: + + #include <cert.h> + + .. code:: + + CERTCertDBHandle *CERT_GetDefaultCertDB(void); + + .. rubric:: Returns + :name: returns_9 + + The function returns the CERTCertDBHandle for the default certificate database. + + .. rubric:: Description + :name: description_7 + + This function is useful for determining whether the default certificate database has been opened. + + .. rubric:: NSS_FindCertKEAType + :name: nss_findcertkeatype + + Returns key exchange type of the keys in an SSL server certificate. + + .. rubric:: Syntax + :name: syntax_12 + + .. code:: + + #include <nss.h> + + .. code:: + + SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert); + + .. rubric:: Parameter + :name: parameter_2 + + This function has the following parameter: + + *a*\ The certificate to check. + + .. rubric:: Returns + :name: returns_10 + + The function returns one of these values: + + - kt_null = 0 + - kt_rsa + - kt_dh + - kt_fortezza + - kt_kea_size + + .. rubric:: Comparing SecItem Objects + :name: comparing_secitem_objects + + .. rubric:: SECITEM_CompareItem + :name: secitem_compareitem + + Compares two SECItem objects and returns a SECComparison enumerator that shows the difference + between them. + + .. rubric:: Syntax + :name: syntax_13 + + .. code:: + + #include <secitem.h> + #include <seccomon.h> + + .. code:: + + SECComparison SECITEM_CompareItem( + SECItem *a, + SECItem *b); + + .. rubric:: Parameters + :name: parameters_10 + + This function has the following parameters: + + *a*\ A pointer to one of the items to be compared. + + *b*\ A pointer to one of the items to be compared. + + .. rubric:: Returns + :name: returns_11 + + The function returns an enumerator of type SECComparison. + + .. code:: + + typedef enum _SECComparison { + SECLessThan = -1, + SECEqual = 0, + SECGreaterThan = 1 + } SECComparison;
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_cryptographic_module/fips_mode_of_operation/index.rst b/security/nss/doc/rst/legacy/reference/nss_cryptographic_module/fips_mode_of_operation/index.rst new file mode 100644 index 0000000000..4d18113f53 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_cryptographic_module/fips_mode_of_operation/index.rst @@ -0,0 +1,190 @@ +.. _mozilla_projects_nss_reference_nss_cryptographic_module_fips_mode_of_operation: + +FIPS mode of operation +====================== + +.. _general-purpose_functions: + +`General-purpose functions <#general-purpose_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_getfunctionlist` + - :ref:`mozilla_projects_nss_reference_fc_initialize` + - :ref:`mozilla_projects_nss_reference_fc_finalize` + - :ref:`mozilla_projects_nss_reference_fc_getinfo` + +.. _slot_and_token_management_functions: + +`Slot and token management functions <#slot_and_token_management_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_getslotlist` + - :ref:`mozilla_projects_nss_reference_fc_getslotinfo` + - :ref:`mozilla_projects_nss_reference_fc_gettokeninfo` + - :ref:`mozilla_projects_nss_reference_fc_waitforslotevent` + - :ref:`mozilla_projects_nss_reference_fc_getmechanismlist` + - :ref:`mozilla_projects_nss_reference_fc_getmechanisminfo` + - :ref:`mozilla_projects_nss_reference_fc_inittoken` + - :ref:`mozilla_projects_nss_reference_fc_initpin` + - :ref:`mozilla_projects_nss_reference_fc_setpin` + +.. _session_management_functions: + +`Session management functions <#session_management_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_opensession` + - :ref:`mozilla_projects_nss_reference_fc_closesession` + - :ref:`mozilla_projects_nss_reference_fc_closeallsessions` + - :ref:`mozilla_projects_nss_reference_fc_getsessioninfo` + - :ref:`mozilla_projects_nss_reference_fc_getoperationstate` + - :ref:`mozilla_projects_nss_reference_fc_setoperationstate` + - :ref:`mozilla_projects_nss_reference_fc_login` + - :ref:`mozilla_projects_nss_reference_fc_logout` + +.. _object_management_functions: + +`Object management functions <#object_management_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These functions manage certificates and keys. + + - :ref:`mozilla_projects_nss_reference_fc_createobject` + - :ref:`mozilla_projects_nss_reference_fc_copyobject` + - :ref:`mozilla_projects_nss_reference_fc_destroyobject` + - :ref:`mozilla_projects_nss_reference_fc_getobjectsize` + - :ref:`mozilla_projects_nss_reference_fc_getattributevalue` + - :ref:`mozilla_projects_nss_reference_fc_setattributevalue` + - :ref:`mozilla_projects_nss_reference_fc_findobjectsinit` + - :ref:`mozilla_projects_nss_reference_fc_findobjects` + - :ref:`mozilla_projects_nss_reference_fc_findobjectsfinal` + +.. _encryption_functions: + +`Encryption functions <#encryption_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These functions support Triple DES and AES in ECB and CBC modes. + + - :ref:`mozilla_projects_nss_reference_fc_encryptinit` + - :ref:`mozilla_projects_nss_reference_fc_encrypt` + - :ref:`mozilla_projects_nss_reference_fc_encryptupdate` + - :ref:`mozilla_projects_nss_reference_fc_encryptfinal` + +.. _decryption_functions: + +`Decryption functions <#decryption_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These functions support Triple DES and AES in ECB and CBC modes. + + - :ref:`mozilla_projects_nss_reference_fc_decryptinit` + - :ref:`mozilla_projects_nss_reference_fc_decrypt` + - :ref:`mozilla_projects_nss_reference_fc_decryptupdate` + - :ref:`mozilla_projects_nss_reference_fc_decryptfinal` + +.. _message_digesting_functions: + +`Message digesting functions <#message_digesting_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These functions support SHA-1, SHA-256, SHA-384, and SHA-512. + + - :ref:`mozilla_projects_nss_reference_fc_digestinit` + - :ref:`mozilla_projects_nss_reference_fc_digest` + - :ref:`mozilla_projects_nss_reference_fc_digestupdate` + - :ref:`mozilla_projects_nss_reference_fc_digestkey` + - :ref:`mozilla_projects_nss_reference_fc_digestfinal` + +.. _signature_and_mac_generation_functions: + +`Signature and MAC generation functions <#signature_and_mac_generation_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These functions support DSA, RSA, ECDSA, and HMAC. + + - :ref:`mozilla_projects_nss_reference_fc_signinit` + - :ref:`mozilla_projects_nss_reference_fc_sign` + - :ref:`mozilla_projects_nss_reference_fc_signupdate` + - :ref:`mozilla_projects_nss_reference_fc_signfinal` + - :ref:`mozilla_projects_nss_reference_fc_signrecoverinit` + - :ref:`mozilla_projects_nss_reference_fc_signrecover` + +.. _signature_and_mac_verification_functions: + +`Signature and MAC verification functions <#signature_and_mac_verification_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These functions support DSA, RSA, ECDSA, and HMAC. + + - :ref:`mozilla_projects_nss_reference_fc_verifyinit` + - :ref:`mozilla_projects_nss_reference_fc_verify` + - :ref:`mozilla_projects_nss_reference_fc_verifyupdate` + - :ref:`mozilla_projects_nss_reference_fc_verifyfinal` + - :ref:`mozilla_projects_nss_reference_fc_verifyrecoverinit` + - :ref:`mozilla_projects_nss_reference_fc_verifyrecover` + +.. _dual-function_cryptographic_functions: + +`Dual-function cryptographic functions <#dual-function_cryptographic_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_digestencryptupdate` + - :ref:`mozilla_projects_nss_reference_fc_decryptdigestupdate` + - :ref:`mozilla_projects_nss_reference_fc_signencryptupdate` + - :ref:`mozilla_projects_nss_reference_fc_decryptverifyupdate` + +.. _key_management_functions: + +`Key management functions <#key_management_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_generatekey`: DSA domain parameters (PQG) + - :ref:`mozilla_projects_nss_reference_fc_generatekeypair`: DSA, RSA, and ECDSA. Performs + pair-wise consistency test. + - :ref:`mozilla_projects_nss_reference_fc_wrapkey`: RSA Key Wrapping + - :ref:`mozilla_projects_nss_reference_fc_unwrapkey`: RSA Key Wrapping + - :ref:`mozilla_projects_nss_reference_fc_derivekey`: Diffie-Hellman, EC Diffie-Hellman + +.. _random_number_generation_functions: + +`Random number generation functions <#random_number_generation_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_seedrandom` + - :ref:`mozilla_projects_nss_reference_fc_generaterandom`: Performs continuous random number + generator test. + +.. _parallel_function_management_functions: + +`Parallel function management functions <#parallel_function_management_functions>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - :ref:`mozilla_projects_nss_reference_fc_getfunctionstatus` + - :ref:`mozilla_projects_nss_reference_fc_cancelfunction`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_cryptographic_module/index.rst b/security/nss/doc/rst/legacy/reference/nss_cryptographic_module/index.rst new file mode 100644 index 0000000000..f413798bac --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_cryptographic_module/index.rst @@ -0,0 +1,29 @@ +.. _mozilla_projects_nss_reference_nss_cryptographic_module: + +NSS cryptographic module +======================== + +.. container:: + + This chapter describes the data types and functions that one can use to perform cryptographic + operations with the NSS cryptographic module. The NSS cryptographic module uses the industry + standard `PKCS #11 <http://www.rsasecurity.com/rsalabs/node.asp?id=2133>`__ v2.20 as its API with + some extensions. Therefore, an application that supports PKCS #11 cryptographic tokens can be + easily modified to use the NSS cryptographic module. + + The NSS cryptographic module has two modes of operation: the non-FIPS (default) mode and FIPS + mode. The FIPS mode is an Approved mode of operation compliant to FIPS 140-2. Both modes of + operation use the same data types but are implemented by different functions. + + - The standard PKCS #11 function C_GetFunctionList or the equivalent NSC_GetFunctionList + function returns pointers to the functions that implement the default mode of operation. + - To enable the FIPS mode of operation, use the function FC_GetFunctionList instead to get + pointers to the functions that implement the FIPS mode of operation. + + The NSS cryptographic module also exports the function NSC_ModuleDBFunc for managing the NSS + module database secmod.db. The following sections document the data types and functions. + + - :ref:`mozilla_projects_nss_reference_nss_cryptographic_module_data_types` + - :ref:`mozilla_projects_nss_pkcs11_functions` + - :ref:`mozilla_projects_nss_reference_nss_cryptographic_module_fips_mode_of_operation` + - NSC_ModuleDBFunc
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_environment_variables/index.rst b/security/nss/doc/rst/legacy/reference/nss_environment_variables/index.rst new file mode 100644 index 0000000000..2482565967 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_environment_variables/index.rst @@ -0,0 +1,515 @@ +.. _mozilla_projects_nss_reference_nss_environment_variables: + +NSS environment variables +========================= + +.. container:: + + .. note:: + + **Note: NSS Environment Variables are subject to be changed and/or removed from NSS.** + +.. _run-time_environment_variables: + +`Run-Time Environment Variables <#run-time_environment_variables>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These environment variables affect the RUN TIME behavior of NSS shared libraries. There is a + separate set of environment variables that affect how NSS is built, documented below. + + +------------------------+------------------------+------------------------+------------------------+ + | Variable | Type | Description | Introduced in version | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSRANDCOUNT`` | Integer | Sets the maximum | 3.12.3 | + | | (byte count) | number of bytes to | | + | | | read from the file | | + | | | named in the | | + | | | environment variable | | + | | | NSRANDFILE (see | | + | | | below). Makes | | + | | | NSRANDFILE usable with | | + | | | /dev/urandom. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSRANDFILE`` | String | Uses this file to seed | Before 3.0 | + | | (file name) | the Pseudo Random | | + | | | Number Generator. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_ALLO | Boolean | Enables the use of MD2 | 3.12.3 | + | W_WEAK_SIGNATURE_ALG`` | (any non-empty value | and MD4 inside | | + | | to enable) | signatures. This was | | + | | | allowed by default | | + | | | before NSS 3.12.3. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS | String | Name the PKCS#11 | 3.6 | + | _DEBUG_PKCS11_MODULE`` | (module name) | module to be traced. | | + | | | :ref:`mozilla | | + | | | _projects_nss_nss_tech | | + | | | _notes_nss_tech_note2` | | + +------------------------+------------------------+------------------------+------------------------+ + | ` | String | Determines the default | 3.12 | + | `NSS_DEFAULT_DB_TYPE`` | ("dbm", "sql", or | Database type to open | | + | | "extern") | if the app does not | | + | | | specify. | | + | | | `NSS_Shared_D | | + | | | B <http://wiki.mozilla | | + | | | .org/NSS_Shared_DB>`__ | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_DIS | String | Define this variable | 3.4 | + | ABLE_ARENA_FREE_LIST`` | (any non-empty value) | to get accurate leak | | + | | | allocation stacks when | | + | | | using leak reporting | | + | | | software. | | + | | | : | | + | | | ref:`mozilla_projects_ | | + | | | nss_memory_allocation` | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_DISABLE_UNLOAD`` | String | Disable unloading of | 3.11.8 | + | | (any non-empty value) | dynamically loaded NSS | | + | | | shared libraries | | + | | | during shutdown. | | + | | | Necessary on some | | + | | | platforms to get | | + | | | correct function names | | + | | | when using leak | | + | | | reporting software. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_ENABLE_AUDIT`` | Boolean | Enable auditing of | 3.11.2 | + | | (1 to enable) | activities of the NSS | | + | | | cryptographic module | | + | | | in FIPS mode. `Audit | | + | | | Data <http://wiki. | | + | | | mozilla.org/FIPS_Opera | | + | | | tional_Environment>`__ | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NS | Boolean | Use libPKIX, rather | 3.12 | + | S_ENABLE_PKIX_VERIFY`` | (any non-empty value | than the old cert | | + | | to enable) | library, to verify | | + | | | certificates. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_FIPS`` | String | Will start NSS in FIPS | 3.12.5 | + | | (" | mode. | | + | | fips","true","on","1") | | | + +------------------------+------------------------+------------------------+------------------------+ + | `` | String | Specifies agorithms | 3.12.3 | + | NSS_HASH_ALG_SUPPORT`` | | allowed to be used in | | + | | | certain applications, | | + | | | such as in signatures | | + | | | on certificates and | | + | | | CRLs. See | | + | | | documentation at `this | | + | | | link <https://bugzill | | + | | | a.mozilla.org/show_bug | | + | | | .cgi?id=483113#c0>`__. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_OUTPUT_FILE`` | String | Output file path name | 3.7 | + | | (filename) | for the | | + | | | :ref:`mozilla_ | | + | | | projects_nss_nss_tech_ | | + | | | notes_nss_tech_note2`. | | + | | | Default is stdout. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_SDB_USE_CACHE`` | String | Controls whether NSS | 3.12 | + | | ("no","yes","auto") | uses a local cache of | | + | | | SQL database contents. | | + | | | Default is "auto". See | | + | | | `the | | + | | | source <http://bonsai | | + | | | .mozilla.org/cvsblame. | | + | | | cgi?file=/mozilla/secu | | + | | | rity/nss/lib/softoken/ | | + | | | sdb.c&rev=1.6#1797>`__ | | + | | | for more information. | | + +------------------------+------------------------+------------------------+------------------------+ + | `NS | String ("0", "1") | Controls the | | + | S_SSL_CBC_RANDOM_IV <h | | workaround for the | | + | ttps://dxr.mozilla.org | | `BEAST <https | | + | /security/search?q=NSS | | ://en.wikipedia.org/wi | | + | _SSL_CBC_RANDOM_IV>`__ | | ki/Transport_Layer_Sec | | + | | | urity#BEAST_attack>`__ | | + | | | attack on SSL 3.0 and | | + | | | TLS 1.0. "0" disables | | + | | | it, "1" enables it. It | | + | | | is also known as 1/n-1 | | + | | | record splitting. | | + | | | Default is "1". | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_SSL_ | String | (Definition for NSS | 3.12.5 | + | ENABLE_RENEGOTIATION`` | ([0|n|N], | 3.12.6 and above) | Modified in 3.12.6 | + | | [1|u|U], | Sets how TLS | | + | | [2|r|R], | renegotiation is | | + | | [3|t|T]) | handled | | + | | | | | + | | | - [1|u|U]: | | + | | | SSL_RE | | + | | | NEGOTIATE_UNRESTRICTED | | + | | | | | + | | | | Server and client | | + | | | are allowed to | | + | | | renegotiate without | | + | | | any restrictions. | | + | | | | This setting was the | | + | | | default prior 3.12.5 | | + | | | and makes products | | + | | | vulnerable. | | + | | | | | + | | | - [0|n|N]: | | + | | | | | + | | | SSL_RENEGOTIATE_NEVER | | + | | | | | + | | | Never allow | | + | | | renegotiation - That | | + | | | was the default for | | + | | | 3.12.5 release. | | + | | | | | + | | | - [3|t|T]: | | + | | | SSL_RE | | + | | | NEGOTIATE_TRANSITIONAL | | + | | | | | + | | | Disallows unsafe | | + | | | renegotiation in | | + | | | server sockets only, | | + | | | but allows clients to | | + | | | continue to | | + | | | renegotiate with | | + | | | vulnerable servers. | | + | | | This value should only | | + | | | be used during the | | + | | | transition period when | | + | | | few servers have been | | + | | | upgraded. | | + | | | | | + | | | - [2|r|R]: | | + | | | SSL_RE | | + | | | NEGOTIATE_REQUIRES_XTN | | + | | | (default) | | + | | | | | + | | | | Only allows | | + | | | renegotiation if the | | + | | | peer's hello bears | | + | | | the TLS | | + | | | renegotiation_info | | + | | | extension. | | + | | | | This is the safe | | + | | | renegotiation. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_SSL_REQU | Boolean | It controls whether | 3.12.5 | + | IRE_SAFE_NEGOTIATION`` | (1 to enable) | safe renegotiation | | + | | | indication is required | | + | | | for initial handshake. | | + | | | In other words a | | + | | | connection will be | | + | | | dropped at initial | | + | | | handshake if a server | | + | | | or client do not | | + | | | support safe | | + | | | renegotiation. The | | + | | | default setting for | | + | | | this option is FALSE. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_SSL_SERVER | Integer | Timeout time to detect | 3.4 | + | _CACHE_MUTEX_TIMEOUT`` | (seconds) | dead or hung process | | + | | | in multi-process SSL | | + | | | server. Default is 30 | | + | | | seconds. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_STRICT_NOFORK`` | String | It is an error to try | 3.12.3 | + | | ("1", | to use a PKCS#11 | | + | | "DISABLED", | crypto module in a | | + | | or any other non-empty | process before it has | | + | | value) | been initialized in | | + | | | that process, even if | | + | | | the module was | | + | | | initialized in the | | + | | | parent process. | | + | | | Beginning in NSS | | + | | | 3.12.3, Softoken will | | + | | | detect this error. | | + | | | This environment | | + | | | variable controls | | + | | | Softoken's response to | | + | | | that error. | | + | | | | | + | | | - If set to "1" or | | + | | | unset, Softoken | | + | | | will trigger an | | + | | | assertion failure | | + | | | in debug builds, | | + | | | and will report an | | + | | | error in non-DEBUG | | + | | | builds. | | + | | | - If set to | | + | | | "DISABLED", | | + | | | Softoken will | | + | | | ignore forks, and | | + | | | behave as it did in | | + | | | older versions. | | + | | | - If set to any other | | + | | | non-empty value, | | + | | | Softoken will | | + | | | report an error in | | + | | | both DEBUG and | | + | | | non-DEBUG builds. | | + +------------------------+------------------------+------------------------+------------------------+ + | ` | String | will trigger an | 3.5 | + | `NSS_STRICT_SHUTDOWN`` | (any non-empty value) | assertion failure in | | + | | | debug builds when a | | + | | | program tries to | | + | | | shutdown NSS before | | + | | | freeing all the | | + | | | resources it acquired | | + | | | from NSS while NSS was | | + | | | initialized. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_TRACE_OCSP`` | Boolean | Enables OCSP tracing. | 3.12 | + | | (any value to enable) | The trace information | | + | | | is written to the file | | + | | | pointed by | | + | | | NSPR_LOG_FILE (default | | + | | | stderr). See `NSS | | + | | | trac | | + | | | ing <http://wiki.mozil | | + | | | la.org/NSS:Tracing>`__ | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_USE_ | Boolean | Tells NSS to send EC | 3.12.3 | + | DECODED_CKA_EC_POINT`` | (any value to enable) | key points across the | | + | | | PKCS#11 interface in | | + | | | the non-standard | | + | | | unencoded format that | | + | | | was used by default | | + | | | before NSS 3.12.3. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_US | Boolean | Tells NSS to allow | 3.12.3 | + | E_SHEXP_IN_CERT_NAME`` | (any value to enable) | shell-style wildcard | | + | | | patterns in | | + | | | certificates to match | | + | | | SSL server host names. | | + | | | This behavior was the | | + | | | default before NSS | | + | | | 3.12.3. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``PKIX_OBJECT_LEA | String | Debug variable for | 3.12 | + | K_TEST_ABORT_ON_LEAK`` | (any non-empty value) | PKIX leak checking. | | + | | | Note: *The code must | | + | | | be built with | | + | | | PKIX_OBJECT_LEAK_TEST | | + | | | defined to use this | | + | | | functionality.* | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SOCKETTRACE`` | Boolean | Controls tracing of | 3.12 | + | | (1 to enable) | socket activity by | | + | | | libPKIX. Messages sent | | + | | | and received will be | | + | | | timestamped and dumped | | + | | | (to stdout) in | | + | | | standard hex-dump | | + | | | format. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SQLITE | Boolean | 1 means force always | 3.12.6 | + | _FORCE_PROXY_LOCKING`` | (1 to enable) | use proxy, 0 means | | + | | | never use proxy, NULL | | + | | | means use proxy for | | + | | | non-local files only. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SSLBYPASS`` | Boolean | Uses PKCS#11 bypass | 3.11 | + | | (1 to enable) | for performance | | + | | | improvement. | | + | | | Do not set this | | + | | | variable if FIPS is | | + | | | enabled. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SSLDEBUG`` | Integer | Debug level | Before 3.0 | + | | | Note: *The code must | | + | | | be built with DEBUG | | + | | | defined to use this | | + | | | functionality.* | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SSLDEBUGFILE`` | String | File where debug or | 3.12 | + | | (file name) | trace information is | | + | | | written. | | + | | | If not set, the debug | | + | | | or trace information | | + | | | is written to stderr. | | + | | | | | + | | | Note: *SSLDEBUG or | | + | | | SSLTRACE have to be | | + | | | set to use this | | + | | | functionality.* | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SSLFORCELOCKS`` | Boolean | Forces NSS to use | 3.11 | + | | (1 to enable) | locks for protection. | | + | | | Overrides the effect | | + | | | of SSL_NO_LOCKS (see | | + | | | ssl.h). | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SSLKEYLOGFILE`` | String | Key log file. If set, | 3.12.6 | + | | (file name) | NSS logs RSA | | + | | | pre-master secrets to | | + | | | this file. This allows | | + | | | packet sniffers to | | + | | | decrypt TLS | | + | | | connections. See | | + | | | :ref:`mozilla_project | | + | | | s_nss_key_log_format`. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``SSLTRACE`` | Integer | Tracing level | Before 3.0 | + | | | Note: *The code must | | + | | | be built with TRACE | | + | | | defined to use this | | + | | | functionality.* | | + +------------------------+------------------------+------------------------+------------------------+ + +.. _build-time_environment_variables: + +`Build-Time Environment Variables <#build-time_environment_variables>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + These environment variables affect the build (compilation) of NSS. + + .. note:: + + **Note: This section is a work in progress and is not yet complete.** + + +------------------------+------------------------+------------------------+------------------------+ + | Variable | Type | Description | Introduced in version | + +------------------------+------------------------+------------------------+------------------------+ + | ``BUILD_OPT`` | Boolean | Do an optimized (not | Before 3.0 | + | | (1 to enable) | DEBUG) build. Default | | + | | | is to do a DEBUG | | + | | | build. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``MOZ_DEBUG_SYMBOLS`` | Boolean | Needed on Windows to | 3.11 | + | | (1 to enable) | build with versions of | | + | | | MSVC (such as VC8 and | | + | | | VC9) that do not | | + | | | understand /PDB:NONE | | + +------------------------+------------------------+------------------------+------------------------+ + | ``MOZ_DEBUG_FLAGS`` | String | When | 3.12.8 | + | | | ``MOZ_DEBUG_SYMBOLS`` | | + | | | is set, you may use | | + | | | ``MOZ_DEBUG_FLAGS`` to | | + | | | specify alternative | | + | | | compiler flags to | | + | | | produce symbolic | | + | | | debugging information | | + | | | in a particular | | + | | | format. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSDISTMODE`` | String | On operating systems | Before 3.0 | + | | | other than Windows, | | + | | | this controls whether | | + | | | copies, absolute | | + | | | symlinks, or relative | | + | | | symlinks of the output | | + | | | files should be | | + | | | published to | | + | | | mozilla/dist. The | | + | | | possible values are: | | + | | | | | + | | | - copy: copies of | | + | | | files are published | | + | | | - absolute_symlink: | | + | | | symlinks whose | | + | | | targets are | | + | | | absolute pathnames | | + | | | are published | | + | | | | | + | | | If not specified, | | + | | | default to relative | | + | | | symlinks (symlinks | | + | | | whose targets are | | + | | | relative pathnames). | | + | | | On Windows, copies of | | + | | | files are always | | + | | | published. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NS_USE_GCC`` | Boolean | On systems where GCC | Before 3.0 | + | | (1 to enable) | is not the default | | + | | | compiler, this tells | | + | | | NSS to build with gcc. | | + +------------------------+------------------------+------------------------+------------------------+ + | `N | Boolean | Enable NSS support in | 3.24 | + | SS_ALLOW_SSLKEYLOGFILE | (1 to enable) | optimized builds for | | + | <https://dxr.mozilla. | | logging SSL/TLS key | | + | org/nss/search?q=NSS_A | | material to a logfile | | + | LLOW_SSLKEYLOGFILE>`__ | | if the SSLKEYLOGFILE | | + | | | environment variable. | | + | | | As of NSS 3.24 this is | | + | | | disabled by default. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_BUI | Boolean | Continue building NSS | 3.12.4 | + | LD_CONTINUE_ON_ERROR`` | (1 to enable) | source directories | | + | | | when a build error | | + | | | occurs. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``N | Boolean | Use the system | 3.12.6 | + | SS_USE_SYSTEM_SQLITE`` | (1 to enable) | installed sqlite | | + | | | library instead of the | | + | | | in-tree version. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_DISA | Boolean | Disable Elliptic Curve | 3.16 | + | BLE_ECC (deprecated)`` | (1 to disable) | Cryptography features. | | + | | | As of NSS 3.16, ECC | | + | | | features are enabled | | + | | | by default. As of NSS | | + | | | 3.33 this variable has | | + | | | no effect. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``NSS_ENA | Boolean | Enable building of | Before 3.16; since | + | BLE_ECC (deprecated)`` | (1 to enable) | code that uses | 3.11. | + | | | Elliptic Curve | | + | | | Cryptography. Unused | | + | | | as of NSS 3.16; see | | + | | | NSS_DISABLE_ECC. | | + +------------------------+------------------------+------------------------+------------------------+ + | ```NSS_FOR | | Boolean | Allows enabling FIPS | 3.24 | + | CE_FIPS`` <https://dxr | | (1 to enable) | mode using | | + | .mozilla.org/nss/searc | | ``NSS_FIPS`` | | + | h?q=NSS_FORCE_FIPS>`__ | | | | + +------------------------+------------------------+------------------------+------------------------+ + | ``OS_TARGET`` | String | For cross-compilation | Before 3.0 | + | | (target OS) | environments only, | | + | | | when the target OS is | | + | | | not the default for | | + | | | the system on which | | + | | | the build is | | + | | | performed. | | + | | | Values understood: | | + | | | WIN95 | | + +------------------------+------------------------+------------------------+------------------------+ + | ``USE_64`` | Boolean | On platforms that has | Before 3.0 | + | | (1 to enable) | separate 32-bit and | | + | | | 64-bit ABIs, NSS | | + | | | builds for the 32-bit | | + | | | ABI by default. This | | + | | | tells NSS to build for | | + | | | the 64-bit ABI. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``USE_DEBUG_RTL`` | Boolean | On Windows, MSVC has | Before 3.0 | + | | (1 to enable) | options to build with | | + | | | a normal Run Time | | + | | | Library or a debug Run | | + | | | Time Library. This | | + | | | tells NSS to build | | + | | | with the Debug Run | | + | | | Time Library. | | + +------------------------+------------------------+------------------------+------------------------+ + | ``USE_PTHREADS`` | Boolean | On platforms where | Before 3.0 | + | | (1 to enable) | POSIX threads are | | + | | | available, but are not | | + | | | the OS'es preferred | | + | | | threads library, this | | + | | | tells NSS and NSPR to | | + | | | build using pthreads. | | + +------------------------+------------------------+------------------------+------------------------+ + | `` | String | Disables at | Before 3.15 | + | NSS_NO_PKCS11_BYPASS`` | (1 to enable) | compile-time the NS | | + | | | ssl code to bypass the | | + | | | pkcs11 layer. When set | | + | | | the SSLBYPASS run-time | | + | | | variable won't take | | + | | | effect | | + +------------------------+------------------------+------------------------+------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_functions/index.rst b/security/nss/doc/rst/legacy/reference/nss_functions/index.rst new file mode 100644 index 0000000000..6793f765b8 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_functions/index.rst @@ -0,0 +1,105 @@ +.. _mozilla_projects_nss_reference_nss_functions: + +NSS functions +============= + +.. container:: + + This page lists all exported functions in NSS 3.11.7 It was ported from + `here <http://www-archive.mozilla.org/projects/security/pki/nss/ref/nssfunctions.html>`__. + + This is a `composite page <http://meta.wikimedia.org/wiki/Help:Template#Composite_pages>`__. + Section headings are links to the individual pages where you can edit them. + + Keywords: + + - Deprecated - function should no longer be used. + - Updated - function has new arguments such as new flag or addition to structure. + +.. _ssl_functions: + +`SSL functions <#ssl_functions>`__ +---------------------------------- + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/SSL_functions")}} + +.. _deprecated_ssl_functions: + +`Deprecated SSL functions <#deprecated_ssl_functions>`__ +-------------------------------------------------------- + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/Deprecated_SSL_functions")}} + +.. _certificate_functions: + +`Certificate functions <#certificate_functions>`__ +-------------------------------------------------- + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/Certificate_functions")}} + +.. _cryptography_functions: + +`Cryptography functions <#cryptography_functions>`__ +---------------------------------------------------- + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/Cryptography_functions")}} + +.. _utility_functions: + +`Utility functions <#utility_functions>`__ +------------------------------------------ + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/Utility_functions")}} + +.. _s.2fmime_functions: + +`S/MIME functions <#s.2fmime_functions>`__ +------------------------------------------ + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/S//MIME_functions")}} + +.. _pkcs_.237_functions: + +`PKCS #7 functions <#pkcs_.237_functions>`__ +-------------------------------------------- + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/PKCS_7_functions")}} + +.. _pkcs_.2312_functions: + +`PKCS #12 functions <#pkcs_.2312_functions>`__ +---------------------------------------------- + +.. container:: + + .. container:: + + {{page("/en-US/docs/NSS/PKCS_12_functions")}}
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_initialize/index.rst b/security/nss/doc/rst/legacy/reference/nss_initialize/index.rst new file mode 100644 index 0000000000..f316e507e4 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_initialize/index.rst @@ -0,0 +1,113 @@ +.. _mozilla_projects_nss_reference_nss_initialize: + +NSS_Initialize +============== + +`Name <#name>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + NSS_Initialize - initialize NSS. + +`Syntax <#syntax>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + SECStatus NSS_Initialize(const char *configdir, + const char *certPrefix, + const char *keyPrefix, + const char *secmodName, + PRUint32 flags); + +`Parameters <#parameters>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSS_Initialize`` has five parameters: + + ``configdir`` + [in] the directory where the certificate, key, and module databases live. To-do: document the + "sql:" prefix. + ``certPrefix`` + [in] prefix added to the beginning of the certificate database, for example, "https-server1-". + ``keyPrefix`` + [in] prefix added to the beginning of the key database, for example, "https-server1-". + ``secmodName`` + [in] name of the security module database, usually "secmod.db". + ``flags`` + [in] bit flags that specify how NSS should be initialized. + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSS_Initialize`` initializes NSS. It is more flexible than ``NSS_Init``, ``NSS_InitReadWrite``, + and ``NSS_NoDB_Init``. If any of those simpler NSS initialization functions suffices for your + needs, call that instead. + + The ``flags`` parameter is a bitwise OR of the following flags: + + - NSS_INIT_READONLY - Open the databases read only. + - NSS_INIT_NOCERTDB - Don't open the cert DB and key DB's, just initialize the volatile certdb. + - NSS_INIT_NOMODDB - Don't open the security module DB, just initialize the PKCS #11 module. + - NSS_INIT_FORCEOPEN - Continue to force initializations even if the databases cannot be opened. + - NSS_INIT_NOROOTINIT - Don't try to look for the root certs module automatically. + - NSS_INIT_OPTIMIZESPACE - Optimize for space instead of speed. Use smaller tables and caches. + - NSS_INIT_PK11THREADSAFE - only load PKCS#11 modules that are thread-safe, i.e., that support + locking - either OS locking or NSS-provided locks . If a PKCS#11 module isn't thread-safe, + don't serialize its calls; just don't load it instead. This is necessary if another piece of + code is using the same PKCS#11 modules that NSS is accessing without going through NSS, for + example, the Java SunPKCS11 provider. + - NSS_INIT_PK11RELOAD - ignore the CKR_CRYPTOKI_ALREADY_INITIALIZED error when loading PKCS#11 + modules. This is necessary if another piece of code is using the same PKCS#11 modules that NSS + is accessing without going through NSS, for example, Java SunPKCS11 provider. + - NSS_INIT_NOPK11FINALIZE - never call C_Finalize on any PKCS#11 module. This may be necessary + in order to ensure continuous operation and proper shutdown sequence if another piece of code + is using the same PKCS#11 modules that NSS is accessing without going through NSS, for + example, Java SunPKCS11 provider. The following limitation applies when this is set + : SECMOD_WaitForAnyTokenEvent will not use C_WaitForSlotEvent, in order to prevent the need + for C_Finalize. This call will be emulated instead. + - NSS_INIT_RESERVED - Currently has no effect, but may be used in the future to trigger better + cooperation between PKCS#11 modules used by both NSS and the Java SunPKCS11 provider. This + should occur after a new flag is defined for C_Initialize by the PKCS#11 working group. + - NSS_INIT_COOPERATE - Sets the above four recommended options for applications that use both + NSS and the Java SunPKCS11 provider. + +.. _return_value: + +`Return value <#return_value>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + ``NSS_Initialize`` returns SECSuccess on success, or SECFailure on failure. + +`Examples <#examples>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. code:: + + #include <nss.h> + + SECStatus rv; + const char *configdir; + + configdir = ...; /* application-specific */ + rv = NSS_Initialize(configdir, "", "", SECMOD_DB, NSS_INIT_NOROOTINIT | NSS_INIT_OPTIMIZESPACE); + +.. _see_also: + +`See also <#see_also>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - NSS_Init, NSS_InitReadWrite, NSS_NoDB_Init, NSS_Shutdown
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_key_functions/index.rst b/security/nss/doc/rst/legacy/reference/nss_key_functions/index.rst new file mode 100644 index 0000000000..5c894bd65b --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_key_functions/index.rst @@ -0,0 +1,60 @@ +.. _mozilla_projects_nss_reference_nss_key_functions: + +NSS Key Functions +================= + +.. container:: + + This chapter describes two functions used to manipulate private keys and key databases such as + the key3.db database provided with NSS. This was converted from `"Chapter 6: Key + Functions" <https://developer.mozilla.org/en-US/docs/NSS/SSL_functions/sslkey.html>`__. + + - :ref:`mozilla_projects_nss_reference` + - `SECKEY_GetDefaultKeyDB <#seckey_getdefaultkeydb>`__ + - `SECKEY_DestroyPrivateKey <#seckey_destroyprivatekey>`__ + + .. rubric:: SECKEY_GetDefaultKeyDB + :name: seckey_getdefaultkeydb + + Returns a handle to the default key database opened by NSS_Init. + + Syntax + + #. include <key.h> + #. include <keyt.h> + + SECKEYKeyDBHandle \*SECKEY_GetDefaultKeyDB(void); + + Returns The function returns a handle of type SECKEYKeyDBHandle. + + Description NSS_Init opens the certificate, key, and security module databases that you specify + for use with NSS. SECKEYKeyDBHandle returns a handle to the key database opened by NSS_Init. + + .. rubric:: SECKEY_DestroyPrivateKey + :name: seckey_destroyprivatekey + + Destroys a private key structure. + + Syntax + + #. include <key.h> + #. include <keyt.h> + + void SECKEY_DestroyPrivateKey(SECKEYPrivateKey \*key); + + Parameter This function has the following parameter: + + key + + A pointer to the private key structure to destroy. + + Description Certificate and key structures are shared objects. When an application makes a copy + of a particular certificate or key structure that already exists in memory, SSL makes a shallow + copy--that is, it increments the reference count for that object rather than making a whole new + copy. When you call CERT_DestroyCertificate or SECKEY_DestroyPrivateKey, the function decrements + the reference count and, if the reference count reaches zero as a result, both frees the memory + and sets all the bits to zero. The use of the word "destroy" in function names or in the + description of a function implies reference counting. + + Never alter the contents of a certificate or key structure. If you attempt to do so, the change + affects all the shallow copies of that structure and can cause severe problems.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools/index.rst new file mode 100644 index 0000000000..f439847286 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools/index.rst @@ -0,0 +1,26 @@ +.. _mozilla_projects_nss_reference_nss_tools: + +NSS Tools Man Pages - work in progress +====================================== + +.. container:: + + certutil :ref:`mozilla_projects_nss_reference_nss_tools_:_certutil` + + pk12util :ref:`mozilla_projects_nss_reference_nss_tools_:_pk12util` + + modutil :ref:`mozilla_projects_nss_reference_nss_tools_:_modutil` + + crlutil :ref:`mozilla_projects_nss_reference_nss_tools_:_crlutil` + + cmsutil :ref:`mozilla_projects_nss_reference_nss_tools_:_cmsutil` + + vfychain :ref:`mozilla_projects_nss_reference_nss_tools_:_vfychain` + + vfyserv :ref:`mozilla_projects_nss_reference_nss_tools_:_vfyserv` + + ssltap :ref:`mozilla_projects_nss_reference_nss_tools_:_ssltab` + + This is still a work in progress and in early stages. + + These man pages where generated from XML docbook files.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__certutil/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__certutil/index.rst new file mode 100644 index 0000000000..2d6aaa3fe3 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__certutil/index.rst @@ -0,0 +1,845 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_certutil: + +NSS tools : certutil +==================== + +.. container:: + + | Name + | certutil — Manage keys and certificate in both NSS databases and other NSS tokens + | Synopsis + | certutil [options] [[arguments]] + | Description + | The Certificate Database Tool, certutil, is a command-line utility + | that can create and modify certificate and key databases. + | It can specifically list, generate, modify, or delete certificates, create or + | change the password, generate new public and private key pairs, + | display the contents of the key database, or delete key pairs within the key database. + | Certificate issuance, part of the key and certificate management process, requires that + | keys and certificates be created in the key database. This document discusses certificate + | and key database management. For information on the security module database management, + | see the modutil manpage. + | Options and Arguments + | Running certutil always requires one and only one command option to + | specify the type of certificate operation. Each option may take arguments, + | anywhere from none to multiple arguments. The command option -H will list + | all the command options available and their relevant arguments. + | Command Options + | -A + | Add an existing certificate to a certificate database. + | The certificate database should already exist; if one is + | not present, this command option will initialize one by default. + | -B + | Run a series of commands from the specified batch file. + | This requires the -i argument. + | -C + | Create a new binary certificate file from a binary + | certificate request file. Use the -i argument to specify + | the certificate request file. If this argument is not + | used, certutil prompts for a filename. + | -D + | Delete a certificate from the certificate database. + + | --rename + | Change the database nickname of a certificate. + + | + | -E + | Add an email certificate to the certificate database. + | -F + | Delete a private key from a key database. Specify the + | key to delete with the -n argument. Specify the database + | from which to delete the key with the -d argument. Use + | the -k argument to specify explicitly whether to delete + | a DSA, RSA, or ECC key. If you don't use the -k + | argument, the option looks for an RSA key matching the + | specified nickname. + | When you delete keys, be sure to also remove any + | certificates associated with those keys from the + | certificate database, by using -D. Some smart cards (for + | example, the Litronic card) do not let you remove a + | public key you have generated. In such a case, only the + | private key is deleted from the key pair. You can + | display the public key with the command certutil -K -h + | tokenname. + | -G + | Generate a new public and private key pair within a key + | database. The key database should already exist; if one + | is not present, this option will initialize one by + | default. Some smart cards (for example, the Litronic + | card) can store only one key pair. If you create a new + | key pair for such a card, the previous pair is + | overwritten. + | -H + | Display a list of the options and arguments used by the + | Certificate Database Tool. + | -K + | List the key ID of keys in the key database. A key ID is + | the modulus of the RSA key or the publicValue of the DSA + | key. IDs are displayed in hexadecimal ("0x" is not + | shown). + | -L + | List all the certificates, or display information about + | a named certificate, in a certificate database. Use the + | -h tokenname argument to specify the certificate + | database on a particular hardware or software token. + | -M + | Modify a certificate's trust attributes using the values + | of the -t argument. + | -N + | Create new certificate and key databases. + | -O + | Print the certificate chain. + | -R + | Create a certificate request file that can be submitted + | to a Certificate Authority (CA) for processing into a + | finished certificate. Output defaults to standard out + | unless you use -o output-file argument. Use the -a + | argument to specify ASCII output. + | -S + | Create an individual certificate and add it to a + | certificate database. + | -T + | Reset the key database or token. + | -U + | List all available modules or print a single named + | module. + | -V + | Check the validity of a certificate and its attributes. + | -W + | Change the password to a key database. + | --merge + | Merge two databases into one. + | --upgrade-merge + | Upgrade an old database and merge it into a new + | database. This is used to migrate legacy NSS databases + | (cert8.db and key3.db) into the newer SQLite databases + | (cert9.db and key4.db). + | Arguments + | Arguments modify a command option and are usually lower case, numbers, or symbols. + | -a + | Use ASCII format or allow the use of ASCII format for + | input or output. This formatting follows RFC 1113. For + | certificate requests, ASCII output defaults to standard + | output unless redirected. + | -b validity-time + | Specify a time at which a certificate is required to be + | valid. Use when checking certificate validity with the + | -V option. The format of the validity-time argument is + | YYMMDDHHMMSS[+HHMM|-HHMM|Z], which allows offsets to be + | set relative to the validity end time. Specifying + | seconds (SS) is optional. When specifying an explicit + | time, use a Z at the end of the term, YYMMDDHHMMSSZ, to + | close it. When specifying an offset time, use + | YYMMDDHHMMSS+HHMM or YYMMDDHHMMSS-HHMM for adding or + | subtracting time, respectively. + | If this option is not used, the validity check defaults + | to the current system time. + | -c issuer + | Identify the certificate of the CA from which a new + | certificate will derive its authenticity. Use the exact + | nickname or alias of the CA certificate, or use the CA's + | email address. Bracket the issuer string with quotation + | marks if it contains spaces. + | -d [prefix]directory + | Specify the database directory containing the + | certificate and key database files. + | certutil supports two types of databases: the legacy + | security databases (cert8.db, key3.db, and secmod.db) + | and new SQLite databases (cert9.db, key4.db, and + | pkcs11.txt). + + NSS recognizes the following prefixes: + + · sql: requests the newer database + + · dbm: requests the legacy database + + | If no prefix is specified the default type is retrieved from NSS_DEFAULT_DB_TYPE. If + NSS_DEFAULT_DB_TYPE is not set + | then dbm: is the default. + + | --dump-ext-val OID + | For single cert, print binary DER encoding of extension OID. + | -e + | Check a certificate's signature during the process of + | validating a certificate. + + | --email email-address + | Specify the email address of a certificate to list. Used with the -L command option. + + | --extGeneric OID:critical-flag:filename[,OID:critical-flag:filename]... + | Add one or multiple extensions that certutil cannot encode yet, by loading their + encodings from external files. + + · OID (example): 1.2.3.4 + + · critical-flag: critical or not-critical + + · filename: full path to a file containing an encoded extension + + | + | -f password-file + | Specify a file that will automatically supply the + | password to include in a certificate or to access a + | certificate database. This is a plain-text file + | containing one password. Be sure to prevent unauthorized + | access to this file. + | -g keysize + | Set a key size to use when generating new public and + | private key pairs. The minimum is 512 bits and the + | maximum is 16384 bits. The default is 2048 bits. Any size + | between the minimum and maximum is allowed. + | -h tokenname + | Specify the name of a token to use or act on. Unless + | specified otherwise the default token is an internal + | slot. + | -i input_file + | Pass an input file to the command. Depending on the + | command option, an input file can be a specific + | certificate, a certificate request file, or a batch file + | of commands. + | -k rsa|dsa|ec|all + | Specify the type of a key. The valid options are RSA, + | DSA, ECC, or all. The default value is rsa. Specifying + | the type of key can avoid mistakes caused by duplicate + | nicknames. + | -k key-type-or-id + | Specify the type or specific ID of a key. + + | The valid key type options are rsa, dsa, ec, or all. The default value is rsa. + Specifying the type of key can avoid + | mistakes caused by duplicate nicknames. Giving a key type generates a new key pair; + giving the ID of an existing key + | reuses that key pair (which is required to renew certificates). + | -l + | Display detailed information when validating a + | certificate with the -V option. + | -m serial-number + | Assign a unique serial number to a certificate being created. This operation should + be performed by a CA. If no + | serial number is provided a default serial number is made from the current time. + Serial numbers are limited to + | integers. + | -n nickname + | Specify the nickname of a certificate or key to list, + | create, add to a database, modify, or validate. Bracket + | the nickname string with quotation marks if it contains + | spaces. + | -o output-file + | Specify the output file name for new certificates or + | binary certificate requests. Bracket the output-file + | string with quotation marks if it contains spaces. If + | this argument is not used the output destination + | defaults to standard output. + | -P dbPrefix + | Specify the prefix used on the certificate and key + | database file. This argument is provided to support + | legacy servers. Most applications do not use a database prefix. + | -p phone + | Specify a contact telephone number to include in new + | certificates or certificate requests. Bracket this + | string with quotation marks if it contains spaces. + | -q pqgfile or curve-name + | Read an alternate PQG value from the specified file when generating DSA key pairs. + | If this argument is not used,certutil generates its own PQG value. PQG files are + created with a separate DSA utility. + + Elliptic curve name is one of the ones from SUITE B: nistp256, nistp384, nistp521 + + | If NSS has been compiled with support curves outside of SUITE B: sect163k1, + nistk163, sect163r1, sect163r2, nistb163, + | sect193r1, sect193r2, sect233k1, nistk233, sect233r1, nistb233, sect239k1, + sect283k1, nistk283, sect283r1, nistb283, + | sect409k1, nistk409, sect409r1, nistb409, sect571k1, nistk571, sect571r1, nistb571, + secp160k1, secp160r1, secp160r2, + | secp192k1, secp192r1, nistp192, secp224k1, secp224r1, nistp224, secp256k1, + secp256r1, secp384r1, secp521r1, + | prime192v1, prime192v2, prime192v3, prime239v1, prime239v2, prime239v3, c2pnb163v1, + c2pnb163v2, c2pnb163v3, + | c2pnb176v1, c2tnb191v1, c2tnb191v2, c2tnb191v3, c2pnb208w1, c2tnb239v1, c2tnb239v2, + c2tnb239v3, c2pnb272w1, + | c2pnb304w1, c2tnb359w1, c2pnb368w1, c2tnb431r1, secp112r1, secp112r2, secp128r1, + secp128r2, sect113r1, sect113r2 + | sect131r1, sect131r2 + + | + | -r + | Display a certificate's binary DER encoding when listing + | information about that certificate with the -L option. + | -s subject + | Identify a particular certificate owner for new + | certificates or certificate requests. Bracket this + | string with quotation marks if it contains spaces. The + | subject identification format follows RFC #1485. + | -t trustargs + | Specify the trust attributes to modify in an existing + | certificate or to apply to a certificate when creating + | it or adding it to a database. There are three available + | trust categories for each certificate, expressed in the + | order SSL, email, object signing for each trust setting. + | In each category position, use none, any, or all of the + | attribute codes: + | + p - Valid peer + | + P - Trusted peer (implies p) + | + c - Valid CA + | + T - Trusted CA to issue client certificates (implies + | c) + | + C - Trusted CA to issue server certificates (SSL only) + | (implies c) + | + u - Certificate can be used for authentication or + | signing + | + w - Send warning (use with other attributes to include + | a warning when the certificate is used in that + | context) + | The attribute codes for the categories are separated by + | commas, and the entire set of attributes enclosed by + | quotation marks. For example: + | -t "TC,C,T" + | Use the -L option to see a list of the current + | certificates and trust attributes in a certificate + | database. + + | Note that the output of the -L option may include "u" flag, which means that there + is a private key associated with + | the certificate. It is a dynamic flag and you cannot set it with certutil. + | -u certusage + | Specify a usage context to apply when validating a + | certificate with the -V option. + | The contexts are the following: + + · C (as an SSL client) + + · V (as an SSL server) + + · L (as an SSL CA) + + · A (as Any CA) + + · Y (Verify CA) + + · S (as an email signer) + + · R (as an email recipient) + + · O (as an OCSP status responder) + + · J (as an object signer) + + | + | -v valid-months + | Set the number of months a new certificate will be + | valid. The validity period begins at the current system + | time unless an offset is added or subtracted with the -w + | option. If this argument is not used, the default + | validity period is three months. When this argument is + | used, the default three-month period is automatically + | added to any value given in the valid-month argument. + | For example, using this option to set a value of 3 would + | cause 3 to be added to the three-month default, creating + | a validity period of six months. You can use negative + | values to reduce the default period. For example, + | setting a value of -2 would subtract 2 from the default + | and create a validity period of one month. + | -w offset-months + | Set an offset from the current system time, in months, + | for the beginning of a certificate's validity period. + | Use when creating the certificate or adding it to a + | database. Express the offset in integers, using a minus + | sign (-) to indicate a negative offset. If this argument + | is not used, the validity period begins at the current + | system time. The length of the validity period is set + | with the -v argument. + | -X + | Force the key and certificate database to open in + | read-write mode. This is used with the -U and -L command + | options. + | -x + | Use certutil to generate the signature for a certificate + | being created or added to a database, rather than + | obtaining a signature from a separate CA. + | -y exp + | Set an alternate exponent value to use in generating a + | new RSA public key for the database, instead of the + | default value of 65537. The available alternate values + | are 3 and 17. + | -z noise-file + | Read a seed value from the specified file to generate a + | new private and public key pair. This argument makes it + | possible to use hardware-generated seed values or + | manually create a value from the keyboard. The minimum + | file size is 20 bytes. + | -0 SSO_password + | Set a site security officer password on a token. + | -1 \| --keyUsage keyword,keyword + | Set a Netscape Certificate Type Extension in the + | certificate. There are several available keywords: + | + digital signature + | + nonRepudiation + | + keyEncipherment + | + dataEncipherment + | + keyAgreement + | + certSigning + | + crlSigning + | + critical + | -2 + | Add a basic constraint extension to a certificate that + | is being created or added to a database. This extension + | supports the certificate chain verification process. + | certutil prompts for the certificate constraint + | extension to select. + | X.509 certificate extensions are described in RFC 5280. + | -3 + | Add an authority key ID extension to a certificate that + | is being created or added to a database. This extension + | supports the identification of a particular certificate, + | from among multiple certificates associated with one + | subject name, as the correct issuer of a certificate. + | The Certificate Database Tool will prompt you to select + | the authority key ID extension. + | X.509 certificate extensions are described in RFC 5280. + | -4 + | Add a CRL distribution point extension to a certificate + | that is being created or added to a database. This + | extension identifies the URL of a certificate's + | associated certificate revocation list (CRL). certutil + | prompts for the URL. + | X.509 certificate extensions are described in RFC 5280. + | -5 \| --nsCertType keyword,keyword + | Add a Netscape certificate type extension to a + | certificate that is being created or added to the + | database. There are several available keywords: + | + sslClient + | + sslServer + | + smime + | + objectSigning + | + sslCA + | + smimeCA + | + objectSigningCA + | + critical + | X.509 certificate extensions are described in RFC 5280. + | -6 \| --extKeyUsage keyword,keyword + | Add an extended key usage extension to a certificate + | that is being created or added to the database. Several + | keywords are available: + | + serverAuth + | + clientAuth + | + codeSigning + | + emailProtection + | + timeStamp + | + ocspResponder + | + stepUp + | + critical + | X.509 certificate extensions are described in RFC 5280. + | -7 emailAddrs + | Add a comma-separated list of email addresses to the + | subject alternative name extension of a certificate or + | certificate request that is being created or added to + | the database. Subject alternative name extensions are + | described in Section 4.2.1.7 of RFC 3280. + | -8 dns-names + | Add a comma-separated list of DNS names to the subject + | alternative name extension of a certificate or + | certificate request that is being created or added to + | the database. Subject alternative name extensions are + | described in Section 4.2.1.7 of RFC 3280. + | --extAIA + | Add the Authority Information Access extension to the + | certificate. X.509 certificate extensions are described + | in RFC 5280. + | --extSIA + | Add the Subject Information Access extension to the + | certificate. X.509 certificate extensions are described + | in RFC 5280. + | --extCP + | Add the Certificate Policies extension to the + | certificate. X.509 certificate extensions are described + | in RFC 5280. + | --extPM + | Add the Policy Mappings extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extPC + | Add the Policy Constraints extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extIA + | Add the Inhibit Any Policy Access extension to the + | certificate. X.509 certificate extensions are described + | in RFC 5280. + | --extSKID + | Add the Subject Key ID extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --source-dir certdir + | Identify the certificate database directory to upgrade. + | --source-prefix certdir + | Give the prefix of the certificate and key databases to + | upgrade. + | --upgrade-id uniqueID + | Give the unique ID of the database to upgrade. + | --upgrade-token-name name + | Set the name of the token to use while it is being + | upgraded. + | -@ pwfile + | Give the name of a password file to use for the database + | being upgraded. + | Usage and Examples + | Most of the command options in the examples listed here have + | more arguments available. The arguments included in these + | examples are the most common ones or are used to illustrate a + | specific scenario. Use the -H option to show the complete list + | of arguments for each command option. + | Creating New Security Databases + | Certificates, keys, and security modules related to managing + | certificates are stored in three related databases: + | \* cert8.db or cert9.db + | \* key3.db or key4.db + | \* secmod.db or pkcs11.txt + | These databases must be created before certificates or keys can + | be generated. + | certutil -N -d [sql:]directory + | Creating a Certificate Request + | A certificate request contains most or all of the information + | that is used to generate the final certificate. This request is + | submitted separately to a certificate authority and is then + | approved by some mechanism (automatically or by human review). + | Once the request is approved, then the certificate is + | generated. + | $ certutil -R -k key-type-or-id [-q pqgfile|curve-name] -g key-size -s s + | ubject [-h tokenname] -d [sql:]directory [-p phone] [-o output-file] [-a + | ] + | The -R command options requires four arguments: + | \* -k to specify either the key type to generate or, when + | renewing a certificate, the existing key pair to use + | \* -g to set the keysize of the key to generate + | \* -s to set the subject name of the certificate + | \* -d to give the security database directory + | The new certificate request can be output in ASCII format (-a) + | or can be written to a specified file (-o). + | For example: + | $ certutil -R -k ec -q nistb409 -g 512 -s "CN=John Smith,O=Example Corp, + | L=Mountain View,ST=California,C=US" -d sql:/home/my/sharednssdb -p 650-5 + | 55-0123 -a -o cert.cer + | Generating key. This may take a few moments... + | Certificate request generated by Netscape + | Phone: 650-555-0123 + | Common Name: John Smith + | Email: (not ed) + | Organization: Example Corp + | State: California + | Country: US + | -----BEGIN NEW CERTIFICATE REQUEST----- + | MIIBIDCBywIBADBmMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEW + | MBQGA1UEBxMNTW91bnRhaW4gVmlldzEVMBMGA1UEChMMRXhhbXBsZSBDb3JwMRMw + | EQYDVQQDEwpKb2huIFNtaXRoMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAMVUpDOZ + | KmHnOx7reP8Cc0Lk+fFWEuYIDX9W5K/BioQOKvEjXyQZhit9aThzBVMoSf1Y1S8J + | CzdUbCg1+IbnXaECAwEAAaAAMA0GCSqGSIb3DQEBBQUAA0EAryqZvpYrUtQ486Ny + | qmtyQNjIi1F8c1Z+TL4uFYlMg8z6LG/J/u1E5t1QqB5e9Q4+BhRbrQjRR1JZx3tB + | 1hP9Gg== + | -----END NEW CERTIFICATE REQUEST----- + | Creating a Certificate + | A valid certificate must be issued by a trusted CA. This can be + | done by specifying a CA certificate (-c) that is stored in the + | certificate database. If a CA key pair is not available, you + | can create a self-signed certificate using the -x argument with + | the -S command option. + | $ certutil -S -k rsa|dsa|ec -n certname -s subject [-c issuer \|-x] -t tr + | ustargs -d [sql:]directory [-m serial-number] [-v valid-months] [-w offs + | et-months] [-p phone] [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 + | emailAddress] [-8 dns-names] [--extAIA] [--extSIA] [--extCP] [--extPM] [ + | --extPC] [--extIA] [--extSKID] + | The series of numbers and --ext\* options set certificate + | extensions that can be added to the certificate when it is + | generated by the CA. + | For example, this creates a self-signed certificate: + | $ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m + | 3650 + | From there, new certificates can reference the self-signed + | certificate: + | $ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" - + | t "u,u,u" -1 -5 -6 -8 -m 730 + | Generating a Certificate from a Certificate Request + | When a certificate request is created, a certificate can be + | generated by using the request and then referencing a + | certificate authority signing certificate (the issuer specified + | in the -c argument). The issuing certificate must be in the + | certificate database in the specified directory. + | certutil -C -c issuer -i cert-request-file -o output-file [-m serial-num + | ber] [-v valid-months] [-w offset-months] -d [sql:]directory [-1] [-2] [ + | -3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names] + | For example: + | $ certutil -C -c "my-ca-cert" -i /home/certs/cert.req -o cert.cer -m 010 + | -v 12 -w 1 -d sql:/home/my/sharednssdb -1 nonRepudiation,dataEncipherme + | nt -5 sslClient -6 clientAuth -7 jsmith@example.com + | Generating Key Pairs + | Key pairs are generated automatically with a certificate + | request or certificate, but they can also be generated + | independently using the -G command option. + | certutil -G -d [sql:]directory \| -h tokenname -k key-type -g key-size [- + | y exponent-value] -q pqgfile|curve-name + | For example: + | $ certutil -G -h lunasa -k ec -g 256 -q sect193r2 + | Listing Certificates + | The -L command option lists all of the certificates listed in + | the certificate database. The path to the directory (-d) is + | required. + | $ certutil -L -d sql:/home/my/sharednssdb + | Certificate Nickname Trust Attri + | butes + | SSL,S/MIME, + | JAR/XPI + | CA Administrator of Instance pki-ca1's Example Domain ID u,u,u + | TPS Administrator's Example Domain ID u,u,u + | Google Internet Authority ,, + | Certificate Authority - Example Domain CT,C,C + | Using additional arguments with -L can return and print the + | information for a single, specific certificate. For example, + | the -n argument passes the certificate name, while the -a + | argument prints the certificate in ASCII format: + | $ certutil -L -d sql:/home/my/sharednssdb -a -n "Certificate Authority - + | Example Domain" + | -----BEGIN CERTIFICATE----- + | MIIDmTCCAoGgAwIBAgIBATANBgkqhkiG9w0BAQUFADA5MRcwFQYDVQQKEw5FeGFt + | cGxlIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTEw + | MDQyOTIxNTY1OFoXDTEyMDQxODIxNTY1OFowOTEXMBUGA1UEChMORXhhbXBsZSBE + | b21haW4xHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTCCASIwDQYJKoZI + | hvcNAQEBBQADggEPADCCAQoCggEBAO/bqUli2KwqXFKmMMG93KN1SANzNTXA/Vlf + | Tmrih3hQgjvR1ktIY9aG6cB7DSKWmtHp/+p4PUCMqL4ZrSGt901qxkePyZ2dYmM2 + | RnelK+SEUIPiUtoZaDhNdiYsE/yuDE8vQWj0vHCVL0w72qFUcSQ/WZT7FCrnUIUI + | udeWnoPSUn70gLhcj/lvxl7K9BHyD4Sq5CzktwYtFWLiiwV+ZY/Fl6JgbGaQyQB2 + | bP4iRMfloGqsxGuB1evWVDF1haGpFDSPgMnEPSLg3/3dXn+HDJbZ29EU8/xKzQEb + | 3V0AHKbu80zGllLEt2Zx/WDIrgJEN9yMfgKFpcmL+BvIRsmh0VsCAwEAAaOBqzCB + | qDAfBgNVHSMEGDAWgBQATgxHQyRUfKIZtdp55bZlFr+tFzAPBgNVHRMBAf8EBTAD + | AQH/MA4GA1UdDwEB/wQEAwIBxjAdBgNVHQ4EFgQUAE4MR0MkVHyiGbXaeeW2ZRa/ + | rRcwRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vbG9jYWxob3N0 + | LmxvY2FsZG9tYWluOjkxODAvY2Evb2NzcDANBgkqhkiG9w0BAQUFAAOCAQEAi8Gk + | L3XO43u7/TDOeEsWPmq+jZsDZ3GZ85Ajt3KROLWeKVZZZa2E2Hnsvf2uXbk5amKe + | lRxdSeRH9g85pv4KY7Z8xZ71NrI3+K3uwmnqkc6t0hhYb1mw/gx8OAAoluQx3biX + | JBDxjI73Cf7XUopplHBjjiwyGIJUO8BEZJ5L+TF4P38MJz1snLtzZpEAX5bl0U76 + | bfu/tZFWBbE8YAWYtkCtMcalBPj6jn2WD3M01kGozW4mmbvsj1cRB9HnsGsqyHCu + | U0ujlL1H/RWcjn607+CTeKH9jLMUqCIqPJNOa+kq/6F7NhNRRiuzASIbZc30BZ5a + | nI7q5n1USM3eWQlVXw== + | -----END CERTIFICATE----- + | Listing Keys + | Keys are the original material used to encrypt certificate + | data. The keys generated for certificates are stored + | separately, in the key database. + | To list all keys in the database, use the -K command option and + | the (required) -d argument to give the path to the directory. + | $ certutil -K -d sql:/home/my/sharednssdb + | certutil: Checking token "NSS Certificate DB" in slot "NSS User Private + | Key and Certificate Services " + | < 0> rsa 455a6673bde9375c2887ec8bf8016b3f9f35861d Thawte Freemail + | Member's Thawte Consulting (Pty) Ltd. ID + | < 1> rsa 40defeeb522ade11090eacebaaf1196a172127df Example Domain + | Administrator Cert + | < 2> rsa 1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5 John Smith user + | cert + | There are ways to narrow the keys listed in the search results: + | \* To return a specific key, use the -n name argument with the + | name of the key. + | \* If there are multiple security devices loaded, then the -h + | tokenname argument can search a specific token or all + | tokens. + | \* If there are multiple key types available, then the -k + | key-type argument can search a specific type of key, like + | RSA, DSA, or ECC. + | Listing Security Modules + | The devices that can be used to store certificates -- both + | internal databases and external devices like smart cards -- are + | recognized and used by loading security modules. The -U command + | option lists all of the security modules listed in the + | secmod.db database. The path to the directory (-d) is required. + | $ certutil -U -d sql:/home/my/sharednssdb + | slot: NSS User Private Key and Certificate Services + | token: NSS Certificate DB + | slot: NSS Internal Cryptographic Services + | token: NSS Generic Crypto Services + | Adding Certificates to the Database + | Existing certificates or certificate requests can be added + | manually to the certificate database, even if they were + | generated elsewhere. This uses the -A command option. + | certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-f + | ile] + | For example: + | $ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/shar + | ednssdb -i /home/example-certs/cert.cer + | A related command option, -E, is used specifically to add email + | certificates to the certificate database. The -E command has + | the same arguments as the -A command. The trust arguments for + | certificates have the format SSL,S/MIME,Code-signing, so the + | middle trust settings relate most to email certificates (though + | the others can be set). For example: + | $ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d sql:/home/my/sh + | arednssdb -i /home/example-certs/email.cer + | Deleting Certificates to the Database + | Certificates can be deleted from a database using the -D + | option. The only required options are to give the security + | database directory and to identify the certificate nickname. + | certutil -D -d [sql:]directory -n "nickname" + | For example: + | $ certutil -D -d sql:/home/my/sharednssdb -n "my-ssl-cert" + | Validating Certificates + | A certificate contains an expiration date in itself, and + | expired certificates are easily rejected. However, certificates + | can also be revoked before they hit their expiration date. + | Checking whether a certificate has been revoked requires + | validating the certificate. Validation can also be used to + | ensure that the certificate is only used for the purposes it + | was initially issued for. Validation is carried out by the -V + | command option. + | certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d [sql:] + | directory + | For example, to validate an email certificate: + | $ certutil -V -n "John Smith's Email Cert" -e -u S,R -d sql:/home/my/sha + | rednssdb + | Modifying Certificate Trust Settings + | The trust settings (which relate to the operations that a + | certificate is allowed to be used for) can be changed after a + | certificate is created or added to the database. This is + | especially useful for CA certificates, but it can be performed + | for any type of certificate. + | certutil -M -n certificate-name -t trust-args -d [sql:]directory + | For example: + | $ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CTu + | ,CTu,CTu" + | Printing the Certificate Chain + | Certificates can be issued in chains because every certificate + | authority itself has a certificate; when a CA issues a + | certificate, it essentially stamps that certificate with its + | own fingerprint. The -O prints the full chain of a certificate, + | going from the initial CA (the root CA) through ever + | intermediary CA to the actual certificate. For example, for an + | email certificate with two CAs in the chain: + | $ certutil -d sql:/home/my/sharednssdb -O -n "jsmith@example.com" + | "Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@ + | thawte.com,CN=Thawte Personal Freemail CA,OU=Certification Services Divi + | sion,O=Thawte Consulting,L=Cape Town,ST=Western Cape,C=ZA] + | "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte P + | ersonal Freemail Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA] + | "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member] + | Resetting a Token + | The device which stores certificates -- both external hardware + | devices and internal software databases -- can be blanked and + | reused. This operation is performed on the device which stores + | the data, not directly on the security databases, so the + | location must be referenced through the token name (-h) as well + | as any directory path. If there is no external token used, the + | default value is internal. + | certutil -T -d [sql:]directory -h token-name -0 security-officer-passwor + | d + | Many networks have dedicated personnel who handle changes to + | security tokens (the security officer). This person must supply + | the password to access the specified token. For example: + | $ certutil -T -d sql:/home/my/sharednssdb -h nethsm -0 secret + | Upgrading or Merging the Security Databases + | Many networks or applications may be using older BerkeleyDB + | versions of the certificate database (cert8.db). Databases can + | be upgraded to the new SQLite version of the database + | (cert9.db) using the --upgrade-merge command option or existing + | databases can be merged with the new cert9.db databases using + | the ---merge command. + | The --upgrade-merge command must give information about the + | original database and then use the standard arguments (like -d) + | to give the information about the new databases. The command + | also requires information that the tool uses for the process to + | upgrade and write over the original database. + | certutil --upgrade-merge -d [sql:]directory [-P dbprefix] --source-dir d + | irectory --source-prefix dbprefix --upgrade-id id --upgrade-token-name n + | ame [-@ password-file] + | For example: + | $ certutil --upgrade-merge -d sql:/home/my/sharednssdb --source-dir /opt + | /my-app/alias/ --source-prefix serverapp- --upgrade-id 1 --upgrade-token + | -name internal + | The --merge command only requires information about the + | location of the original database; since it doesn't change the + | format of the database, it can write over information without + | performing interim step. + | certutil --merge -d [sql:]directory [-P dbprefix] --source-dir directory + | --source-prefix dbprefix [-@ password-file] + | For example: + | $ certutil --merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/ + | alias/ --source-prefix serverapp- + | Running certutil Commands from a Batch File + | A series of commands can be run sequentially from a text file + | with the -B command option. The only argument for this + | specifies the input file. + | $ certutil -B -i /path/to/batch-file + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security + | information. The last versions of these legacy databases are: + | \* cert8.db for certificates + | \* key3.db for keys + | \* secmod.db for PKCS #11 module information + | BerkeleyDB has performance limitations, though, which prevent + | it from being easily used by multiple applications + | simultaneously. NSS has some flexibility that allows + | applications to use their own, independent database engine + | while keeping a shared database and working around the access + | issues. Still, NSS requires more flexibility to provide a truly + | shared security database. + | In 2009, NSS introduced a new set of databases that are SQLite + | databases rather than BerkleyDB. These new databases provide + | more accessibility and performance: + | \* cert9.db for certificates + | \* key4.db for keys + | \* pkcs11.txt, which is listing of all of the PKCS #11 modules + | contained in a new subdirectory in the security databases + | directory + | Because the SQLite databases are designed to be shared, these + | are the shared database type. The shared database type is + | preferred; the legacy format is included for backward + | compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that + | the given security databases follow the more common legacy + | type. Using the SQLite databases must be manually specified by + | using the sql: prefix with the given security directory. For + | example: + | $ certutil -L -d sql:/home/my/sharednssdb + | To set the shared database type as the default type for the + | tools, set the NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the + | change permanent. + | Most applications do not use the shared database by default, + | but they can be configured to use them. For example, this + | how-to article covers how to configure Firefox and Thunderbird + | to use the new shared NSS databases: + | \* https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS + | databases, see the NSS project wiki: + | \* https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | pk12util (1) + | modutil (1) + | certutil has arguments or operations that use features defined + | in several IETF RFCs. + | \* `http://tools.ietf.org/html/rfc5280 <https://datatracker.ietf.org/doc/html/rfc5280>`__ + | \* `http://tools.ietf.org/html/rfc1113 <https://datatracker.ietf.org/doc/html/rfc1113>`__ + | \* `http://tools.ietf.org/html/rfc1485 <https://datatracker.ietf.org/doc/html/rfc1485>`__ + | The NSS wiki has information on the new database design and how + | to configure applications to use it. + | \* https://wiki.mozilla.org/NSS_Shared_DB_Howto + | \* https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like + | JSS), check out the NSS project wiki at + | + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site + | relates directly to NSS code changes and releases. + | Mailing lists: + | https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with + | Netscape, Red Hat, Sun, Oracle, Mozilla, and Google. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + | LICENSE + | Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL was not + distributed with this file, You can + | obtain one at https://mozilla.org/MPL/2.0/. + + | NOTES + | 1. Mozilla NSS bug 836477 + | https://bugzilla.mozilla.org/show_bug.cgi?id=836477 diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__cmsutil/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__cmsutil/index.rst new file mode 100644 index 0000000000..cf7509ffe3 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__cmsutil/index.rst @@ -0,0 +1,192 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_cmsutil: + +NSS tools : cmsutil +=================== + +.. container:: + + Name + + | cmsutil — Performs basic cryptograpic operations, such as encryption and + | decryption, on Cryptographic Message Syntax (CMS) messages. + + Synopsis + + cmsutil [options] `arguments <arguments>`__ + + Description + + | The cmsutil command-line uses the S/MIME Toolkit to perform basic + | operations, such as encryption and decryption, on Cryptographic Message + | Syntax (CMS) messages. + + | To run cmsutil, type the command cmsutil option [arguments] where option + | and arguments are combinations of the options and arguments listed in the + | following section. Each command takes one option. Each option may take + | zero or more arguments. To see a usage string, issue the command without + | options. + + Options and Arguments + + Options + + | Options specify an action. Option arguments modify an action. The options + | and arguments for the cmsutil command are defined as follows: + + -D + + Decode a message. + + -C + + Encrypt a message. + + -E + + Envelope a message. + + -O + + Create a certificates-only message. + + -S + + Sign a message. + + Arguments + + Option arguments modify an action and are lowercase. + + -c content + + Use this detached content (decode only). + + -d dbdir + + Specify the key/certificate database directory (default is ".") + + -e envfile + + | Specify a file containing an enveloped message for a set of + | recipients to which you would like to send an encrypted message. + | If this is the first encrypted message for that set of recipients, + | a new enveloped message will be created that you can then use for + | future messages (encrypt only). + + -G + + Include a signing time attribute (sign only). + + -h num + + Generate email headers with info about CMS message (decode only). + + -i infile + + Use infile as a source of data (default is stdin). + + -N nickname + + Specify nickname of certificate to sign with (sign only). + + -n + + Suppress output of contents (decode only). + + -o outfile + + Use outfile as a destination of data (default is stdout). + + -P + + Include an S/MIME capabilities attribute. + + -p password + + Use password as key database password. + + -r recipient1,recipient2, ... + + | Specify list of recipients (email addresses) for an encrypted or + | enveloped message. For certificates-only message, list of + | certificates to send. + + -T + + Suppress content in CMS message (sign only). + + -u certusage + + Set type of cert usage (default is certUsageEmailSigner). + + -Y ekprefnick + + Specify an encryption key preference by nickname. + + Usage + + Encrypt Example + + cmsutil -C [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, . . ." -e + envfile + + | + | Decode Example + + cmsutil -D [-i infile] [-o outfile] [-d dbdir] [-p password] [-c content] [-n] [-h num] + + | + | Envelope Example + + cmsutil -E [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, ..." + + | + | Certificate-only Example + + cmsutil -O [-i infile] [-o outfile] [-d dbdir] [-p password] -r "cert1,cert2, . . ." + + | + | Sign Message Example + + cmsutil -S [-i infile] [-o outfile] [-d dbdir] [-p password] -N nickname[-TGP] [-Y ekprefnick] + + | + | See also + + certutil(1) + + See Also + + Additional Resources + + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [1]\ http://pki.fedoraproject.org/wiki/. + + | For information specifically about NSS, the NSS project wiki is located at + | [2]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + Copyright + + (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + + References + + | Visible links + | 1. http://pki.fedoraproject.org/wiki/ + | 2. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__crlutil/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__crlutil/index.rst new file mode 100644 index 0000000000..9745be2a0a --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__crlutil/index.rst @@ -0,0 +1,379 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_crlutil: + +NSS tools : crlutil +=================== + +.. container:: + + Name + + | crlutil — List, generate, modify, or delete CRLs within the NSS security + | database file(s) and list, create, modify or delete certificates entries + | in a particular CRL. + + Synopsis + + crlutil [options] `[[arguments]] <arguments>`__ + + | STATUS + | This documentation is still work in progress. Please contribute to the initial review in + Mozilla NSS bug 836477[1] + + Description + + | The Certificate Revocation List (CRL) Management Tool, crlutil, is a + | command-line utility that can list, generate, modify, or delete CRLs + | within the NSS security database file(s) and list, create, modify or + | delete certificates entries in a particular CRL. + + | The key and certificate management process generally begins with creating + | keys in the key database, then generating and managing certificates in the + | certificate database(see certutil tool) and continues with certificates + | expiration or revocation. + + | This document discusses certificate revocation list management. For + | information on security module database management, see Using the Security + | Module Database Tool. For information on certificate and key database + | management, see Using the Certificate Database Tool. + + To run the Certificate Revocation List Management Tool, type the command + + crlutil option [arguments] + + | where options and arguments are combinations of the options and arguments + | listed in the following section. Each command takes one option. Each + | option may take zero or more arguments. To see a usage string, issue the + | command without options, or with the -H option. + + Options and Arguments + + Options + + | Options specify an action. Option arguments modify an action. The options + | and arguments for the crlutil command are defined as follows: + + -G + + Create new Certificate Revocation List(CRL).- + + -D + + Delete Certificate Revocation List from cert database. + + -I + + Import a CRL to the cert database + + -E + + Erase all CRLs of specified type from the cert database + + -L + + List existing CRL located in cert database file. + + -M + + | Modify existing CRL which can be located in cert db or in + | arbitrary file. If located in file it should be encoded in ASN.1 + | encode format. + + -G + + Arguments + + Option arguments modify an action and are lowercase. + + -B + + Bypass CA signature checks. + + -P dbprefix + + | Specify the prefix used on the NSS security database files (for + | example, my_cert8.db and my_key3.db). This option is provided as a + | special case. Changing the names of the certificate and key + | databases is not recommended. + + -a + + | Use ASCII format or allow the use of ASCII format for input and + | output. This formatting follows RFC #1113. + + -c crl-gen-file + + | Specify script file that will be used to control crl + | generation/modification. See crl-cript-file format below. If + | options -M|-G is used and -c crl-script-file is not specified, + | crlutil will read script data from standard input. + + -d directory + + | Specify the database directory containing the certificate and key + | database files. On Unix the Certificate Database Tool defaults to + | $HOME/.netscape (that is, ~/.netscape). On Windows NT the default + | is the current directory. + + The NSS database files must reside in the same directory. + + -i crl-import-file + + Specify the file which contains the CRL to import + + -f password-file + + | Specify a file that will automatically supply the password to + | include in a certificate or to access a certificate database. This + | is a plain-text file containing one password. Be sure to prevent + | unauthorized access to this file. + + -l algorithm-name + + | Specify a specific signature algorithm. List of possible + | algorithms: MD2 \| MD4 \| MD5 \| SHA1 \| SHA256 \| SHA384 \| SHA512 + + -n nickname + + | Specify the nickname of a certificate or key to list, create, add + | to a database, modify, or validate. Bracket the nickname string + | with quotation marks if it contains spaces. + + -o output-file + + | Specify the output file name for new CRL. Bracket the output-file + | string with quotation marks if it contains spaces. If this + | argument is not used the output destination defaults to standard + | output. + + -t crl-type + + | Specify type of CRL. possible types are: 0 - SEC_KRL_TYPE, 1 - + | SEC_CRL_TYPE. This option is obsolete + + -u url + + Specify the url. + + CRL Generation script syntax + + CRL generation script file has the following syntax: + + \* Line with comments should have # as a first symbol of a line + + \* Set "this update" or "next update" CRL fields: + + update=YYYYMMDDhhmmssZ nextupdate=YYYYMMDDhhmmssZ + + | Field "next update" is optional. Time should be in GeneralizedTime format + | (YYYYMMDDhhmmssZ). For example: 20050204153000Z + + \* Add an extension to a CRL or a crl certificate entry: + + addext extension-name critical/non-critical [arg1[arg2 ...]] + + Where: + + | extension-name: string value of a name of known extensions. + | critical/non-critical: is 1 when extension is critical and 0 otherwise. + | arg1, arg2: specific to extension type extension parameters + + | addext uses the range that was set earlier by addcert and will install an + | extension to every cert entries within the range. + + \* Add certificate entries(s) to CRL: + + addcert range date + + | range: two integer values separated by dash: range of certificates that + | will be added by this command. dash is used as a delimiter. Only one cert + | will be added if there is no delimiter. date: revocation date of a cert. + | Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ). + + \* Remove certificate entry(s) from CRL + + rmcert range + + Where: + + | range: two integer values separated by dash: range of certificates that + | will be added by this command. dash is used as a delimiter. Only one cert + | will be added if there is no delimiter. + + \* Change range of certificate entry(s) in CRL + + range new-range + + Where: + + | new-range: two integer values separated by dash: range of certificates + | that will be added by this command. dash is used as a delimiter. Only one + | cert will be added if there is no delimiter. + + Implemented Extensions + + | The extensions defined for CRL provide methods for associating additional + | attributes with CRLs of theirs entries. For more information see RFC #3280 + + \* Add The Authority Key Identifier extension: + + | The authority key identifier extension provides a means of identifying the + | public key corresponding to the private key used to sign a CRL. + + authKeyId critical [key-id \| dn cert-serial] + + Where: + + | authKeyIdent: identifies the name of an extension critical: value of 1 of + | 0. Should be set to 1 if this extension is critical or 0 otherwise. + | key-id: key identifier represented in octet string. dn:: is a CA + | distinguished name cert-serial: authority certificate serial number. + + \* Add Issuer Alternative Name extension: + + | The issuer alternative names extension allows additional identities to be + | associated with the issuer of the CRL. Defined options include an rfc822 + | name (electronic mail address), a DNS name, an IP address, and a URI. + + issuerAltNames non-critical name-list + + Where: + + | subjAltNames: identifies the name of an extension should be set to 0 since + | this is non-critical extension name-list: comma separated list of names + + \* Add CRL Number extension: + + | The CRL number is a non-critical CRL extension which conveys a + | monotonically increasing sequence number for a given CRL scope and CRL + | issuer. This extension allows users to easily determine when a particular + | CRL supersedes another CRL + + crlNumber non-critical number + + Where: + + | crlNumber: identifies the name of an extension critical: should be set to + | 0 since this is non-critical extension number: value of long which + | identifies the sequential number of a CRL. + + \* Add Revocation Reason Code extension: + + | The reasonCode is a non-critical CRL entry extension that identifies the + | reason for the certificate revocation. + + reasonCode non-critical code + + Where: + + | reasonCode: identifies the name of an extension non-critical: should be + | set to 0 since this is non-critical extension code: the following codes + | are available: + + | unspecified (0), keyCompromise (1), cACompromise (2), affiliationChanged + | (3), superseded (4), cessationOfOperation (5), certificateHold (6), + | removeFromCRL (8), privilegeWithdrawn (9), aACompromise (10) + + \* Add Invalidity Date extension: + + | The invalidity date is a non-critical CRL entry extension that provides + | the date on which it is known or suspected that the private key was + | compromised or that the certificate otherwise became invalid. + + invalidityDate non-critical date + + Where: + + | crlNumber: identifies the name of an extension non-critical: should be set + | to 0 since this is non-critical extension date: invalidity date of a cert. + | Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ). + + Usage + + | The Certificate Revocation List Management Tool's capabilities are grouped + | as follows, using these combinations of options and arguments. Options and + | arguments in square brackets are optional, those without square brackets + | are required. + + | See "Implemented extensions" for more information regarding extensions and + | their parameters. + + \* Creating or modifying a CRL: + + crlutil -G|-M -c crl-gen-file -n nickname [-i crl] [-u url] [-d keydir] [-P dbprefix] [-l alg] + [-a] [-B] + + | + | \* Listing all CRls or a named CRL: + + crlutil -L [-n crl-name] [-d krydir] + + | + | \* Deleting CRL from db: + + crlutil -D -n nickname [-d keydir] [-P dbprefix] + + | + | \* Erasing CRLs from db: + + crlutil -E [-d keydir] [-P dbprefix] + + | + | \* Deleting CRL from db: + + crlutil -D -n nickname [-d keydir] [-P dbprefix] + + | + | \* Erasing CRLs from db: + + crlutil -E [-d keydir] [-P dbprefix] + + | + | \* Import CRL from file: + + crlutil -I -i crl [-t crlType] [-u url] [-d keydir] [-P dbprefix] [-B] + + | + | See also + + certutil(1) + + See Also + + Additional Resources + + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [1]\ http://pki.fedoraproject.org/wiki/. + + | For information specifically about NSS, the NSS project wiki is located at + | [2]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape, Red Hat, + | Sun, Oracle, Mozilla, and Google. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + License + + Licensed under the Mozilla Public License, v. 2.0. + + | If a copy of the MPL was not distributed with this file, You can + | obtain one at https://mozilla.org/MPL/2.0/. + + References + + 1. Mozilla NSS bug 836477 - https://bugzilla.mozilla.org/show_bug.cgi?id=836477 + + | Visible links + | 1. http://pki.fedoraproject.org/wiki/ + | 2. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__modutil/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__modutil/index.rst new file mode 100644 index 0000000000..3e88fe0ce5 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__modutil/index.rst @@ -0,0 +1,901 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_modutil: + +NSS tools : modutil +=================== + +.. container:: + + Name + + | modutil - Manage PKCS #11 module information within the security module + | database. + + Synopsis + + modutil [options] [[arguments]] + + STATUS + + This documentation is still work in progress. Please contribute to the initial review in Mozilla + NSS bug 836477[1] + + Description + + | The Security Module Database Tool, modutil, is a command-line utility + | for managing PKCS #11 module information both within secmod.db files and + | within hardware tokens. modutil can add and delete PKCS #11 modules, + | change passwords on security databases, set defaults, list module + | contents, enable or disable slots, enable or disable FIPS 140-2 + | compliance, and assign default providers for cryptographic operations. + | This tool can also create certificate, key, and module security database + | files. + + | The tasks associated with security module database management are part of + | a process that typically also involves managing key databases and + | certificate databases. + + Options + + | Running modutil always requires one (and only one) option to specify the + | type of module operation. Each option may take arguments, anywhere from + | none to multiple arguments. + + Options + + -add modulename + + | Add the named PKCS #11 module to the database. Use this option + | with the -libfile, -ciphers, and -mechanisms arguments. + + -changepw tokenname + + | Change the password on the named token. If the token has not been + | initialized, this option initializes the password. Use this option + | with the -pwfile and -newpwfile arguments. A password is + | equivalent to a personal identification number (PIN). + + -chkfips + + | Verify whether the module is in the given FIPS mode. true means to + | verify that the module is in FIPS mode, while false means to + | verify that the module is not in FIPS mode. + + -create + + | Create new certificate, key, and module databases. Use the -dbdir + | directory argument to specify a directory. If any of these + | databases already exist in a specified directory, modutil returns + | an error message. + + -default modulename + + | Specify the security mechanisms for which the named module will be + | a default provider. The security mechanisms are specified with the + | -mechanisms argument. + + -delete modulename + + | Delete the named module. The default NSS PKCS #11 module cannot be + | deleted. + + -disable modulename + + | Disable all slots on the named module. Use the -slot argument to + | disable a specific slot. + + The internal NSS PKCS #11 module cannot be disabled. + + -enable modulename + + | Enable all slots on the named module. Use the -slot argument to + | enable a specific slot. + + -fips [true \| false] + + | Enable (true) or disable (false) FIPS 140-2 compliance for the + | default NSS module. + + -force + + | Disable modutil's interactive prompts so it can be run from a + | script. Use this option only after manually testing each planned + | operation to check for warnings and to ensure that bypassing the + | prompts will cause no security lapses or loss of + | database integrity. + + -jar JAR-file + + | Add a new PKCS #11 module to the database using the named JAR + | file. Use this command with the -installdir and -tempdir + | arguments. The JAR file uses the NSS PKCS #11 JAR format to + | identify all the files to be installed, the module's name, the + | mechanism flags, and the cipher flags, as well as any files to be + | installed on the target machine, including the PKCS #11 module + | library file and other files such as documentation. This is + | covered in the JAR installation file section in the man page, + | which details the special script needed to perform an installation + | through a server or with modutil. + + -list [modulename] + + | Display basic information about the contents of the secmod.db + | file. Specifying a modulename displays detailed information about + | a particular module and its slots and tokens. + + -rawadd + + Add the module spec string to the secmod.db database. + + -rawlist + + | Display the module specs for a specified module or for all + | loadable modules. + + -undefault modulename + + | Specify the security mechanisms for which the named module will + | not be a default provider. The security mechanisms are specified + | with the -mechanisms argument. + + Arguments + + MODULE + + Give the security module to access. + + MODULESPEC + + Give the security module spec to load into the security database. + + -ciphers cipher-enable-list + + | Enable specific ciphers in a module that is being added to the + | database. The cipher-enable-list is a colon-delimited list of + | cipher names. Enclose this list in quotation marks if it contains + | spaces. + + -dbdir [sql:]directory + + | Specify the database directory in which to access or create + | security module database files. + + | modutil supports two types of databases: the legacy security + | databases (cert8.db, key3.db, and secmod.db) and new SQLite + | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + + --dbprefix prefix + + | Specify the prefix used on the database files, such as my\_ for + | my_cert8.db. This option is provided as a special case. Changing + | the names of the certificate and key databases is not recommended. + + -installdir root-installation-directory + + | Specify the root installation directory relative to which files + | will be installed by the -jar option. This directory should be one + | below which it is appropriate to store dynamic library files, such + | as a server's root directory. + + -libfile library-file + + | Specify a path to a library file containing the implementation of + | the PKCS #11 interface module that is being added to the database. + + -mechanisms mechanism-list + + | Specify the security mechanisms for which a particular module will + | be flagged as a default provider. The mechanism-list is a + | colon-delimited list of mechanism names. Enclose this list in + | quotation marks if it contains spaces. + + | The module becomes a default provider for the listed mechanisms + | when those mechanisms are enabled. If more than one module claims + | to be a particular mechanism's default provider, that mechanism's + | default provider is undefined. + + | modutil supports several mechanisms: RSA, DSA, RC2, RC4, RC5, AES, + | DES, DH, SHA1, SHA256, SHA512, SSL, TLS, MD5, MD2, RANDOM (for + | random number generation), and FRIENDLY (meaning certificates are + | publicly readable). + + -newpwfile new-password-file + + | Specify a text file containing a token's new or replacement + | password so that a password can be entered automatically with the + | -changepw option. + + -nocertdb + + | Do not open the certificate or key databases. This has several + | effects: + + | o With the -create command, only a module security file is + | created; certificate and key databases are not created. + + | o With the -jar command, signatures on the JAR file are not + | checked. + + | o With the -changepw command, the password on the NSS internal + | module cannot be set or changed, since this password is + | stored in the key database. + + -pwfile old-password-file + + | Specify a text file containing a token's existing password so that + | a password can be entered automatically when the -changepw option + | is used to change passwords. + + -secmod secmodname + + | Give the name of the security module database (like secmod.db) to + | load. + + -slot slotname + + | Specify a particular slot to be enabled or disabled with the + | -enable or -disable options. + + -string CONFIG_STRING + + | Pass a configuration string for the module being added to the + | database. + + -tempdir temporary-directory + + | Give a directory location where temporary files are created during + | the installation by the -jar option. If no temporary directory is + | specified, the current directory is used. + + Usage and Examples + + Creating Database Files + + | Before any operations can be performed, there must be a set of security + | databases available. modutil can be used to create these files. The only + | required argument is the database that where the databases will be + | located. + + modutil -create -dbdir [sql:]directory + + Adding a Cryptographic Module + + | Adding a PKCS #11 module means submitting a supporting library file, + | enabling its ciphers, and setting default provider status for various + | security mechanisms. This can be done by supplying all of the information + | through modutil directly or by running a JAR file and install script. For + | the most basic case, simply upload the library: + + modutil -add modulename -libfile library-file [-ciphers cipher-enable-list] [-mechanisms + mechanism-list] + + For example: + + modutil -dbdir sql:/home/my/sharednssdb -add "Example PKCS #11 Module" -libfile "/tmp/crypto.so" + -mechanisms RSA:DSA:RC2:RANDOM + + | Using database directory ... + | Module "Example PKCS #11 Module" added to database. + + Installing a Cryptographic Module from a JAR File + + | PKCS #11 modules can also be loaded using a JAR file, which contains all + | of the required libraries and an installation script that describes how to + | install the module. The JAR install script is described in more detail in + | [1]the section called “JAR Installation File Format”. + + | The JAR installation script defines the setup information for each + | platform that the module can be installed on. For example: + + | Platforms { + | Linux:5.4.08:x86 { + | ModuleName { "Example PKCS #11 Module" } + | ModuleFile { crypto.so } + | DefaultMechanismFlags{0x0000} + | CipherEnableFlags{0x0000} + | Files { + | crypto.so { + | Path{ /tmp/crypto.so } + | } + | setup.sh { + | Executable + | Path{ /tmp/setup.sh } + | } + | } + | } + | Linux:6.0.0:x86 { + | EquivalentPlatform { Linux:5.4.08:x86 } + | } + | } + + | Both the install script and the required libraries must be bundled in a + | JAR file, which is specified with the -jar argument. + + modutil -dbdir sql:/home/mt"jar-install-filey/sharednssdb -jar install.jar -installdir + sql:/home/my/sharednssdb + + | This installation JAR file was signed by: + | ---------------------------------------------- + + \**SUBJECT NAME*\* + + | C=US, ST=California, L=Mountain View, CN=Cryptorific Inc., OU=Digital ID + | Class 3 - Netscape Object Signing, OU="www.verisign.com/repository/CPS + | Incorp. by Ref.,LIAB.LTD(c)9 6", OU=www.verisign.com/CPS Incorp.by Ref + | . LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3 + | Organization, OU="VeriSign, Inc.", O=VeriSign Trust Network \**ISSUER + | NAME**, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 + | VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization, + | OU="VeriSign, Inc.", O=VeriSign Trust Network + | ---------------------------------------------- + + | Do you wish to continue this installation? (y/n) y + | Using installer script "installer_script" + | Successfully parsed installation script + | Current platform is Linux:5.4.08:x86 + | Using installation parameters for platform Linux:5.4.08:x86 + | Installed file crypto.so to /tmp/crypto.so + | Installed file setup.sh to ./pk11inst.dir/setup.sh + | Executing "./pk11inst.dir/setup.sh"... + | "./pk11inst.dir/setup.sh" executed successfully + | Installed module "Example PKCS #11 Module" into module database + + Installation completed successfully + + Adding Module Spec + + | Each module has information stored in the security database about its + | configuration and parameters. These can be added or edited using the + | -rawadd command. For the current settings or to see the format of the + | module spec in the database, use the -rawlist option. + + modutil -rawadd modulespec + + Deleting a Module + + A specific PKCS #11 module can be deleted from the secmod.db database: + + modutil -delete modulename -dbdir [sql:]directory + + Displaying Module Information + + | The secmod.db database contains information about the PKCS #11 modules + | that are available to an application or server to use. The list of all + | modules, information about specific modules, and database configuration + | specs for modules can all be viewed. + + To simply get a list of modules in the database, use the -list command. + + modutil -list [modulename] -dbdir [sql:]directory + + | Listing the modules shows the module name, their status, and other + | associated security databases for certificates and keys. For example: + + modutil -list -dbdir sql:/home/my/sharednssdb + + | Listing of PKCS #11 Modules + | ----------------------------------------------------------- + | 1. NSS Internal PKCS #11 Module + | slots: 2 slots attached + | status: loaded + + | slot: NSS Internal Cryptographic Services + | token: NSS Generic Crypto Services + + | slot: NSS User Private Key and Certificate Services + | token: NSS Certificate DB + | ----------------------------------------------------------- + + | Passing a specific module name with the -list returns details information + | about the module itself, like supported cipher mechanisms, version + | numbers, serial numbers, and other information about the module and the + | token it is loaded on. For example: + + modutil -list "NSS Internal PKCS #11 Module" -dbdir sql:/home/my/sharednssdb + + | ----------------------------------------------------------- + | Name: NSS Internal PKCS #11 Module + | Library file: \**Internal ONLY module*\* + | Manufacturer: Mozilla Foundation + | Description: NSS Internal Crypto Services + | PKCS #11 Version 2.20 + | Library Version: 3.11 + | Cipher Enable Flags: None + | Default Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + + | Slot: NSS Internal Cryptographic Services + | Slot Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + | Manufacturer: Mozilla Foundation + | Type: Software + | Version Number: 3.11 + | Firmware Version: 0.0 + | Status: Enabled + | Token Name: NSS Generic Crypto Services + | Token Manufacturer: Mozilla Foundation + | Token Model: NSS 3 + | Token Serial Number: 0000000000000000 + | Token Version: 4.0 + | Token Firmware Version: 0.0 + | Access: Write Protected + | Login Type: Public (no login required) + | User Pin: NOT Initialized + + | Slot: NSS User Private Key and Certificate Services + | Slot Mechanism Flags: None + | Manufacturer: Mozilla Foundation + | Type: Software + | Version Number: 3.11 + | Firmware Version: 0.0 + | Status: Enabled + | Token Name: NSS Certificate DB + | Token Manufacturer: Mozilla Foundation + | Token Model: NSS 3 + | Token Serial Number: 0000000000000000 + | Token Version: 8.3 + | Token Firmware Version: 0.0 + | Access: NOT Write Protected + | Login Type: Login required + | User Pin: Initialized + + | A related command, -rawlist returns information about the database + | configuration for the modules. (This information can be edited by loading + | new specs using the -rawadd command.) + + | modutil -rawlist -dbdir sql:/home/my/sharednssdb + | name="NSS Internal PKCS #11 Module" parameters="configdir=. certPrefix= keyPrefix= + secmod=secmod.db flags=readOnly " NSS="trustOrder=75 cipherOrder=100 + slotParams={0x00000001=[slotFlags=RSA,RC4,RC2,DES,DH,SHA1,MD5,MD2,SSL,TLS,AES,RANDOM askpw=any + timeout=30 ] } Flags=internal,critical" + + Setting a Default Provider for Security Mechanisms + + | Multiple security modules may provide support for the same security + | mechanisms. It is possible to set a specific security module as the + | default provider for a specific security mechanism (or, conversely, to + | prohibit a provider from supplying those mechanisms). + + modutil -default modulename -mechanisms mechanism-list + + | To set a module as the default provider for mechanisms, use the -default + | command with a colon-separated list of mechanisms. The available + | mechanisms depend on the module; NSS supplies almost all common + | mechanisms. For example: + + modutil -default "NSS Internal PKCS #11 Module" -dbdir -mechanisms RSA:DSA:RC2 + + Using database directory c:\databases... + + Successfully changed defaults. + + Clearing the default provider has the same format: + + modutil -undefault "NSS Internal PKCS #11 Module" -dbdir -mechanisms MD2:MD5 + + Enabling and Disabling Modules and Slots + + | Modules, and specific slots on modules, can be selectively enabled or + | disabled using modutil. Both commands have the same format: + + modutil -enable|-disable modulename [-slot slotname] + + For example: + + modutil -enable "NSS Internal PKCS #11 Module" -slot "NSS Internal Cryptographic Services " + -dbdir . + + Slot "NSS Internal Cryptographic Services " enabled. + + | Be sure that the appropriate amount of trailing whitespace is after the + | slot name. Some slot names have a significant amount of whitespace that + | must be included, or the operation will fail. + + Enabling and Verifying FIPS Compliance + + | The NSS modules can have FIPS 140-2 compliance enabled or disabled using + | modutil with the -fips option. For example: + + modutil -fips true -dbdir sql:/home/my/sharednssdb/ + + FIPS mode enabled. + + | To verify that status of FIPS mode, run the -chkfips command with either a + | true or false flag (it doesn't matter which). The tool returns the current + | FIPS setting. + + modutil -chkfips false -dbdir sql:/home/my/sharednssdb/ + + FIPS mode enabled. + + Changing the Password on a Token + + Initializing or changing a token's password: + + modutil -changepw tokenname [-pwfile old-password-file] [-newpwfile new-password-file] + + modutil -dbdir sql:/home/my/sharednssdb -changepw "NSS Certificate DB" + + | Enter old password: + | Incorrect password, try again... + | Enter old password: + | Enter new password: + | Re-enter new password: + | Token "Communicator Certificate DB" password changed successfully. + + JAR Installation File Format + + | When a JAR file is run by a server, by modutil, or by any program that + | does not interpret JavaScript, a special information file must be included + | to install the libraries. There are several things to keep in mind with + | this file: + + o It must be declared in the JAR archive's manifest file. + + o The script can have any name. + + | o The metainfo tag for this is Pkcs11_install_script. To declare + | meta-information in the manifest file, put it in a file that is passed + | to signtool. + + Sample Script + + | For example, the PKCS #11 installer script could be in the file + | pk11install. If so, the metainfo file for signtool includes a line such as + | this: + + + Pkcs11_install_script: pk11install + + | The script must define the platform and version number, the module name + | and file, and any optional information like supported ciphers and + | mechanisms. Multiple platforms can be defined in a single install file. + + | ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc } + | Platforms { + | WINNT::x86 { + | ModuleName { "Example Module" } + | ModuleFile { win32/fort32.dll } + | DefaultMechanismFlags{0x0001} + | DefaultCipherFlags{0x0001} + | Files { + | win32/setup.exe { + | Executable + | RelativePath { %temp%/setup.exe } + | } + | win32/setup.hlp { + | RelativePath { %temp%/setup.hlp } + | } + | win32/setup.cab { + | RelativePath { %temp%/setup.cab } + | } + | } + | } + | WIN95::x86 { + | EquivalentPlatform {WINNT::x86} + | } + | SUNOS:5.5.1:sparc { + | ModuleName { "Example UNIX Module" } + | ModuleFile { unix/fort.so } + | DefaultMechanismFlags{0x0001} + | CipherEnableFlags{0x0001} + | Files { + | unix/fort.so { + | RelativePath{%root%/lib/fort.so} + | AbsolutePath{/usr/local/netscape/lib/fort.so} + | FilePermissions{555} + | } + | xplat/instr.html { + | RelativePath{%root%/docs/inst.html} + | AbsolutePath{/usr/local/netscape/docs/inst.html} + | FilePermissions{555} + | } + | } + | } + | IRIX:6.2:mips { + | EquivalentPlatform { SUNOS:5.5.1:sparc } + | } + | } + + Script Grammar + + | The script is basic Java, allowing lists, key-value pairs, strings, and + | combinations of all of them. + + --> valuelist + + | valuelist --> value valuelist + | <null> + + | value ---> key_value_pair + | string + + key_value_pair --> key { valuelist } + + key --> string + + | string --> simple_string + | "complex_string" + + simple_string --> [^ \\t\n\""{""}"]+ + + complex_string --> ([^\"\\\r\n]|(\\\")|(\\\\))+ + + | Quotes and backslashes must be escaped with a backslash. A complex string + | must not include newlines or carriage returns.Outside of complex strings, + | all white space (for example, spaces, tabs, and carriage returns) is + | considered equal and is used only to delimit tokens. + + Keys + + | The Java install file uses keys to define the platform and module + | information. + + | ForwardCompatible gives a list of platforms that are forward compatible. + | If the current platform cannot be found in the list of supported + | platforms, then the ForwardCompatible list is checked for any platforms + | that have the same OS and architecture in an earlier version. If one is + | found, its attributes are used for the current platform. + + | Platforms (required) Gives a list of platforms. Each entry in the list is + | itself a key-value pair: the key is the name of the platform and the value + | list contains various attributes of the platform. The platform string is + | in the format system name:OS release:architecture. The installer obtains + | these values from NSPR. OS release is an empty string on non-Unix + | operating systems. NSPR supports these platforms: + + o AIX (rs6000) + + o BSDI (x86) + + o FREEBSD (x86) + + o HPUX (hppa1.1) + + o IRIX (mips) + + o LINUX (ppc, alpha, x86) + + o MacOS (PowerPC) + + o NCR (x86) + + o NEC (mips) + + o OS2 (x86) + + o OSF (alpha) + + o ReliantUNIX (mips) + + o SCO (x86) + + o SOLARIS (sparc) + + o SONY (mips) + + o SUNOS (sparc) + + o UnixWare (x86) + + o WIN16 (x86) + + o WIN95 (x86) + + o WINNT (x86) + + For example: + + | IRIX:6.2:mips + | SUNOS:5.5.1:sparc + | Linux:2.0.32:x86 + | WIN95::x86 + + | The module information is defined independently for each platform in the + | ModuleName, ModuleFile, and Files attributes. These attributes must be + | given unless an EquivalentPlatform attribute is specified. + + Per-Platform Keys + + | Per-platform keys have meaning only within the value list of an entry in + | the Platforms list. + + | ModuleName (required) gives the common name for the module. This name is + | used to reference the module by servers and by the modutil tool. + + | ModuleFile (required) names the PKCS #11 module file for this platform. + | The name is given as the relative path of the file within the JAR archive. + + | Files (required) lists the files that need to be installed for this + | module. Each entry in the file list is a key-value pair. The key is the + | path of the file in the JAR archive, and the value list contains + | attributes of the file. At least RelativePath or AbsolutePath must be + | specified for each file. + + | DefaultMechanismFlags specifies mechanisms for which this module is the + | default provider; this is equivalent to the -mechanism option with the + | -add command. This key-value pair is a bitstring specified in hexadecimal + | (0x) format. It is constructed as a bitwise OR. If the + | DefaultMechanismFlags entry is omitted, the value defaults to 0x0. + + | RSA: 0x00000001 + | DSA: 0x00000002 + | RC2: 0x00000004 + | RC4: 0x00000008 + | DES: 0x00000010 + | DH: 0x00000020 + | FORTEZZA: 0x00000040 + | RC5: 0x00000080 + | SHA1: 0x00000100 + | MD5: 0x00000200 + | MD2: 0x00000400 + | RANDOM: 0x08000000 + | FRIENDLY: 0x10000000 + | OWN_PW_DEFAULTS: 0x20000000 + | DISABLE: 0x40000000 + + | CipherEnableFlags specifies ciphers that this module provides that NSS + | does not provide (so that the module enables those ciphers for NSS). This + | is equivalent to the -cipher argument with the -add command. This key is a + | bitstring specified in hexadecimal (0x) format. It is constructed as a + | bitwise OR. If the CipherEnableFlags entry is omitted, the value defaults + | to 0x0. + + | EquivalentPlatform specifies that the attributes of the named platform + | should also be used for the current platform. This makes it easier when + | more than one platform uses the same settings. + + Per-File Keys + + | Some keys have meaning only within the value list of an entry in a Files + | list. + + | Each file requires a path key the identifies where the file is. Either + | RelativePath or AbsolutePath must be specified. If both are specified, the + | relative path is tried first, and the absolute path is used only if no + | relative root directory is provided by the installer program. + + | RelativePath specifies the destination directory of the file, relative to + | some directory decided at install time. Two variables can be used in the + | relative path: %root% and %temp%. %root% is replaced at run time with the + | directory relative to which files should be installed; for example, it may + | be the server's root directory. The %temp% directory is created at the + | beginning of the installation and destroyed at the end. The purpose of + | %temp% is to hold executable files (such as setup programs) or files that + | are used by these programs. Files destined for the temporary directory are + | guaranteed to be in place before any executable file is run; they are not + | deleted until all executable files have finished. + + | AbsolutePath specifies the destination directory of the file as an + | absolute path. + + | Executable specifies that the file is to be executed during the course of + | the installation. Typically, this string is used for a setup program + | provided by a module vendor, such as a self-extracting setup executable. + | More than one file can be specified as executable, in which case the files + | are run in the order in which they are specified in the script file. + + | FilePermissions sets permissions on any referenced files in a string of + | octal digits, according to the standard Unix format. This string is a + | bitwise OR. + + | user read: 0400 + | user write: 0200 + | user execute: 0100 + | group read: 0040 + | group write: 0020 + | group execute: 0010 + | other read: 0004 + | other write: 0002 + | other execute: 0001 + + | Some platforms may not understand these permissions. They are applied only + | insofar as they make sense for the current platform. If this attribute is + | omitted, a default of 777 is assumed. + + NSS Database Types + + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + + o cert8.db for certificates + + o key3.db for keys + + o secmod.db for PKCS #11 module information + + | BerkeleyDB has performance limitations, though, which prevent it from + | being easily used by multiple applications simultaneously. NSS has some + | flexibility that allows applications to use their own, independent + | database engine while keeping a shared database and working around the + | access issues. Still, NSS requires more flexibility to provide a truly + | shared security database. + + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + + o cert9.db for certificates + + o key4.db for keys + + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + + modutil -create -dbdir sql:/home/my/sharednssdb + + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + + export NSS_DEFAULT_DB_TYPE="sql" + + | This line can be added to the ~/.bashrc file to make the change + | permanent. + + | Most applications do not use the shared database by default, but they can + | be configured to use them. For example, this how-to article covers how to + | configure Firefox and Thunderbird to use the new shared NSS databases: + + o https://wiki.mozilla.org/NSS_Shared_DB_Howto + + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + + o https://wiki.mozilla.org/NSS_Shared_DB + + See Also + + certutil (1) + + pk12util (1) + + signtool (1) + + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + + o https://wiki.mozilla.org/NSS_Shared_DB_Howto + + o https://wiki.mozilla.org/NSS_Shared_DB + + Additional Resources + + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | [2]http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, Sun, Oracle, Mozilla, and Google. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + License + + | Licensed under the Mozilla Public License, v. 2.0. + | If a copy of the MPL was not distributed with this file, + | You can obtain one at https://mozilla.org/MPL/2.0/. + + References + + | 1. Mozilla NSS bug 836477 + | https://bugzilla.mozilla.org/show_bug.cgi?id=836477 + + | Visible links + | 1. JAR Installation File Format + | file:///tmp/xmlto.eUWOJ0/modutil.pro...r-install-file + | 2. http://www.mozilla.org/projects/security/pki/nss/
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__pk12util/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__pk12util/index.rst new file mode 100644 index 0000000000..4c13285f30 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__pk12util/index.rst @@ -0,0 +1,442 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_pk12util: + +NSS tools : pk12util +==================== + +.. container:: + + NSS tools : pk12util + + Name + + | pk12util — Export and import keys and certificate to or from a PKCS #12 + | file and the NSS database + + Synopsis + + pk12util [-i p12File|-l p12File|-o p12File] [-d [sql:]directory] [-h tokenname] [-P dbprefix] + [-r] [-v] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] + + Description + + | The PKCS #12 utility, pk12util, enables sharing certificates among any + | server that supports PKCS#12. The tool can import certificates and keys + | from PKCS#12 files into security databases, export certificates, and list + | certificates and keys. + + Options and Arguments + + Options + + -i p12file + + | Import keys and certificates from a PKCS#12 file into a security + | database. + + -l p12file + + List the keys and certificates in PKCS#12 file. + + -o p12file + + | Export keys and certificates from the security database to a + | PKCS#12 file. + + Arguments + + -c keyCipher + + Specify the key encryption algorithm. + + -C certCipher + + Specify the key cert (overall package) encryption algorithm. + + | + | -d [sql:]directory + + | Specify the database directory into which to import to or export + | from certificates and keys. + + | pk12util supports two types of databases: the legacy security + | databases (cert8.db, key3.db, and secmod.db) and new SQLite + | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + + -h tokenname + + Specify the name of the token to import into or export from. + + -k slotPasswordFile + + Specify the text file containing the slot's password. + + -K slotPassword + + Specify the slot's password. + + -m \| --key-len keyLength + + | Specify the desired length of the symmetric key to be used to + | encrypt the private key. + + -n \| --cert-key-len certKeyLength + + | Specify the desired length of the symmetric key to be used to + | encrypt the certificates and other meta-data. + + -n certname + + Specify the nickname of the cert and private key to export. + + -P prefix + + | Specify the prefix used on the certificate and key databases. This + | option is provided as a special case. Changing the names of the + | certificate and key databases is not recommended. + + -r + + | Dumps all of the data in raw (binary) form. This must be saved as + | a DER file. The default is to return information in a pretty-print + | ASCII format, which displays the information about the + | certificates and public keys in the p12 file. + + -v + + Enable debug logging when importing. + + -w p12filePasswordFile + + Specify the text file containing the pkcs #12 file password. + + -W p12filePassword + + Specify the pkcs #12 file password. + + Return Codes + + o 0 - No error + + o 1 - User Cancelled + + o 2 - Usage error + + o 6 - NLS init error + + o 8 - Certificate DB open error + + o 9 - Key DB open error + + o 10 - File initialization error + + o 11 - Unicode conversion error + + o 12 - Temporary file creation error + + o 13 - PKCS11 get slot error + + o 14 - PKCS12 decoder start error + + o 15 - error read from import file + + o 16 - pkcs12 decode error + + o 17 - pkcs12 decoder verify error + + o 18 - pkcs12 decoder validate bags error + + o 19 - pkcs12 decoder import bags error + + o 20 - key db conversion version 3 to version 2 error + + o 21 - cert db conversion version 7 to version 5 error + + o 22 - cert and key dbs patch error + + o 23 - get default cert db error + + o 24 - find cert by nickname error + + o 25 - create export context error + + o 26 - PKCS12 add password itegrity error + + o 27 - cert and key Safes creation error + + o 28 - PKCS12 add cert and key error + + o 29 - PKCS12 encode error + + Examples + + Importing Keys and Certificates + + | The most basic usage of pk12util for importing a certificate or key is the + | PKCS#12 input file (-i) and some way to specify the security database + | being accessed (either -d for a directory or -h for a token). + + pk12util -i p12File [-h tokenname] [-v] [-d [sql:]directory] [-P dbprefix] [-k + slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] + + For example: + + # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb + + | Enter a password which will be used to encrypt your keys. + | The password should be at least 8 characters long, + | and should contain at least one non-alphabetic character. + + | Enter new password: + | Re-enter password: + | Enter password for PKCS12 file: + | pk12util: PKCS12 IMPORT SUCCESSFUL + + Exporting Keys and Certificates + + | Using the pk12util command to export certificates and keys requires both + | the name of the certificate to extract from the database (-n) and the + | PKCS#12-formatted output file to write to. There are optional parameters + | that can be used to encrypt the file to protect the certificate material. + + pk12util -o p12File -n certname [-c keyCipher] [-C certCipher] [-m|--key_len keyLen] + [-n|--cert_key_len certKeyLen] [-d [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K + slotPassword] [-w p12filePasswordFile|-W p12filePassword] + + For example: + + | # pk12util -o certs.p12 -n Server-Cert -d sql:/home/my/sharednssdb + | Enter password for PKCS12 file: + | Re-enter password: + + Listing Keys and Certificates + + | The information in a .p12 file are not human-readable. The certificates + | and keys in the file can be printed (listed) in a human-readable + | pretty-print format that shows information for every certificate and any + | public keys in the .p12 file. + + pk12util -l p12File [-h tokenname] [-r] [-d [sql:]directory] [-P dbprefix] [-k + slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] + + For example, this prints the default ASCII output: + + # pk12util -l certs.p12 + + | Enter password for PKCS12 file: + | Key(shrouded): + | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID + + | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC + | Parameters: + | Salt: + | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f + | Iteration Count: 1 (0x1) + | Certificate: + | Data: + | Version: 3 (0x2) + | Serial Number: 13 (0xd) + | Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption + | Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C + | A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T + | own,ST=Western Cape,C=ZA" + + | Alternatively, the -r prints the certificates and then exports them into + | separate DER binary files. This allows the certificates to be fed to + | another application that supports .p12 files. Each certificate is written + | to a sequentially-number file, beginning with file0001.der and continuing + | through file000N.der, incrementing the number for every certificate: + + | # pk12util -l test.p12 -r + | Enter password for PKCS12 file: + | Key(shrouded): + | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID + + | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC + | Parameters: + | Salt: + | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f + | Iteration Count: 1 (0x1) + | Certificate Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting + + Certificate Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID + + Password Encryption + + | PKCS#12 provides for not only the protection of the private keys but also + | the certificate and meta-data associated with the keys. Password-based + | encryption is used to protect private keys on export to a PKCS#12 file + | and, optionally, the entire package. If no algorithm is specified, the + | tool defaults to using PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc for + | private key encryption. PKCS12 V2 PBE with SHA1 and 40 Bit RC4 is the + | default for the overall package encryption when not in FIPS mode. When in + | FIPS mode, there is no package encryption. + + The private key is always protected with strong encryption by default. + + Several types of ciphers are supported. + + Symmetric CBC ciphers for PKCS#5 V2 + + o DES-CBC + + o RC2-CBC + + o RC5-CBCPad + + o DES-EDE3-CBC (the default for key encryption) + + o AES-128-CBC + + o AES-192-CBC + + o AES-256-CBC + + o CAMELLIA-128-CBC + + o CAMELLIA-192-CBC + + o CAMELLIA-256-CBC + + PKCS#12 PBE ciphers + + o PKCS #12 PBE with Sha1 and 128 Bit RC4 + + o PKCS #12 PBE with Sha1 and 40 Bit RC4 + + o PKCS #12 PBE with Sha1 and Triple DES CBC + + o PKCS #12 PBE with Sha1 and 128 Bit RC2 CBC + + o PKCS #12 PBE with Sha1 and 40 Bit RC2 CBC + + o PKCS12 V2 PBE with SHA1 and 128 Bit RC4 + + | o PKCS12 V2 PBE with SHA1 and 40 Bit RC4 (the default for + | non-FIPS mode) + + o PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc + + o PKCS12 V2 PBE with SHA1 and 2KEY Triple DES-cbc + + o PKCS12 V2 PBE with SHA1 and 128 Bit RC2 CBC + + o PKCS12 V2 PBE with SHA1 and 40 Bit RC2 CBC + + PKCS#5 PBE ciphers + + o PKCS #5 Password Based Encryption with MD2 and DES CBC + + o PKCS #5 Password Based Encryption with MD5 and DES CBC + + o PKCS #5 Password Based Encryption with SHA1 and DES CBC + + | With PKCS#12, the crypto provider may be the soft token module or an + | external hardware module. If the cryptographic module does not support the + | requested algorithm, then the next best fit will be selected (usually the + | default). If no suitable replacement for the desired algorithm can be + | found, the tool returns the error no security module can perform the + | requested operation. + + NSS Database Types + + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + + o cert8.db for certificates + + o key3.db for keys + + o secmod.db for PKCS #11 module information + + | BerkeleyDB has performance limitations, though, which prevent it from + | being easily used by multiple applications simultaneously. NSS has some + | flexibility that allows applications to use their own, independent + | database engine while keeping a shared database and working around the + | access issues. Still, NSS requires more flexibility to provide a truly + | shared security database. + + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + + o cert9.db for certificates + + o key4.db for keys + + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + + # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb + + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + + export NSS_DEFAULT_DB_TYPE="sql" + + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + + | Most applications do not use the shared database by default, but they can + | be configured to use them. For example, this how-to article covers how to + | configure Firefox and Thunderbird to use the new shared NSS databases: + + o https://wiki.mozilla.org/NSS_Shared_DB_Howto + + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + + o https://wiki.mozilla.org/NSS_Shared_DB + + See Also + + certutil (1) + + modutil (1) + + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + + o https://wiki.mozilla.org/NSS_Shared_DB_Howto + + o https://wiki.mozilla.org/NSS_Shared_DB + + Additional Resources + + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | [1]http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, Sun, Oracle, Mozilla, and Google. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + License + + | Licensed under the Mozilla Public License, v. 2.0. + | If a copy of the MPL was not distributed with this file, + | You can obtain one at https://mozilla.org/MPL/2.0/. + + References + + | 1. Mozilla NSS bug 836477 + | https://bugzilla.mozilla.org/show_bug.cgi?id=836477
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__ssltab/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__ssltab/index.rst new file mode 100644 index 0000000000..3ef0db4039 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__ssltab/index.rst @@ -0,0 +1,573 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_ssltab: + +NSS tools : ssltab +================== + +.. container:: + + Name + + ssltap — Tap into SSL connections and display the data going by + + Synopsis + + libssltap [-vhfsxl] [-p port] [hostname:port] + + Description + + | The SSL Debugging Tool ssltap is an SSL-aware command-line proxy. It + | watches TCP connections and displays the data going by. If a connection is + | SSL, the data display includes interpreted SSL records and handshaking + + Options + + -v + + Print a version string for the tool. + + -h + + | Turn on hex/ASCII printing. Instead of outputting raw data, the + | command interprets each record as a numbered line of hex values, + | followed by the same data as ASCII characters. The two parts are + | separated by a vertical bar. Nonprinting characters are replaced + | by dots. + + -f + + | Turn on fancy printing. Output is printed in colored HTML. Data + | sent from the client to the server is in blue; the server's reply + | is in red. When used with looping mode, the different connections + | are separated with horizontal lines. You can use this option to + | upload the output into a browser. + + -s + + | Turn on SSL parsing and decoding. The tool does not automatically + | detect SSL sessions. If you are intercepting an SSL connection, + | use this option so that the tool can detect and decode SSL + | structures. + + | If the tool detects a certificate chain, it saves the DER-encoded + | certificates into files in the current directory. The files are + | named cert.0x, where x is the sequence number of the certificate. + + | If the -s option is used with -h, two separate parts are printed + | for each record: the plain hex/ASCII output, and the parsed SSL + | output. + + -x + + | Turn on hex/ASCII printing of undecoded data inside parsed SSL + | records. Used only with the -s option. This option uses the same + | output format as the -h option. + + -l prefix + + | Turn on looping; that is, continue to accept connections rather + | than stopping after the first connection is complete. + + -p port + + Change the default rendezvous port (1924) to another port. + + The following are well-known port numbers: + + \* HTTP 80 + + \* HTTPS 443 + + \* SMTP 25 + + \* FTP 21 + + \* IMAP 143 + + \* IMAPS 993 (IMAP over SSL) + + \* NNTP 119 + + \* NNTPS 563 (NNTP over SSL) + + Usage and Examples + + | You can use the SSL Debugging Tool to intercept any connection + | information. Although you can run the tool at its most basic by issuing + | the ssltap command with no options other than hostname:port, the + | information you get in this way is not very useful. For example, assume + | your development machine is called intercept. The simplest way to use the + | debugging tool is to execute the following command from a command shell: + + $ ssltap www.netscape.com + + | The program waits for an incoming connection on the default port 1924. In + | your browser window, enter the URL http://intercept:1924. The browser + | retrieves the requested page from the server at www.netscape.com, but the + | page is intercepted and passed on to the browser by the debugging tool on + | intercept. On its way to the browser, the data is printed to the command + | shell from which you issued the command. Data sent from the client to the + | server is surrounded by the following symbols: --> [ data ] Data sent from + | the server to the client is surrounded by the following symbols: "left + | arrow"-- [ data ] The raw data stream is sent to standard output and is + | not interpreted in any way. This can result in peculiar effects, such as + | sounds, flashes, and even crashes of the command shell window. To output a + | basic, printable interpretation of the data, use the -h option, or, if you + | are looking at an SSL connection, the -s option. You will notice that the + | page you retrieved looks incomplete in the browser. This is because, by + | default, the tool closes down after the first connection is complete, so + | the browser is not able to load images. To make the tool continue to + | accept connections, switch on looping mode with the -l option. The + | following examples show the output from commonly used combinations of + | options. + + Example 1 + + $ ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt + + Output + + | Connected to interzone.mcom.com:443 + | -->; [ + | alloclen = 66 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 39 (0x27) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | (0x000006) SSL3/RSA/RC2CBC40/MD5 + | } + | session-id = { } + | challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 + + | 0x2592 } + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 03 e5 \|..... + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | 0: 02 00 00 46 \|...F + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 \| + | wn&l.ì..XOG.-.E + | 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f \| + + | \\.uC§L.Ç.d<PAHO. + | session ID = { + | length = 32 + + | contents = {..} + | 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 \| ...¨*1.)..@7W.§2 + | 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 \| VoRbþ=³e±...R£È. + | } + | cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + | } + | 0: 0b 00 02 c5 \|...Å + | type = 11 (certificate) + | length = 709 (0x0002c5) + | CertificateChain { + | chainlength = 706 (0x02c2) + | Certificate { + | size = 703 (0x02bf) + | data = { saved in file 'cert.001' } + | } + | } + | 0: 0c 00 00 ca \|.... + | type = 12 (server_key_exchange) + | length = 202 (0x0000ca) + | 0: 0e 00 00 00 \|.... + | type = 14 (server_hello_done) + | length = 0 (0x000000) + | } + | } + | ] + | --> [ + | SSLRecord { + | 0: 16 03 00 00 44 \|....D + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | 0: 10 00 00 40 \|...@ + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + + | } + | ] + | <-- [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + + | } + | ] + | --> [ + | SSLRecord { + | 0: 17 03 00 01 1f \|..... + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 a0 \|.... + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | < encrypted > + + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 df \|....ß + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | < encrypted > + + | } + | SSLRecord { + | 0: 15 03 00 00 12 \|..... + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | < encrypted > + | } + | ] + | Server socket closed. + + Example 2 + + | The -s option turns on SSL parsing. Because the -x option is not used in + | this example, undecoded values are output as raw data. The output is + | routed to a text file. + + $ ssltap -s -p 444 interzone.mcom.com:443 > s.txt + + Output + + | Connected to interzone.mcom.com:443 + | --> [ + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c + | 0x3fd0 } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | session ID = { + | length = 32 + | contents = {..} + | } + | cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + | } + | type = 11 (certificate) + | length = 709 (0x0002c5) + | CertificateChain { + | chainlength = 706 (0x02c2) + | Certificate { + | size = 703 (0x02bf) + | data = { saved in file 'cert.001' } + | } + | } + | type = 12 (server_key_exchange) + | length = 202 (0x0000ca) + | type = 14 (server_hello_done) + | length = 0 (0x000000) + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | --> [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | > encrypted > + | } + | ] + | [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | > encrypted > + | } + | SSLRecord { + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | > encrypted > + | } + | ] + | Server socket closed. + + Example 3 + + | In this example, the -h option turns hex/ASCII format. There is no SSL + | parsing or decoding. The output is routed to a text file. + + $ ssltap -h -p 444 interzone.mcom.com:443 > h.txt + + Output + + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 \| .@....'......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 \| ........á....... + | 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 \| ..þ[V.I.\xd9 ...º¹R + | 40: 6f 2d \|o- + | ] + | <-- [ + | 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d \| ........F....... + | 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b \| h.:y`..<..³.Òi; + | 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 \| x.K.¦R.KFè. ... + | 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 \| MR.ý..QH.....¶vw + | 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b \| \*ô..¡.a¢d...... + | 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 \| ..Å......0...0.. + | 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 \| $ .......60...*. + | 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 \| H.÷......0w1.0.. + | 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 \| .U....US1,0*..U. + | 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d \| ..#Netscape Comm + | a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f \| unications Corpo + | b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 \| ration1.0...U... + | c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 \| .Hardcore1'0%..U + | d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 \| ....Hardcore Cer + | e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 \| tificate Server + | f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 \| II0...9805160103 + | <additional data lines> + | ] + | <additional records in same format> + | Server socket closed. + + Example 4 + + | In this example, the -s option turns on SSL parsing, and the -h option + | turns on hex/ASCII format. Both formats are shown for each record. The + | output is routed to a text file. + + $ ssltap -hs -p 444 interzone.mcom.com:443 > hs.txt + + Output + + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 \| .=....$......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 \| ........á....... + | 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 \|U..yÇ\xb0 ,.x.]µÏé + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db + + | 0xcfe9 } + | } + | ] + | <additional records in same formats> + | Server socket closed. + + Usage Tips + + | When SSL restarts a previous session, it makes use of cached information + | to do a partial handshake. If you wish to capture a full SSL handshake, + | restart the browser to clear the session id cache. + + | If you run the tool on a machine other than the SSL server to which you + | are trying to connect, the browser will complain that the host name you + | are trying to connect to is different from the certificate. If you are + | using the default BadCert callback, you can still connect through a + | dialog. If you are not using the default BadCert callback, the one you + | supply must allow for this possibility. + + See Also + + | The NSS Security Tools are also documented at + | [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + + Additional Resources + + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [2]\ http://pki.fedoraproject.org/wiki/. + + | For information specifically about NSS, the NSS project wiki is located at + | [3]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat and Sun. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + Copyright + + (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + + References + + | Visible links + | 1. + `http://www.mozilla.org/projects/secu.../pki/nss/tools <https://www.mozilla.org/projects/security/pki/nss/tools>`__ + | 2. http://pki.fedoraproject.org/wiki/ + | 3. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__ssltap/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__ssltap/index.rst new file mode 100644 index 0000000000..64543cf7a3 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__ssltap/index.rst @@ -0,0 +1,573 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_ssltap: + +NSS tools : ssltap +================== + +.. container:: + + Name + + ssltap — Tap into SSL connections and display the data going by + + Synopsis + + libssltap [-vhfsxl] [-p port] [hostname:port] + + Description + + | The SSL Debugging Tool ssltap is an SSL-aware command-line proxy. It + | watches TCP connections and displays the data going by. If a connection is + | SSL, the data display includes interpreted SSL records and handshaking + + Options + + -v + + Print a version string for the tool. + + -h + + | Turn on hex/ASCII printing. Instead of outputting raw data, the + | command interprets each record as a numbered line of hex values, + | followed by the same data as ASCII characters. The two parts are + | separated by a vertical bar. Nonprinting characters are replaced + | by dots. + + -f + + | Turn on fancy printing. Output is printed in colored HTML. Data + | sent from the client to the server is in blue; the server's reply + | is in red. When used with looping mode, the different connections + | are separated with horizontal lines. You can use this option to + | upload the output into a browser. + + -s + + | Turn on SSL parsing and decoding. The tool does not automatically + | detect SSL sessions. If you are intercepting an SSL connection, + | use this option so that the tool can detect and decode SSL + | structures. + + | If the tool detects a certificate chain, it saves the DER-encoded + | certificates into files in the current directory. The files are + | named cert.0x, where x is the sequence number of the certificate. + + | If the -s option is used with -h, two separate parts are printed + | for each record: the plain hex/ASCII output, and the parsed SSL + | output. + + -x + + | Turn on hex/ASCII printing of undecoded data inside parsed SSL + | records. Used only with the -s option. This option uses the same + | output format as the -h option. + + -l prefix + + | Turn on looping; that is, continue to accept connections rather + | than stopping after the first connection is complete. + + -p port + + Change the default rendezvous port (1924) to another port. + + The following are well-known port numbers: + + \* HTTP 80 + + \* HTTPS 443 + + \* SMTP 25 + + \* FTP 21 + + \* IMAP 143 + + \* IMAPS 993 (IMAP over SSL) + + \* NNTP 119 + + \* NNTPS 563 (NNTP over SSL) + + Usage and Examples + + | You can use the SSL Debugging Tool to intercept any connection + | information. Although you can run the tool at its most basic by issuing + | the ssltap command with no options other than hostname:port, the + | information you get in this way is not very useful. For example, assume + | your development machine is called intercept. The simplest way to use the + | debugging tool is to execute the following command from a command shell: + + $ ssltap www.netscape.com + + | The program waits for an incoming connection on the default port 1924. In + | your browser window, enter the URL http://intercept:1924. The browser + | retrieves the requested page from the server at www.netscape.com, but the + | page is intercepted and passed on to the browser by the debugging tool on + | intercept. On its way to the browser, the data is printed to the command + | shell from which you issued the command. Data sent from the client to the + | server is surrounded by the following symbols: --> [ data ] Data sent from + | the server to the client is surrounded by the following symbols: "left + | arrow"-- [ data ] The raw data stream is sent to standard output and is + | not interpreted in any way. This can result in peculiar effects, such as + | sounds, flashes, and even crashes of the command shell window. To output a + | basic, printable interpretation of the data, use the -h option, or, if you + | are looking at an SSL connection, the -s option. You will notice that the + | page you retrieved looks incomplete in the browser. This is because, by + | default, the tool closes down after the first connection is complete, so + | the browser is not able to load images. To make the tool continue to + | accept connections, switch on looping mode with the -l option. The + | following examples show the output from commonly used combinations of + | options. + + Example 1 + + $ ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt + + Output + + | Connected to interzone.mcom.com:443 + | -->; [ + | alloclen = 66 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 39 (0x27) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | (0x000006) SSL3/RSA/RC2CBC40/MD5 + | } + | session-id = { } + | challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 + + | 0x2592 } + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 03 e5 \|..... + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | 0: 02 00 00 46 \|...F + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 \| + | wn&l.ì..XOG.-.E + | 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f \| + + | \\.uC§L.Ç.d<PAHO. + | session ID = { + | length = 32 + + | contents = {..} + | 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 \| ...¨*1.)..@7W.§2 + | 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 \| VoRbþ=³e±...R£È. + | } + | cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + | } + | 0: 0b 00 02 c5 \|...Å + | type = 11 (certificate) + | length = 709 (0x0002c5) + | CertificateChain { + | chainlength = 706 (0x02c2) + | Certificate { + | size = 703 (0x02bf) + | data = { saved in file 'cert.001' } + | } + | } + | 0: 0c 00 00 ca \|.... + | type = 12 (server_key_exchange) + | length = 202 (0x0000ca) + | 0: 0e 00 00 00 \|.... + | type = 14 (server_hello_done) + | length = 0 (0x000000) + | } + | } + | ] + | --> [ + | SSLRecord { + | 0: 16 03 00 00 44 \|....D + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | 0: 10 00 00 40 \|...@ + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + + | } + | ] + | <-- [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + + | } + | ] + | --> [ + | SSLRecord { + | 0: 17 03 00 01 1f \|..... + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 a0 \|.... + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | < encrypted > + + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 df \|....ß + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | < encrypted > + + | } + | SSLRecord { + | 0: 15 03 00 00 12 \|..... + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | < encrypted > + | } + | ] + | Server socket closed. + + Example 2 + + | The -s option turns on SSL parsing. Because the -x option is not used in + | this example, undecoded values are output as raw data. The output is + | routed to a text file. + + $ ssltap -s -p 444 interzone.mcom.com:443 > s.txt + + Output + + | Connected to interzone.mcom.com:443 + | --> [ + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c + | 0x3fd0 } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | session ID = { + | length = 32 + | contents = {..} + | } + | cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + | } + | type = 11 (certificate) + | length = 709 (0x0002c5) + | CertificateChain { + | chainlength = 706 (0x02c2) + | Certificate { + | size = 703 (0x02bf) + | data = { saved in file 'cert.001' } + | } + | } + | type = 12 (server_key_exchange) + | length = 202 (0x0000ca) + | type = 14 (server_hello_done) + | length = 0 (0x000000) + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | --> [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | > encrypted > + | } + | ] + | [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | > encrypted > + | } + | SSLRecord { + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | > encrypted > + | } + | ] + | Server socket closed. + + Example 3 + + | In this example, the -h option turns hex/ASCII format. There is no SSL + | parsing or decoding. The output is routed to a text file. + + $ ssltap -h -p 444 interzone.mcom.com:443 > h.txt + + Output + + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 \| .@....'......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 \| ........á....... + | 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 \| ..þ[V.I.\xd9 ...º¹R + | 40: 6f 2d \|o- + | ] + | <-- [ + | 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d \| ........F....... + | 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b \| h.:y`..<..³.Òi; + | 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 \| x.K.¦R.KFè. ... + | 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 \| MR.ý..QH.....¶vw + | 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b \| \*ô..¡.a¢d...... + | 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 \| ..Å......0...0.. + | 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 \| $ .......60...*. + | 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 \| H.÷......0w1.0.. + | 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 \| .U....US1,0*..U. + | 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d \| ..#Netscape Comm + | a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f \| unications Corpo + | b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 \| ration1.0...U... + | c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 \| .Hardcore1'0%..U + | d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 \| ....Hardcore Cer + | e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 \| tificate Server + | f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 \| II0...9805160103 + | <additional data lines> + | ] + | <additional records in same format> + | Server socket closed. + + Example 4 + + | In this example, the -s option turns on SSL parsing, and the -h option + | turns on hex/ASCII format. Both formats are shown for each record. The + | output is routed to a text file. + + $ ssltap -hs -p 444 interzone.mcom.com:443 > hs.txt + + Output + + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 \| .=....$......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 \| ........á....... + | 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 \|U..yÇ\xb0 ,.x.]µÏé + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db + + | 0xcfe9 } + | } + | ] + | <additional records in same formats> + | Server socket closed. + + Usage Tips + + | When SSL restarts a previous session, it makes use of cached information + | to do a partial handshake. If you wish to capture a full SSL handshake, + | restart the browser to clear the session id cache. + + | If you run the tool on a machine other than the SSL server to which you + | are trying to connect, the browser will complain that the host name you + | are trying to connect to is different from the certificate. If you are + | using the default BadCert callback, you can still connect through a + | dialog. If you are not using the default BadCert callback, the one you + | supply must allow for this possibility. + + See Also + + | The NSS Security Tools are also documented at + | [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + + Additional Resources + + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [2]\ http://pki.fedoraproject.org/wiki/. + + | For information specifically about NSS, the NSS project wiki is located at + | [3]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat and Sun. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + Copyright + + (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + + References + + | Visible links + | 1. + `http://www.mozilla.org/projects/secu.../pki/nss/tools <https://www.mozilla.org/projects/security/pki/nss/tools>`__ + | 2. http://pki.fedoraproject.org/wiki/ + | 3. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__vfychain/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__vfychain/index.rst new file mode 100644 index 0000000000..e6d92ccd47 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__vfychain/index.rst @@ -0,0 +1,132 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_vfychain: + +NSS tools : vfychain +==================== + +.. container:: + + Name + + | vfychain — vfychain [options] [revocation options] certfile [[options] + | certfile] ... + + Synopsis + + vfychain + + Description + + | The verification Tool, vfychain, verifies certificate chains. modutil can + | add and delete PKCS #11 modules, change passwords on security databases, + | set defaults, list module contents, enable or disable slots, enable or + | disable FIPS 140-2 compliance, and assign default providers for + | cryptographic operations. This tool can also create certificate, key, and + | module security database files. + + | The tasks associated with security module database management are part of + | a process that typically also involves managing key databases and + | certificate databases. + + Options + + | -a + | the following certfile is base64 encoded + + | -b YYMMDDHHMMZ + | Validate date (default: now) + + | -d directory + | database directory + + | -f + | Enable cert fetching from AIA URL + + | -o oid + | Set policy OID for cert validation(Format OID.1.2.3) + + -p + + Use PKIX Library to validate certificate by calling: + + \* CERT_VerifyCertificate if specified once, + + \* CERT_PKIXVerifyCert if specified twice and more. + + | -r + | Following certfile is raw binary DER (default) + + | -t + | Following cert is explicitly trusted (overrides db trust) + + -u usage + + | 0=SSL client, 1=SSL server, 2=SSL StepUp, 3=SSL CA, 4=Email + | signer, 5=Email recipient, 6=Object signer, + | 9=ProtectedObjectSigner, 10=OCSP responder, 11=Any CA + + | -v + | Verbose mode. Prints root cert subject(double the argument for + | whole root cert info) + + | -w password + | Database password + + | -W pwfile + | Password file + + | Revocation options for PKIX API (invoked with -pp options) is a + | collection of the following flags: [-g type [-h flags] [-m type + | [-s flags]] ...] ... + + Where: + + | -g test-type + | Sets status checking test type. Possible values are "leaf" or + | "chain" + + | -g test type + | Sets status checking test type. Possible values are "leaf" or + | "chain". + + | -h test flags + | Sets revocation flags for the test type it follows. Possible + | flags: "testLocalInfoFirst" and "requireFreshInfo". + + | -m method type + | Sets method type for the test type it follows. Possible types are + | "crl" and "ocsp". + + | -s method flags + | Sets revocation flags for the method it follows. Possible types + | are "doNotUse", "forbidFetching", "ignoreDefaultSrc", + | "requireInfo" and "failIfNoInfo". + + Additional Resources + + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + Copyright + + (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + + References + + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/nss_tools__colon__vfyserv/index.rst b/security/nss/doc/rst/legacy/reference/nss_tools__colon__vfyserv/index.rst new file mode 100644 index 0000000000..f2c2e9c651 --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/nss_tools__colon__vfyserv/index.rst @@ -0,0 +1,50 @@ +.. _mozilla_projects_nss_reference_nss_tools_:_vfyserv: + +NSS tools : vfyserv +=================== + +.. container:: + + Name + + vfyserv — TBD + + Synopsis + + vfyserv + + Description + + The vfyserv tool verifies a certificate chain + + Options + + Additional Resources + + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + + Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + + IRC: Freenode at #dogtag-pki + + Authors + + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + + Copyright + + (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + + References + + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/reference/troubleshoot/index.rst b/security/nss/doc/rst/legacy/reference/troubleshoot/index.rst new file mode 100644 index 0000000000..d2b11c30ca --- /dev/null +++ b/security/nss/doc/rst/legacy/reference/troubleshoot/index.rst @@ -0,0 +1,78 @@ +.. _mozilla_projects_nss_reference_troubleshoot: + +troubleshoot +============ + +.. _troubleshooting_nss_and_jss_builds: + +`Troubleshooting NSS and JSS Builds <#troubleshooting_nss_and_jss_builds>`__ +---------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <nntp://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + This page summarizes information on troubleshooting the NSS and JSS build and test systems, + including known problems and configuration suggestions. + + If you have suggestions for this page, please post them to + `mozilla.dev.tech.crypto <nntp://news.mozilla.org/mozilla.dev.tech.crypto>`__. + +.. _building_nss: + +`Building NSS <#building_nss>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Having /usr/ucb/bin in the path before /usr/ccs/bin breaks the build on 64-bit Solaris. + + - The Solaris compiler needs to be workshop-5.0 or greater. + + - The 64-bit builds don't support gcc. + + - If the build fails early on the gmakein coreconf try updating your cvs tree with -P: + cd mozilla + cvs update -P + + - Building a 32-bit version on a 64-bit may fail with: + + .. code:: + + /usr/include/features.h:324:26: fatal error: bits/predefs.h: No such file or directory + + In this case remember to set USE_64=1 + +.. _testing_nss: + +`Testing NSS <#testing_nss>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The SSL stress test opens 2,048 TCP connections in quick succession. Kernel data structures may + remain allocated for these connections for up to two minutes. Some systems may not be configured + to allow this many simultaneous connections by default; if the stress tests fail, try increasing + the number of simultaneous sockets supported. + +.. _building_jss: + +`Building JSS <#building_jss>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - **Windows Only:** The shell invoked by gmake, ``shmsdos.exe``, is likely to crash when + invoking some Java tools on Windows. The current workaround is to use some other shell in + place of ``shmsdos``, such as ``sh.exe``, which should be distributed with the `Cygnus + toolkit <http://sourceware.cygnus.com/cygwin/download.html>`__ you installed to build NSS. The + change is unfortunately rather drastic: to trick gmake, you rename the shell program. + + cd c:/Programs/cygnus/bin *(or wherever your GNU tools are installed)* + cp shmsdos.exe shmsdos.bak *(backup shmsdos)* + cp sh.exe shmsdos.exe *(substitute alternative shell)* + + Making this change will probably break other builds you are making on the same machine. You + may need to switch the shell back and forthdepending on which product you are building. We + will try to provide a moreconvenient solution in the future. If you have the MKS toolkit + installed, the <tt>sh.exe</tt> that comes with this toolkit can be used as well.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/release_notes/index.rst b/security/nss/doc/rst/legacy/release_notes/index.rst new file mode 100644 index 0000000000..53904229be --- /dev/null +++ b/security/nss/doc/rst/legacy/release_notes/index.rst @@ -0,0 +1,138 @@ +.. _mozilla_projects_nss_release_notes: + +Older NSS release notes +======================= + +.. container:: + + This page lists release notes for older versions of NSS. + See :ref:`mozilla_projects_nss_nss_releases` :ref:`mozilla_projects_nss_nss_releases` for recent + release notes. The links below are provided for historical information. + + - NSS 3.14 + + - :ref:`mozilla_projects_nss_nss_3_14_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_2_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_1_release_notes` + - :ref:`mozilla_projects_nss_nss_3_14_release_notes` + + - NSS 3.12 + + - :ref:`mozilla_projects_nss_nss_3_12_6_release_notes` + - :ref:`mozilla_projects_nss_nss_3_12_5_release_notes` + - :ref:`mozilla_projects_nss_nss_3_12_4_release_notes` + - NSS 3.12.3.2 Release Notes + - NSS 3.12.3.1 Release Notes + - :ref:`mozilla_projects_nss_nss_3_12_3_release_notes` + - :ref:`mozilla_projects_nss_nss_3_12_2_release_notes_html` + - :ref:`mozilla_projects_nss_nss_3_12_1_release_notes_html` + - :ref:`mozilla_projects_nss_nss_3_12_release_notes_html` + + - NSS 3.11 + + - :ref:`mozilla_projects_nss_nss_3_11_10_release_notes_html` + - `NSS 3.11.9 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.9/nss-3.11.9-release-notes.html>`__ + - `NSS 3.11.8 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.8/nss-3.11.8-release-notes.html>`__ + - `NSS 3.11.7 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.7/nss-3.11.7-release-notes.html>`__ + - `NSS 3.11.6 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.6/nss-3.11.6-release-notes.html>`__ + - `NSS 3.11.5 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.5/nss-3.11.5-release-notes.html>`__ + - `NSS 3.11.4 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.4/nss-3.11.4-release-notes.html>`__ + - `NSS 3.11.3 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.3/nss-3.11.3-release-notes.html>`__ + - `NSS 3.11.2 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.2/nss-3.11.2-release-notes.html>`__ + - `NSS 3.11.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11.1/nss-3.11.1-release-notes.html>`__ + - `NSS 3.11 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.11/nss-3.11-release-notes.html>`__ + + - NSS 3.10 + + - `NSS 3.10.2 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.10.2/nss-3.10.2-release-notes.html>`__ + - `NSS 3.10.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.10.1/nss-3.10.1-release-notes.html>`__ + - `NSS 3.10 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.10/nss-3.10-release-notes.html>`__ + + - NSS 3.9 + + - `NSS 3.9.5 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.9.5/nss-3.9.5-release-notes.html>`__ + - `NSS 3.9.4 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.9.4/nss-3.9.4-release-notes.html>`__ + - `NSS 3.9.3 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.9.3/nss-3.9.3-release-notes.html>`__ + - `NSS 3.9.2 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.9.2/nss-3.9.2-release-notes.html>`__ + - `NSS 3.9.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.9/nss-3.9.1-release-notes.html>`__ + - `NSS 3.9 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.9/nss-3.9-release-notes.html>`__ + + - NSS 3.8 + + - `NSS 3.8 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.8/nss-3.8-release-notes.html>`__ + + - NSS 3.7 + + - `NSS 3.7.7 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.7.7/nss-3.7.7-release-notes.html>`__ + - `NSS 3.7.5 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.7.5/nss-3.7.5-release-notes.html>`__ + - `NSS 3.7.3 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.7.3/nss-3.7.3-release-notes.html>`__ + - `NSS 3.7.2 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.7.2/nss-3.7.2-release-notes.html>`__ + - `NSS 3.7.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.7.1/nss-3.7.1-release-notes.html>`__ + - `NSS 3.7 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.7/nss-3.7-release-notes.html>`__ + + - NSS 3.6 + + - `NSS 3.6.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.6.1/nss-3.6.1-release-notes.html>`__ + - `NSS 3.6 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.6/nss-3.6-release-notes.html>`__ + + - NSS 3.4 + + - `NSS 3.4.3 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.4.3/nss-3.4.3-release-notes.html>`__ + - `NSS 3.4.2 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.4.2/nss-3.4.2-release-notes.html>`__ + - `NSS 3.4.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.4.1/nss-3.4.1-release-notes.html>`__ + - `NSS 3.4 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/nss-3.4/nss-3.4-release-notes.html>`__ + + - NSS 3.3 + + - `NSS 3.3.2 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/release_notes_332.html>`__ + - `NSS 3.3.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/release_notes_331.html>`__ + - `NSS 3.3 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/release_notes_33.html>`__ + + - NSS 3.2 + + - `NSS 3.2.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/release_notes_321.html>`__ + - `NSS 3.2 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/release_notes_32.html>`__ + + - NSS 3.1 + + - `NSS 3.1.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/release_notes_311.html>`__ + - `NSS 3.1 Release + Notes <http://www-archive.mozilla.org/projects/security/pki/nss/release_notes_31.html>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/s_mime_functions/index.rst b/security/nss/doc/rst/legacy/s_mime_functions/index.rst new file mode 100644 index 0000000000..10e53a69c9 --- /dev/null +++ b/security/nss/doc/rst/legacy/s_mime_functions/index.rst @@ -0,0 +1,111 @@ +.. _mozilla_projects_nss_s_mime_functions: + +S/MIME functions +================ + +.. container:: + + The public functions listed here perform S/MIME operations using the `S/MIME + Toolkit <http://www-archive.mozilla.org/projects/security/pki/nss/smime/>`__. + + The `Mozilla Cross Reference <http://mxr.mozilla.org/>`__ (MXR) link for each function provides + access to the function definition, prototype definition, and source code references. The NSS + version column indicates which versions of NSS support the function. + + ==================================================== =========== =============== + Function name/documentation Source code NSS versions + ``NSS_CMSContentInfo_GetBulkKey`` MXR 3.2 and later + ``NSS_CMSContentInfo_GetBulkKeySize`` MXR 3.2 and later + ``NSS_CMSContentInfo_GetContent`` MXR 3.2 and later + ``NSS_CMSContentInfo_GetContentEncAlgTag`` MXR 3.2 and later + ``NSS_CMSContentInfo_GetContentTypeTag`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetBulkKey`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetContent`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetContent_Data`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetContentEncAlg`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetContent_DigestedData`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetContent_EncryptedData`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetContent_EnvelopedData`` MXR 3.2 and later + ``NSS_CMSContentInfo_SetContent_SignedData`` MXR 3.2 and later + ``NSS_CMSDecoder_Cancel`` MXR 3.2 and later + ``NSS_CMSDecoder_Finish`` MXR 3.2 and later + ``NSS_CMSDecoder_Start`` MXR 3.2 and later + ``NSS_CMSDecoder_Update`` MXR 3.2 and later + ``NSS_CMSDigestContext_Cancel`` MXR 3.2 and later + ``NSS_CMSDigestContext_FinishMultiple`` MXR 3.2 and later + ``NSS_CMSDigestContext_FinishSingle`` MXR 3.2 and later + ``NSS_CMSDigestContext_StartMultiple`` MXR 3.2 and later + ``NSS_CMSDigestContext_StartSingle`` MXR 3.2 and later + ``NSS_CMSDigestContext_Update`` MXR 3.2 and later + ``NSS_CMSDigestedData_Create`` MXR 3.2 and later + ``NSS_CMSDigestedData_Destroy`` MXR 3.2 and later + ``NSS_CMSDigestedData_GetContentInfo`` MXR 3.2 and later + ``NSS_CMSDEREncode`` MXR 3.2 and later + ``NSS_CMSEncoder_Cancel`` MXR 3.2 and later + ``NSS_CMSEncoder_Finish`` MXR 3.2 and later + ``NSS_CMSEncoder_Start`` MXR 3.2 and later + ``NSS_CMSEncoder_Update`` MXR 3.2 and later + ``NSS_CMSEncryptedData_Create`` MXR 3.2 and later + ``NSS_CMSEncryptedData_Destroy`` MXR 3.2 and later + ``NSS_CMSEncryptedData_GetContentInfo`` MXR 3.2 and later + ``NSS_CMSEnvelopedData_AddRecipient`` MXR 3.2 and later + ``NSS_CMSEnvelopedData_Create`` MXR 3.2 and later + ``NSS_CMSEnvelopedData_Destroy`` MXR 3.2 and later + ``NSS_CMSEnvelopedData_GetContentInfo`` MXR 3.2 and later + ``NSS_CMSMessage_ContentLevel`` MXR 3.2 and later + ``NSS_CMSMessage_ContentLevelCount`` MXR 3.2 and later + ``NSS_CMSMessage_Copy`` MXR 3.2 and later + ``NSS_CMSMessage_Create`` MXR 3.2 and later + ``NSS_CMSMessage_CreateFromDER`` MXR 3.2 and later + ``NSS_CMSMessage_Destroy`` MXR 3.2 and later + ``NSS_CMSMessage_GetContent`` MXR 3.2 and later + ``NSS_CMSMessage_GetContentInfo`` MXR 3.2 and later + ``NSS_CMSMessage_IsEncrypted`` MXR 3.4.1 and later + ``NSS_CMSMessage_IsSigned`` MXR 3.4 and later + ``NSS_CMSRecipientInfo_Create`` MXR 3.2 and later + ``NSS_CMSRecipientInfo_CreateFromDER`` MXR 3.8 and later + ``NSS_CMSRecipientInfo_CreateNew`` MXR 3.8 and later + ``NSS_CMSRecipientInfo_CreateWithSubjKeyID`` MXR 3.7 and later + ``NSS_CMSRecipientInfo_CreateWithSubjKeyIDFromCert`` MXR 3.7 and later + ``NSS_CMSRecipientInfo_Destroy`` MXR 3.2 and later + ``NSS_CMSRecipientInfo_Encode`` MXR 3.8 and later + ``NSS_CMSRecipientInfo_GetCertAndKey`` MXR 3.8 and later + ``NSS_CMSRecipientInfo_UnwrapBulkKey`` MXR 3.7.2 and later + ``NSS_CMSRecipientInfo_WrapBulkKey`` MXR 3.7.2 and later + ``NSS_CMSSignedData_AddCertChain`` MXR 3.2 and later + ``NSS_CMSSignedData_AddCertList`` MXR 3.2 and later + ``NSS_CMSSignedData_AddCertificate`` MXR 3.2 and later + ``NSS_CMSSignedData_AddDigest`` MXR 3.2 and later + ``NSS_CMSSignedData_AddSignerInfo`` MXR 3.2 and later + ``NSS_CMSSignedData_Create`` MXR 3.2 and later + ``NSS_CMSSignedData_CreateCertsOnly`` MXR 3.2 and later + ``NSS_CMSSignedData_Destroy`` MXR 3.2 and later + ``NSS_CMSSignedData_GetContentInfo`` MXR 3.2 and later + ``NSS_CMSSignedData_GetDigestAlgs`` MXR 3.2 and later + ``NSS_CMSSignedData_GetSignerInfo`` MXR 3.2 and later + ``NSS_CMSSignedData_HasDigests`` MXR 3.2 and later + ``NSS_CMSSignedData_ImportCerts`` MXR 3.2 and later + ``NSS_CMSSignedData_SetDigests`` MXR 3.2 and later + ``NSS_CMSSignedData_SetDigestValue`` MXR 3.4 and later + ``NSS_CMSSignedData_SignerInfoCount`` MXR 3.2 and later + ``NSS_CMSSignedData_VerifyCertsOnly`` MXR 3.2 and later + ``NSS_CMSSignedData_VerifySignerInfo`` MXR 3.2 and later + ``NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs`` MXR 3.6 and later + ``NSS_CMSSignerInfo_AddSMIMECaps`` MXR 3.2 and later + ``NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs`` MXR 3.2 and later + ``NSS_CMSSignerInfo_AddSigningTime`` MXR 3.2 and later + ``NSS_CMSSignerInfo_Create`` MXR 3.2 and later + ``NSS_CMSSignerInfo_CreateWithSubjKeyID`` MXR 3.6 and later + ``NSS_CMSSignerInfo_Destroy`` MXR 3.2 and later + ``NSS_CMSSignerInfo_GetCertList`` MXR 3.2 and later + ``NSS_CMSSignerInfo_GetSignerCommonName`` MXR 3.2 and later + ``NSS_CMSSignerInfo_GetSignerEmailAddress`` MXR 3.2 and later + ``NSS_CMSSignerInfo_GetSigningCertificate`` MXR 3.2 and later + ``NSS_CMSSignerInfo_GetSigningTime`` MXR 3.2 and later + ``NSS_CMSSignerInfo_GetVerificationStatus`` MXR 3.2 and later + ``NSS_CMSSignerInfo_GetVersion`` MXR 3.2 and later + ``NSS_CMSSignerInfo_IncludeCerts`` MXR 3.2 and later + ``NSS_CMSUtil_VerificationStatusToString`` MXR 3.2 and later + ``NSS_SMIMESignerInfo_SaveSMIMEProfile`` MXR 3.4 and later + ``NSS_SMIMEUtil_FindBulkAlgForRecipients`` MXR 3.2 and later + ==================================================== =========== ===============
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/gtstd/index.rst b/security/nss/doc/rst/legacy/ssl_functions/gtstd/index.rst new file mode 100644 index 0000000000..520c9aa66c --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/gtstd/index.rst @@ -0,0 +1,264 @@ +.. _mozilla_projects_nss_ssl_functions_gtstd: + +gtstd +===== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are + inclined to help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: Getting Started With SSL + :name: Getting_Started_With_SSL + + -------------- + +.. _chapter_2_getting_started_with_ssl: + +`Chapter 2 <#chapter_2_getting_started_with_ssl>`__ Getting Started With SSL +---------------------------------------------------------------------------- + +.. container:: + + This chapter describes how to set up your environment, including certificate and key databases. + + | `SSL, PKCS #11, and the Default Security Databases <#1011970>`__ + | `Setting Up the Certificate and Key Databases <#1011987>`__ + | `Building NSS Programs <#1013274>`__ + +.. _ssl_pkcs_11_and_the_default_security_databases: + +`SSL, PKCS #11, and the Default Security Databases <#ssl_pkcs_11_and_the_default_security_databases>`__ +------------------------------------------------------------------------------------------------------- + +.. container:: + + The basic relationships among the NSS libraries are described in `Introduction to Network + Security Services <../../intro.html>`__. Before running the sample programs, it's important to + understand the relationships between the SSL interface, the PKCS #11 interface, PKCS #11 modules, + and the default Netscape security databases. + + A **PKCS #11 module** (also called a **cryptographic module**) manages cryptographic services + such as encryption and decryption via the PKCS #11 interface. PKCS #11 modules can be thought of + as drivers for cryptographic devices that can be implemented in either hardware or software. + Netscape provides a built-in PKCS #11 module with NSS. Other kinds of PKCS #11 modules include + the Netscape FORTEZZA module, used by the government, and the Litronic PKCS #11 module for smart + card readers. + + `Figure 2.1 <#1013181>`__ illustrates the relationships between NSPR, SSL, PKCS #11, and the + available cryptographic modules. SSL is built on top of NSPR, which handles sockets, threads, and + related low-level OS operations. On any given server or client, one or more PKCS #11 modules may + be available. + + **Figure 2.1 Relationships among NSS libraries, cryptographic modules, slots, and tokens** + + .. image:: /en-US/docs/Mozilla/Projects/NSS/SSL_functions/gtstd/pkcs.gif + + As shown in the figure, SSL communicates with PKCS #11 modules through the PKCS #11 interface. + Any PKCS #11 module that supports PKCS #11 can be used with the NSS libraries. Netscape software + uses a file called ``secmod.db`` to keep track of the modules available. + + A PKCS #11 module always has one or more **slots,** which may be implemented as physical hardware + slots in some form of physical reader (for example, for smart cards) or as conceptual slots in + software. Each slot for a PKCS #11 module can in turn contain a **token,** which is the hardware + or software device that actually provides cryptographic services and optionally stores + certificates and keys. + + Netscape provides three built-in modules with NSS and with server and client products: + + - The default Netscape Internal PKCS #11 Module comes with two built-in tokens: + + - The Generic Crypto Services token performs all cryptographic operations, such as + encryption, decryption, and hashing. + - The Communicator Certificate DB token handles all communication with the certificate and + key database files (called ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db``, respectively, + where\ *X* is a version number) that store certificates and keys. + + - The FORTEZZA module is intended for use with FORTEZZA hardware tokens. + - The FIPS 140-1 module is compliant with the FIPS 140-1 government standard for implementations + of cryptographic modules. Many products sold to the U.S. government must comply with one or + more of the FIPS standards. The FIPS 140-1 module includes a single, built-in FIPS 140-1 + Certificate DB token (see `Figure 2.1 <#1013181>`__), which handles both cryptographic + operations and communication with the ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db`` files. + + If you are creating a server application, you must use the Certificate Database Tool, which comes + with NSS, to create the ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db`` files and populate them + with the appropriate certificates and keys. + + If you are creating a client application, you can use either the Certificate Database Tool or the + Communicator security interface to create the database files and populate them with the + appropriate certificates and keys. You can use Communicator to set up client certificate + databases by obtaining certificates from either a public CA or from a certificate server such as + Netscape Certificate Management System. The instructions that follow assume you are using the + Certificate Database Tool to set up both the server and client databases for testing purposes. + + You can use the Security Module Database Tool, a command-line utility that comes with NSS, to + manage PKCS #11 module information within s\ ``ecmod.db`` files. The Security Module Database + Tool allows you to add and delete PKCS #11 modules, change passwords, set defaults, list module + contents, enable or disable slots, enable or disable FIPS-140-1 compliance, and assign default + providers for cryptographic operations. + +.. _setting_up_the_certificate_and_key_databases: + +`Setting Up the Certificate and Key Databases <#setting_up_the_certificate_and_key_databases>`__ +------------------------------------------------------------------------------------------------ + +.. container:: + + Before you can run the sample programs (``server.c`` and ``client.c``) that come with NSS, you + must set up certificate, key, and security module databases for both the client and the server + and populate them with valid CA, client SSL, and server SSL certificates. The following sections + decribe how to the Certificate Database Tool to perform these tasks: + + | `Setting Up the CA DB and Certificate <#1012301>`__ + | `Setting Up the Server DB and Certificate <#1012351>`__ + | `Setting Up the Client DB and Certificate <#1012067>`__ + | `Verifying the Server and Client Certificates <#1012108>`__ + + **WARNING:** The instructions below illustrate the use of NSS command line tools to operate a + simple root Certificate Authority for test purposes only. The CA, SSL server and SSL client + certificates produced by these instructions work correctly for short term testing purposes. + Although it is possible to use NSS command line tools to operate a proper CA, these + instructions do not provide nearly enough understanding of the many considerations required to + competently operate a CA. The NSS teams **strongly** recommends that users should not attempt + to operate a CA for use in mission critical production business uses using NSS's command line + tools, nor with the simple command line test tools that come with any package of cryptographic + libraries. Many who have attempted it have eventually come to regret that decision. For + production deployment, the NSS team strongly recommends that you either: + + - Use certificates from a competent third-party CA that is already known to your relying + party software (e.g. your SSL clients), or + - Use professional grade CA software, such as Red Hat's + `Dogtag <http://pki.fedoraproject.org/wiki/PKI_Main_Page>`__ `Certificate + System <http://www.redhat.com/certificate_system/>`__, to set up and operate your own CA + and issue your own certificates. + + For complete information about the command-line options used in the examples that follow, see + `Using the Certificate Database Tool <../../tools/certutil.html>`__. + +.. _setting_up_the_ca_db_and_certificate: + +`Setting Up the CA DB and Certificate <#setting_up_the_ca_db_and_certificate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Set up the CA with its own separate set of databases. + + #. Create a new certificate database in the ``CA_db`` directory. + ``>mkdir CA_db >certutil -N -d CA_db`` + #. Create the self-signed Root CA certificate, specifying the subject name for the certificate. + ``>certutil -S -d CA_db -n "MyCo's Root CA" -s "CN=My CA,O=MyCo,ST=California,C=US" -t "CT,," -x -2 Enter Password or Pin for "Communicator Certificate DB":`` + #. Extract the CA certificate from the CA's certificate database to a file. + ``>certutil -L -d CA_db -n "MyCo's Root CA" -a -o CA_db/rootca.crt Enter Password or Pin for "Communicator Certificate DB":`` + #. Display the contents of the CA's certificate databases. + ``>certutil -L -d CA_db`` + + The trust flag settings ``"CTu,u,u"`` indicate that the certificate is a CA certificate that is + trusted to issue both client (``C``) and server (``T``) SSL certificates. The ``u`` flag + indicates that the private key for the CA certificate is present in this set of databases, so the + CA can issue SSL client and server certificates with these databases. + +.. _setting_up_the_server_db_and_certificate: + +`Setting Up the Server DB and Certificate <#setting_up_the_server_db_and_certificate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The sections that follow describe how to set up the Server DB and certificate: + + #. Create a new certificate database in the ``server_db`` directory. + ``>mkdir server_db >certutil -N -d server_db`` + #. Import the new CA certificate into the server's certificate database, and mark it trusted for + issuing certificates for SSL client and server authentication. + ``>certutil -A -d server_db -n "MyCo's Root CA" -t "TC,," -a -i CA_db/rootca.crt`` + #. Create the server certificate request, specifying the subject name for the server certificate. + We make the common name (CN) be identical to the hostname of the server. Note that this step + generates the server's private key, so it must be done in the server's database directory. + ``>certutil -R -d server_db -s "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -a -o server_db/server.req Enter Password or Pin for "Communicator Certificate DB":`` + #. This step simulates the CA signing and issuing a new server certificate based on the server's + certificate request. The new cert is signed with the CA's private key, so this operation uses + the CA's databases. This step leaves the server's new certificate in a file. + ``>certutil -C -d CA_db -c "MyCo's Root CA" -a -i server_db/server.req -o server_db/server.crt -2 -6 Enter Password or Pin for "Communicator Certificate DB":`` + #. Import (Add) the new server certificate to the server's certificate database in the + ``server_db`` directory with the appropriate nickname. Notice that no trust is explicitly + needed for this certificate. + ``>certutil -A -d server_db -n myco.mcom.org -a -i server_db/server.crt -t ",,"`` + #. Display the contents of the server's certificate databases. + ``>certutil -L -d server_db`` + + The trust flag settings ``"u,u,u"`` indicate that the server's databases contain the private key + for this certificate. This is necessary for the SSL server to be able to do its job. + +.. _setting_up_the_client_db_and_certificate: + +`Setting Up the Client DB and Certificate <#setting_up_the_client_db_and_certificate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Setting up the client certificate database involves three stages: + + #. Create a new certificate database in the ``client_db`` directory. + ``>mkdir client_db >certutil -N -d client_db`` + #. Import the new CA certificate into the client's certificate database, and mark it trusted for + issuing certificates for SSL client and server authentication. + ``>certutil -A -d client_db -n "MyCo's Root CA" -t "TC,," -a -i CA_db/rootca.crt`` + #. Create the client certificate request, specifying the subject name for the certificate. + ``>certutil -R -d client_db -s "CN=Joe Client,O=MyCo,ST=California,C=US" -a -o client_db/client.req Enter Password or Pin for "Communicator Certificate DB":`` + #. This step simulates the CA signing and issuing a new client certificate based on the client's + certificate request. The new cert is signed with the CA's private key, so this operation uses + the CA's databases. This step leaves the client's new certificate in a file. + ``>certutil -C -d CA_db -c "MyCo's Root CA" -a -i client_db/client.req -o client_db/client.crt -2 -6 Enter Password or Pin for "Communicator Certificate DB":`` + #. Add the new client certificate to the client's certificate database in the ``client_db`` + directory with the appropriate nickname. Notice that no trust is required for this + certificate. + ``>certutil -A -d client_db -n "Joe Client" -a -i client_db/client.crt -t ",,"`` + #. Display the contents of the client's certificate databases. + ``>certutil -L -d client_db`` + + The trust flag settings ``"u,u,u"`` indicate that the client's databases contain the private key + for this certificate. This is necessary for the SSL client to be able to authenticate to the + server. + +.. _verifying_the_server_and_client_certificates: + +`Verifying the Server and Client Certificates <#verifying_the_server_and_client_certificates>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + When you have finished setting up the server and client certificate databases, verify that the + client and server certificates are valid, as follows: + + ``>certutil -V -d server_db -u V -n myco.mcom.org certutil: certificate is valid`` + + ``>certutil -V -d client_db -u C -n "Joe Client" certutil: certificate is valid`` + +.. _building_nss_programs: + +`Building NSS Programs <#building_nss_programs>`__ +-------------------------------------------------- + +.. container:: + + On Unix, use the GNU utility ``gmake`` to run the makefile. On Windows NT, use the ``nmake`` + utility that comes with Visual C++. + + If you create your own makefiles, be sure to include the libraries in the same order that they + are listed in the sample makefiles. In addition, you must use the following compiler flags: + + Solaris flags: + + ``-c -O -KPIC -DSVR4 -DSYSV -D__svr4 -D__svr4__ -DSOLARIS -D_REENTRANT -DSOLARIS2_5 -D_SVID_GETTOD -DXP_UNIX -UDEBUG -DNDEBUG`` + + Windows NT flags: + + ``-c -O2 -MD -W3 -nologo -D_X86_ -GT -DWINNT -DXP_PC -UDEBUG -U_DEBUG -DNDEBUG -DWIN32 -D_WINDOWS``
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/index.rst b/security/nss/doc/rst/legacy/ssl_functions/index.rst new file mode 100644 index 0000000000..ccbc7a84a4 --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/index.rst @@ -0,0 +1,83 @@ +.. _mozilla_projects_nss_ssl_functions: + +SSL functions +============= + +.. container:: + + The public functions listed here are used to configure sockets for communication via the SSL and + TLS protocols. In addition to the functions listed here, applications that support SSL use some + of the Certificate functions, Crypto functions, and Utility functions described below on this + page. + + Other sources of information: + + - The :ref:`mozilla_projects_nss_reference` documents the functions most commonly used by + applications to support SSL. + - The :ref:`mozilla_projects_nss` home page links to additional SSL documentation. + + If documentation is available for a function listed below, the function name is linked to either + its MDC wiki page or its entry in the + :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference`. The `Mozilla Cross + Reference <https://dxr.mozilla.org/>`__ (DXR) link for each function provides access to the + function definition, prototype definition, and source code references. The NSS version column + indicates which versions of NSS support the function. + + ======================================================== =========== ================ + Function name/documentation Source code NSS versions + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1228530` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285` MXR 3.2 and later + ``NSS_SetFrancePolicy`` MXR 3.2 and later + ``NSSSSL_VersionCheck`` MXR 3.2.1 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088805` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088928` MXR 3.2 and later + ``SSL_CertDBHandleSet`` MXR 3.2 and later + ``SSL_Canbypass`` MXR 3.11.7 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1210463` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214800` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1208119` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214758` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` MXR 3.2 and later + ``SSL_ForceHandshakeWithTimeout`` MXR 3.11.4 and later + ``SSL_GetChannelInfo`` MXR 3.4 and later + ``SSL_GetCipherSuiteInfo`` MXR 3.4 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1126622` MXR 3.2 and later + ``SSL_GetMaxServerCacheLocks`` MXR 3.4 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092869` MXR 3.2 and later + ``SSL_GetStatistics`` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1112702` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1085950` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1162055` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089420` MXR 3.2 and later + ``SSL_LocalCertificate`` MXR 3.4 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1194921` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1204897` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1068466` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1096168` MXR 3.2 and later + ``SSL_PreencryptedFileToStream`` MXR 3.2 and later + ``SSL_PreencryptedStreamToFile`` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052` MXR 3.2 and later + ``SSL_ReHandshakeWithTimeout`` MXR 3.11.4 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001` MXR 3.2 and later + ``SSL_RestartHandshakeAfterCertReq`` MXR 3.2 and later + ``SSL_RestartHandshakeAfterServerCert`` MXR 3.2 and later + ``SSL_RevealCert`` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092805` MXR 3.2 and later + ``SSL_SetMaxServerCacheLocks`` MXR 3.4 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1124562` MXR 3.2 and later + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792` MXR 3.2 and later + ``SSL_ShutdownServerSessionIDCache`` MXR 3.7.4 and later + ======================================================== =========== ================
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/old_ssl_reference/index.rst b/security/nss/doc/rst/legacy/ssl_functions/old_ssl_reference/index.rst new file mode 100644 index 0000000000..c39e51557f --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/old_ssl_reference/index.rst @@ -0,0 +1,269 @@ +.. _mozilla_projects_nss_ssl_functions_old_ssl_reference: + +OLD SSL Reference +================= + +.. container:: + + .. rubric:: OLD SSL Reference + :name: OLD_SSL_Reference + + .. note:: + + - We are migrating this SSL Reference into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are + inclined to help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + +.. _ssl_reference: + +`SSL Reference <#ssl_reference>`__ +---------------------------------- + +.. container:: + + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__\ * + Writer: Sean Cotter + Manager: Wan-Teh Chang* + + .. rubric:: `Chapter 1 Overview of an SSL Application <sslintro.html#1028068>`__ + :name: chapter_1_overview_of_an_ssl_application + + SSL and related APIs allow compliant applications to configure sockets for authenticated, + tamper-proof, and encrypted communications. This chapter introduces some of the basic SSL + functions. Chapter 2, "Getting Started With SSL" illustrates their use in sample client and + server applications. + + - `Initialization <sslintro.html#1027662>`__ + + - `Initializing Caches <sslintro.html#1039943>`__ + + - `Configuration <sslintro.html#1027742>`__ ` <sslintro.html#1027816>`__ + - `Communication <sslintro.html#1027816>`__ ` <sslintro.html#1027820>`__ + - `Functions Used by Callbacks <sslintro.html#1027820>`__ ` <sslintro.html#1030535>`__ + - `Cleanup <sslintro.html#1030535>`__ + + .. rubric:: `Chapter 2 Getting Started With SSL <gtstd.html#1005439>`__ + :name: chapter_2_getting_started_with_ssl + + This chapter describes how to set up your environment, including certificate and key + databases, to run the NSS sample code. The sample code and makefiles are available via LXR in + the SSLSamples directory. + + - `SSL, PKCS #11, and the Default Security Databases <gtstd.html#1011970>`__ + ` <gtstd.html#1011987>`__ + - `Setting Up the Certificate and Key Databases <gtstd.html#1011987>`__ + + - `Setting Up the CA DB and Certificate <gtstd.html#1012301>`__ ` <gtstd.html#1012351>`__ + - `Setting Up the Server DB and Certificate <gtstd.html#1012351>`__ ` <gtstd.html#1012067>`__ + - `Setting Up the Client DB and Certificate <gtstd.html#1012067>`__ ` <gtstd.html#1012108>`__ + - `Verifying the Server and Client Certificates <gtstd.html#1012108>`__ + + - `Building NSS Programs <gtstd.html#1013274>`__ + + .. rubric:: `Chapter 3 Selected SSL Types and Structures <ssltyp.html#1029792>`__ + :name: chapter_3_selected_ssl_types_and_structures + + This chapter describes some of the most important types and structures used with the functions + described in the rest of this document, and how to manage the memory used for them. Additional + types are described with the functions that use them or in the header files. + + - `Types and Structures <ssltyp.html#1030559>`__ + + - `CERTCertDBHandle <ssltyp.html#1028465>`__ ` <ssltyp.html#1027387>`__ + - `CERTCertificate <ssltyp.html#1027387>`__ ` <ssltyp.html#1028593>`__ + - `PK11SlotInfo <ssltyp.html#1028593>`__ ` <ssltyp.html#1026076>`__ + - `SECItem <ssltyp.html#1026076>`__ ` <ssltyp.html#1026727>`__ + - `SECKEYPrivateKey <ssltyp.html#1026727>`__ ` <ssltyp.html#1026722>`__ + - `SECStatus <ssltyp.html#1026722>`__ + + - `Managing SECItem Memory <ssltyp.html#1029645>`__ + + - `SECItem_FreeItem <ssltyp.html#1030620>`__ ` <ssltyp.html#1030773>`__ + - `SECItem_ZfreeItem <ssltyp.html#1030773>`__ + + .. rubric:: :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1047959` + :name: chapter_4_ssl_functions + + This chapter describes the core SSL functions. + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1022864` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1237143` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1237143` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1234224` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1234224` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1068466` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1068466` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1204897` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1204897` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1208119` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1208119` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1154189` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1162055` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1162055` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1098841` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1228530` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1105952` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1105952` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1210463` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1210463` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1163855` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1090577` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1085950` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1194921` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1194921` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214758` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214758` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214800` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1214800` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089578` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088805` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088928` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088928` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1126622` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1126622` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1112702` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1112702` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1127321` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089420` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092785` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092785` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092805` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092805` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092869` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1092869` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1124562` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1124562` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1127893` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1096168` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1061582` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1095840` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1061858` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1198429` + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1206365` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1220189` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1220189` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207298` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207298` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207350` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1207350` + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1231825` + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1231825` + + .. rubric:: `Chapter 5 Certificate Functions <sslcrt.html#1047959>`__ + :name: chapter_5_certificate_functions + + This chapter describes the functions and related types used to work with a certificate + database such as the cert7.db database provided with Communicator. + + - `Validating Certificates <sslcrt.html#1060423>`__ + + - `CERT_VerifyCertNow <sslcrt.html#1058011>`__ ` <sslcrt.html#1050342>`__ + - `CERT_VerifyCertName <sslcrt.html#1050342>`__ ` <sslcrt.html#1056662>`__ + - `CERT_CheckCertValidTimes <sslcrt.html#1056662>`__ ` <sslcrt.html#1056760>`__ + - `NSS_CmpCertChainWCANames <sslcrt.html#1056760>`__ + + - `Manipulating Certificates <sslcrt.html#1056436>`__ + + - `CERT_DupCertificate <sslcrt.html#1058344>`__ ` <sslcrt.html#1050532>`__ + - `CERT_DestroyCertificate <sslcrt.html#1050532>`__ + + - `Getting Certificate Information <sslcrt.html#1056475>`__ + + - `CERT_FindCertByName <sslcrt.html#1050345>`__ ` <sslcrt.html#1050346>`__ + - `CERT_GetCertNicknames <sslcrt.html#1050346>`__ ` <sslcrt.html#1050349>`__ + - `CERT_FreeNicknames <sslcrt.html#1050349>`__ ` <sslcrt.html#1052308>`__ + - `CERT_GetDefaultCertDB <sslcrt.html#1052308>`__ ` <sslcrt.html#1056950>`__ + - `NSS_FindCertKEAType <sslcrt.html#1056950>`__ + + - `Comparing SecItem Objects <sslcrt.html#1055384>`__ + + - `SECITEM_CompareItem <sslcrt.html#1057028>`__ + + .. rubric:: `Chapter 6 Key Functions <sslkey.html#1047959>`__ + :name: chapter_6_key_functions + + This chapter describes two functions used to manipulate private keys and key databases such as + the key3.db database provided with Communicator. + + - `SECKEY_GetDefaultKeyDB <sslkey.html#1051479>`__ ` <sslkey.html#1051017>`__ + - `SECKEY_DestroyPrivateKey <sslkey.html#1051017>`__ + + .. rubric:: `Chapter 7 PKCS #11 Functions <pkfnc.html#1027946>`__ + :name: chapter_7_pkcs_11_functions + + This chapter describes the core PKCS #11 functions that an application needs for communicating + with cryptographic modules. In particular, these functions are used for obtaining + certificates, keys, and passwords. + + - `PK11_FindCertFromNickname <pkfnc.html#1035673>`__ ` <pkfnc.html#1026891>`__ + - `PK11_FindKeyByAnyCert <pkfnc.html#1026891>`__ ` <pkfnc.html#1030779>`__ + - `PK11_GetSlotName <pkfnc.html#1030779>`__ ` <pkfnc.html#1026964>`__ + - `PK11_GetTokenName <pkfnc.html#1026964>`__ ` <pkfnc.html#1026762>`__ + - `PK11_IsHW <pkfnc.html#1026762>`__ ` <pkfnc.html#1022948>`__ + - `PK11_IsPresent <pkfnc.html#1022948>`__ ` <pkfnc.html#1022991>`__ + - `PK11_IsReadOnly <pkfnc.html#1022991>`__ ` <pkfnc.html#1023128>`__ + - `PK11_SetPasswordFunc <pkfnc.html#1023128>`__ + + .. rubric:: `Chapter 8 NSS and SSL Error Codes <sslerr.html#1013897>`__ + :name: chapter_8_nss_and_ssl_error_codes + + NSS error codes are retrieved using the NSPR function PR_GetError. In addition to the error + codes defined by NSPR, PR_GetError retrieves the error codes described in this chapter. + + - `SSL Error Codes <sslerr.html#1040263>`__ ` <sslerr.html#1039257>`__ + - `SEC Error Codes <sslerr.html#1039257>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/pkfnc/index.rst b/security/nss/doc/rst/legacy/ssl_functions/pkfnc/index.rst new file mode 100644 index 0000000000..b71487dd7a --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/pkfnc/index.rst @@ -0,0 +1,439 @@ +.. _mozilla_projects_nss_ssl_functions_pkfnc: + +pkfnc +===== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to + help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: PKCS #11 Functions + :name: PKCS_11_Functions + + -------------- + +.. _chapter_7_pkcs_11_functions: + +`Chapter 7 +PKCS #11 Functions <#chapter_7_pkcs_11_functions>`__ +---------------------------------------------------- + +.. container:: + + This chapter describes the core PKCS #11 functions that an application needs for communicating + with cryptographic modules. In particular, these functions are used for obtaining certificates, + keys, and passwords. + + | ```PK11_FindCertFromNickname`` <#1035673>`__ + | ```PK11_FindKeyByAnyCert`` <#1026891>`__ + | ```PK11_GetSlotName`` <#1030779>`__ + | ```PK11_GetTokenName`` <#1026964>`__ + | ```PK11_IsHW`` <#1026762>`__ + | ```PK11_IsPresent`` <#1022948>`__ + | ```PK11_IsReadOnly`` <#1022991>`__ + | ```PK11_SetPasswordFunc`` <#1023128>`__ + + .. rubric:: PK11_FindCertFromNickname + :name: pk11_findcertfromnickname + + Finds a certificate from its nickname. + + .. rubric:: Syntax + :name: syntax + + .. code:: + + #include <pk11func.h> + #include <certt.h> + + .. code:: + + CERTCertificate *PK11_FindCertFromNickname( + char *nickname, + void *wincx); + + .. rubric:: Parameters + :name: parameters + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the nickname in the certificate | + | | database or to the nickname in the token. | + | nickname | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to application data for the password | + | | callback function. This pointer is set with | + | wincx | :ref:`moz | + | | illa_projects_nss_ssl_functions_sslfnc#1088040` | + | | during SSL configuration. To retrieve its | + | | current value, use | + | | :ref:`mozi | + | | lla_projects_nss_ssl_functions_sslfnc#1123385`. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns + + The function returns one of these values: + + - If successful, a pointer to a certificate structure. + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description + + A nickname is an alias for a certificate subject. There may be multiple certificates with the + same subject, and hence the same nickname. This function will return the newest certificate that + matches the subject, based on the NotBefore / NotAfter fields of the certificate. When you are + finished with the certificate structure returned by ``PK11_FindCertFromNickname``, you must free + it by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__. + + The ``PK11_FindCertFromNickname`` function calls the password callback function set with + ```PK11_SetPasswordFunc`` <#1023128>`__ and passes it the pointer specified by the ``wincx`` + parameter. + + .. rubric:: PK11_FindKeyByAnyCert + :name: pk11_findkeybyanycert + + Finds the private key associated with a specified certificate in any available slot. + + .. rubric:: Syntax + :name: syntax_2 + + .. code:: + + #include <pk11func.h> + #include <certt.h> + #include <keyt.h> + + .. code:: + + SECKEYPrivateKey *PK11_FindKeyByAnyCert( + CERTCertificate *cert, + void *wincx); + + .. rubric:: Parameters + :name: parameters_2 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a certificate structure in the | + | | certificate database. | + | cert | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to application data for the password | + | | callback function. This pointer is set with | + | wincx | :ref:`moz | + | | illa_projects_nss_ssl_functions_sslfnc#1088040` | + | | during SSL configuration. To retrieve its | + | | current value, use | + | | :ref:`mozi | + | | lla_projects_nss_ssl_functions_sslfnc#1123385`. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_2 + + The function returns one of these values: + + - If successful, a pointer to a private key structure. + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_2 + + When you are finished with the private key structure returned by ``PK11_FindKeyByAnyCert``, you + must free it by calling ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__. + + The ``PK11_FindKeyByAnyCert`` function calls the password callback function set with + ```PK11_SetPasswordFunc`` <#1023128>`__ and passes it the pointer specified by the ``wincx`` + parameter. + + .. rubric:: PK11_GetSlotName + :name: pk11_getslotname + + Gets the name of a slot. + + .. rubric:: Syntax + :name: syntax_3 + + .. code:: + + #include <pk11func.h> + + .. code:: + + char *PK11_GetSlotName(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_3 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a slot info structure. | + | | | + | slot | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_3 + + The function returns one of these values: + + - If successful, a pointer to the name of the slot (a string). + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_3 + + If the slot is freed, the string with the slot name may also be freed. If you want to preserve + it, copy the string before freeing the slot. Do not try to free the string yourself. + + .. rubric:: PK11_GetTokenName + :name: pk11_gettokenname + + Gets the name of the token. + + .. rubric:: Syntax + :name: syntax_4 + + .. code:: + + #include <pk11func.h> + + .. code:: + + char *PK11_GetTokenName(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_4 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a slot info structure. | + | | | + | slot | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_4 + + The function returns one of these values: + + - If successful, a pointer to the name of the token (a string). + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_4 + + If the slot is freed, the string with the token name may also be freed. If you want to preserve + it, copy the string before freeing the slot. Do not try to free the string yourself. + + .. rubric:: PK11_IsHW + :name: pk11_ishw + + Finds out whether a slot is implemented in hardware or software. + + .. rubric:: Syntax + :name: syntax_5 + + .. code:: + + #include <pk11func.h> + #include <prtypes.h> + + .. code:: + + PRBool PK11_IsHW(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_5 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a slot info structure. | + | | | + | slot | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_5 + + The function returns one of these values: + + - If the slot is implemented in hardware, ``PR_TRUE``. + - If the slot is implemented in software, ``PR_FALSE``. + + .. rubric:: PK11_IsPresent + :name: pk11_ispresent + + Finds out whether the token for a slot is available. + + .. rubric:: Syntax + :name: syntax_6 + + .. code:: + + #include <pk11func.h> + #include <prtypes.h> + + .. code:: + + PRBool PK11_IsPresent(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_6 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a slot info structure. | + | | | + | slot | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_6 + + The function returns one of these values: + + - If token is available, ``PR_TRUE``. + - If token is disabled or missing, ``PR_FALSE``. + + .. rubric:: PK11_IsReadOnly + :name: pk11_isreadonly + + Finds out whether a slot is read-only. + + .. rubric:: Syntax + :name: syntax_7 + + .. code:: + + #include <pk11func.h> + #include <prtypes.h> + + .. code:: + + PRBool PK11_IsReadOnly(PK11SlotInfo *slot); + + .. rubric:: Parameters + :name: parameters_7 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a slot info structure. | + | | | + | slot | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_7 + + The function returns one of these values: + + - If slot is read-only, ``PR_TRUE``. + - Otherwise, ``PR_FALSE``. + + .. rubric:: PK11_SetPasswordFunc + :name: pk11_setpasswordfunc + + Defines a callback function used by the NSS libraries whenever information protected by a + password needs to be retrieved from the key or certificate databases. + + .. rubric:: Syntax + :name: syntax_8 + + .. code:: + + #include <pk11func.h> + #include <prtypes.h> + + .. code:: + + void PK11_SetPasswordFunc(PK11PasswordFunc func); + + .. rubric:: Parameter + :name: parameter + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the callback function to set. | + | | | + | func | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Description + :name: description_5 + + During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11 + token (either a smart card or soft token) to access protected information, such as a private key. + Such information is protected with a password that can be retrieved by calling an + application-supplied callback function. The callback function is identified in a call to + ``PK11_SetPasswordFunc`` that takes place during NSS initialization. + + The callback function set up by ``PK11_SetPasswordFunc`` has the following prototype: + + .. code:: + + typedef char *(*PK11PasswordFunc)( + PK11SlotInfo *slot, + PRBool retry, + void *arg); + + This callback function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a slot info structure. | + | | | + | slot | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | Set to ``PR_TRUE`` if this is a retry. This | + | | implies that the callback has previously | + | retry | returned the wrong password. | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer supplied by the application that can | + | | be used to pass state information. Can be | + | arg | ``NULL``. | + +-------------------------------------------------+-------------------------------------------------+ + + This callback function returns one of these values: + + - If successful, a pointer to the password. This memory must have been allocated with + ```PR_Malloc`` <../../../../../nspr/reference/html/prmem2.html#21428>`__ or + ```PL_strdup`` <../../../../../nspr/reference/html/plstr.html#21753>`__. + - If unsuccessful, returns ``NULL``. + + Many tokens keep track of the number of attempts to enter a password and do not allow further + attempts after a certain point. Therefore, if the ``retry`` argument is ``PR_TRUE``, indicating + that the password was tried and is wrong, the callback function should return ``NULL`` to + indicate that it is unsuccessful, rather than attempting to return the same password again. + Failing to terminate when the ``retry`` argument is ``PR_TRUE`` can result in an endless loop. + + Several functions in the NSS libraries use the password callback function to obtain the password + before performing operations that involve the protected information. The third parameter to the + password callback function is application-defined and can be used for any purpose. For example, + Communicator uses the parameter to pass information about which window is associated with the + modal dialog box requesting the password from the user. When NSS libraries call the password + callback function, the value they pass in the third parameter is determined by + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040`. + + .. rubric:: See Also + :name: see_also + + For examples of password callback functions, see the samples in the + :ref:`mozilla_projects_nss_nss_sample_code` directory.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslcrt/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslcrt/index.rst new file mode 100644 index 0000000000..677ec4f598 --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/sslcrt/index.rst @@ -0,0 +1,632 @@ +.. _mozilla_projects_nss_ssl_functions_sslcrt: + +sslcrt +====== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are + inclined to help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: Certificate Functions + :name: Certificate_Functions + + -------------- + +.. _chapter_5_certificate_functions: + +`Chapter 5 + <#chapter_5_certificate_functions>`__ Certificate Functions +------------------------------------------------------------ + +.. container:: + + This chapter describes the functions and related types used to work with a certificate database + such as the ``cert7.db`` database provided with Communicator. + + | `Validating Certificates <#1060423>`__ + | `Manipulating Certificates <#1056436>`__ + | `Getting Certificate Information <#1056475>`__ + | `Comparing SecItem Objects <#1055384>`__ + +.. _validating_certificates: + +`Validating Certificates <#validating_certificates>`__ +------------------------------------------------------ + +.. container:: + + | ```CERT_VerifyCertNow`` <#1058011>`__ + | ```CERT_VerifyCertName`` <#1050342>`__ + | ```CERT_CheckCertValidTimes`` <#1056662>`__ + | ```NSS_CmpCertChainWCANames`` <#1056760>`__ + + .. rubric:: CERT_VerifyCertNow + :name: cert_verifycertnow + + Checks that the current date is within the certificate's validity period and that the CA + signature on the certificate is valid. + + .. rubric:: Syntax + :name: syntax + + .. code:: + + #include <cert.h> + + .. code:: + + SECStatus CERT_VerifyCertNow( + CERTCertDBHandle *handle, + CERTCertificate *cert, + PRBool checkSig, + SECCertUsage certUsage, + void *wincx); + + .. rubric:: Parameters + :name: parameters + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate database handle. | + | | | + | handle | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate to be checked. | + | | | + | cert | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | Indicates whether certificate signatures are to | + | | be checked. ``PR_TRUE`` means certificate | + | checkSig | signatures are to be checked. ``PR_FALSE`` | + | | means certificate signatures will not be | + | | checked. | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | One of these values: | + | | | + | certUsage | - ``certUsageSSLClient`` | + | | - ``certUsageSSLServer`` | + | | - ``certUsageSSLServerWithStepUp`` | + | | - ``certUsageSSLCA`` | + | | - ``certUsageEmailSigner`` | + | | - ``certUsageEmailRecipient`` | + | | - ``certUsageObjectSigner`` | + | | - ``certUsageUserCertImport`` | + | | - ``certUsageVerifyCA`` | + | | - ``certUsageProtectedObjectSigner`` | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The PIN argument value to pass to PK11 | + | | functions. See description below for more | + | wincx | information. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error + code. + + .. rubric:: Description + :name: description + + The ``CERT_VerifyCertNow`` function must call one or more PK11 functions to obtain the services + of a PKCS #11 module. Some of the PK11 functions require a PIN argument (see + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` for details), which must be specified in + the ``wincx`` parameter. To obtain the value to pass in the ``wincx`` parameter, call + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385`. + + .. rubric:: CERT_VerifyCertName + :name: cert_verifycertname + + Compares the common name specified in the subject DN for a certificate with a specified hostname. + + .. rubric:: Syntax + :name: syntax_2 + + .. code:: + + #include <cert.h> + + .. code:: + + SECStatus CERT_VerifyCertName( + CERTCertificate *cert, + char *hostname); + + .. rubric:: Parameters + :name: parameters_2 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate against which to | + | | check the hostname referenced by ``hostname``. | + | cert | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The hostname to be checked. | + | | | + | hostname | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_2 + + The function returns one of these values: + + - If the common name in the subject DN for the certificate matches the domain name passed in the + ``hostname`` parameter, ``SECSuccess``. + - If the common name in the subject DN for the certificate is not identical to the domain name + passed in the ``hostname`` parameter, ``SECFailure``. Use + ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error + code. + + .. rubric:: Description + :name: description_2 + + The comparison performed by CERT_VerifyCertName is not a simple string comparison. Instead, it + takes account of the following rules governing the construction of common names in SSL server + certificates: + + - ``*`` matches anything + - ``?`` matches one character + - ``\`` escapes a special character + - ``$`` matches the end of the string + - ``[abc]`` matches one occurrence of ``a``, ``b``, or ``c``. The only character that needs to + be escaped in this is ``]``, all others are not special. + - ``[a-z]`` matches any character between ``a`` and ``z`` + - ``[^az]`` matches any character except ``a`` or ``z`` + - ``~`` followed by another shell expression removes any pattern matching the shell expression + from the match list + - ``(foo|bar)`` matches either the substring ``foo`` or the substring ``bar``. These can be + shell expressions as well. + + .. rubric:: CERT_CheckCertValidTimes + :name: cert_checkcertvalidtimes + + Checks whether a specified time is within a certificate's validity period. + + .. rubric:: Syntax + :name: syntax_3 + + .. code:: + + #include <cert.h> + #include <certt.h> + + .. code:: + + SECCertTimeValidity CERT_CheckCertValidTimes( + CERTCertificate *cert, + int64 t); + + .. rubric:: Parameters + :name: parameters_3 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate whose validity | + | | period you want to check against. | + | cert | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The time to check against the certificate's | + | | validity period. For more information, see the | + | t | NSPR header ``pr_time.h``. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_3 + + The function returns an enumerator of type ``SECCertTimeValidity``: + + .. code:: + + typedef enum { + secCertTimeValid, + secCertTimeExpired, + secCertTimeNotValidYet + } SECCertTimeValidity; + + .. rubric:: NSS_CmpCertChainWCANames + :name: nss_cmpcertchainwcanames + + Determines whether any of the signers in the certificate chain for a specified certificate are on + a specified list of CA names. + + .. rubric:: Syntax + :name: syntax_4 + + .. code:: + + #include <nss.h> + + .. code:: + + SECStatus NSS_CmpCertChainWCANames( + CERTCertificate *cert, + CERTDistNames *caNames); + + .. rubric:: Parameters + :name: parameters_4 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate structure for the | + | | certificate whose certificate chain is to be | + | cert | checked. | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to a structure that contains a list | + | | of distinguished names (DNs) against which to | + | caNames | check the DNs for the signers in the | + | | certificate chain. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_4 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error + code. + +.. _manipulating_certificates: + +`Manipulating Certificates <#manipulating_certificates>`__ +---------------------------------------------------------- + +.. container:: + + | ```CERT_DupCertificate`` <#1058344>`__ + | ```CERT_DestroyCertificate`` <#1050532>`__ + + .. rubric:: CERT_DupCertificate + :name: cert_dupcertificate + + Makes a shallow copy of a specified certificate. + + .. rubric:: Syntax + :name: syntax_5 + + .. code:: + + #include <cert.h> + + .. code:: + + CERTCertificate *CERT_DupCertificate(CERTCertificate *c) + + .. rubric:: Parameter + :name: parameter + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate object to be | + | | duplicated. | + | c | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_5 + + If successful, the function returns a pointer to a certificate object of type + ```CERTCertificate`` <ssltyp.html#1027387>`__. + + .. rubric:: Description + :name: description_3 + + The ``CERT_DupCertificate`` function increments the reference count for the certificate passed in + the ``c`` parameter. + + .. rubric:: CERT_DestroyCertificate + :name: cert_destroycertificate + + Destroys a certificate object. + + .. rubric:: Syntax + :name: syntax_6 + + .. code:: + + #include <cert.h> + #include <certt.h> + + .. code:: + + void CERT_DestroyCertificate(CERTCertificate *cert); + + .. rubric:: Parameters + :name: parameters_5 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate to destroy. | + | | | + | cert | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Description + :name: description_4 + + Certificate and key structures are shared objects. When an application makes a copy of a + particular certificate or key structure that already exists in memory, SSL makes a *shallow* + copy--that is, it increments the reference count for that object rather than making a whole new + copy. When you call ```CERT_DestroyCertificate`` <#1050532>`__ or + ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__, the function decrements the reference + count and, if the reference count reaches zero as a result, both frees the memory and sets all + the bits to zero. The use of the word "destroy" in function names or in the description of a + function implies reference counting. + + Never alter the contents of a certificate or key structure. If you attempt to do so, the change + affects all the shallow copies of that structure and can cause severe problems. + +.. _getting_certificate_information: + +`Getting Certificate Information <#getting_certificate_information>`__ +---------------------------------------------------------------------- + +.. container:: + + | ```CERT_FindCertByName`` <#1050345>`__ + | ```CERT_GetCertNicknames`` <#1050346>`__ + | ```CERT_FreeNicknames`` <#1050349>`__ + | ```CERT_GetDefaultCertDB`` <#1052308>`__ + | ```NSS_FindCertKEAType`` <#1056950>`__ + + .. rubric:: CERT_FindCertByName + :name: cert_findcertbyname + + Finds the certificate in the certificate database with a specified DN. + + .. rubric:: Syntax + :name: syntax_7 + + .. code:: + + #include <cert.h> + + .. code:: + + CERTCertificate *CERT_FindCertByName ( + CERTCertDBHandle *handle, + SECItem *name); + + .. rubric:: Parameters + :name: parameters_6 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate database handle. | + | | | + | handle | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The subject DN of the certificate you wish to | + | | find. | + | name | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_6 + + If successful, the function returns a certificate object of type + ```CERTCertificate`` <ssltyp.html#1027387>`__. + + .. rubric:: CERT_GetCertNicknames + :name: cert_getcertnicknames + + Returns the nicknames of the certificates in a specified certificate database. + + .. rubric:: Syntax + :name: syntax_8 + + .. code:: + + #include <cert.h> + #include <certt.h> + + .. code:: + + CERTCertNicknames *CERT_GetCertNicknames ( + CERTCertDBHandle *handle, + int what, + void *wincx); + + .. rubric:: Parameters + :name: parameters_7 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the certificate database handle. | + | | | + | handle | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | One of these values: | + | | | + | what | - ``SEC_CERT_NICKNAMES_ALL`` | + | | - ``SEC_CERT_NICKNAMES_USER`` | + | | - ``SEC_CERT_NICKNAMES_SERVER`` | + | | - ``SEC_CERT_NICKNAMES_CA`` | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The PIN argument value to pass to PK11 | + | | functions. See description below for more | + | wincx | information. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_7 + + The function returns a ``CERTCertNicknames`` object containing the requested nicknames. + + .. rubric:: Description + :name: description_5 + + ``CERT_GetCertNicknames`` must call one or more PK11 functions to obtain the services of a PKCS + #11 module. Some of the PK11 functions require a PIN argument (see + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040` for details), which must be specified in + the ``wincx`` parameter. To obtain the value to pass in the ``wincx`` parameter, call + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385`. + + .. rubric:: CERT_FreeNicknames + :name: cert_freenicknames + + Frees a ``CERTCertNicknames`` structure. This structure is returned by + ```CERT_GetCertNicknames`` <#1050346>`__. + + .. rubric:: Syntax + :name: syntax_9 + + .. code:: + + #include <cert.h> + + .. code:: + + void CERT_FreeNicknames(CERTCertNicknames *nicknames); + + .. rubric:: Parameters + :name: parameters_8 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the ``CERTCertNicknames`` | + | | structure to be freed. | + | nicknames | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: CERT_GetDefaultCertDB + :name: cert_getdefaultcertdb + + Returns a handle to the default certificate database. + + .. rubric:: Syntax + :name: syntax_10 + + .. code:: + + #include <cert.h> + + .. code:: + + CERTCertDBHandle *CERT_GetDefaultCertDB(void); + + .. rubric:: Returns + :name: returns_8 + + The function returns the ```CERTCertDBHandle`` <ssltyp.html#1028465>`__ for the default + certificate database. + + .. rubric:: Description + :name: description_6 + + This function is useful for determining whether the default certificate database has been opened. + + .. rubric:: NSS_FindCertKEAType + :name: nss_findcertkeatype + + Returns key exchange type of the keys in an SSL server certificate. + + .. rubric:: Syntax + :name: syntax_11 + + .. code:: + + #include <nss.h> + + .. code:: + + SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert); + + .. rubric:: Parameter + :name: parameter_2 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The certificate to check. | + | | | + | a | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_9 + + The function returns one of these values: + + - ``kt_null = 0`` + - ``kt_rsa`` + - ``kt_dh`` + - ``kt_fortezza`` + - ``kt_kea_size`` + +.. _comparing_secitem_objects: + +`Comparing SecItem Objects <#comparing_secitem_objects>`__ +---------------------------------------------------------- + +.. container:: + + .. rubric:: SECITEM_CompareItem + :name: secitem_compareitem + + Compares two ```SECItem`` <ssltyp.html#1026076>`__ objects and returns a ``SECComparison`` + enumerator that shows the difference between them. + + .. rubric:: Syntax + :name: syntax_12 + + .. code:: + + #include <secitem.h> + #include <seccomon.h> + + .. code:: + + SECComparison SECITEM_CompareItem( + SECItem *a, + SECItem *b); + + .. rubric:: Parameters + :name: parameters_9 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to one of the items to be compared. | + | | | + | a | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to one of the items to be compared. | + | | | + | b | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_10 + + The function returns an enumerator of type ``SECComparison``. + + .. code:: + + typedef enum _SECComparison { + SECLessThan = -1, + SECEqual = 0, + SECGreaterThan = 1 + } SECComparison;
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslerr/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslerr/index.rst new file mode 100644 index 0000000000..50d5a19c81 --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/sslerr/index.rst @@ -0,0 +1,1434 @@ +.. _mozilla_projects_nss_ssl_functions_sslerr: + +sslerr +====== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are + inclined to help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: NSS and SSL Error Codes + :name: NSS_and_SSL_Error_Codes + + -------------- + +.. _chapter_8_nss_and_ssl_error_codes: + +`Chapter 8 + <#chapter_8_nss_and_ssl_error_codes>`__\ NSS and SSL Error Codes +----------------------------------------------------------------- + +.. container:: + + NSS error codes are retrieved using the NSPR function + `PR_GetError <../../../../../nspr/reference/html/prerr.html#PR_GetError>`__. In addition to the + `error codes defined by + NSPR <https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prerr.h>`__, PR_GetError + retrieves the error codes described in this chapter. + + | `SSL Error Codes <#1040263>`__ + | `SEC Error Codes <#1039257>`__ + +.. _ssl_error_codes: + +`SSL Error Codes <#ssl_error_codes>`__ +-------------------------------------- + +.. container:: + + **Table 8.1 Error codes defined in sslerr.h** + + +--------------------------------+--------------------------------+--------------------------------+ + | **Constant** | **Value** | **Description** | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_EXPORT_ONLY_SERVER | -12288 | "Unable to communicate | + | | | securely. Peer does not | + | | | support high-grade | + | | | encryption." | + | | | | + | | | The local system was | + | | | configured to support the | + | | | cipher suites permitted for | + | | | domestic use. The remote | + | | | system was configured to | + | | | support only the cipher suites | + | | | permitted for export use. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_US_ONLY_SERVER | -12287 | "Unable to communicate | + | | | securely. Peer requires | + | | | high-grade encryption which is | + | | | not supported." | + | | | | + | | | The remote system was | + | | | configured to support the | + | | | cipher suites permitted for | + | | | domestic use. The local system | + | | | was configured to support only | + | | | the cipher suites permitted | + | | | for export use. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_NO_CYPHER_OVERLAP | -12286 | "Cannot communicate securely | + | | | with peer: no common | + | | | encryption algorithm(s)." | + | | | | + | | | The local and remote systems | + | | | share no cipher suites in | + | | | common. This can be due to a | + | | | misconfiguration at either | + | | | end. It can be due to a server | + | | | being misconfigured to use a | + | | | non-RSA certificate with the | + | | | RSA key exchange algorithm. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_NO_CERTIFICATE | -12285 | "Unable to find the | + | | | certificate or key necessary | + | | | for authentication." | + | | | | + | | | This error has many potential | + | | | causes; for example: | + | | | | + | | | Certificate or key not found | + | | | in database. | + | | | | + | | | Certificate not marked trusted | + | | | in database and Certificate's | + | | | issuer not marked trusted in | + | | | database. | + | | | | + | | | Wrong password for key | + | | | database. | + | | | | + | | | Missing database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_CERTIFICATE | -12284 | "Unable to communicate | + | | | securely with peer: peers's | + | | | certificate was rejected." | + | | | | + | | | A certificate was received | + | | | from the remote system and was | + | | | passed to the certificate | + | | | authentication callback | + | | | function provided by the local | + | | | application. That callback | + | | | function returned SECFailure, | + | | | and the bad certificate | + | | | callback function either was | + | | | not configured or did not | + | | | choose to override the error | + | | | code returned by the | + | | | certificate authentication | + | | | callback function. | + +--------------------------------+--------------------------------+--------------------------------+ + | | -12283 | (unused) | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_CLIENT | -12282 | "The server has encountered | + | | | bad data from the client." | + | | | | + | | | This error code should occur | + | | | only on sockets that are | + | | | acting as servers. It is a | + | | | generic error, used when none | + | | | of the other more specific | + | | | error codes defined in this | + | | | file applies. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_SERVER | -12281 | "The client has encountered | + | | | bad data from the server." | + | | | | + | | | This error code should occur | + | | | only on sockets that are | + | | | acting as clients. It is a | + | | | generic error, used when none | + | | | of the other more specific | + | | | error codes defined in this | + | | | file applies. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERRO | -12280 | "Unsupported certificate | + | R_UNSUPPORTED_CERTIFICATE_TYPE | | type." | + | | | | + | | | The operation encountered a | + | | | certificate that was not one | + | | | of the well known certificate | + | | | types handled by the | + | | | certificate library. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_UNSUPPORTED_VERSION | -12279 | "Peer using unsupported | + | | | version of security protocol." | + | | | | + | | | On a client socket, this means | + | | | the remote server has | + | | | attempted to negotiate the use | + | | | of a version of SSL that is | + | | | not supported by the NSS | + | | | library, probably an invalid | + | | | version number. On a server | + | | | socket, this means the remote | + | | | client has requested the use | + | | | of a version of SSL older than | + | | | version 2. | + +--------------------------------+--------------------------------+--------------------------------+ + | | -12278 | (unused) | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_WRONG_CERTIFICATE | -12277 | "Client authentication failed: | + | | | private key in key database | + | | | does not correspond to public | + | | | key in certificate database." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_CERT_DOMAIN | -12276 | "Unable to communicate | + | | | securely with peer: requested | + | | | domain name does not match the | + | | | server's certificate." | + | | | | + | | | This error code should be | + | | | returned by the certificate | + | | | authentication callback | + | | | function when it detects that | + | | | the Common Name in the remote | + | | | server's certificate does not | + | | | match the hostname sought by | + | | | the local client, according to | + | | | the matching rules specified | + | | | for | + | | | `CERT_VerifyCertN | + | | | ame <sslcrt.html#1050342>`__. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_POST_WARNING | -12275 | (unused) | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_SSL2_DISABLED | -12274 | "Peer only supports SSL | + | | | version 2, which is locally | + | | | disabled." | + | | | | + | | | The remote server has asked to | + | | | use SSL version 2, and SSL | + | | | version 2 is disabled in the | + | | | local client's configuration. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_MAC_READ | -12273 | "SSL received a record with an | + | | | incorrect Message | + | | | Authentication Code." | + | | | | + | | | This usually indicates that | + | | | the client and server have | + | | | failed to come to agreement on | + | | | the set of keys used to | + | | | encrypt the application data | + | | | and to check message | + | | | integrity. If this occurs | + | | | frequently on a server, an | + | | | active attack (such as the | + | | | "million question" attack) may | + | | | be underway against the | + | | | server. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_MAC_ALERT | -12272 | "SSL peer reports incorrect | + | | | Message Authentication Code." | + | | | The remote system has reported | + | | | that it received a message | + | | | with a bad Message | + | | | Authentication Code from the | + | | | local system. This may | + | | | indicate that an attack on | + | | | that server is underway. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_CERT_ALERT | -12271 | "SSL peer cannot verify your | + | | | certificate." | + | | | | + | | | The remote system has received | + | | | a certificate from the local | + | | | system, and has rejected it | + | | | for some reason. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_REVOKED_CERT_ALERT | -12270 | "SSL peer rejected your | + | | | certificate as revoked." | + | | | | + | | | The remote system has received | + | | | a certificate from the local | + | | | system, and has determined | + | | | that the certificate has been | + | | | revoked. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_EXPIRED_CERT_ALERT | -12269 | "SSL peer rejected your | + | | | certificate as expired." | + | | | | + | | | The remote system has received | + | | | a certificate from the local | + | | | system, and has determined | + | | | that the certificate has | + | | | expired. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_SSL_DISABLED | -12268 | "Cannot connect: SSL is | + | | | disabled." | + | | | | + | | | The local socket is configured | + | | | in such a way that it cannot | + | | | use any of the SSL cipher | + | | | suites. Possible causes | + | | | include: (a) both SSL2 and | + | | | SSL3 are disabled, (b) All the | + | | | individual SSL cipher suites | + | | | are disabled, or (c) the | + | | | socket is configured to | + | | | handshake as a server, but the | + | | | certificate associated with | + | | | that socket is inappropriate | + | | | for the Key Exchange Algorithm | + | | | selected. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_FORTEZZA_PQG | -12267 | "Cannot connect: SSL peer is | + | | | in another FORTEZZA domain." | + | | | | + | | | The local system and the | + | | | remote system are in different | + | | | FORTEZZA domains. They must be | + | | | in the same domain to | + | | | communicate. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_UNKNOWN_CIPHER_SUITE | -12266 | "An unknown SSL cipher suite | + | | | has been requested." | + | | | | + | | | The application has attempted | + | | | to configure SSL to use an | + | | | unknown cipher suite. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_NO_CIPHERS_SUPPORTED | -12265 | "No cipher suites are present | + | | | and enabled in this program." | + | | | | + | | | Possible causes: (a) all | + | | | cipher suites have been | + | | | configured to be disabled, (b) | + | | | the only cipher suites that | + | | | are configured to be enabled | + | | | are those that are disallowed | + | | | by cipher export policy, (c) | + | | | the socket is configured to | + | | | handshake as a server, but the | + | | | certificate associated with | + | | | that socket is inappropriate | + | | | for the Key Exchange Algorithm | + | | | selected. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_BAD_BLOCK_PADDING | -12264 | "SSL received a record with | + | | | bad block padding." | + | | | | + | | | SSL was using a Block cipher, | + | | | and the last block in an SSL | + | | | record had incorrect padding | + | | | information in it. This | + | | | usually indicates that the | + | | | client and server have failed | + | | | to come to agreement on the | + | | | set of keys used to encrypt | + | | | the application data and to | + | | | check message integrity. If | + | | | this occurs frequently on a | + | | | server, an active attack (such | + | | | as the "million question" | + | | | attack) may be underway | + | | | against the server. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_RX_RECORD_TOO_LONG | -12263 | "SSL received a record that | + | | | exceeded the maximum | + | | | permissible length." | + | | | | + | | | This generally indicates that | + | | | the remote peer system has a | + | | | flawed implementation of SSL, | + | | | and is violating the SSL | + | | | specification. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_TX_RECORD_TOO_LONG | -12262 | "SSL attempted to send a | + | | | record that exceeded the | + | | | maximum permissible length." | + | | | | + | | | This error should never occur. | + | | | If it does, it indicates a | + | | | flaw in the NSS SSL library. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_CLOSE_NOTIFY_ALERT | -12230 | "SSL peer has closed this | + | | | connection." | + | | | | + | | | The local socket received an | + | | | SSL3 alert record from the | + | | | remote peer, reporting that | + | | | the remote peer has chosen to | + | | | end the connection. The | + | | | receipt of this alert is an | + | | | error only if it occurs while | + | | | a handshake is in progress. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12210 | "SSL Server attempted to use | + | OR_PUB_KEY_SIZE_LIMIT_EXCEEDED | | domestic-grade public key with | + | | | export cipher suite." | + | | | | + | | | On a client socket, this error | + | | | reports that the remote server | + | | | has failed to perform an "SSL | + | | | Step down" for an export | + | | | cipher. It has sent a | + | | | certificate bearing a | + | | | domestic-grade public key, but | + | | | has not sent a | + | | | ServerKeyExchange message | + | | | containing an export-grade | + | | | public key for the key | + | | | exchange algorithm. Such a | + | | | connection cannot be permitted | + | | | without violating U.S. export | + | | | policies. On a server socket, | + | | | this indicates a failure of | + | | | the local library. | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -12206 | "Server has no key for the | + | SL_ERROR_NO_SERVER_KEY_FOR_ALG | | attempted key exchange | + | | | algorithm." | + | | | | + | | | An SSL client has requested an | + | | | SSL cipher suite that uses a | + | | | Key Exchange Algorithm for | + | | | which the local server has no | + | | | appropriate public key. This | + | | | indicates a configuration | + | | | error on the local server. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12205 | "PKCS #11 token was inserted | + | _ERROR_TOKEN_INSERTION_REMOVAL | | or removed while operation was | + | | | in progress." | + | | | | + | | | A cryptographic operation | + | | | required to complete the | + | | | handshake failed because the | + | | | token that was performing it | + | | | was removed while the | + | | | handshake was underway. | + | | | Another token may also have | + | | | been inserted into the same | + | | | slot. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_TOKEN_SLOT_NOT_FOUND | -12204 | "No PKCS#11 token could be | + | | | found to do a required | + | | | operation." | + | | | | + | | | A cryptographic operation | + | | | required a PKCS#11 token with | + | | | specific abilities, and no | + | | | token could be found in any | + | | | slot, including the "soft | + | | | token" in the internal virtual | + | | | slot, that could do the job. | + | | | May indicate a server | + | | | configuration error, such as | + | | | having a certificate that is | + | | | inappropriate for the Key | + | | | Exchange Algorithm selected. | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12203 | "Cannot communicate securely | + | L_ERROR_NO_COMPRESSION_OVERLAP | | with peer: no common | + | | | compression algorithm(s)." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12202 | "Cannot initiate another SSL | + | _ERROR_HANDSHAKE_NOT_COMPLETED | | handshake until current | + | | | handshake is complete." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ | -12201 | "Received incorrect handshakes | + | ERROR_BAD_HANDSHAKE_HASH_VALUE | | hash values from peer." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_CERT_KEA_MISMATCH | -12200 | "The certificate provided | + | | | cannot be used with the | + | | | selected key exchange | + | | | algorithm." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ | -12199 | "No certificate authority is | + | ERROR_NO_TRUSTED_SSL_CLIENT_CA | | trusted for SSL client | + | | | authentication." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_SESSION_NOT_FOUND | -12198 | "Client's SSL session ID not | + | | | found in server's session | + | | | cache." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12185 | "SSL server cache not | + | OR_SERVER_CACHE_NOT_CONFIGURED | | configured and not disabled | + | | | for this socket." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12176 | "Renegotiation is not allowed | + | RROR_RENEGOTIATION_NOT_ALLOWED | | on this SSL socket." | + +--------------------------------+--------------------------------+--------------------------------+ + | **Received a malformed (too | | | + | long or short or invalid | | | + | content) SSL handshake: ** | | | + | | | | + | All the error codes in the | | | + | following block indicate that | | | + | the local socket received an | | | + | improperly formatted SSL3 | | | + | handshake message from the | | | + | remote peer. This probably | | | + | indicates a flaw in the remote | | | + | peer's implementation. | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ER | -12261 | "SSL received a malformed | + | ROR_RX_MALFORMED_HELLO_REQUEST | | Hello Request handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12260 | "SSL received a malformed | + | RROR_RX_MALFORMED_CLIENT_HELLO | | Client Hello handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12259 | "SSL received a malformed | + | RROR_RX_MALFORMED_SERVER_HELLO | | Server Hello handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ | -12258 | "SSL received a malformed | + | ERROR_RX_MALFORMED_CERTIFICATE | | Certificate handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR | -12257 | "SSL received a malformed | + | _RX_MALFORMED_SERVER_KEY_EXCH | | Server Key Exchange handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12256 | "SSL received a malformed | + | RROR_RX_MALFORMED_CERT_REQUEST | | Certificate Request handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12255 | "SSL received a malformed | + | _ERROR_RX_MALFORMED_HELLO_DONE | | Server Hello Done handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ | -12254 | "SSL received a malformed | + | ERROR_RX_MALFORMED_CERT_VERIFY | | Certificate Verify handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR | -12253 | "SSL received a malformed | + | _RX_MALFORMED_CLIENT_KEY_EXCH | | Client Key Exchange handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -12252 | "SSL received a malformed | + | SL_ERROR_RX_MALFORMED_FINISHED | | Finished handshake message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_R | -12178 | "SSL received a malformed New | + | X_MALFORMED_NEW_SESSION_TICKET | | Session Ticket handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | **Received a malformed (too | | | + | long or short) SSL record:** | | | + | | | | + | All the error codes in the | | | + | following block indicate that | | | + | the local socket received an | | | + | improperly formatted SSL3 | | | + | record from the remote peer. | | | + | This probably indicates a flaw | | | + | in the remote peer's | | | + | implementation. | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ER | -12251 | "SSL received a malformed | + | ROR_RX_MALFORMED_CHANGE_CIPHER | | Change Cipher Spec record." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_RX_MALFORMED_ALERT | -12250 | "SSL received a malformed | + | | | Alert record." | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12249 | "SSL received a malformed | + | L_ERROR_RX_MALFORMED_HANDSHAKE | | Handshake record." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ | -12248 | "SSL received a malformed | + | RX_MALFORMED_APPLICATION_DATA | | Application Data record." | + +--------------------------------+--------------------------------+--------------------------------+ + | **Received an SSL handshake | | | + | that was inappropriate for the | | | + | current state:** | | | + | | | | + | All the error codes in the | | | + | following block indicate that | | | + | the local socket received an | | | + | SSL3 handshake message from | | | + | the remote peer at a time when | | | + | it was inappropriate for the | | | + | peer to have sent this | | | + | message. For example, a server | | | + | received a message from | | | + | another server. This probably | | | + | indicates a flaw in the remote | | | + | peer's implementation. | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12247 | "SSL received an unexpected | + | OR_RX_UNEXPECTED_HELLO_REQUEST | | Hello Request handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ER | -12246 | "SSL received an unexpected | + | ROR_RX_UNEXPECTED_CLIENT_HELLO | | Client Hello handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ER | -12245 | "SSL received an unexpected | + | ROR_RX_UNEXPECTED_SERVER_HELLO | | Server Hello handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12244 | "SSL received an unexpected | + | RROR_RX_UNEXPECTED_CERTIFICATE | | Certificate handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ | -12243 | "SSL received an unexpected | + | RX_UNEXPECTED_SERVER_KEY_EXCH | | Server Key Exchange handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ER | -12242 | "SSL received an unexpected | + | ROR_RX_UNEXPECTED_CERT_REQUEST | | Certificate Request handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ | -12241 | "SSL received an unexpected | + | ERROR_RX_UNEXPECTED_HELLO_DONE | | Server Hello Done handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12240 | "SSL received an unexpected | + | RROR_RX_UNEXPECTED_CERT_VERIFY | | Certificate Verify handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ | -12239 | "SSL received an unexpected | + | RX_UNEXPECTED_CLIENT_KEY_EXCH | | Client Key Exchange handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12238 | "SSL received an unexpected | + | L_ERROR_RX_UNEXPECTED_FINISHED | | Finished handshake message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_RX | -12179 | "SSL received an unexpected | + | _UNEXPECTED_NEW_SESSION_TICKET | | New Session Ticket handshake | + | | | message." | + +--------------------------------+--------------------------------+--------------------------------+ + | **Received an SSL record that | | | + | was inappropriate for the | | | + | current state:** | | | + | | | | + | All the error codes in the | | | + | following block indicate that | | | + | the local socket received an | | | + | SSL3 record from the remote | | | + | peer at a time when it was | | | + | inappropriate for the peer to | | | + | have sent this message. This | | | + | probably indicates a flaw in | | | + | the remote peer's | | | + | implementation. | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12237 | "SSL received an unexpected | + | OR_RX_UNEXPECTED_CHANGE_CIPHER | | Change Cipher Spec record." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_RX_UNEXPECTED_ALERT | -12236 | "SSL received an unexpected | + | | | Alert record." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12235 | "SSL received an unexpected | + | _ERROR_RX_UNEXPECTED_HANDSHAKE | | Handshake record." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ | -12234 | "SSL received an unexpected | + | RX_UNEXPECTED_APPLICATION_DATA | | Application Data record." | + +--------------------------------+--------------------------------+--------------------------------+ + | **Received record/message with | | | + | unknown discriminant:** | | | + | | | | + | All the error codes in the | | | + | following block indicate that | | | + | the local socket received an | | | + | SSL3 record or handshake | | | + | message from the remote peer | | | + | that it was unable to | | | + | interpret because the byte | | | + | that identifies the type of | | | + | record or message contained an | | | + | unrecognized value. This | | | + | probably indicates a flaw in | | | + | the remote peer's | | | + | implementation. | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12233 | "SSL received a record with an | + | L_ERROR_RX_UNKNOWN_RECORD_TYPE | | unknown content type." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_RX_UNKNOWN_HANDSHAKE | -12232 | "SSL received a handshake | + | | | message with an unknown | + | | | message type." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_RX_UNKNOWN_ALERT | -12231 | "SSL received an alert record | + | | | with an unknown alert | + | | | description." | + +--------------------------------+--------------------------------+--------------------------------+ + | **Received an alert report:** | | | + | | | | + | | All the error codes in the | | | + | following block indicate | | | + | that the local socket | | | + | received an SSL3 or TLS | | | + | alert record from the remote | | | + | peer, reporting some issue | | | + | that it had with an SSL | | | + | record or handshake message | | | + | it received. (Some \_Alert | | | + | codes are listed in other | | | + | blocks.) | | | + | | | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ER | -12229 | "SSL peer was not expecting a | + | ROR_HANDSHAKE_UNEXPECTED_ALERT | | handshake message it | + | | | received." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12228 | "SSL peer was unable to | + | OR_DECOMPRESSION_FAILURE_ALERT | | successfully decompress an SSL | + | | | record it received." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12227 | "SSL peer was unable to | + | _ERROR_HANDSHAKE_FAILURE_ALERT | | negotiate an acceptable set of | + | | | security parameters." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12226 | "SSL peer rejected a handshake | + | _ERROR_ILLEGAL_PARAMETER_ALERT | | message for unacceptable | + | | | content." | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12225 | "SSL peer does not support | + | L_ERROR_UNSUPPORTED_CERT_ALERT | | certificates of the type it | + | | | received." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12224 | "SSL peer had some unspecified | + | RROR_CERTIFICATE_UNKNOWN_ALERT | | issue with the certificate it | + | | | received." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12197 | "Peer was unable to decrypt an | + | _ERROR_DECRYPTION_FAILED_ALERT | | SSL record it received." | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -12196 | "Peer received an SSL record | + | SL_ERROR_RECORD_OVERFLOW_ALERT | | that was longer than is | + | | | permitted." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_UNKNOWN_CA_ALERT | -12195 | "Peer does not recognize and | + | | | trust the CA that issued your | + | | | certificate." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ACCESS_DENIED_ALERT | -12194 | "Peer received a valid | + | | | certificate, but access was | + | | | denied." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_DECODE_ERROR_ALERT | -12193 | "Peer could not decode an SSL | + | | | handshake message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_DECRYPT_ERROR_ALERT | -12192 | "Peer reports failure of | + | | | signature verification or key | + | | | exchange." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ | -12191 | "Peer reports negotiation not | + | ERROR_EXPORT_RESTRICTION_ALERT | | in compliance with export | + | | | regulations." | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12190 | "Peer reports incompatible or | + | L_ERROR_PROTOCOL_VERSION_ALERT | | unsupported protocol version." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12189 | "Server requires ciphers more | + | OR_INSUFFICIENT_SECURITY_ALERT | | secure than those supported by | + | | | client." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_INTERNAL_ERROR_ALERT | -12188 | "Peer reports it experienced | + | | | an internal error." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_USER_CANCELED_ALERT | -12187 | "Peer user canceled | + | | | handshake." | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12186 | "Peer does not permit | + | L_ERROR_NO_RENEGOTIATION_ALERT | | renegotiation of SSL security | + | | | parameters." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12184 | "SSL peer does not support | + | OR_UNSUPPORTED_EXTENSION_ALERT | | requested TLS hello | + | | | extension." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ | -12183 | "SSL peer could not obtain | + | CERTIFICATE_UNOBTAINABLE_ALERT | | your certificate from the | + | | | supplied URL." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12182 | "SSL peer has no certificate | + | _ERROR_UNRECOGNIZED_NAME_ALERT | | for the requested DNS name." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ | -12181 | "SSL peer was unable to get an | + | BAD_CERT_STATUS_RESPONSE_ALERT | | OCSP response for its | + | | | certificate." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12180 | "SSL peer reported bad | + | RROR_BAD_CERT_HASH_VALUE_ALERT | | certificate hash value." | + +--------------------------------+--------------------------------+--------------------------------+ + | **Unspecified errors that | | | + | occurred while attempting some | | | + | operation:** | | | + | | | | + | All the error codes in the | | | + | following block describe the | | | + | operation that was being | | | + | attempted at the time of the | | | + | unspecified failure. These | | | + | failures may be caused by the | | | + | system running out of memory, | | | + | or errors returned by PKCS#11 | | | + | routines that did not provide | | | + | meaningful error codes of | | | + | their own. These should rarely | | | + | be seen. (Certain of these | | | + | error codes have more specific | | | + | meanings, as described.) | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12223 | "SSL experienced a failure of | + | _ERROR_GENERATE_RANDOM_FAILURE | | its random number generator." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_SIGN_HASHES_FAILURE | -12222 | "Unable to digitally sign data | + | | | required to verify your | + | | | certificate." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ER | -12221 | "SSL was unable to extract the | + | ROR_EXTRACT_PUBLIC_KEY_FAILURE | | public key from the peer's | + | | | certificate." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12220 | "Unspecified failure while | + | OR_SERVER_KEY_EXCHANGE_FAILURE | | processing SSL Server Key | + | | | Exchange handshake." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERR | -12219 | "Unspecified failure while | + | OR_CLIENT_KEY_EXCHANGE_FAILURE | | processing SSL Client Key | + | | | Exchange handshake." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_ENCRYPTION_FAILURE | -12218 | "Bulk data encryption | + | | | algorithm failed in selected | + | | | cipher suite." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_DECRYPTION_FAILURE | -12217 | "Bulk data decryption | + | | | algorithm failed in selected | + | | | cipher suite." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_SOCKET_WRITE_FAILURE | -12216 | "Attempt to write encrypted | + | | | data to underlying socket | + | | | failed." | + | | | | + | | | After the data to be sent was | + | | | encrypted, the attempt to send | + | | | it out the socket failed. | + | | | Likely causes include that the | + | | | peer has closed the | + | | | connection. | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_MD5_DIGEST_FAILURE | -12215 | "MD5 digest function failed." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_SHA_DIGEST_FAILURE | -12214 | "SHA-1 digest function | + | | | failed." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12213 | "Message Authentication Code | + | _ERROR_MAC_COMPUTATION_FAILURE | | computation failed." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12212 | "Failure to create Symmetric | + | _ERROR_SYM_KEY_CONTEXT_FAILURE | | Key context." | + +--------------------------------+--------------------------------+--------------------------------+ + | SS | -12211 | "Failure to unwrap the | + | L_ERROR_SYM_KEY_UNWRAP_FAILURE | | Symmetric key in Client Key | + | | | Exchange message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_ERROR_IV_PARAM_FAILURE | -12209 | "PKCS11 code failed to | + | | | translate an IV into a param." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL_E | -12208 | "Failed to initialize the | + | RROR_INIT_CIPHER_SUITE_FAILURE | | selected cipher suite." | + +--------------------------------+--------------------------------+--------------------------------+ + | SSL | -12207 | "Failed to generate session | + | _ERROR_SESSION_KEY_GEN_FAILURE | | keys for SSL session." | + | | | | + | | | On a client socket, indicates | + | | | a failure of the PKCS11 key | + | | | generation function. On a | + | | | server socket, indicates a | + | | | failure of one of the | + | | | following: (a) to unwrap the | + | | | pre-master secret from the | + | | | ClientKeyExchange message, (b) | + | | | to derive the master secret | + | | | from the premaster secret, (c) | + | | | to derive the MAC secrets, | + | | | cryptographic keys, and | + | | | initialization vectors from | + | | | the master secret. If | + | | | encountered repeatedly on a | + | | | server socket, this can | + | | | indicate that the server is | + | | | actively under a "million | + | | | question" attack. | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -12177 | "SSL received a compressed | + | SL_ERROR_DECOMPRESSION_FAILURE | | record that could not be | + | | | decompressed." | + +--------------------------------+--------------------------------+--------------------------------+ + +.. _sec_error_codes: + +`SEC Error Codes <#sec_error_codes>`__ +-------------------------------------- + +.. container:: + + **Table 8.2 Security error codes defined in secerr.h** + + +--------------------------------+--------------------------------+--------------------------------+ + | **Constant** | **Value** | **Description** | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_IO | -8192 | An I/O error occurred during | + | | | authentication; or | + | | | an error occurred during | + | | | crypto operation (other than | + | | | signature verification). | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_LIBRARY_FAILURE | -8191 | Security library failure. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_DATA | -8190 | Security library: received bad | + | | | data. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OUTPUT_LEN | -8189 | Security library: output | + | | | length error. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INPUT_LEN | -8188 | Security library: input length | + | | | error. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INVALID_ARGS | -8187 | Security library: invalid | + | | | arguments. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INVALID_ALGORITHM | -8186 | Security library: invalid | + | | | algorithm. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INVALID_AVA | -8185 | Security library: invalid AVA. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INVALID_TIME | -8184 | Security library: invalid | + | | | time. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_DER | -8183 | Security library: improperly | + | | | formatted DER-encoded message. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_SIGNATURE | -8182 | Peer's certificate has an | + | | | invalid signature. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_EXPIRED_CERTIFICATE | -8181 | Peer's certificate has | + | | | expired. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_REVOKED_CERTIFICATE | -8180 | Peer's certificate has been | + | | | revoked. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNKNOWN_ISSUER | -8179 | Peer's certificate issuer is | + | | | not recognized. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_KEY | -8178 | Peer's public key is invalid | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_PASSWORD | -8177 | The password entered is | + | | | incorrect. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_RETRY_PASSWORD | -8176 | New password entered | + | | | incorrectly. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_NODELOCK | -8175 | Security library: no nodelock. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_DATABASE | -8174 | Security library: bad | + | | | database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_MEMORY | -8173 | Security library: memory | + | | | allocation failure. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNTRUSTED_ISSUER | -8172 | Peer's certificate issuer has | + | | | been marked as not trusted by | + | | | the user. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNTRUSTED_CERT | -8171 | Peer's certificate has been | + | | | marked as not trusted by the | + | | | user. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_DUPLICATE_CERT | -8170 | Certificate already exists in | + | | | your database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_DUPLICATE_CERT_NAME | -8169 | Downloaded certificate's name | + | | | duplicates one already in your | + | | | database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_ADDING_CERT | -8168 | Error adding certificate to | + | | | database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_FILING_KEY | -8167 | Error refiling the key for | + | | | this certificate. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_KEY | -8166 | The private key for this | + | | | certificate cannot be found in | + | | | key database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CERT_VALID | -8165 | This certificate is valid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CERT_NOT_VALID | -8164 | This certificate is not valid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CERT_NO_RESPONSE | -8163 | Certificate library: no | + | | | response. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ER | -8162 | The certificate issuer's | + | ROR_EXPIRED_ISSUER_CERTIFICATE | | certificate has expired. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_EXPIRED | -8161 | The CRL for the certificate's | + | | | issuer has expired. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_BAD_SIGNATURE | -8160 | The CRL for the certificate's | + | | | issuer has an invalid | + | | | signature. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_INVALID | -8159 | New CRL has an invalid format. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC | -8158 | Certificate extension value is | + | _ERROR_EXTENSION_VALUE_INVALID | | invalid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_EXTENSION_NOT_FOUND | -8157 | Certificate extension not | + | | | found. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CA_CERT_INVALID | -8156 | Issuer certificate is invalid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERR | -8155 | Certificate path length | + | OR_PATH_LEN_CONSTRAINT_INVALID | | constraint is invalid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CERT_USAGES_INVALID | -8154 | Certificate usages field is | + | | | invalid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_INTERNAL_ONLY | -8153 | Internal-only module. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INVALID_KEY | -8152 | The key does not support the | + | | | requested operation. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ER | -8151 | Certificate contains unknown | + | ROR_UNKNOWN_CRITICAL_EXTENSION | | critical extension. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OLD_CRL | -8150 | New CRL is not later than the | + | | | current one. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_EMAIL_CERT | -8149 | Not encrypted or signed: you | + | | | do not yet have an email | + | | | certificate. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ | -8148 | Not encrypted: you do not have | + | ERROR_NO_RECIPIENT_CERTS_QUERY | | certificates for each of the | + | | | recipients. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NOT_A_RECIPIENT | -8147 | Cannot decrypt: you are not a | + | | | recipient, or matching | + | | | certificate and private key | + | | | not found. | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -8146 | Cannot decrypt: key encryption | + | EC_ERROR_PKCS7_KEYALG_MISMATCH | | algorithm does not match your | + | | | certificate. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKCS7_BAD_SIGNATURE | -8145 | Signature verification failed: | + | | | no signer found, too many | + | | | signers found, \\ | + | | | or improper or corrupted data. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNSUPPORTED_KEYALG | -8144 | Unsupported or unknown key | + | | | algorithm. | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -8143 | Cannot decrypt: encrypted | + | EC_ERROR_DECRYPTION_DISALLOWED | | using a disallowed algorithm | + | | | or key size. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_SEC_FORTEZZA_BAD_CARD | -8142 | FORTEZZA card has not been | + | | | properly initialized. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_SEC_FORTEZZA_NO_CARD | -8141 | No FORTEZZA cards found. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_SEC_FORTEZZA_NONE_SELECTED | -8140 | No FORTEZZA card selected. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_SEC_FORTEZZA_MORE_INFO | -8139 | Please select a personality to | + | | | get more info on. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP | -8138 | Personality not found | + | _SEC_FORTEZZA_PERSON_NOT_FOUND | | | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_SEC_FORTEZZA_NO_MORE_INFO | -8137 | No more information on that | + | | | personality. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_SEC_FORTEZZA_BAD_PIN | -8136 | Invalid PIN. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_SEC_FORTEZZA_PERSON_ERROR | -8135 | Couldn't initialize FORTEZZA | + | | | personalities. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_KRL | -8134 | No KRL for this site's | + | | | certificate has been found. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_KRL_EXPIRED | -8133 | The KRL for this site's | + | | | certificate has expired. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_KRL_BAD_SIGNATURE | -8132 | The KRL for this site's | + | | | certificate has an invalid | + | | | signature. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_REVOKED_KEY | -8131 | The key for this site's | + | | | certificate has been revoked. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_KRL_INVALID | -8130 | New KRL has an invalid format. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NEED_RANDOM | -8129 | Security library: need random | + | | | data. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_MODULE | -8128 | Security library: no security | + | | | module can perform the | + | | | requested operation. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_TOKEN | -8127 | The security card or token | + | | | does not exist, needs to be | + | | | initialized, or has been | + | | | removed. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_READ_ONLY | -8126 | Security library: read-only | + | | | database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_SLOT_SELECTED | -8125 | No slot or token was selected. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC | -8124 | A certificate with the same | + | _ERROR_CERT_NICKNAME_COLLISION | | nickname already exists. | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8123 | A key with the same nickname | + | C_ERROR_KEY_NICKNAME_COLLISION | | already exists. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_SAFE_NOT_CREATED | -8122 | Error while creating safe | + | | | object. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAGGAGE_NOT_CREATED | -8121 | Error while creating baggage | + | | | object. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_JAVA_REMOVE_PRINCIPAL_ERROR | -8120 | Couldn't remove the principal. | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_JAVA_DELETE_PRIVILEGE_ERROR | -8119 | Couldn't delete the privilege | + +--------------------------------+--------------------------------+--------------------------------+ + | XP_JAVA_CERT_NOT_EXISTS_ERROR | -8118 | This principal doesn't have a | + | | | certificate. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_EXPORT_ALGORITHM | -8117 | Required algorithm is not | + | | | allowed. | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8116 | Error attempting to export | + | C_ERROR_EXPORTING_CERTIFICATES | | certificates. | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8115 | Error attempting to import | + | C_ERROR_IMPORTING_CERTIFICATES | | certificates. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKCS12_DECODING_PFX | -8114 | Unable to import. Decoding | + | | | error. File not valid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKCS12_INVALID_MAC | -8113 | Unable to import. Invalid MAC. | + | | | Incorrect password or corrupt | + | | | file. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PK | -8112 | Unable to import. MAC | + | CS12_UNSUPPORTED_MAC_ALGORITHM | | algorithm not supported. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKC | -8111 | Unable to import. Only | + | S12_UNSUPPORTED_TRANSPORT_MODE | | password integrity and privacy | + | | | modes supported. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR | -8110 | Unable to import. File | + | _PKCS12_CORRUPT_PFX_STRUCTURE | | structure is corrupt. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PK | -8109 | Unable to import. Encryption | + | CS12_UNSUPPORTED_PBE_ALGORITHM | | algorithm not supported. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ER | -8108 | Unable to import. File version | + | ROR_PKCS12_UNSUPPORTED_VERSION | | not supported. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKC | -8107 | Unable to import. Incorrect | + | S12_PRIVACY_PASSWORD_INCORRECT | | privacy password. | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -8106 | Unable to import. Same | + | EC_ERROR_PKCS12_CERT_COLLISION | | nickname already exists in | + | | | database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_USER_CANCELLED | -8105 | The user clicked cancel. | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -8104 | Not imported, already in | + | EC_ERROR_PKCS12_DUPLICATE_DATA | | database. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_MESSAGE_SEND_ABORTED | -8103 | Message not sent. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INADEQUATE_KEY_USAGE | -8102 | Certificate key usage | + | | | inadequate for attempted | + | | | operation. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INADEQUATE_CERT_TYPE | -8101 | Certificate type not approved | + | | | for application. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CERT_ADDR_MISMATCH | -8100 | Address in signing certificate | + | | | does not match address in | + | | | message headers. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERR | -8099 | Unable to import. Error | + | OR_PKCS12_UNABLE_TO_IMPORT_KEY | | attempting to import private | + | | | key. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERR | -8098 | Unable to import. Error | + | OR_PKCS12_IMPORTING_CERT_CHAIN | | attempting to import | + | | | certificate chain. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKCS12_U | -8097 | Unable to export. Unable to | + | NABLE_TO_LOCATE_OBJECT_BY_NAME | | locate certificate or key by | + | | | nickname. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERRO | -8096 | Unable to export. Private key | + | R_PKCS12_UNABLE_TO_EXPORT_KEY | | could not be located and | + | | | exported. | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8095 | Unable to export. Unable to | + | C_ERROR_PKCS12_UNABLE_TO_WRITE | | write the export file. | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -8094 | Unable to import. Unable to | + | EC_ERROR_PKCS12_UNABLE_TO_READ | | read the import file. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKCS1 | -8093 | Unable to export. Key database | + | 2_KEY_DATABASE_NOT_INITIALIZED | | corrupt or deleted. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_KEYGEN_FAIL | -8092 | Unable to generate | + | | | public-private key pair. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INVALID_PASSWORD | -8091 | Password entered is invalid. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_RETRY_OLD_PASSWORD | -8090 | Old password entered | + | | | incorrectly. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_NICKNAME | -8089 | Certificate nickname already | + | | | in use. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NOT_FORTEZZA_ISSUER | -8088 | Peer FORTEZZA chain has a | + | | | non-FORTEZZA Certificate. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_E | -8087 | "A sensitive key cannot be | + | RROR_CANNOT_MOVE_SENSITIVE_KEY | | moved to the slot where it is | + | | | needed." | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8086 | Invalid module name. | + | C_ERROR_JS_INVALID_MODULE_NAME | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_JS_INVALID_DLL | -8085 | Invalid module path/filename. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_JS_ADD_MOD_FAILURE | -8084 | Unable to add module. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_JS_DEL_MOD_FAILURE | -8083 | Unable to delete module. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OLD_KRL | -8082 | New KRL is not later than the | + | | | current one. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CKL_CONFLICT | -8081 | New CKL has different issuer | + | | | than current CKL. | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8080 | Certificate issuer is not | + | C_ERROR_CERT_NOT_IN_NAME_SPACE | | permitted to issue a | + | | | certificate with this name. | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_KRL_NOT_YET_VALID | -8079 | "The key revocation list for | + | | | this certificate is not yet | + | | | valid." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_NOT_YET_VALID | -8078 | "The certificate revocation | + | | | list for this certificate is | + | | | not yet valid." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNKNOWN_CERT | -8077 | "The requested certificate | + | | | could not be found." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNKNOWN_SIGNER | -8076 | "The signer's certificate | + | | | could not be found." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ | -8075 | "The location for the | + | ERROR_CERT_BAD_ACCESS_LOCATION | | certificate status server has | + | | | invalid format." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ER | -8074 | "The OCSP response cannot be | + | ROR_OCSP_UNKNOWN_RESPONSE_TYPE | | fully decoded; it is of an | + | | | unknown type." | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8073 | "The OCSP server returned | + | C_ERROR_OCSP_BAD_HTTP_RESPONSE | | unexpected/invalid HTTP data." | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8072 | "The OCSP server found the | + | C_ERROR_OCSP_MALFORMED_REQUEST | | request to be corrupted or | + | | | improperly formed." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OCSP_SERVER_ERROR | -8071 | "The OCSP server experienced | + | | | an internal error." | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -8070 | "The OCSP server suggests | + | EC_ERROR_OCSP_TRY_SERVER_LATER | | trying again later." | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8069 | "The OCSP server requires a | + | C_ERROR_OCSP_REQUEST_NEEDS_SIG | | signature on this request." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_E | -8068 | "The OCSP server has refused | + | RROR_OCSP_UNAUTHORIZED_REQUEST | | this request as unauthorized." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERRO | -8067 | "The OCSP server returned an | + | R_OCSP_UNKNOWN_RESPONSE_STATUS | | unrecognizable status." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OCSP_UNKNOWN_CERT | -8066 | "The OCSP server has no status | + | | | for the certificate." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OCSP_NOT_ENABLED | -8065 | "You must enable OCSP before | + | | | performing this operation." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_E | -8064 | "You must set the OCSP default | + | RROR_OCSP_NO_DEFAULT_RESPONDER | | responder before performing | + | | | this operation." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC | -8063 | "The response from the OCSP | + | _ERROR_OCSP_MALFORMED_RESPONSE | | server was corrupted or | + | | | improperly formed." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ER | -8062 | "The signer of the OCSP | + | ROR_OCSP_UNAUTHORIZED_RESPONSE | | response is not authorized to | + | | | give status for this | + | | | certificate." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OCSP_FUTURE_RESPONSE | -8061 | "The OCSP response is not yet | + | | | valid (contains a date in the | + | | | future)." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OCSP_OLD_RESPONSE | -8060 | "The OCSP response contains | + | | | out-of-date information." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_DIGEST_NOT_FOUND | -8059 | "The CMS or PKCS #7 Digest was | + | | | not found in signed message." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ | -8058 | "The CMS or PKCS #7 Message | + | ERROR_UNSUPPORTED_MESSAGE_TYPE | | type is unsupported." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_MODULE_STUCK | -8057 | "PKCS #11 module could not be | + | | | removed because it is still in | + | | | use." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_TEMPLATE | -8056 | "Could not decode ASN.1 data. | + | | | Specified template was | + | | | invalid." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_NOT_FOUND | -8055 | "No matching CRL was found." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ | -8054 | "You are attempting to import | + | ERROR_REUSED_ISSUER_AND_SERIAL | | a cert with the same | + | | | issuer/serial as an existing | + | | | cert, but that is not the same | + | | | cert." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BUSY | -8053 | "NSS could not shutdown. | + | | | Objects are still in use." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_EXTRA_INPUT | -8052 | "DER-encoded message contained | + | | | extra unused data." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ER | -8051 | "Unsupported elliptic curve." | + | ROR_UNSUPPORTED_ELLIPTIC_CURVE | | | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_E | -8050 | "Unsupported elliptic curve | + | RROR_UNSUPPORTED_EC_POINT_FORM | | point form." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNRECOGNIZED_OID | -8049 | "Unrecognized Object | + | | | IDentifier." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_E | -8048 | "Invalid OCSP signing | + | RROR_OCSP_INVALID_SIGNING_CERT | | certificate in OCSP response." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC | -8047 | "Certificate is revoked in | + | _ERROR_REVOKED_CERTIFICATE_CRL | | issuer's certificate | + | | | revocation list." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ | -8046 | "Issuer's OCSP responder | + | ERROR_REVOKED_CERTIFICATE_OCSP | | reports certificate is | + | | | revoked." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_INVALID_VERSION | -8045 | "Issuer's Certificate | + | | | Revocation List has an unknown | + | | | version number." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_E | -8044 | "Issuer's V1 Certificate | + | RROR_CRL_V1_CRITICAL_EXTENSION | | Revocation List has a critical | + | | | extension." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_ | -8043 | "Issuer's V2 Certificate | + | CRL_UNKNOWN_CRITICAL_EXTENSION | | Revocation List has an unknown | + | | | critical extension." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNKNOWN_OBJECT_TYPE | -8042 | "Unknown object type | + | | | specified." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_INCOMPATIBLE_PKCS11 | -8041 | "PKCS #11 driver violates the | + | | | spec in an incompatible way." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NO_EVENT | -8040 | "No new slot event is | + | | | available at this time." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_ALREADY_EXISTS | -8039 | "CRL already exists." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_NOT_INITIALIZED | -8038 | "NSS is not initialized." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_TOKEN_NOT_LOGGED_IN | -8037 | "The operation failed because | + | | | the PKCS#11 token is not | + | | | logged in." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERR | -8036 | "The configured OCSP | + | OR_OCSP_RESPONDER_CERT_INVALID | | responder's certificate is | + | | | invalid." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OCSP_BAD_SIGNATURE | -8035 | "OCSP response has an invalid | + | | | signature." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_OUT_OF_SEARCH_LIMITS | -8034 | "Certification validation | + | | | search is out of search | + | | | limits." | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8033 | "Policy mapping contains | + | C_ERROR_INVALID_POLICY_MAPPING | | any-policy." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ | -8032 | "Certificate chain fails | + | ERROR_POLICY_VALIDATION_FAILED | | policy validation." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_E | -8031 | "Unknown location type in | + | RROR_UNKNOWN_AIA_LOCATION_TYPE | | certificate AIA extension." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_HTTP_RESPONSE | -8030 | "Server returned a bad HTTP | + | | | response." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_BAD_LDAP_RESPONSE | -8029 | "Server returned a bad LDAP | + | | | response." | + +--------------------------------+--------------------------------+--------------------------------+ + | S | -8028 | "Failed to encode data with | + | EC_ERROR_FAILED_TO_ENCODE_DATA | | ASN.1 encoder." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ | -8027 | "Bad information access | + | ERROR_BAD_INFO_ACCESS_LOCATION | | location in certificate | + | | | extension." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_LIBPKIX_INTERNAL | -8026 | "Libpkix internal error | + | | | occurred during cert | + | | | validation." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKCS11_GENERAL_ERROR | -8025 | "A PKCS #11 module returned | + | | | CKR_GENERAL_ERROR, indicating | + | | | that an unrecoverable error | + | | | has occurred." | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8024 | "A PKCS #11 module returned | + | C_ERROR_PKCS11_FUNCTION_FAILED | | CKR_FUNCTION_FAILED, | + | | | indicating that the requested | + | | | function could not be | + | | | performed. Trying the same | + | | | operation again might | + | | | succeed." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_PKCS11_DEVICE_ERROR | -8023 | "A PKCS #11 module returned | + | | | CKR_DEVICE_ERROR, indicating | + | | | that a problem has occurred | + | | | with the token or slot." | + +--------------------------------+--------------------------------+--------------------------------+ + | SE | -8022 | "Unknown information access | + | C_ERROR_BAD_INFO_ACCESS_METHOD | | method in certificate | + | | | extension." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_CRL_IMPORT_FAILED | -8021 | "Error attempting to import a | + | | | CRL." | + +--------------------------------+--------------------------------+--------------------------------+ + | SEC_ERROR_UNKNOWN_PKCS11_ERROR | -8018 | "Unknown PKCS #11 error." | + | | | (unknown error value mapping) | + +--------------------------------+--------------------------------+--------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslfnc/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslfnc/index.rst new file mode 100644 index 0000000000..9bfbd92fc0 --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/sslfnc/index.rst @@ -0,0 +1,3595 @@ +.. _mozilla_projects_nss_ssl_functions_sslfnc: + +sslfnc +====== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to + help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: SSL Functions + :name: SSL_Functions + + -------------- + +.. _chapter_4_ssl_functions: + +`Chapter 4 SSL Functions <#chapter_4_ssl_functions>`__ +------------------------------------------------------ + +.. container:: + + This chapter describes the core SSL functions. + + - `SSL Initialization Functions <#ssl_initialization_functions>`__ + - `SSL Export Policy Functions <#ssl_export_policy_functions>`__ + - `SSL Configuration Functions <#ssl_configuration_functions>`__ + - `SSL Communication Functions <#ssl_communication_functions>`__ + - `SSL Functions Used by Callbacks <#ssl_functions_used_by_callbacks>`__ + - `SSL Handshake Functions <#ssl_handshake_functions>`__ + - `NSS Shutdown Function <#nss_shutdown_function>`__ + - `Deprecated Functions <#deprecated_functions>`__ + +.. _ssl_initialization_functions: + +`SSL Initialization Functions <#ssl_initialization_functions>`__ +---------------------------------------------------------------- + +.. container:: + + This section describes the initialization functions that are specific to SSL. For a complete list + of NSS initialization functions, see `Initialization <sslintro.html#1027662>`__. + + Note that at least one of the functions listed in `SSL Export Policy Functions <#1098841>`__ must + also be called during NSS initialization. + + | ```NSS_Init`` <#1067601>`__ + | ```NSS_InitReadWrite`` <#1237143>`__ + | ```NSS_NoDB_Init`` <#1234224>`__ + | ```SSL_OptionSetDefault`` <#1068466>`__ + | ```SSL_OptionGetDefault`` <#1204897>`__ + | ```SSL_CipherPrefSetDefault`` <#1084747>`__ + | ```SSL_CipherPrefGetDefault`` <#1208119>`__ + | ```SSL_ClearSessionCache`` <#1138601>`__ + | ```SSL_ConfigServerSessionIDCache`` <#1143851>`__ + | ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ + | ```SSL_InheritMPServerSIDCache`` <#1162055>`__ + + .. rubric:: NSS_Init + :name: nss_init + + Sets up configuration files and performs other tasks required to run Network Security Services. + Database files are opened read-only. + + .. rubric:: Syntax + :name: syntax + + .. code:: + + #include "nss.h" + + .. code:: + + SECStatus NSS_Init(char *configdir); + + .. rubric:: Parameter + :name: parameter + + This function has the following parameter: + + +---------------+---------------------------------------------------------------------------------+ + | ``configdir`` | A pointer to a string containing the pathname of the directory where the | + | | certificate, key, and security module databases reside. | + +---------------+---------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code. + + .. rubric:: Description + :name: description + + ``NSS_Init`` opens the ``cert``\ *N*\ ``.db``, ``key``\ *N*\ ``.db``, and ``secmod.db`` files + (where\ *N* is a numeric digit) in the specified directory. ``NSS_Init`` is\ *not* idempotent, so + call it only once. + + ``NSS_Init`` opens the database files read-only. If you are performing operations that require + write permission, for example S/MIME operations such as adding a certificate, use + ```NSS_InitReadWrite`` <#1237143>`__ instead. + + Before calling ``NSS_Init``, your program must call ``PR_Init``. + + The policy flags for all cipher suites are turned off by default, disallowing all cipher suites. + Therefore, an application cannot use NSS to perform any cryptographic operations until after it + enables appropriate cipher suites by calling one of the `SSL Export Policy + Functions <#1098841>`__: + + - ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, and + ```NSS_SetFrancePolicy`` <#1105952>`__ configure the cipher suites for domestic, + international, and French versions of software products with encryption features. + - ```SSL_CipherPolicySet`` <#1104647>`__ sets policy flags for individual cipher suites, one at + a time. This may be helpful if you have an export license that permits more or fewer + capabilities than those allowed by the other export policy functions. + + .. rubric:: NSS_InitReadWrite + :name: nss_initreadwrite + + Sets up configuration files and performs other tasks required to run Network Security Services. + Unlike ```NSS_Init`` <#1067601>`__, ``NSS_InitReadWrite`` provides both read and write access to + database files. + + .. rubric:: Syntax + :name: syntax_2 + + .. code:: + + #include "nss.h" + + .. code:: + + SECStatus NSS_InitReadWrite(char *configdir); + + .. rubric:: Parameter + :name: parameter_2 + + This function has the following parameter: + + +---------------+---------------------------------------------------------------------------------+ + | ``configdir`` | A pointer to a string containing the pathname of the directory where the | + | | certificate, key, and security module databases reside. | + +---------------+---------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_2 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code. + + .. rubric:: Description + :name: description_2 + + ``NSS_InitReadWrite`` opens the ``cert``\ *N*\ ``.db``, ``key``\ *N*\ ``.db``, and ``secmod.db`` + files (where\ *N* is a numeric digit) with both read and write permission in the specified + directory. ``NSS_InitReadWrite`` is\ *not* idempotent, so call it only once. + + Use ``NSS_InitReadWrite`` rather than ```NSS_Init`` <#1067601>`__ if you are performing + operations that require write permission, such as some S/MIME operations. + + Before calling ``NSS_InitReadWrite``, your program must call ``PR_Init``. + + The policy flags for all cipher suites are turned off by default, disallowing all cipher suites. + Therefore, an application cannot use NSS to perform any cryptographic operations until after it + enables appropriate cipher suites by calling one of the `SSL Export Policy + Functions <#1098841>`__. + + .. rubric:: NSS_NoDB_Init + :name: nss_nodb_init + + Performs tasks required to run Network Security Services without setting up configuration files. + **Important:** This NSS function is not intended for use with SSL, which requires that the + certificate and key database files be opened. + + .. rubric:: Syntax + :name: syntax_3 + + .. code:: + + #include "nss.h" + + .. code:: + + SECStatus NSS_NoDB_Init(char *reserved); + + .. rubric:: Parameter + :name: parameter_3 + + This function has the following parameter: + + ============ ==================== + ``reserved`` Should be ``NULL``.. + ============ ==================== + + .. rubric:: Returns + :name: returns_3 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use ``PR_GetError`` to retrieve the error code. + + .. rubric:: Description + :name: description_3 + + ``NSS_NoDB_Init`` opens only the temporary database and the internal PKCS #112 module. Unlike + ``NSS_Init``, ``NSS_NoDB_Init`` allows applications that do not have access to storage for + databases to run raw crypto, hashing, and certificate functions. + + ``NSS_NoDB_Init`` is\ *not* idempotent, so call it only once. + + Before calling ``NSS_NoDB_Init``, your program must call ``PR_Init``. + + The policy flags for all cipher suites are turned off by default, disallowing all cipher suites. + Therefore, an application cannot use NSS to perform any cryptographic operations until after it + enables appropriate cipher suites by calling one of the `SSL Export Policy + Functions <#1098841>`__. + + .. rubric:: SSL_OptionSetDefault + :name: ssl_optionsetdefault + + Changes the default value of a specified SSL option for all subsequently opened sockets as long + as the current application program is running. + + ``SSL_OptionSetDefault`` replaces the deprecated function ```SSL_EnableDefault`` <#1206365>`__. + + .. rubric:: Syntax + :name: syntax_4 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_OptionSetDefault(PRInt32 option, PRBool on); + + .. rubric:: Parameters + :name: parameters + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``option`` | One of the following values (except as noted, | + | | the factory setting is "off"): | + | | | + | | - ``SSL_SECURITY`` enables use of security | + | | protocol. Factory setting is on. WARNING: If | + | | you turn this option off, the session will | + | | not be an SSL session and will not have | + | | certificate-based authentication, tamper | + | | detection, or encryption. | + | | - ``SSL_REQUEST_CERTIFICATE`` is a server | + | | option that requests a client to | + | | authenticate itself. | + | | - ``SSL_REQUIRE_CERTIFICATE`` is a server | + | | option that requires a client to | + | | authenticate itself (only if | + | | ``SSL_REQUEST_CERTIFICATE`` is also on). If | + | | client does not provide certificate, the | + | | connection terminates. Default state is a | + | | third state similar to on, that provides | + | | backward compatibility with older Netscape | + | | server products. | + | | - ``SSL_HANDSHAKE_AS_CLIENT`` controls the | + | | behavior of ``PR_Accept``,. If this option | + | | is off, the ``PR_Accept`` configures the SSL | + | | socket to handshake as a server. If it is | + | | on, then ``PR_Accept`` configures the SSL | + | | socket to handshake as a client, even though | + | | it accepted the connection as a TCP server. | + | | - ``SSL_HANDSHAKE_AS_SERVER`` controls the | + | | behavior of ``PR_Connect``. If this option | + | | is off, then ``PR_Connect`` configures the | + | | SSL socket to handshake as a client. If it | + | | is on, then ``PR_Connect`` configures the | + | | SSL socket to handshake as a server, even | + | | though it connected as a TCP client. | + | | - ``SSL_ENABLE_FDX`` tells the SSL library | + | | whether the application will have two | + | | threads, one reading and one writing, or | + | | just one thread doing reads and writes | + | | alternately. The factory setting for this | + | | option (which is the default, unless the | + | | application changes the default) is off | + | | (``PR_FALSE``), which means that the | + | | application will not do simultaneous reads | + | | and writes. An application that wishes to do | + | | sumultaneous reads and writes should set | + | | this to ``PR_TRUE``. | + | | | + | | In NSS 2.8, the ``SSL_ENABLE_FDX`` option only | + | | affects the behavior of non-blocking SSL | + | | sockets. See the description below for more | + | | information on this option. | + +-------------------------------------------------+-------------------------------------------------+ + | | - ``SSL_ENABLE_SSL3`` enables the application | + | | to communicate with SSL v3. Factory setting | + | | is on. If you turn this option off, an | + | | attempt to establish a connection with a | + | | peer that only understands SSL v3 will fail. | + | | - ``SSL_ENABLE_SSL2`` enables the application | + | | to communicate with SSL v2. Factory setting | + | | is on. If you turn this option off, an | + | | attempt to establish a connection with a | + | | peer that only understands SSL v2 will fail. | + | | - ``SSL_ENABLE_TLS`` is a peer of the | + | | ``SSL_ENABLE_SSL2`` and ``SSL_ENABLE_SSL3`` | + | | options. The IETF standard Transport Layer | + | | Security (TLS) protocol, RFC 2246, is a | + | | modified version of SSL3. It uses the SSL | + | | version number 3.1, appearing to be a | + | | "minor" revision of SSL 3.0. NSS 2.8 | + | | supports TLS in addition to SSL2 and SSL3. | + | | You can think of it as | + | | "``SSL_ENABLE_SSL3.1``". See the description | + | | below for more information about this | + | | option. | + | | - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL | + | | library whether or not to send SSL3 client | + | | hello messages in SSL2-compatible format. If | + | | set to ``PR_TRUE``, it will; otherwise, it | + | | will not. Factory setting is on | + | | (``PR_TRUE``). See the description below for | + | | more information on this option. | + | | - ``SSL_NO_CACHE`` disallows use of the | + | | session cache. Factory setting is off. If | + | | you turn this option on, this socket will be | + | | unable to resume a session begun by another | + | | socket. When this socket's session is | + | | finished, no other socket will be able to | + | | resume the session begun by this socket. | + | | - ``SSL_ROLLBACK_DETECTION`` disables | + | | detection of a rollback attack. Factory | + | | setting is on. You must turn this option off | + | | to interoperate with TLS clients ( such as | + | | certain versions of Microsoft Internet | + | | Explorer) that do not conform to the TLS | + | | specification regarding rollback attacks. | + | | Important: turning this option off means | + | | that your code will not comply with the TLS | + | | 3.1 and SSL 3.0 specifications regarding | + | | rollback attack and will therefore be | + | | vulnerable to this form of attack. | + +-------------------------------------------------+-------------------------------------------------+ + | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns | + | | option off. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_4 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_4 + + This function changes the default values for all subsequently opened sockets as long as the + current application program is running. This function must be called once for each default value + you want to change from the factory setting. To change a value in a socket that is already open, + use ```SSL_OptionSet`` <#1086543>`__. + + Keep the following in mind when deciding on the operating parameters you want to use with a + particular socket: + + Enabling the ``SSL_REQUIRE_CERTIFICATE`` option is not recommended. If the client has no + certificate and this option is enabled, the client's connection terminates with an error. The + user is likely to think something is wrong with either the client or the server, and is unlikely + to realize that the problem is the lack of a certificate. It is better to allow the SSL handshake + to complete and then have your application return an error message to the client that informs the + user of the need for a certificate. + + - As mentioned in `Communication <sslintro.html#1027816>`__, when an application imports a + socket into SSL after the TCP connection on that socket has already been established, it must + call ``SSL_ResetHandshake`` to determine whether the socket is for a client or server. At + first glance this may seem unnecessary, since ``SSL_Enable`` can set + ``SSL_HANDSHAKE_AS_CLIENT`` or ``SSL_HANDSHAKE_AS_SERVER``. However, these settings control + the behavior of + ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__ + and + ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__ + only; if you don't call one of those functions after importing a non-SSL socket with + ``SSL_Import`` (as in the case of an already established TCP connection), SSL still needs to + know whether the application is functioning as a client or server. For a complete discussion + of the use of ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` with + ``SSL_EnableDefault`` and ``SSL_Enable``, see `SSL_OptionSet <#1086543>`__. + - The SSL protocol is defined to be able to handle simultaneous two-way communication between + applications at each end of an SSL connection. Two-way simultaneous communication is also + known as "Full Duplex", abbreviated FDX. However, most application protocols that use SSL are + not two-way simultaneous, but two-way alternate, also known as "Half Dupled"; that is, each + end takes turns sending, and each end is either sending, or receiving, but not both at the + same time. + + For an application to do full duplex, it would typically have two threads sharing the socket; one + doing all the reading and the other doing all the writing. + + The ``SSL_ENABLE_FDX`` option tells the SSL library whether the application will have two + threads, one reading and one writing, or just one thread doing reads and writes alternately. + + - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL library whether or not to send SSL3 client hello + messages in SSL2-compatible format. If an SSL3 client hello message is sent to a server that + only understands SSL2 and not SSL3, then the server will interpret the SSL3 client hello as a + very large message, and the connection will usually seem to "hang" while the SSL2 server + expects more data that will never arrive. For this reason, the SSL3 spec allows SSL3 client + hellos to be sent in SSL2 format, and it recommends that SSL3 servers all accept SSL3 client + hellos in SSL2 format. When an SSL2-only server receives an SSL3 client hello in SSL2 format, + it can (and probably will) negotiate the protocol version correctly, not causing a "hang". + + Some applications may wish to force SSL3 client hellos to be sent in SSL3 format, not in + SSL2-compatible format. They might wish to do this if they knew, somehow, that the server does + not understand SSL2-compatible client hello messages. + + Note that calling ``SSL_Enable`` to set ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly + also sets the ``SSL_ENABLE_SSL2`` option to ``PR_FALSE`` for that SSL socket. Calling + ``SSL_EnableDefault`` to change the application default setting for ``SSL_V2_COMPATIBLE_HELLO`` + to ``PR_FALSE`` implicitly also sets the default value for ``SSL_ENABLE_SSL2`` option to + ``PR_FALSE`` for that application. + + - The options ``SSL_ENABLE_SSL2``, ``SSL_ENABLE_SSL3``, and ``SSL_ENABLE_TLS``\ can each be set + to ``PR_TRUE`` or ``PR_FALSE`` independently of each other. NSS 2.8 will negotiate the higest + protocol version with the peer application from among the set of protocols that are commonly + enabled in both applications. + + Note that SSL3 and TLS share the same set of cipher suites. When both SSL3 and TLS are enabled, + all SSL3/TLS ciphersuites that are enabled are enabled for both SSL3 and TLS. + + .. rubric:: SSL_OptionGetDefault + :name: ssl_optiongetdefault + + Gets the value of a specified SSL default option. + + ``SSL_OptionGetDefault`` is the complementary function for + ```SSL_OptionSetDefault`` <#1068466>`__. + + .. rubric:: Syntax + :name: syntax_5 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_OptionGetDefault(PRInt32 option, PRBool *on) + + .. rubric:: Parameters + :name: parameters_2 + + This function has the parameters listed below. + + +------------+------------------------------------------------------------------------------------+ + | ``option`` | The value of the option whose default setting you wish to get. For information | + | | about the options available and the possible values to pass in this parameter, see | + | | the description of the ``option`` parameter under | + | | ```SSL_OptionSetDefault`` <#1068466>`__. | + +------------+------------------------------------------------------------------------------------+ + | ``on`` | A pointer to the value of the option specified in the option parameter. | + | | ``PR_TRUE`` indicates that the option is on; ``PR_FALSE`` indicates that the | + | | option is off. | + +------------+------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_5 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain error code. + + .. rubric:: Description + :name: description_5 + + ``SSL_CipherPrefGetDefault`` gets the application default preference for the specified SSL2, + SSL3, or TLS cipher A cipher suite is used only if the policy allows it and the preference for it + is set to ``PR_TRUE``. + + .. rubric:: SSL_CipherPrefSetDefault + :name: ssl_cipherprefsetdefault + + Enables or disables SSL2 or SSL3 cipher suites (subject to which cipher suites are permitted or + disallowed by previous calls to one or more of the `SSL Export Policy Functions <#1098841>`__). + This function must be called once for each cipher you want to enable or disable by default. + + .. rubric:: Syntax + :name: syntax_6 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool enabled); + + .. rubric:: Parameters + :name: parameters_3 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``cipher`` | One of the following values for SSL2 (factory | + | | settings for all are enabled): | + | | | + | | ``SSL_EN_RC4_128_WITH_ | + | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 | + | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 | + | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W | + | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` | + | | | + | | Or one of the following values for SSL3/TLS | + | | (unless indicated otherwise, factory settings | + | | for all are enabled): | + | | | + | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` (not enabled | + | | by default) | + | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` | + | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (not enabled | + | | by default; client side only) | + | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``SSL_RSA_WITH_RC4_128_MD5`` | + | | ``SSL_RSA_WITH_RC4_128_SHA`` (not enabled by | + | | default) | + | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` (not enabled | + | | by default) | + | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` | + | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` | + | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` | + | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (not enabled | + | | by default; client side only) | + | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (not enabled | + | | by default; client side only) | + | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` | + | | ``SSL_RSA_WITH_DES_CBC_SHA`` | + | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` | + | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` | + | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` | + | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` | + | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` | + | | ``SSL_RSA_WITH_NULL_SHA`` (not enabled by | + | | default) | + | | ``SSL_RSA_WITH_NULL_MD5`` (not enabled by | + | | default) | + +-------------------------------------------------+-------------------------------------------------+ + | ``enabled`` | If nonzero, the specified cipher is enabled. If | + | | zero, the cipher is disabled. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_6 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_6 + + The CipherPrefSetDefault function enables or disables individual cipher suites globally. You + typically call this in response to changes in user-controlled settings. You must call this + function once for each cipher you want to enable or disable. To enable or disable cipher suites + for an individual socket, use ```SSL_CipherPrefSet`` <#1214758>`__. + + The set of available SSL cipher suites may grow from release to release of NSS. Applications will + find it desirable to determine, at run time, what SSL2 cipher kinds and SSL3 cipher suites are + actually implememted in a particular release. Applications may disable any cipher suites that + they don't know about (for example, that they cannot present to the user via a GUI). To that end, + NSS provides a table that can be examined at run time. All aspects of this table are declared in + ``ssl.h``. + + ``SSL_ImplementedCiphers[]`` is an external array of unsigned 16-bit integers whose values are + either SSL2 cipher kinds or SSL3 cipher suites. The values are the same as the values used to + enable or disable a cipher suite via calls to ```SSL_CipherPrefSetDefault`` <#1084747>`__, and + are defined in ``sslproto.h``. The number of values in the table is contained in an external + 16-bit integer named ``SSL_NumImplementedCiphers``. The macro ``SSL_IS_SSL2_CIPHER`` can be used + to determine whether a particular value is an SSL2 or an SSL3 cipher. + + **WARNING**: Using the external array ``SSL_ImplementedCiphers[]`` directly is deprecated. It + causes dynamic linking issues at run-time after an update of NSS because the actual size of the + array changes between releases. The recommended way of accessing the array is through the + ``SSL_GetImplementedCiphers()`` and ``SSL_GetNumImplementedCiphers()`` accessors. + + By default, all SSL2 and 12 SSL3/TLS cipher suites are enabled. However, this does not + necessarily mean that they are all permitted. The ``SSL_CipherPrefSetDefault`` function cannot + override cipher suite policy settings that are not permitted; see `SSL Export Policy + Functions <#1098841>`__ for details. Your application must call one of the export policy + functions before it can perform any cryptographic operations. + + The ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` and ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` cipher + suites are defined in RFC 2246. They work with both SSL3 and TLS. They use symmetric ciphers with + an effective key size of 56 bits. The so-called 56-bit export browsers and servers use these + cipher suites. + + The cipher suite numbers for the ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` and + ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` cipher suites have been changed so that they are no longer + "experimental" values. If an application attempts to set or set the policy or preference for one + of the old FIPS cipher suite numbers, the library recognizes the old number and sets or gets the + value for the new cipher suite number instead. + + In this release, the three ``SSL_FORTEZZA_`` cipher suites cannot be enabled unless there is a + PKCS #11 module available with a FORTEZZA-enabled token. The ``SSL_FORTEZZA_`` cipher suites will + be removed in NSS 3.11. + + .. rubric:: SSL_CipherPrefGetDefault + :name: ssl_cipherprefgetdefault + + Gets the current default preference setting for a specified SSL2 or SSL3 cipher suite. + + .. rubric:: Syntax + :name: syntax_7 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_CipherPrefSetDefault(PRInt32 cipher, PRBool *enabled); + + .. rubric:: Parameters + :name: parameters_4 + + This function has the parameters listed below. + + +---------+---------------------------------------------------------------------------------------+ + | cipher | The cipher suite whose default preference setting you want to get. For a list of the | + | | cipher suites you can specify, see ```SSL_CipherPrefSetDefault`` <#1084747>`__. | + +---------+---------------------------------------------------------------------------------------+ + | enabled | A pointer to the default value associated with the cipher specified in the ``cipher`` | + | | parameter. If nonzero, the specified cipher is enabled. If zero, the cipher is | + | | disabled. | + +---------+---------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_7 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain error code. + + .. rubric:: Description + :name: description_7 + + ``SSL_CipherPrefGetDefault`` performs the complementary function to ``SSL_CipherPrefSetDefault``. + It returns the application process' current default preference value for the specified cipher + suite. If the application has not previously set the default preference, + ``SSL_CipherPrefGetDefault`` returns the factory setting. + + .. rubric:: SSL_ClearSessionCache + :name: ssl_clearsessioncache + + Empties the SSL client session ID cache. + + .. rubric:: Syntax + :name: syntax_8 + + .. code:: + + #include "ssl.h" + + .. code:: + + void SSL_ClearSessionCache(void); + + .. rubric:: Description + :name: description_8 + + You must call ``SSL_ClearSessionCache`` after you use one of the `SSL Export Policy + Functions <#1098841>`__ to change cipher suite policy settings or use + ```SSL_CipherPrefSetDefault`` <#1084747>`__ to enable or disable any cipher suite. Otherwise, the + old settings remain in the session cache and will be used instead of the new settings. + + This function clears only the client cache. The client cache is not configurable. It is located + in RAM (not on disk), and has the following characteristics: + + - maximum number of entries: unlimited + - SSL 2.0 timeout value: 100 seconds + - SSL 3.0 timeout value: 24 hours + + .. + + **NOTE:** If an SSL client application does not call ``SSL_ClearSessionCache`` before + shutdown, ```NSS_Shutdown`` <#1061858>`__ fails with the error code ``SEC_ERROR_BUSY``. + + .. rubric:: SSL_ConfigServerSessionIDCache + :name: ssl_configserversessionidcache + + Sets up parameters for and opens the server session cache for a single-process application. + + .. rubric:: Syntax + :name: syntax_9 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_ConfigServerSessionIDCache( + int maxCacheEntries, + PRUint32 timeout, + PRUint32 ssl3_timeout, + const char *directory); + + .. rubric:: Parameters + :name: parameters_5 + + This function has the parameters listed below. + + +---------------------+---------------------------------------------------------------------------+ + | ``maxCacheEntries`` | The maximum number of entries in the cache. If a ``NULL`` value is | + | | passed, the server default value of 10,000 is used. | + +---------------------+---------------------------------------------------------------------------+ + | ``timeout`` | The lifetime in seconds of an SSL2 session. The minimum timeout value is | + | | 5 seconds and the maximum is 24 hours. Values outside this range are | + | | replaced by the server default value of 100 seconds. | + +---------------------+---------------------------------------------------------------------------+ + | ``ssl3_timeout`` | The lifetime in seconds of an SSL3 session. The minimum timeout value is | + | | 5 seconds and the maximum is 24 hours. Values outside this range are | + | | replaced by the server default value of 24 hours. | + +---------------------+---------------------------------------------------------------------------+ + | ``directory`` | A pointer to a string specifying the pathname of the directory that will | + | | contain the session cache. If a ``NULL`` value is passed, the server | + | | default value is used: ``/tmp`` (Unix) or ``\\temp`` (NT). | + +---------------------+---------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_8 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain error code. + + .. rubric:: Description + :name: description_9 + + If you are writing an application that will use SSL sockets that handshake as a server, you must + call ``SSL_ConfigServerSessionIDCache`` to configure additional session caches for *server* + sessions. If your server application uses multiple processes (instead of or in addition to + multiple threads), use ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ instead. You must use one of + these functions to create a server cache. This function creates two caches: the\ *server session + ID cache* (also called the server session cache, or server cache), and the\ *client-auth + certificate cache* (also called the client cert cache, or client auth cache). Both caches are + used only for sessions where the program handshakes as a server. The client-auth certificate + cache is used to remember the certificates previously presented by clients for client certificate + authentication. + + Passing a ``NULL`` value or a value that is out of range for any of the parameters causes the + server default value to be used in the server cache. The values that you pass affect only the + server cache, not the client cache. + +.. _initializing_multi-processing_with_a_shared_ssl_server_cache: + +`Initializing Multi-Processing with a Shared SSL Server Cache <#initializing_multi-processing_with_a_shared_ssl_server_cache>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + To start a multi-processing application, the initial parent process calls + ```SSL_ConfigMPServerSIDCache`` <#1142625>`__, and then creates child processes, by one of these + methods: + + - Call ``fork`` and then ``exec`` (Unix) + - Call ``CreateProcess`` (Win32) + - Call ``PR_CreateProcess`` (both Unix and Win32) + + It is essential that the parent allow the child to inherit the file descriptors. WIN32's + ``CreateProcess`` takes an argument that tells it whether or not to permit files to be inherited; + this argument must be ``TRUE``. + + When a new child that has been created by either ``CreateProcess`` or ``exec`` begins, it may + have inherited file descriptors (FDs), but not the parent's memory. Therefore, to find out what + FDs it has inherited, it must be told about them. To that end, the function + ```SSL_ConfigMPServerSIDCache`` <#1142625>`__ sets an environment variable named + ``SSL_INHERITANCE``. The value of the variable is a printable ASCII string, containing all the + information needed to set up and use the inherited FDs. + + There are two ways to transfer the content of ``SSL_INHERITANCE`` from parent to child: + + - The child inherits the parent's environment, which must include the ``SSL_INHERITANCE`` + variable. For the child to inherit the parent's environment you must set a specific argument + to ``CreateProcess`` or ``PR_CreateProcess``. + - The parent transmits the content of ``SSL_INHERITANCE`` to the child by some other means, such + as on the command line, or in another file or pipe. + + In either case, the child must call ```SSL_InheritMPServerSIDCache`` <#1162055>`__ to complete + the inheritance of the shared cache FDs/handles. + + .. rubric:: SSL_ConfigMPServerSIDCache + :name: ssl_configmpserversidcache + + Sets up parameters for and opens the server session cache for a multi-process application. + + .. rubric:: Syntax + :name: syntax_10 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_ConfigMPServerSIDCache( + int maxCacheEntries, + PRUint32 timeout, + PRUint32 ssl3_timeout, + const char *directory); + + .. rubric:: Parameters + :name: parameters_6 + + This function has the parameters listed below. + + +---------------------+---------------------------------------------------------------------------+ + | ``maxCacheEntries`` | The maximum number of entries in the cache. If a ``NULL`` value is | + | | passed, the server default value of 10,000 is used. | + +---------------------+---------------------------------------------------------------------------+ + | ``timeout`` | The lifetime in seconds of an SSL2 session. The minimum timeout value is | + | | 5 seconds and the maximum is 24 hours. Values outside this range are | + | | replaced by the server default value of 100 seconds. | + +---------------------+---------------------------------------------------------------------------+ + | ``ssl3_timeout`` | The lifetime in seconds of an SSL3 session. The minimum timeout value is | + | | 5 seconds and the maximum is 24 hours. Values outside this range are | + | | replaced by the server default value of 24 hours. | + +---------------------+---------------------------------------------------------------------------+ + | ``directory`` | A pointer to a string specifying the pathname of the directory that will | + | | contain the session cache. If a ``NULL`` value is passed, the server | + | | default value is used: ``/tmp`` (Unix) or ``\\temp`` (NT). | + +---------------------+---------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_9 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain error code. + + .. rubric:: Description + :name: description_10 + + This function is identical to ```SSL_ConfigServerSessionIDCache`` <#1143851>`__, except that it + is for use with applications that use multiple processes. You must use one or the other of these + functions to create a server cache, not both. + + If your application will use multiple processes (instead of, or in addition to, multiple + threads), and all of the processes appear to be on the same server (same IP address and port + number), then those processes must share a common SSL session cache. The common parent of all the + processes must call this function to create the cache before creating the other processes. + + An application uses multiple processes\ *only* if it uses the Unix function ``fork``, or the + Win32 function ``CreateProcess``. This is not the same as using multiple threads or multiple + processors. Note that an SSL server that uses Fortezza hardware devices is limited to a single + process. It can use multiple threads, and thereby make use of multiple processors, but this must + all be done from a single process. + + This function creates two caches: the\ *server session ID cache* (also called the server session + cache, or server cache), and the\ *client-auth certificate cache* (also called the client cert + cache, or client auth cache). Both caches are used only for sessions where the program handshakes + as a server. The client-auth certificate cache is used to remember the certificates previously + presented by clients for client certificate authentication. + + Passing a ``NULL`` value or a value that is out of range for any of the parameters causes the + server default value to be used in the server cache. The values that you pass affect only the + server cache, not the client cache. Before the cache can be used in the child process, the child + process must complete its initialization using ```SSL_InheritMPServerSIDCache`` <#1162055>`__. + + .. rubric:: SSL_InheritMPServerSIDCache + :name: ssl_inheritmpserversidcache + + Ensures the inheritance of file descriptors to a child process. + + .. rubric:: Syntax + :name: syntax_11 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_InheritMPServerSIDCache (const char *envString); + + .. rubric:: Parameters + :name: parameters_7 + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | ``envString`` | A pointer to the location of the inheritance | + | | information. The value depends on how you are | + | | passing the information. | + | | | + | | If a ``NULL`` value is passed, the function | + | | looks for the ``SSL_INHERITANCE`` variable that | + | | has been inherited as part of the child's | + | | environment. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_10 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_11 + + This function completes the inheritance of file descriptors from a parent to a child process. + After the child process is created, it must call this function to complete its initialization. + + The value of the ``envString`` argument depends on which of the two possible inheritance schemes + you have used. (See `Initializing Multi-Processing with a Shared SSL Server Cache <#1154189>`__.) + + - If the ``SSL_INHERITANCE`` variable has been inherited as part of the child's environment, the + child must pass a ``NULL`` pointer as the ``envString`` argument. This causes the function to + look in the environment for the variable. + - If the parent has transmitted the value of the ``SSL_INHERITANCE`` variable to the child by + some other means, the child must pass a pointer to that string as the ``envString`` argument + to complete the inheritance. + + When this function returns ``SECSuccess``, the server cache is ready to be used by the SSL code. + +.. _ssl_export_policy_functions: + +`SSL Export Policy Functions <#ssl_export_policy_functions>`__ +-------------------------------------------------------------- + +.. container:: + + The SSL export policy functions determine which cipher suites are\ *permitted* for use in an SSL + session. They do not determine which cipher suites are actually\ *enabled*--that is, turned on + and ready to use. To enable or disable a permitted cipher suite, use + ```SSL_CipherPrefSetDefault`` <#1084747>`__; but bear in mind that + ```SSL_CipherPrefSetDefault`` <#1084747>`__ can't enable any cipher suite that is not explicitly + permitted as a result of a call to one of the export policy functions. + + By default, none of the cipher suites supported by SSL are permitted. The functions + ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, and + ```NSS_SetFrancePolicy`` <#1105952>`__ permit the use of approved cipher suites for domestic, + international, and French versions, respectively, of software products with encryption features. + The policy settings permitted by these functions conform with current U.S. export regulations as + understood by Netscape (for products with and without "retail status" as defined by the `latest + U.S. Export Regulations <http://w3.access.gpo.gov/bxa/ear/ear_data.html>`__) and French import + regulations. + + Under some circumstances, you may be required to abide by the terms of an export license that + permits more or fewer capabilities than those allowed by these three functions. In such cases, + use ```SSL_CipherPolicySet`` <#1104647>`__ to explicitly enable those cipher suites you may + legally export. + + For descriptions of cipher suites supported by SSL, see `Introduction to + SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_SSL>`__. + + Applications must call one of the export policy functions before attempting to perform any + cryptographic operations: + + | ```NSS_SetDomesticPolicy`` <#1228530>`__ + | ```NSS_SetExportPolicy`` <#1100285>`__ + | ```NSS_SetFrancePolicy`` <#1105952>`__ + | ```SSL_CipherPolicySet`` <#1104647>`__ + + The following function is also described in this section: + + ```SSL_CipherPolicyGet`` <#1210463>`__ + + .. rubric:: NSS_SetDomesticPolicy + :name: nss_setdomesticpolicy + + Configures cipher suites to conform with current U.S. export regulations related to domestic + software products with encryption features. + + .. rubric:: Syntax + :name: syntax_12 + + .. code:: + + #include "ssl.h" + + .. code:: + + extern SECStatus NSS_SetDomesticPolicy(void); + + .. rubric:: Returns + :name: returns_11 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, returns ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_12 + + ``NSS_SetDomesticPolicy`` configures all the cipher suites listed under + ```SSL_CipherPolicySet`` <#1104647>`__ for software that is\ *not* intended for export, and is + thus not required to conform with U.S. export regulations related to domestic software products + with encryption features. After calling this function, all cipher suites listed are permitted + (but not necessarily enabled; see `SSL Export Policy Functions <#1098841>`__) for the calling + application. + + When an SSL connection is established, SSL permits the use of the strongest cipher suites that + are both permitted and enabled for the software on both ends of the connection. For example, if a + client that has called ``NSS_SetDomesticPolicy`` establishes an SSL connection with a server for + which some cipher suites are either not permitted or not enabled (such as an international + version of Netscape server software), SSL uses the strongest cipher suites supported by the + server that are also supported by the client. + + Under some circumstances, you may be required to abide by the terms of an export license that + permits more or fewer capabilities than those allowed by ``NSS_SetDomesticPolicy``. In that case, + first call ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or + ```NSS_SetFrancePolicy`` <#1105952>`__, then call ```SSL_CipherPolicySet`` <#1104647>`__ + repeatedly to explicitly allow or disallow cipher suites until only those that you may legally + export are permitted. + + .. rubric:: Important + :name: important + + If you call ``NSS_SetDomesticPolicy`` sometime after initialization to change cipher suite policy + settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the + session cache and will be used instead of the new settings. + + .. rubric:: NSS_SetExportPolicy + :name: nss_setexportpolicy + + Configures the SSL cipher suites to conform with current U.S. export regulations related to + international software products with encryption features. + + .. rubric:: Syntax + :name: syntax_13 + + .. code:: + + #include "ssl.h" + + .. code:: + + extern SECStatus NSS_SetExportPolicy(void); + + .. rubric:: Returns + :name: returns_12 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, returns ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_13 + + ``NSS_SetExportPolicy`` configures all the cipher suites listed under + ```SSL_CipherPolicySet`` <#1104647>`__ to conform with current U.S. export regulations related to + international software products with encryption features (as Netscape understands them). Calling + this function permits use of cipher suites listed below (but doesn't necessarily enable them; see + `SSL Export Policy Functions <#1098841>`__). Policy for these suites is set to ``SSL_ALLOWED`` + unless otherwise indicated. ``SSL_RESTRICTED`` means the suite can be used by clients only when + they are communicating with domestic server software or with international server software that + presents a Global ID certificate. For more details on policy settings, see + ```SSL_CipherPolicySet`` <#1104647>`__. + + For SSL 2.0: + + - ``SSL_EN_RC4_128_EXPORT40_WITH_MD5`` + - ``SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5`` + + For SSL 3.0: + + - ``SSL_RSA_WITH_NULL_MD5`` + - ``SSL_RSA_WITH_RC4_128_MD5 (SSL_RESTRICTED)`` + - ``SSL_RSA_WITH_3DES_EDE_CBC_SHA (SSL_RESTRICTED)`` + - ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` + - ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` + + Under some circumstances, you may be required to abide by the terms of an export license that + permits more or fewer capabilities than those allowed by ``NSS_SetExportPolicy``. In that case, + you should first call ```NSS_SetDomesticPolicy`` <#1228530>`__, + ```NSS_SetExportPolicy`` <#1100285>`__, or ```NSS_SetFrancePolicy`` <#1105952>`__, then call + ```SSL_CipherPolicySet`` <#1104647>`__ repeatedly to explicitly allow or disallow cipher suites + until only those that you may legally export are permitted. + + .. rubric:: Important + :name: important_2 + + If you call ``NSS_SetExportPolicy`` sometime after initialization to change cipher suite policy + settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the + session cache and will be used instead of the new settings. + + .. rubric:: NSS_SetFrancePolicy + :name: nss_setfrancepolicy + + Configures the SSL cipher suites to conform with French import regulations related to software + products with encryption features. + + .. rubric:: Syntax + :name: syntax_14 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus NSS_SetFrancePolicy(void); + + .. rubric:: Returns + :name: returns_13 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, returns ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_14 + + ``NSS_SetFrancePolicy`` configures all the cipher suites listed under + ```SSL_CipherPolicySet`` <#1104647>`__ to conform with current U.S. export regulations and French + import regulations (as Netscape understands them) related to software products with encryption + features. Calling this function permits use of cipher suites listed below (but doesn't + necessarily enable them; see `SSL Export Policy Functions <#1098841>`__). Policy for these suites + is set to ``SSL_ALLOWED``. For more details on policy settings, see + ```SSL_CipherPolicySet`` <#1104647>`__. + + For SSL 2.0: + + - ``SSL_EN_RC4_128_EXPORT40_WITH_MD5`` + - ``SSL_EN_RC2_128_CBC_EXPORT40_WITH_MD5`` + + For SSL 3.0: + + - ``SSL_RSA_WITH_NULL_MD5`` + - ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` + - ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` + + Under some circumstances, you may be required to abide by the terms of an export license that + permits more or fewer capabilities than those allowed by ``NSS_SetFrancePolicy``. In that case, + you should first call ```NSS_SetDomesticPolicy`` <#1228530>`__, + ```NSS_SetExportPolicy`` <#1100285>`__, or ```NSS_SetFrancePolicy`` <#1105952>`__, then call + ```SSL_CipherPolicySet`` <#1104647>`__ repeatedly to explicitly allow or disallow cipher suites + until only those that you may legally export are permitted. + + .. rubric:: Important + :name: important_3 + + If you call ``NSS_SetFrancePolicy`` sometime after initialization to change cipher suite policy + settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the + session cache and will be used instead of the new settings. + + .. rubric:: SSL_CipherPolicySet + :name: ssl_cipherpolicyset + + Sets policy for the use of individual cipher suites. + + ``SSL_CipherPolicySet`` replaces the deprecated function ```SSL_SetPolicy`` <#1207350>`__. + + .. rubric:: Syntax + :name: syntax_15 + + .. code:: + + #include "ssl.h" + #include "proto.h" + + .. code:: + + SECStatus SSL_CipherPolicySet(PRInt32 cipher, PRInt32 policy); + + .. rubric:: Parameters + :name: parameters_8 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``cipher`` | A value from one of the following lists. | + | | | + | | Values for SSL2 (all are disallowed by | + | | default): | + | | | + | | ``SSL_EN_RC4_128_WITH_ | + | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 | + | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 | + | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W | + | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` | + | | | + | | Values for SSL3/TLS (all are disallowed by | + | | default): | + | | | + | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (client | + | | side only) | + | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (client | + | | side only) | + | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` | + | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` | + | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (client side | + | | only) | + | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (client | + | | side only) | + | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (client | + | | side only) | + | | ``SSL_RSA_WITH_RC4_128_MD5`` | + | | ``SSL_RSA_WITH_RC4_128_SHA`` | + | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` | + | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (client | + | | side only) | + | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (client | + | | side only) | + | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` | + | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` | + | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` | + | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (client side | + | | only) | + | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (client side | + | | only) | + | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` | + | | ``SSL_RSA_WITH_DES_CBC_SHA`` | + | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` | + | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` | + | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` | + | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` | + | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` | + | | ``SSL_RSA_WITH_NULL_SHA`` | + | | ``SSL_RSA_WITH_NULL_MD5`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``policy`` | One of the following values: | + | | | + | | - ``SSL_ALLOWED``. Cipher is always allowed by | + | | U.S. government policy. | + | | - ``SSL_RESTRICTED``. Cipher is allowed by | + | | U.S. government policy for servers with | + | | Global ID certificates. | + | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed | + | | by U.S. government policy. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_14 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_15 + + ``SSL_CipherPolicySet`` tells the SSL library that the specified cipher suite is allowed by the + application's export license, or is not allowed by the application's export license, or is + allowed to be used only with a Step-Up certificate. It overrides the factory default policy for + that cipher suite. The default policy for all cipher suites is ``SSL_NOT_ALLOWED``, meaning that + the application's export license does not approve the use of this cipher suite. A U.S. "domestic" + version of a product typically sets all cipher suites to ``SSL_ALLOWED``. This setting is used to + separate export and domestic versions of a product, and is not intended to express user cipher + preferences. This setting affects all SSL sockets in the application process that are opened + after a call to ``SSL_CipherPolicySet``. + + Under some circumstances, you may be required to abide by the terms of an export license that + permits more or fewer capabilities than those allowed by + ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or + ```NSS_SetFrancePolicy`` <#1105952>`__. In that case, first call + ```NSS_SetDomesticPolicy`` <#1228530>`__, ```NSS_SetExportPolicy`` <#1100285>`__, or + ```NSS_SetFrancePolicy`` <#1105952>`__, then call ``SSL_CipherPolicySet`` repeatedly to + explicitly allow or disallow cipher suites until only those that you may legally export are + permitted. + + In a domestic US product, all the cipher suites are (presently) allowed. In an export client + product, some cipher suites are always allowed (such as those with 40-bit keys), some are never + allowed (such as triple-DES), and some are allowed (such as RC4_128) for use with approved + servers, typically servers owned by banks with special Global ID certificates. (For details, see + ```NSS_SetExportPolicy`` <#1100285>`__ and ```NSS_SetFrancePolicy`` <#1105952>`__.) When an SSL + connection is established, SSL uses only cipher suites that have previously been explicitly + permitted by a call to one of the SSL export policy functions. + + Note that the value ``SSL_RESTRICTED`` (passed in the ``policy`` parameter) is currently used + only by SSL clients, which can use it to set policy for connections with servers that have SSL + step-up certificates. + + .. rubric:: Important + :name: important_4 + + If you call ``SSL_CipherPolicySet`` sometime after initialization to change cipher suite policy + settings, you must also call ``SSL_ClearSessionCache``. Otherwise, the old settings remain in the + session cache and will be used instead of the new settings. + + .. rubric:: See Also + :name: see_also + + Permitting a cipher suite is not necessarily the same as enabling it. For details, see `SSL + Export Policy Functions <#1098841>`__. + + For descriptions of cipher suites supported by SSL, see `Introduction to + SSL <https://developer.mozilla.org/en-US/docs/Archive/Security/Introduction_to_SSL>`__. + + .. rubric:: SSL_CipherPolicyGet + :name: ssl_cipherpolicyget + + Gets the current policy setting for a specified cipher suite. + + ``SSL_CipherPolicyGet`` is the complementary function for ```SSL_CipherPolicySet`` <#1104647>`__. + + .. rubric:: Syntax + :name: syntax_16 + + .. code:: + + #include "ssl.h" + #include "proto.h" + + .. code:: + + SECStatus SSL_CipherPolicyGet(PRInt32 cipher, PRInt32 *policy); + + .. rubric:: Parameters + :name: parameters_9 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``cipher`` | A value identifying a cipher suite. For a list | + | | of possible values, see | + | | ```SSL_CipherPolicySet`` <#1104647>`__. | + +-------------------------------------------------+-------------------------------------------------+ + | policy | A pointer to one of the following values: | + | | | + | | - ``SSL_ALLOWED``. Cipher is always allowed by | + | | U.S. government policy. | + | | - ``SSL_RESTRICTED``. Cipher is allowed by | + | | U.S. government policy for servers with | + | | Global ID certificates. | + | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed | + | | by U.S. government policy. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Description + :name: description_16 + + See the description above for ```SSL_CipherPolicySet`` <#1104647>`__. + +.. _ssl_configuration_functions: + +`SSL Configuration Functions <#ssl_configuration_functions>`__ +-------------------------------------------------------------- + +.. container:: + + SSL configuration involves several NSPR functions in addition to the SSL functions listed here. + For a complete list of configuration functions, see `Configuration <sslintro.html#1027742>`__. + + | `SSL Configuration <#1090577>`__ + | `Callback Configuration <#1089578>`__ + +.. _ssl_configuration: + +`SSL Configuration <#ssl_configuration>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | ```SSL_ImportFD`` <#1085950>`__ + | ```SSL_OptionSet`` <#1086543>`__ + | ```SSL_OptionGet`` <#1194921>`__ + | ```SSL_CipherPrefSet`` <#1214758>`__ + | ```SSL_CipherPrefGet`` <#1214800>`__ + | ```SSL_ConfigSecureServer`` <#1217647>`__ + | ```SSL_SetURL`` <#1087792>`__ + | ```SSL_SetPKCS11PinArg`` <#1088040>`__ + + .. rubric:: SSL_ImportFD + :name: ssl_importfd + + Imports an existing NSPR file descriptor into SSL and returns a new SSL socket. + + .. rubric:: Syntax + :name: syntax_17 + + .. code:: + + #include "ssl.h" + + .. code:: + + PRFileDesc *SSL_ImportFD( + PRFileDesc *model, + PRFileDesc *fd); + + .. rubric:: Parameters + :name: parameters_10 + + This function has the following parameters: + + ========= ======================================================== + ``model`` A pointer to the model file descriptor. + ``fd`` A pointer to the file descriptor for the new SSL socket. + ========= ======================================================== + + .. rubric:: Returns + :name: returns_15 + + The function returns one of these values: + + - If successful, a pointer to a new socket file descriptor. + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_17 + + Any SSL function that takes a pointer to a file descriptor (socket) as a parameter will have no + effect (even though the SSL function may return ``SECSuccess``) if the socket is not an SSL + socket. Sockets do not automatically become secure SSL sockets when they are created by the NSPR + functions. You must pass an NSPR socket's file descriptor to ``SSL_ImportFD`` to make it an SSL + socket before you call any other SSL function that takes the socket's file descriptor as a + parameter + + ``SSL_ImportFD`` imports an existing NSPR file descriptor into SSL and returns a new SSL socket + file descriptor. If the ``model`` parameter is not ``NULL``, the configuration of the new file + descriptor is copied from the model. If the ``model`` parameter is ``NULL``, then the default SSL + configuration is used. + + The new file descriptor returned by ``SSL_ImportFD`` is not necessarily equal to the original + NSPR file descriptor. If, after calling ``SSL_ImportFD``, the file descriptors are not equal, you + should perform all operations on the new ``PRFileDesc`` structure, never the old one. Even when + it's time to close the file descriptor, always close the new ``PRFileDesc`` structure, never the + old one. + + .. rubric:: SSL_OptionSet + :name: ssl_optionset + + Sets a single configuration parameter of a specified socket. Call once for each parameter you + want to change. + + ``SSL_OptionSet`` replaces the deprecated function ```SSL_Enable`` <#1220189>`__. + + .. rubric:: Syntax + :name: syntax_18 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_OptionSet( + PRFileDesc *fd, + PRInt32 option, + PRBool on); + + .. rubric:: Parameters + :name: parameters_11 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``fd`` | Pointer to the NSPR file descriptor for the SSL | + | | socket. | + +-------------------------------------------------+-------------------------------------------------+ + | ``option`` | One of the following values (default values are | + | | determined by the use of | + | | ```SSL_OptionSetDefault`` <#1068466>`__): | + | | | + | | - ``SSL_SECURITY`` enables use of security | + | | protocol. WARNING: If you turn this option | + | | off, the session will not be an SSL session | + | | and will not have certificate-based | + | | authentication, tamper detection, or | + | | encryption. | + | | - ``SSL_REQUEST_CERTIFICATE`` is a server | + | | option that requests a client to | + | | authenticate itself. | + | | - ``SSL_REQUIRE_CERTIFICATE`` is a server | + | | option that requires a client to | + | | authenticate itself (only if | + | | ``SSL_REQUEST_CERTIFICATE`` is also on). If | + | | client does not provide certificate, the | + | | connection terminates. | + | | - ``SSL_HANDSHAKE_AS_CLIENT`` controls the | + | | behavior of ``PR_Accept``,. If this option | + | | is off, the ``PR_Accept`` configures the SSL | + | | socket to handshake as a server. If it is | + | | on, then ``PR_Accept`` configures the SSL | + | | socket to handshake as a client, even though | + | | it accepted the connection as a TCP server. | + | | - ``SSL_HANDSHAKE_AS_SERVER`` controls the | + | | behavior of ``PR_Connect``. If this option | + | | is off, then ``PR_Connect`` configures the | + | | SSL socket to handshake as a client. If it | + | | is on, then ``PR_Connect`` configures the | + | | SSL socket to handshake as a server, even | + | | though it connected as a TCP client. | + | | - ``SSL_ENABLE_FDX`` tells the SSL library | + | | whether the application will have two | + | | threads, one reading and one writing, or | + | | just one thread doing reads and writes | + | | alternately. The factory setting for this | + | | option (which is the default, unless the | + | | application changes the default) is off | + | | (``PR_FALSE``), which means that the | + | | application will not do simultaneous reads | + | | and writes. An application that needs to do | + | | simultaneous reads and writes should set | + | | this to ``PR_TRUE``. | + | | | + | | In NSS 2.8, the ``SSL_ENABLE_FDX`` option only | + | | affects the behavior of nonblocking SSL | + | | sockets. See the description below for more | + | | information on this option. | + +-------------------------------------------------+-------------------------------------------------+ + | | - ``SSL_ENABLE_SSL3`` enables the application | + | | to communicate with SSL v3. If you turn this | + | | option off, an attempt to establish a | + | | connection with a peer that understands only | + | | SSL v3 will fail. | + | | - ``SSL_ENABLE_SSL2`` enables the application | + | | to communicate with SSL v2. If you turn this | + | | option off, an attempt to establish a | + | | connection with a peer that understands only | + | | SSL v2 will fail. | + | | - ``SSL_ENABLE_TLS`` is a peer of the | + | | ``SSL_ENABLE_SSL2`` and ``SSL_ENABLE_SSL3`` | + | | options. The IETF standard Transport Layer | + | | Security (TLS) protocol, RFC 2246, is a | + | | modified version of SSL3. It uses the SSL | + | | version number 3.1, appearing to be a | + | | "minor" revision of SSL3.0. NSS 2.8 supports | + | | TLS in addition to SSL2 and SSL3. You can | + | | think of it as "``SSL_ENABLE_SSL3.1``." See | + | | the description below for more information | + | | about this option. | + | | - ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL | + | | library whether or not to send SSL3 client | + | | hello messages in SSL2-compatible format. If | + | | set to ``PR_TRUE``, it will; otherwise, it | + | | will not. See the description below for more | + | | information on this option. | + | | - ``SSL_NO_CACHE`` disallows use of the | + | | session cache. Factory setting is off. If | + | | you turn this option on, this socket will be | + | | unable to resume a session begun by another | + | | socket. When this socket's session is | + | | finished, no other socket will be able to | + | | resume the session begun by this socket. | + | | - ``SSL_ROLLBACK_DETECTION`` disables | + | | detection of a rollback attack. Factory | + | | setting is on. You must turn this option off | + | | to interoperate with TLS clients ( such as | + | | certain versions of Microsoft Internet | + | | Explorer) that do not conform to the TLS | + | | specification regarding rollback attacks. | + | | Important: turning this option off means | + | | that your code will not comply with the TLS | + | | 3.1 and SSL 3.0 specifications regarding | + | | rollback attack and will therefore be | + | | vulnerable to this form of attack. | + +-------------------------------------------------+-------------------------------------------------+ + | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns | + | | option off. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_16 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, returns ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_18 + + Keep the following in mind when deciding on the operating parameters you want to use with a + particular socket: + + - Turning on ``SSL_REQUIRE_CERTIFICATE`` will have no effect unless ``SSL_REQUEST_CERTIFICATE`` + is also turned on. If you enable ``SSL_REQUEST_CERTIFICATE``, then you should explicitly + enable or disable ``SSL_REQUIRE_CERTIFICATE`` rather than allowing it to default. Enabling the + ``SSL_REQUIRE_CERTIFICATE`` option is not recommended. If the client has no certificate and + this option is enabled, the client's connection terminates with an error. The user is likely + to think something is wrong with either the client or the server, and is unlikely to realize + that the problem is the lack of a certificate. It is better to allow the SSL handshake to + complete and then return an error message to the client that informs the user of the need for + a certificate. + + Some applications may wish to force SSL3 client hellos to be sent in SSL3 format, not in + SSL2-compatible format. They might wish to do this if they knew, somehow, that the server does + not understand SSL2-compatible client hello messages. + + ``SSL_V2_COMPATIBLE_HELLO`` tells the SSL library whether or not to send SSL3 client hello + messages in SSL2-compatible format. Note that calling ``SSL_OptionSet`` to set + ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly also sets the ``SSL_ENABLE_SSL2`` option + to ``PR_FALSE`` for that SSL socket. Calling ``SSL_EnableDefault`` to change the application + default setting for ``SSL_V2_COMPATIBLE_HELLO`` to ``PR_FALSE`` implicitly also sets the default + value for ``SSL_ENABLE_SSL2`` option to ``PR_FALSE`` for that application. + + - The options ``SSL_ENABLE_SSL2``, ``SSL_ENABLE_SSL3``, and ``SSL_ENABLE_TLS``\ can each be set + to ``PR_TRUE`` or ``PR_FALSE`` independently of each other. NSS 2.8 and later versions will + negotiate the highest protocol version with the peer application from among the set of + protocols that are commonly enabled in both applications. + + Note that SSL3 and TLS share the same set of cipher suites. When both SSL3 and TLS are enabled, + all SSL3/TLS cipher suites that are enabled are enabled for both SSL3 and TLS. + + As mentioned in `Communication <sslintro.html#1027816>`__, when an application imports a socket + into SSL after the TCP connection on that socket has already been established, it must call + `SSL_ResetHandshake <#1058001>`__ to indicate whether the socket is for a client or server. At + first glance this may seem unnecessary, since ``SSL_OptionSet`` can set + ``SSL_HANDSHAKE_AS_CLIENT`` or ``SSL_HANDSHAKE_AS_SERVER``. However, these settings control the + behavior of + ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__ + and + ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__ + only; if you don't call one of those functions after importing a non-SSL socket with + ``SSL_Import`` (as in the case of an already established TCP connection), SSL still needs to know + whether the application is functioning as a client or server. + + If a socket file descriptor is imported as an SSL socket before it is connected, it is implicitly + configured to handshake as a client or handshake as a server when the connection is made. If the + application calls ``PR_Connect`` (connecting as a TCP client), then the SSL socket is (by + default) configured to handshake as an SSL client. If the application calls ``PR_Accept`` + (connecting the socket as a TCP server) then the SSL socket is (by default) configured to + handshake as an SSL server. ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` control + this implicit configuration. + + Both ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` are initially set to off--that + is, the process default for both values is ``PR_FALSE`` when the process begins. The process + default can be changed from the initial values by using ``SSL_EnableDefault``, and the value for + a particular socket can be changed by using ``SSL_OptionSet``. + + When you import a new SSL socket with ``SSL_ImportFD`` using a model file descriptor, the new SSL + socket inherits its values for ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` from + the model file descriptor. + + When ``PR_Accept`` accepts a new connection from a listen file descriptor and creates a new file + descriptor for the new connection, the listen file descriptor also acts as a model for the new + file descriptor, and the new file descriptor inherits its values from the model. + + ``SSL_HANDSHAKE_AS_CLIENT`` and ``SSL_HANDSHAKE_AS_SERVER`` cannot both be turned on + simultaneously. If you use ``SSL_OptionSet`` to turn one of these on when the other one is + already turned on for a particular socket, the function returns with the error code set to + ``SEC_ERROR_INVALID_ARGS``. Likewise, using ``SSL_EnableDefault`` to turn on the global default + for one of these when the global default for the other one is already turned for a particular + socket generates the same error. However, there is no good reason for these to be mutually + exclusive. This restirction will be removed in future releases. + + If a socket that is already connected gets imported into SSL after it has been connected (that + is, after ``PR_Accept`` or ``PR_Connect`` has returned), then no implicit SSL handshake + configuration as a client or server will have been done by ``PR_Connect`` or ``PR_Accept`` on + that socket. In this case, a call to ``SSL_ResetHandshake`` is required to explicitly configure + the socket to handshake as a client or as a server. If ``SSL_ResetHandshake`` is not called to + explicitly configure the socket handshake, a crash is likely to occur when the first I/O + operation is done on the socket after it is imported into SSL. + + .. rubric:: SSL_OptionGet + :name: ssl_optionget + + ``SSL_OptionGet`` gets the value of a specified SSL option on a specified SSL socket. + + .. rubric:: Syntax + :name: syntax_19 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_OptionGet( + PRFileDesc *fd, + PRInt32 option, + PRBool *on); + + .. rubric:: Parameters + :name: parameters_12 + + This function has the following parameters: + + +------------+------------------------------------------------------------------------------------+ + | ``fd`` | Pointer to the file descriptor for the SSL socket. | + +------------+------------------------------------------------------------------------------------+ + | ``option`` | The value of the option whose default setting you wish to get. For information | + | | about the options available and the possible values to pass in this parameter, see | + | | the description of the ``option`` parameter under | + | | ```SSL_OptionSet`` <#1086543>`__. | + +------------+------------------------------------------------------------------------------------+ + | ``on`` | ``PR_TRUE`` indicates the specified option is on; ``PR_FALSE`` indicates it is | + | | off. | + +------------+------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_17 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, returns ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_19 + + See the description above for ```SSL_OptionSet`` <#1086543>`__. + + .. rubric:: SSL_CipherPrefSet + :name: ssl_cipherprefset + + ``SSL_CipherPrefSet`` specifies the use of a specified cipher suite on a specified SSL socket. + + .. rubric:: Syntax + :name: syntax_20 + + .. code:: + + #include "ssl.h" + #include "proto.h" + + .. code:: + + SECStatus SSL_CipherPrefSet( + PRFileDesc *fd, + PRInt32 cipher, + PRBool enabled); + + .. rubric:: Parameters + :name: parameters_13 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``fd`` | Pointer to the file descriptor for the SSL | + | | socket. | + +-------------------------------------------------+-------------------------------------------------+ + | ``cipher`` | One of the following values for SSL2 (all are | + | | enabled by default): | + | | | + | | ``SSL_EN_RC4_128_WITH_ | + | | MD5 SSL_EN_RC4_128_EXPORT40_WITH_MD5 | + | | SSL_EN_RC2_128_CBC_WITH_MD5 SSL_EN_RC2_128 | + | | _CBC_EXPORT40_WITH_MD5 SSL_EN_DES_64_CBC_W | + | | ITH_MD5 SSL_EN_DES_192_EDE3_CBC_WITH_MD5`` | + | | | + | | Or one of the following values for SSL3/TLS | + | | (unless indicated otherwise, all are enabled by | + | | default): | + | | | + | | ``TLS_DHE_RSA_WITH_AES_256_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``TLS_DHE_DSS_WITH_AES_256_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``TLS_RSA_WITH_AES_256_CBC_SHA`` (not enabled | + | | by default) | + | | ``SSL_FORTEZZA_DMS_WITH_RC4_128_SHA`` | + | | ``TLS_DHE_DSS_WITH_RC4_128_SHA`` (not enabled | + | | by default; client side only) | + | | ``TLS_DHE_RSA_WITH_AES_128_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``TLS_DHE_DSS_WITH_AES_128_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``SSL_RSA_WITH_RC4_128_MD5`` | + | | ``SSL_RSA_WITH_RC4_128_SHA`` (not enabled by | + | | default) | + | | ``TLS_RSA_WITH_AES_128_CBC_SHA`` (not enabled | + | | by default) | + | | ``SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA`` (not | + | | enabled by default; client side only) | + | | ``SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA`` | + | | ``SSL_RSA_WITH_3DES_EDE_CBC_SHA`` | + | | ``SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA`` | + | | ``SSL_DHE_RSA_WITH_DES_CBC_SHA`` (not enabled | + | | by default; client side only) | + | | ``SSL_DHE_DSS_WITH_DES_CBC_SHA`` (not enabled | + | | by default; client side only) | + | | ``SSL_RSA_FIPS_WITH_DES_CBC_SHA`` | + | | ``SSL_RSA_WITH_DES_CBC_SHA`` | + | | ``TLS_RSA_EXPORT1024_WITH_RC4_56_SHA`` | + | | ``TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA`` | + | | ``SSL_RSA_EXPORT_WITH_RC4_40_MD5`` | + | | ``SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5`` | + | | ``SSL_FORTEZZA_DMS_WITH_NULL_SHA`` | + | | ``SSL_RSA_WITH_NULL_SHA`` (not enabled by | + | | default) | + | | ``SSL_RSA_WITH_NULL_MD5`` (not enabled by | + | | default) | + +-------------------------------------------------+-------------------------------------------------+ + | ``enabled`` | If nonzero, the specified cipher is enabled. If | + | | zero, the cipher is disabled. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Description + :name: description_20 + + ``SSL_CipherPrefSet`` is a new function in NSS 2.6 and later. It allows the application to set + the user preferences for cipher suites on an individual socket, overriding the default value for + the preference (which can be set with ```SSL_CipherPrefSetDefault`` <#1084747>`__). If an + application needs to set the cipher preferences on an individual socket, it should do so before + initiating an SSL handshake, not during an SSL handshake. + + For more information on the use of the TLS and FIPS cipher suites, see + ```SSL_CipherPrefSetDefault`` <#1084747>`__. + + .. rubric:: SSL_CipherPrefGet + :name: ssl_cipherprefget + + Gets the current preference setting for a specified SSL2 or SSL3 cipher suite. + + .. rubric:: Syntax + :name: syntax_21 + + .. code:: + + #include "ssl.h" + #include "proto.h" + + .. code:: + + SECStatus SSL_CipherPrefGet( + PRFileDesc *fd, + PRInt32 cipher, + PRBool *enabled); + + .. rubric:: Parameters + :name: parameters_14 + + This function has the parameters listed below. + + +---------+---------------------------------------------------------------------------------------+ + | ``fd`` | Pointer to the file descriptor for the SSL socket. | + +---------+---------------------------------------------------------------------------------------+ + | cipher | The cipher suite whose default preference setting you want to get. For a list of the | + | | cipher suites you can specify, see ```SSL_CipherPrefSet`` <#1214758>`__. | + +---------+---------------------------------------------------------------------------------------+ + | enabled | A pointer to the default value associated with the cipher specified in the ``cipher`` | + | | parameter. If nonzero, the specified cipher is enabled. If zero, the cipher is | + | | disabled. | + +---------+---------------------------------------------------------------------------------------+ + + .. rubric:: Description + :name: description_21 + + ``SSL_CipherPrefGet`` performs the complementary function to ``SSL_CipherPrefSet``. It returns + the current preference setting for the SSL cipher suite for the socket. If the application has + not previously set the cipher preference for this cipher on this socket, the value will be either + the process default value or the value inherited from a listen socket or a model socket. + + .. rubric:: SSL_ConfigSecureServer + :name: ssl_configsecureserver + + Configures a listen socket with the information needed to handshake as an SSL server. + ``SSL_ConfigSecureServer`` requires the certificate for the server and the server's private key. + The arguments are copied. + + .. rubric:: Syntax + :name: syntax_22 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_ConfigSecureServer( + PRFileDesc *fd, + CERTCertificate *cert, + SECKEYPrivateKey *key, + SSLKEAType keaType); + + .. rubric:: Parameters + :name: parameters_15 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL | + | | listen socket. | + +-------------------------------------------------+-------------------------------------------------+ + | ``cert`` | A pointer to the server's certificate | + | | structure. | + +-------------------------------------------------+-------------------------------------------------+ + | ``key`` | A pointer to the server's private key | + | | structure. | + +-------------------------------------------------+-------------------------------------------------+ + | ``keaType`` | Key exchange type for use with specified | + | | certificate and key. These values are currently | + | | valid: | + | | | + | | - ``kt_rsa`` | + | | - ``kt_dh`` | + | | - ``kt_fortezza`` | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_18 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_22 + + Before SSL can handshake as a server on a socket, it must be configured to do so with a call to + SSL_ConfigSecureServer (among other things). This function configures a listen socket. Child + sockets created by + ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__ + inherit the configuration. + + Servers can be configured with more than one certificate for a given port, and different + certificates can support different key-exchange algorithms. To find out what key-exchange + algorithm a particular certificate supports, pass the certificate structure to + ```NSS_FindCertKEAType`` <sslcrt.html#1056950>`__. You can then pass the ``SSLKEAType`` value + returned by ``NSS_FindCertKEAType`` in the ``keaType`` parameter of ``SSL_ConfigSecureServer``. + The server uses the specified key-exchange algorithm with the specified certificate and key. + + When the ``keaType`` is ``kt_rsa``, this function generates a step-down key that is supplied as + part of the handshake if needed. (A step-down key is needed when the server's public key is + stronger than is allowed for export ciphers.) In this case, if the server is expected to continue + running for a long time, you should call this function periodically (once a day, for example) to + generate a new step-down key. + + SSL makes and keeps internal copies (or increments the reference counts, as appropriate) of + certificate and key structures. The application should destroy its copies when it has no further + use for them by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ and + ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__. + + .. rubric:: SSL_SetURL + :name: ssl_seturl + + Sets the domain name of the intended server in the client's SSL socket. + + .. rubric:: Syntax + :name: syntax_23 + + .. code:: + + #include "ssl.h" + + .. code:: + + int SSL_SetURL( + PRFileDesc *fd, + char *url); + + .. rubric:: Parameters + :name: parameters_16 + + This function has the following parameters: + + ======= ================================================================== + ``fd`` A pointer to a file descriptor. + ``url`` A pointer to a string specifying the desired server's domain name. + ======= ================================================================== + + .. rubric:: Returns + :name: returns_19 + + The function returns one of the following values: + + - If successful, zero. + - If unsuccessful, ``-1``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_23 + + The client application's certificate authentication callback function needs to compare the domain + name in the server's certificate against the domain name of the server the client was attempting + to contact. This step is vital because it is the client's\ *only* protection against a + man-in-the-middle attack. + + The client application uses ``SSL_SetURL`` to set the domain name of the desired server before + performing the first SSL handshake. The client application's certificate authentication callback + function gets this string by calling ```SSL_RevealURL`` <#1081175>`__. + + .. rubric:: SSL_SetPKCS11PinArg + :name: ssl_setpkcs11pinarg + + Sets the argument passed to the password callback function specified by a call to + ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__. + + .. rubric:: Syntax + :name: syntax_24 + + .. code:: + + #include "ssl.h" + + .. code:: + + int SSL_SetPKCS11PinArg(PRFileDesc *fd, void *a); + + .. rubric:: Parameters + :name: parameters_17 + + This function has the following parameters: + + +--------+----------------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +--------+----------------------------------------------------------------------------------------+ + | ``a`` | A pointer supplied by the application that can be used to pass state information. This | + | | value is passed as the third argument of the application's password function. The | + | | meaning is determined solely by the application. | + +--------+----------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_20 + + The function returns one of the following values: + + - If successful, zero. + - If unsuccessful, ``-1``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_24 + + During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11 + token (either a smart card or soft token) to access protected information, such as a private key. + Such information is protected with a password that can be retrieved by calling an + application-supplied callback function. The callback function is specified in a call to + ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ that takes place during NSS initialization. + + Several functions in the NSS libraries use the password callback function to obtain the password + before performing operations that involve the protected information. When NSS libraries call the + password callback function, the value they pass in as the third parameter is the value of the + ``a`` argument to ``PK11_SetPKCS11PinArg``. The third parameter to the password callback function + is application-defined and can be used for any purpose. For example, Communicator uses the + parameter to pass information about which window is associated with the modal dialog box + requesting the password from the user. + + You can obtain the PIN argument by calling ```SSL_RevealPinArg`` <#1123385>`__. + +.. _callback_configuration: + +`Callback Configuration <#callback_configuration>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + At the beginning of an SSL application, it is often necessary to set up callback functions for + the SSL API to use when it needs to call the application. These functions are used to request + authentication information from the application or to inform the application when a handshake is + completed. + + | ```SSL_AuthCertificateHook`` <#1088805>`__ + | ```SSL_AuthCertificate`` <#1088888>`__ + | ```SSL_BadCertHook`` <#1088928>`__ + | ```SSL_GetClientAuthDataHook`` <#1126622>`__ + | ```NSS_GetClientAuthData`` <#1106762>`__ + | ```SSL_HandshakeCallback`` <#1112702>`__ + + Setting up the callback functions described in this section may be optional for some + applications. However, all applications must use + ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ to set up the password callback function during + NSS initialization. + + For examples of the callback functions listed here, see `Chapter 2, "Getting Started With + SSL." <gtstd.html#1005439>`__ + + .. rubric:: SSL_AuthCertificateHook + :name: ssl_authcertificatehook + + Specifies a certificate authentication callback function called to authenticate an incoming + certificate. + + .. rubric:: Syntax + :name: syntax_25 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_AuthCertificateHook( + PRFileDesc *fd, + SSLAuthCertificate f, + void *arg); + + .. rubric:: Parameters + :name: parameters_18 + + This function has the following parameters: + + +---------+---------------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +---------+---------------------------------------------------------------------------------------+ + | ``f`` | A pointer to the callback function. If ``NULL``, the default callback function, | + | | ```SSL_AuthCertificate`` <#1088888>`__, will be used. | + +---------+---------------------------------------------------------------------------------------+ + | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can | + | | be ``NULL``. | + +---------+---------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_21 + + The function returns one of the following values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_25 + + The callback function set up by ``SSL_AuthCertificateHook`` is called to authenticate an incoming + certificate. If the ``checksig`` parameter is set to ``PR_TRUE``, the callback function also + verifies the digital signature. + + **NOTE:** If you do not call\ ``SSL_AuthCertificateHook`` to supply a certificate + authentication callback function, SSL uses the default callback function, + ```SSL_AuthCertificate`` <#1088888>`__. + + The callback function has the following prototype: + + .. code:: + + typedef SECStatus (*SSLAuthCertificate) ( + void *arg, + PRFileDesc *fd, + PRBool checksig, + PRBool isServer); + + This callback function has the following parameters: + + +--------------+----------------------------------------------------------------------------------+ + | ``arg`` | A pointer supplied by the application (in the call to | + | | ``SSL_AuthCertificateHook``) that can be used to pass state information. Can be | + | | ``NULL``. | + +--------------+----------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +--------------+----------------------------------------------------------------------------------+ + | ``checksig`` | ``PR_TRUE``\ means signatures are to be checked and the certificate chain is to | + | | be validated. ``PR_FALSE`` means they are not to be checked. (The value is | + | | normally ``PR_TRUE``.) | + +--------------+----------------------------------------------------------------------------------+ + | ``isServer`` | ``PR_TRUE`` means the callback function should evaluate the certificate as a | + | | server does, treating the remote end as a client. ``PR_FALSE`` means the | + | | callback function should evaluate the certificate as a client does, treating the | + | | remote end as a server. | + +--------------+----------------------------------------------------------------------------------+ + + The callback function returns one of these values: + + - If authentication is successful, ``SECSuccess``. + - If authentication is not successful, ``SECFailure``. If the callback returns ``SECFailure``, + the callback should indicate the reason for the failure (if possible) by calling + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + with the appropriate error code. + + The callback function obtains the certificate to be authenticated by calling + ```SSL_PeerCertificate`` <#1096168>`__. + + If ``isServer`` is false, the callback should also check that the domain name in the remote + server's certificate matches the desired domain name specified in a previous call to + ```SSL_SetURL`` <#1087792>`__. To obtain that domain name, the callback calls + ```SSL_RevealURL`` <#1081175>`__. + + The callback may need to call one or more PK11 functions to obtain the services of a PKCS #11 + module. Some of the PK11 functions require a PIN argument (see + ```SSL_SetPKCS11PinArg`` <#1088040>`__ for details). To obtain the value that was set with + ```SSL_SetPKCS11PinArg`` <#1088040>`__, the callback calls ```SSL_RevealPinArg`` <#1123385>`__. + + If the callback returns ``SECFailure``, the SSL connection is terminated immediately unless the + application has supplied a bad-certificate callback function by having previously called + ```SSL_BadCertHook`` <#1088928>`__. A bad-certificate callback function gives the application the + opportunity to choose to accept the certificate as authentic and authorized even though it failed + the check performed by the certificate authentication callback function. + + .. rubric:: See Also + :name: see_also_2 + + For examples of certificate authentication callback functions, see the sample code referenced + from `Chapter 2, "Getting Started With SSL." <gtstd.html#1005439>`__ + + .. rubric:: SSL_AuthCertificate + :name: ssl_authcertificate + + Default callback function used to authenticate certificates received from the remote end of an + SSL connection if the application has not previously called + ```SSL_AuthCertificateHook`` <#1088805>`__ to specify its own certificate authentication callback + function. + + .. rubric:: Syntax + :name: syntax_26 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_AuthCertificate( + void *arg, + PRFileDesc *fd, + PRBool checksig, + PRBool isServer); + + .. rubric:: Parameters + :name: parameters_19 + + This function has the following parameters: + + +--------------+----------------------------------------------------------------------------------+ + | ``arg`` | A pointer to the handle of the certificate database to be used in validating the | + | | certificate's signature. (This use of the ``arg`` parameter is required for | + | | ``SSL_AuthCertificate``, but not for all implementations of a certificate | + | | authentication callback function.) | + +--------------+----------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +--------------+----------------------------------------------------------------------------------+ + | ``checksig`` | ``PR_TRUE``\ means signatures are to be checked and the certificate chain is to | + | | be validated. ``PR_FALSE`` means they are not to be checked. (The value is | + | | normally ``PR_TRUE``.) | + +--------------+----------------------------------------------------------------------------------+ + | ``isServer`` | ``PR_TRUE`` means the callback function should evaluate the certificate as a | + | | server does, treating the remote end is a client. ``PR_FALSE`` means the | + | | callback function should evaluate the certificate as a client does, treating the | + | | remote end as a server. | + +--------------+----------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_22 + + The function returns one of these values: + + - If authentication is successful, ``SECSuccess``. + - If authentication is not successful, ``SECFailure``. + + .. rubric:: Description + :name: description_26 + + SSL calls ``SSL_AuthCertificate`` by default (if no other callback function is provided) to + authenticate an incoming certificate. If the ``checksig`` parameter is set to ``PR_TRUE`` (which + is normally the case), the function also verifies the digital signature and the certificate + chain. + + If the socket is a client socket, ``SSL_AuthCertificate`` tests the domain name in the SSL socket + against the domain name in the server certificate's subject DN: + + - If the domain name in the SSL socket doesn't match the domain name in the server certificate's + subject DN, the function fails. + - If the SSL socket has not had a domain name set (that is, if ```SSL_SetURL`` <#1087792>`__ has + not been called) or its domain name is set to an empty string, the function fails. + + SSL_BadCertHook + + Sets up a callback function to deal with a situation where the + ```SSL_AuthCertificate`` <#1088888>`__ callback function has failed. This callback function + allows the application to override the decision made by the certificate authorization callback + and authorize the certificate for use in the SSL connection. + + .. rubric:: Syntax + :name: syntax_27 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_BadCertHook( + PRFileDesc *fd, + SSLBadCertHandler f, + void *arg); + + .. rubric:: Parameters + :name: parameters_20 + + This function has the following parameters: + + +---------+---------------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +---------+---------------------------------------------------------------------------------------+ + | ``f`` | A pointer to the application's callback function. | + +---------+---------------------------------------------------------------------------------------+ + | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can | + | | be ``NULL``. | + +---------+---------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_23 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_27 + + The bad-certificate callback function gives the program an opportunity to do something (for + example, log the attempt or authorize the certificate) when certificate authentication is not + successful. If such a callback function is not provided by the application, the SSL connection + simply fails when certificate authentication is not successful. + + The callback function set up by ``SSL_BadCertHook`` has the following prototype: + + .. code:: + + typedef SECStatus (*SSLBadCertHandler)( + void *arg, + PRFileDesc *fd); + + This callback function has the following parameters: + + ======= =================================================================== + ``arg`` The ``arg`` parameter passed to ```SSL_BadCertHook`` <#1088928>`__. + ``fd`` A pointer to the file descriptor for the SSL socket. + ======= =================================================================== + + The callback function returns one of these values: + + - ``SECSuccess``: The callback has chosen to authorize the certificate for use in this SSL + connection, despite the fact that it failed the examination by the certificate authentication + callback. + - ``SECFailure``: The certificate is not authorized for this SSL connection. The SSL connection + will be terminated immediately. + + To obtain the certificate that was rejected by the certificate authentication callback, the + bad-certificate callback function calls ```SSL_PeerCertificate`` <#1096168>`__. Since it is + called immediately after the certificate authentication callback returns, the bad-certificate + callback function can obtain the error code set by the certificate authentication callback by + calling + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + immediately, as the first operation it performs. Note: once the bad-certificate callback function + returns, the peer certificate is destroyed, and SSL_PeerCertificate will fail. + + The callback may need to call one or more PK11 functions to obtain the services of a PKCS #11 + module. Some of the PK11 functions require a PIN argument (see + ```SSL_SetPKCS11PinArg`` <#1088040>`__ for details). To obtain the value previously passed, the + callback calls ```SSL_RevealPinArg`` <#1123385>`__ + + .. rubric:: See Also + :name: see_also_3 + + SSL_GetClientAuthDataHook + + Defines a callback function for SSL to use in a client application when a server asks for client + authentication information. This callback function is required if your client application is + going to support client authentication. + + .. rubric:: Syntax + :name: syntax_28 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_GetClientAuthDataHook( + PRFileDesc *fd, + SSLGetClientAuthData f, + void *a); + + .. rubric:: Parameters + :name: parameters_21 + + This function has the following parameters: + + +---------+---------------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +---------+---------------------------------------------------------------------------------------+ + | ``f`` | A pointer to the application's callback function that delivers the key and | + | | certificate. | + +---------+---------------------------------------------------------------------------------------+ + | ``arg`` | A pointer supplied by the application that can be used to pass state information. Can | + | | be ``NULL``. | + +---------+---------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_24 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_28 + + The callback function set with ``SSL_GetClientAuthDataHook`` is used to get information from a + client application when authentication is requested by the server. The callback function + retrieves the client's private key and certificate. + + SSL provides an implementation of this callback function; see + ```NSS_GetClientAuthData`` <#1106762>`__ for details. Unlike + ```SSL_AuthCertificate`` <#1088888>`__, ```NSS_GetClientAuthData`` <#1106762>`__ is not a default + callback function. You must set it explicitly with ``SSL_GetClientAuthDataHook`` if you want to + use it. + + The callback function has the following prototype: + + .. code:: + + typedef SECStatus (*SSLGetClientAuthData)( + void *arg, + PRFileDesc *fd, + CertDistNames *caNames, + CERTCertificate **pRetCert, + SECKEYPrivateKey **pRetKey); + + This callback function has the following parameters: + + ============ ================================================================================= + ``arg`` The ``arg`` parameter passed to ``SSL_GetClientAuthDataHook``. + ``fd`` A pointer to the file descriptor for the SSL socket. + ``caNames`` A pointer to distinguished names of CAs that the server accepts. + ``pRetCert`` A pointer to a pointer to a certificate structure, for returning the certificate. + ``pRetKey`` A pointer to a pointer to a key structure, for returning the private key. + ============ ================================================================================= + + The callback function returns one of these values: + + - If data returned is valid, ``SECSuccess``. + - If the function cannot obtain a certificate, ``SECFailure``. + + .. rubric:: NSS_GetClientAuthData + :name: nss_getclientauthdata + + Callback function that a client application can use to get the client's private key and + certificate when authentication is requested by a remote server. + + .. rubric:: Syntax + :name: syntax_29 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus NSS_GetClientAuthData( + void * arg, + PRFileDesc *socket, + struct CERTDistNamesStr *caNames, + struct CERTCertificateStr **pRetCert, + struct SECKEYPrivateKeyStr **pRetKey); + + .. rubric:: Parameters + :name: parameters_22 + + This function has the following parameters: + + +--------------+----------------------------------------------------------------------------------+ + | ``arg`` | The ``arg`` parameter passed to ``SSL_GetClientAuthDataHook``, which should be a | + | | pointer to a ``NULL``-terminated string containing the nickname of the | + | | certificate and key pair to use. If ``arg`` is ``NULL``, | + | | ``NSS_GetClientAuthData`` searches the certificate and key databases for a | + | | suitable match and uses the certificate and key pair it finds, if any. | + +--------------+----------------------------------------------------------------------------------+ + | ``socket`` | A pointer to the file descriptor for the SSL socket. | + +--------------+----------------------------------------------------------------------------------+ + | ``caNames`` | A pointer to distinguished names of CAs that the server accepts. | + +--------------+----------------------------------------------------------------------------------+ + | ``pRetCert`` | A pointer to a pointer to a certificate structure, for returning the | + | | certificate. | + +--------------+----------------------------------------------------------------------------------+ + | ``pRetKey`` | A pointer to a pointer to a key structure, for returning the private key. | + +--------------+----------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_25 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_29 + + Unlike ```SSL_AuthCertificate`` <#1088888>`__, ``NSS_GetClientAuthData`` is not a default + callback function. You must set it explicitly with ```SSL_GetClientAuthDataHook`` <#1126622>`__ + for each SSL client socket. + + Once ``NSS_GetClientAuthData`` has been set for a client socket, SSL invokes it whenever SSL + needs to know what certificate and private key (if any) to use to respond to a request for client + authentication. + + .. rubric:: SSL_HandshakeCallback + :name: ssl_handshakecallback + + Sets up a callback function used by SSL to inform either a client application or a server + application when the handshake is completed. + + .. rubric:: Syntax + :name: syntax_30 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_HandshakeCallback( + PRFileDesc *fd, + SSLHandshakeCallback cb, + void *client_data); + + .. rubric:: Parameters + :name: parameters_23 + + This function has the following parameters: + + +-----------------+-------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +-----------------+-------------------------------------------------------------------------------+ + | ``cb`` | A pointer to the application's callback function. | + +-----------------+-------------------------------------------------------------------------------+ + | ``client_data`` | A pointer to the value of the ``client_data`` argument that was passed to | + | | ``SSL_HandshakeCallback``. | + +-----------------+-------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_26 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_30 + + The callback function set by ``SSL_HandshakeCallback`` has the following prototype: + + .. code:: + + typedef void (*SSLHandshakeCallback)( + PRFileDesc *fd, + void *client_data); + + This callback function has the following parameters: + + +-----------------+-------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +-----------------+-------------------------------------------------------------------------------+ + | ``client_data`` | A pointer supplied by the application that can be used to pass state | + | | information. Can be ``NULL``. | + +-----------------+-------------------------------------------------------------------------------+ + + .. rubric:: See Also + :name: see_also_4 + +.. _ssl_communication_functions: + +`SSL Communication Functions <#ssl_communication_functions>`__ +-------------------------------------------------------------- + +.. container:: + + Most communication functions are described in the `NSPR + Reference <../../../../../nspr/reference/html/index.html>`__. For a complete list of + communication functions used by SSL-enabled applications, see + `Communication <sslintro.html#1027816>`__. + + | ```SSL_InvalidateSession`` <#1089420>`__ + | ```SSL_DataPending`` <#1092785>`__ + | ```SSL_SecurityStatus`` <#1092805>`__ + | ```SSL_GetSessionID`` <#1092869>`__ + | ```SSL_SetSockPeerID`` <#1124562>`__ + + .. rubric:: SSL_InvalidateSession + :name: ssl_invalidatesession + + Removes the current session on a particular SSL socket from the session cache. + + .. rubric:: Syntax + :name: syntax_31 + + .. code:: + + #include "ssl.h" + + .. code:: + + int SSL_InvalidateSession(PRFileDesc *fd); + + .. rubric:: Parameter + :name: parameter_4 + + This function has the following parameter: + + ====== ==================================================== + ``fd`` A pointer to the file descriptor for the SSL socket. + ====== ==================================================== + + .. rubric:: Returns + :name: returns_27 + + The function returns one of these values: + + - If successful, zero. + - If unsuccessful, -1. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_31 + + After you call ``SSL_InvalidateSession``, the existing connection using the session can continue, + but no new connections can resume this SSL session. + + .. rubric:: SSL_DataPending + :name: ssl_datapending + + Returns the number of bytes waiting in internal SSL buffers to be read by the local application + from the SSL socket. + + .. rubric:: Syntax + :name: syntax_32 + + .. code:: + + #include "ssl.h" + + .. code:: + + int SSL_DataPending(PRFileDesc *fd); + + .. rubric:: Parameter + :name: parameter_5 + + This function has the following parameter: + + ====== ========================================================== + ``fd`` A pointer to a file descriptor for a connected SSL socket. + ====== ========================================================== + + .. rubric:: Returns + :name: returns_28 + + The function returns an integer: + + - If successful, the function returns the number of bytes waiting in internal SSL buffers for + the specified socket. + - If ``SSL_SECURITY`` has not been enabled with a call to + ```SSL_OptionSetDefault`` <#1068466>`__ or ```SSL_OptionSet`` <#1086543>`__, the function + returns zero. + + .. rubric:: Description + :name: description_32 + + The ``SSL_DataPending`` function determines whether there is any received and decrypted + application data remaining in the SSL socket's receive buffers after a prior read operation. This + function does not reveal any information about data that has been received but has not yet been + decrypted. Hence, if this function returns zero, that does not necessarily mean that a subsequent + call to + ```PR_Read`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Read>`__ + would block. + + .. rubric:: SSL_SecurityStatus + :name: ssl_securitystatus + + Gets information about the security parameters of the current connection. + + .. rubric:: Syntax + :name: syntax_33 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_SecurityStatus( + PRFileDesc *fd, + int *on, + char **cipher, + int *keysize, + int *secretKeySize, + char **issuer, + char **subject); + + .. rubric:: Parameters + :name: parameters_24 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``fd`` | The file descriptor for the SSL socket. | + +-------------------------------------------------+-------------------------------------------------+ + | ``on`` | A pointer to an integer. On output, the integer | + | | will be one of these values: | + | | | + | | - ``SSL_SECURITY_STATUS_ OFF (= 0)`` | + | | - ``SSL_SECURITY_STATUS_ ON_HIGH (= 1)`` | + | | - ``SSL_SECURITY_STATUS_ON_LOW (= 2)`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``cipher`` | A pointer to a string pointer. On output, the | + | | string pointer references a newly allocated | + | | string specifying the name of the cipher. For | + | | SSL v2, the string is one of the following: | + | | | + | | ``RC4`` | + | | ``RC4-Export`` | + | | | + | | ``RC2-CBC`` | + | | | + | | ``RC2-CBC-Export`` | + | | | + | | ``DES-CBC`` | + | | | + | | ``DES-EDE3-CBC`` | + | | | + | | For SSL v3, the string is one of the following: | + | | | + | | ``RC4`` | + | | ``RC4-40`` | + | | | + | | ``RC2-CBC`` | + | | | + | | ``RC2-CBC-40`` | + | | | + | | ``DES-CBC`` | + | | | + | | ``3DES-EDE-CBC`` | + | | | + | | ``DES-CBC-40`` | + | | | + | | ``FORTEZZA`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``keySize`` | A pointer to an integer. On output, the integer | + | | is the session key size used, in bits. | + +-------------------------------------------------+-------------------------------------------------+ + | ``secretKeySize`` | A pointer to an integer. On output, the integer | + | | indicates the size, in bits, of the secret | + | | portion of the session key used (also known as | + | | the "effective key size"). The secret key size | + | | is never greater than the session key size. | + +-------------------------------------------------+-------------------------------------------------+ + | ``issuer`` | A pointer to a string pointer. On output, the | + | | string pointer references a newly allocated | + | | string specifying the DN of the issuer of the | + | | certificate at the other end of the connection, | + | | in RFC1485 format. If no certificate is | + | | supplied, the string is "``no certificate``." | + +-------------------------------------------------+-------------------------------------------------+ + | ``subject`` | A pointer to a string pointer specifying the | + | | distinguished name of the certificate at the | + | | other end of the connection, in RFC1485 format. | + | | If no certificate is supplied, the string is | + | | "``no certificate``." | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_29 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_33 + + The ``SSL_SecurityStatus`` function fills in values only if you supply pointers to values of the + appropriate type. Pointers passed can be ``NULL``, in which case the function does not supply + values. When you are finished with them, you should free all the returned values using + ```PR_Free`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Free>`__. + + .. rubric:: SSL_GetSessionID + :name: ssl_getsessionid + + Returns a ```SECItem`` <ssltyp.html#1026076>`__ structure containing the SSL session ID + associated with a file descriptor. + + .. rubric:: Syntax + :name: syntax_34 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECItem *SSL_GetSessionID(PRFileDesc *fd); + + .. rubric:: Parameter + :name: parameter_6 + + This function has the following parameter: + + ====== ==================================================== + ``fd`` A pointer to the file descriptor for the SSL socket. + ====== ==================================================== + + .. rubric:: Returns + :name: returns_30 + + The function returns one of these values: + + If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_34 + + This function returns a ```SECItem`` <ssltyp.html#1026076>`__ structure containing the SSL + session ID associated with the file descriptor ``fd``. When the application is finished with the + ``SECItem`` structure returned by this function, it should free the structure by calling + ``SECITEM_FreeItem(item, PR_TRUE)``. + + .. rubric:: SSL_SetSockPeerID + :name: ssl_setsockpeerid + + Associates a peer ID with a socket to facilitate looking up the SSL session when it is tunneling + through a proxy. + + .. rubric:: Syntax + :name: syntax_35 + + .. code:: + + #include "ssl.h" + + .. code:: + + int SSL_SetSockPeerID(PRFileDesc *fd, char *peerID); + + .. rubric:: Parameters + :name: parameters_25 + + This function has the following parameters: + + +------------+------------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +------------+------------------------------------------------------------------------------------+ + | ``peerID`` | An ID number assigned by the application to keep track of the SSL session | + | | associated with the peer. | + +------------+------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_31 + + The function returns one of these values: + + - If successful, zero. + - If unsuccessful, -1. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_35 + + SSL peers frequently reconnect after a relatively short time has passed. To avoid the overhead of + repeating the full SSL handshake in situations like this, the SSL protocol supports the use of a + session cache, which retains information about each connection for some predetermined length of + time. For example, a client session cache includes the hostname and port number of each server + the client connects with, plus additional information such as the master secret generated during + the SSL handshake. + + For a direct connection with a server, the hostname and port number are sufficient for the client + to identify the server as one for which it has an entry in its session cache. However, the + situation is more complicated if the client is on an intranet and is connecting to a server on + the Internet through a proxy. In this case, the client first connects to the proxy, and the + client and proxy exchange messages specified by the proxy protocol that allow the proxy, in turn, + to connect to the requested server on behalf of the client. This arrangement is known as SSL + tunneling. + + Client session cache entries for SSL connections that tunnel through a particular proxy all have + the same hostname and port number--that is, the hostname and port number of the proxy. To + determine whether a particular server with which the client is attempting to connect has an entry + in the session cache, the session cache needs some additional information that identifies that + server. This additional identifying information is known as a peer ID. The peer ID is associated + with a socket, and must be set before the SSL handshake occurs--that is, before the SSL handshake + is initiated by a call to a function such as ``PR_Read`` or + ```SSL_ForceHandshake`` <#1133431>`__. To set the peer ID, you use ``SSL_SetSockPeerID``. + + In summary, SSL uses three pieces of information to identify a server's entry in the client + session cache: the hostname, port number, and peer ID. In the case of a client that is tunneling + through a proxy, the hostname and port number identify the proxy, and the peer ID identifies the + desired server. Netscape recommends that the client set the peer ID to a string that consists of + the server's hostname and port number, like this: "``www.hostname.com:387``". This convention + guarantees that each server has a unique entry in the client session cache. + + .. rubric:: See Also + :name: see_also_5 + + For information about configuring the session cache for a server, see + ```SSL_ConfigServerSessionIDCache`` <#1143851>`__. + +.. _ssl_functions_used_by_callbacks: + +`SSL Functions Used by Callbacks <#ssl_functions_used_by_callbacks>`__ +---------------------------------------------------------------------- + +.. container:: + + | ```SSL_PeerCertificate`` <#1096168>`__ + | ```SSL_RevealURL`` <#1081175>`__ + | ```SSL_RevealPinArg`` <#1123385>`__ + + .. rubric:: SSL_PeerCertificate + :name: ssl_peercertificate + + Returns a pointer to the certificate structure for the certificate received from the remote end + of the SSL connection. + + .. rubric:: Syntax + :name: syntax_36 + + .. code:: + + #include "ssl.h" + + .. code:: + + CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd); + + .. rubric:: Parameter + :name: parameter_7 + + This function has the following parameter: + + ====== ==================================================== + ``fd`` A pointer to the file descriptor for the SSL socket. + ====== ==================================================== + + .. rubric:: Returns + :name: returns_32 + + The function returns one of these values: + + - If successful, a pointer to a certificate structure. + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_36 + + The ``SSL_PeerCertificate`` function is used by certificate authentication and bad-certificate + callback functions to obtain the certificate under scrutiny. If the client calls + ``SSL_PeerCertificate``, it always returns the server's certificate. If the server calls + ``SSL_PeerCertificate``, it may return ``NULL`` if client authentication is not enabled or if the + client had no certificate when asked. + + SSL makes and keeps internal copies (or increments the reference counts, as appropriate) of + certificate and key structures. The application should destroy its copies when it has no further + use for them by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ and + ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__. + + .. rubric:: SSL_RevealURL + :name: ssl_revealurl + + Returns a pointer to a newly allocated string containing the domain name of the desired server. + + .. rubric:: Syntax + :name: syntax_37 + + .. code:: + + #include "ssl.h" + + .. code:: + + char *SSL_RevealURL(PRFileDesc *fd); + + .. rubric:: Parameter + :name: parameter_8 + + This function has the following parameter: + + ====== ==================================================== + ``fd`` A pointer to the file descriptor for the SSL socket. + ====== ==================================================== + + .. rubric:: Returns + :name: returns_33 + + The function returns one of the following values: + + - If successful, returns a pointer to a newly allocated string containing the domain name of the + desired server. + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_37 + + The ``SSL_RevealURL`` function is used by certificate authentication callback function to obtain + the domain name of the desired SSL server for the purpose of comparing it with the domain name in + the certificate presented by the server actually contacted. When the callback function is + finished with the string returned, the string should be freed with a call to + ```PR_Free`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Free>`__. + + .. rubric:: SSL_RevealPinArg + :name: ssl_revealpinarg + + Returns the ``PKCS11PinArg`` value associated with the socket. + + .. rubric:: Syntax + :name: syntax_38 + + .. code:: + + #include "ssl.h" + + .. code:: + + void *SSL_RevealPinArg(PRFileDesc *fd); + + .. rubric:: Parameter + :name: parameter_9 + + This function has the following parameter: + + ====== ==================================================== + ``fd`` A pointer to the file descriptor for the SSL socket. + ====== ==================================================== + + .. rubric:: Returns + :name: returns_34 + + The function returns one of the following values: + + - If successful, the ``PKCS11PinArg`` value associated with the socket. + - If unsuccessful, ``NULL``. + + .. rubric:: Description + :name: description_38 + + The ``SSL_RevealPinArg`` function is used by callback functions to obtain the PIN argument that + NSS passes to certain functions. The PIN argument points to memory allocated by the application. + The application is responsible for managing the memory referred to by this pointer. For more + information about this argument, see ```SSL_SetPKCS11PinArg`` <#1088040>`__. + +.. _ssl_handshake_functions: + +`SSL Handshake Functions <#ssl_handshake_functions>`__ +------------------------------------------------------ + +.. container:: + + | ```SSL_ForceHandshake`` <#1133431>`__ + | ```SSL_ReHandshake`` <#1232052>`__ + | ```SSL_ResetHandshake`` <#1058001>`__ + + .. rubric:: SSL_ForceHandshake + :name: ssl_forcehandshake + + Drives a handshake for a specified SSL socket to completion on a socket that has already been + prepared to do a handshake or is in the middle of doing a handshake. + + .. rubric:: Syntax + :name: syntax_39 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_ForceHandshake(PRFileDesc *fd); + + .. rubric:: Parameters + :name: parameters_26 + + This function has the following parameter: + + ====== ================================================== + ``fd`` Pointer to the file descriptor for the SSL socket. + ====== ================================================== + + .. rubric:: Returns + :name: returns_35 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_39 + + When you are forcing the initial handshake on a blocking socket, this function returns when the + handshake is complete. For subsequent handshakes, the function can return either because the + handshake is complete, or because application data has been received on the connection that must + be processed (that is, the application must read it) before the handshake can continue. + + You can use ``SSL_ForceHandshake`` when a handshake is desired but neither end has anything to + say immediately. This occurs, for example, when an HTTPS server has received a request and + determines that before it can answer the request, it needs to request an authentication + certificate from the client. At the HTTP protocol level, nothing more is being said (that is, no + HTTP request or response is being sent), so the server uses ``SSL_ForceHandshake`` to make the + handshake occur. + + ``SSL_ForceHandshake`` does not prepare a socket to do a handshake by itself. The following + functions prepare a socket (previously imported into SSL and configured as necessary) to do a + handshake: + + - ``PR_Connect`` + - ``PR_Accept`` + - ```SSL_ReHandshake`` <#1232052>`__ (after the first handshake is finished) + - ```SSL_ResetHandshake`` <#1058001>`__ (for sockets that were connected or accepted prior to + being imported) + + A call to ``SSL_ForceHandshake`` will almost always be preceded by one of those functions. + + In versions prior to NSS 1.2, you cannot force a subsequent handshake. If you use this function + after the initial handshake, it returns immediately without forcing a handshake. + + .. rubric:: SSL_ReHandshake + :name: ssl_rehandshake + + Causes SSL to begin a new SSL 3.0 handshake on a connection that has already completed one + handshake. + + ``SSL_ReHandshake`` replaces the deprecated function ```SSL_RedoHandshake`` <#1231825>`__. + + .. rubric:: Syntax + :name: syntax_40 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_RedoHandshake(PRFileDesc *fd, PRBool flushCache); + + .. rubric:: Parameter + :name: parameter_10 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL | + | | socket. | + +-------------------------------------------------+-------------------------------------------------+ + | ``flushCache`` | If ``flushCache`` is non-zero, the SSL3 cache | + | | entry will be flushed first, ensuring that a | + | | full SSL handshake from scratch will occur. | + | | | + | | If ``flushCache`` is zero, and an SSL | + | | connection is established, it will do the much | + | | faster session restart handshake. This will | + | | regenerate the symmetric session keys without | + | | doing another private key operation. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_36 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <../../../../../nspr/reference/html/prerr.html#26127>`__ to obtain the error + code. + + .. rubric:: Description + :name: description_40 + + If ``flushCache`` is non-zero, the ``SSL_ReHandshake`` function invalidates the current SSL + session associated with the specified ``fd`` from the session cache and starts another full SSL + 3.0 handshake. It is for use with SSL 3.0 only. You can call this function to redo the handshake + if you have changed one of the socket's configuration parameters (for example, if you are going + to request client authentication). + + Setting ``flushCache`` to zero can be useful, for example, if you are using export ciphers and + want to keep changing the symmetric keys to foil potential attackers. + + ``SSL_ReHandshake`` only initiates the new handshake by sending the first message of that + handshake. To drive the new handshake to completion, you must either call ``SSL_ForceHandshake`` + or do another I/O operation (read or write) on the socket. A call to ``SSL_ReHandshake`` is + typically followed by a call to ``SSL_ForceHandshake``. + + .. rubric:: SSL_ResetHandshake + :name: ssl_resethandshake + + Resets the handshake state for a specified socket. + + .. rubric:: Syntax + :name: syntax_41 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_ResetHandshake( + PRFileDesc *fd, + PRBool asServer); + + .. rubric:: Parameters + :name: parameters_27 + + This function has the following parameters: + + +--------------+----------------------------------------------------------------------------------+ + | ``fd`` | A pointer to the file descriptor for the SSL socket. | + +--------------+----------------------------------------------------------------------------------+ + | ``asServer`` | A Boolean value. ``PR_TRUE`` means the socket will attempt to handshake as a | + | | server the next time it tries, and ``PR_FALSE`` means the socket will attempt to | + | | handshake as a client the next time it tries. | + +--------------+----------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_37 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_41 + + Calling ``SSL_ResetHandshake`` causes the SSL handshake protocol to start from the beginning on + the next I/O operation. That is, the handshake starts with no cipher suite already in use, just + as it does on the first handshake on a new socket. + + When an application imports a socket into SSL after the TCP connection on that socket has already + been established, it must call ``SSL_ResetHandshake`` to determine whether SSL should behave like + an SSL client or an SSL server. Note that this step would not be necessary if the socket weren't + already connected. For an SSL socket that is configured before it is connected, SSL figures this + out when the application calls + ```PR_Connect`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Connect>`__ + or + ```PR_Accept`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_Accept>`__. + If the socket is already connected before SSL gets involved, you must provide this extra hint. + +.. _nss_shutdown_function: + +`NSS Shutdown Function <#nss_shutdown_function>`__ +-------------------------------------------------- + +.. container:: + + .. rubric:: NSS_Shutdown + :name: nss_shutdown + + Closes the key and certificate databases that were opened by ```NSS_Init`` <#1067601>`__. + + .. rubric:: Syntax + :name: syntax_42 + + .. code:: + + #include "nss.h" + + .. code:: + + SECStatus NSS_Shutdown(void); + + .. rubric:: Description + :name: description_42 + + Note that if any reference to an NSS object is leaked (for example, if an SSL client application + doesn't call ```SSL_ClearSessionCache`` <#1138601>`__ first), ``NSS_Shutdown`` fails with the + error code ``SEC_ERROR_BUSY``. + +.. _deprecated_functions: + +`Deprecated Functions <#deprecated_functions>`__ +------------------------------------------------ + +.. container:: + + The following functions have been replaced with newer versions but are still supported: + + | ```SSL_EnableDefault`` <#1206365>`__ + | ```SSL_Enable`` <#1220189>`__ + | ```SSL_EnableCipher`` <#1207298>`__ + | ```SSL_SetPolicy`` <#1207350>`__ + + .. rubric:: SSL_EnableDefault + :name: ssl_enabledefault + + Changes a default value for all subsequently opened sockets as long as the current application + program is running. + + ``SSL_EnableDefault`` has been replaced by ```SSL_OptionSetDefault`` <#1068466>`__ and works the + same way. + + .. rubric:: Syntax + :name: syntax_43 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_EnableDefault(int which, PRBool on); + + .. rubric:: Parameters + :name: parameters_28 + + This function has the following parameters: + + +-----------+-------------------------------------------------------------------------------------+ + | ``which`` | For information about the values that can be passed in the ``which`` parameter, see | + | | ```SSL_OptionSetDefault`` <#1068466>`__. | + +-----------+-------------------------------------------------------------------------------------+ + | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns option off. | + +-----------+-------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_38 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_43 + + For detailed information about using ``SSL_Enable``, see the description of + ```SSL_OptionSetDefault`` <#1068466>`__. + + .. rubric:: SSL_Enable + :name: ssl_enable + + Sets a single configuration parameter of a specified socket. Call once for each parameter you + want to change. + + ``SSL_Enable`` has been replaced by ```SSL_OptionSet`` <#1086543>`__ and works the same way. + + .. rubric:: Syntax + :name: syntax_44 + + .. code:: + + #include "ssl.h" + + .. code:: + + SECStatus SSL_Enable( + PRFileDesc *fd, + int which, + PRBool on); + + .. rubric:: Parameters + :name: parameters_29 + + This function has the following parameters: + + +-----------+-------------------------------------------------------------------------------------+ + | ``fd`` | Pointer to the file descriptor for the SSL socket. | + +-----------+-------------------------------------------------------------------------------------+ + | ``which`` | For information about the values that can be passed in the ``which`` parameter, see | + | | the description of the ``option`` parameter under ```SSL_OptionSet`` <#1086543>`__. | + +-----------+-------------------------------------------------------------------------------------+ + | ``on`` | ``PR_TRUE`` turns option on; ``PR_FALSE`` turns option off. | + +-----------+-------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_39 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, returns ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_44 + + For detailed information about using ``SSL_Enable``, see the description of + ```SSL_OptionSet`` <#1086543>`__. + + .. rubric:: SSL_EnableCipher + :name: ssl_enablecipher + + Enables or disables cipher suites (subject to which cipher suites are permitted or disallowed by + previous calls to one or more of the `SSL Export Policy Functions <#1098841>`__). This function + must be called once for each cipher you want to enable or disable. + + ``SSL_EnableCipher`` has been replaced by ```SSL_CipherPrefSetDefault`` <#1084747>`__ and works + the same way. + + .. rubric:: Syntax + :name: syntax_45 + + .. code:: + + #include "ssl.h" + #include "sslproto.h" + + .. code:: + + SECStatus SSL_EnableCipher(long which, PRBool enabled); + + .. rubric:: Parameters + :name: parameters_30 + + This function has the following parameters: + + +-------------+-----------------------------------------------------------------------------------+ + | ``which`` | The cipher suite whose default preference setting you want to set. For a list of | + | | the cipher suites you can specify, see | + | | ```SSL_CipherPrefSetDefault`` <#1084747>`__. | + +-------------+-----------------------------------------------------------------------------------+ + | ``enabled`` | If nonzero, the specified cipher is enabled. If zero, the cipher is disabled. | + +-------------+-----------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_40 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_45 + + For detailed information about using ``SSL_EnableCipher``, see the description of + ```SSL_CipherPrefSetDefault`` <#1084747>`__. + + .. rubric:: SSL_SetPolicy + :name: ssl_setpolicy + + Sets policy for the use of individual cipher suites. + + ``SSL_SetPolicy`` has been replaced by ```SSL_CipherPolicySet`` <#1104647>`__ and works the same + way. + + .. rubric:: Syntax + :name: syntax_46 + + .. code:: + + #include <ssl.h> + #include <sslproto.h> + + .. code:: + + SECStatus SSL_SetPolicy(long which, int policy); + + .. rubric:: Parameters + :name: parameters_31 + + This function has the following parameters: + + +-------------------------------------------------+-------------------------------------------------+ + | ``which`` | The cipher suite for which you want to set | + | | policy. For a list of possible values, see | + | | ```SSL_CipherPolicySet`` <#1104647>`__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``policy`` | One of the following values: | + | | | + | | - ``SSL_ALLOWED``. Cipher is always allowed by | + | | U.S. government policy. | + | | - ``SSL_RESTRICTED``. Cipher is allowed by | + | | U.S. government policy for servers with | + | | Global ID certificates. | + | | - ``SSL_NOT_ALLOWED``. Cipher is never allowed | + | | by U.S. government policy. | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Returns + :name: returns_41 + + The function returns one of these values: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_46 + + For detailed information about using ``SSL_SetPolicy``, see the description of + ```SSL_CipherPolicySet`` <#1104647>`__. + + .. rubric:: SSL_RedoHandshake + :name: ssl_redohandshake + + Causes SSL to begin a full, new SSL 3.0 handshake from scratch on a connection that has already + completed one handshake. + + .. rubric:: Syntax + :name: syntax_47 + + .. code:: + + #include "ssl.h" + + .. code:: + + int SSL_RedoHandshake(PRFileDesc *fd); + + .. rubric:: Parameter + :name: parameter_11 + + This function has the following parameter: + + ====== ==================================================== + ``fd`` A pointer to the file descriptor for the SSL socket. + ====== ==================================================== + + .. rubric:: Returns + :name: returns_42 + + The function returns one of these values: + + - If successful, zero. + - If unsuccessful, -1. Use + ```PR_GetError`` <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference/PR_GetError>`__ + to obtain the error code. + + .. rubric:: Description + :name: description_47 + + The ``SSL_RedoHandshake`` function invalidates the current SSL session associated with the ``fd`` + parameter from the session cache and starts another full SSL 3.0 handshake. It is for use with + SSL 3.0 only. You can call this function to redo the handshake if you have changed one of the + socket's configuration parameters (for example, if you are going to request client + authentication). + + ``SSL_RedoHandshake`` only initiates the new handshake by sending the first message of that + handshake. To drive the new handshake to completion, you must either call ``SSL_ForceHandshake`` + or do another I/O operation (read or write) on the socket. A call to ``SSL_RedoHandshake`` is + typically followed by a call to ``SSL_ForceHandshake``. diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslintro/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslintro/index.rst new file mode 100644 index 0000000000..aeedd90b9c --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/sslintro/index.rst @@ -0,0 +1,291 @@ +.. _mozilla_projects_nss_ssl_functions_sslintro: + +sslintro +======== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are + inclined to help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: Overview of an SSL Application + :name: Overview_of_an_SSL_Application + + -------------- + +.. _chapter_1_overview_of_an_ssl_application: + +`Chapter 1 + <#chapter_1_overview_of_an_ssl_application>`__ Overview of an SSL Application +------------------------------------------------------------------------------ + +.. container:: + + SSL and related APIs allow compliant applications to configure sockets for authenticated, + tamper-proof, and encrypted communications. This chapter introduces some of the basic SSL + functions. `Chapter 2, "Getting Started With SSL" <gtstd.html#1005439>`__ illustrates their use + in sample client and server applications. + + An SSL application typically includes five parts: + + | `Initialization <#1027662>`__ + | `Configuration <#1027742>`__ + | `Communication <#1027816>`__ + | `Functions Used by Callbacks <#1027820>`__ + | `Cleanup <#1030535>`__ + + Although the details differ somewhat for client and server applications, the concepts and many of + the functions are the same for both. + + **WARNING:** Some of the SSL header files provided as part of NSS 2.0 include both public APIs + documented in the NSS 2.0 documentation set and private APIs intended for internal use by the + NSS implementation of SSL. You should use only the SSL APIs (and related certificate, key, and + PKCS #11 APIs) that are described in this document, the SSL Reference. Other APIs that may be + exposed in the header files are not supported for application use. + +.. _initialization_2: + +` <#initialization_2>`__ Initialization +--------------------------------------- + +.. container:: + + Initialization includes setting up configuration files, setting global defaults, and setting up + callback functions. Functions used in the initialization part of an application can include the + following: + + - ``PR_Init``. Initializes NSPR. Must be called before any other NSS functions. + - ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__. Sets the global callback function to + obtain passwords for PKCS #11 modules. Required. + - ``NSS_Init``. Sets up configuration files and performs other tasks required to run Network + Security Services. ``NSS_Init`` is *not* idempotent, so call it only once. Required. + - ``SSL_OptionSetDefault``. Changes default values for all subsequently opened sockets as long + as the application is running (compare with + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792` which only configures the socket that + is currently open). This function must be called once for each default value that needs to be + changed. Optional. + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1228530`, + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1100285`, + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1105952`, or + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1104647`. These functions tell the library + which cipher suites are permitted by policy (for example, to comply with export restrictions). + Cipher suites disabled by policy cannot be enabled by user preference. One of these functions + must be called before any cryptographic operations can be performed with NSS. + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1084747`. Enables all ciphers chosen by user + preference. Optional. + +.. _initializing_caches: + +`Initializing Caches <#initializing_caches>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + SSL peers frequently reconnect after a relatively short time has passed. To avoid the overhead of + repeating the full SSL handshake in situations like this, the SSL protocol supports the use of a + session cache, which retains information about each connection, such as the master secret + generated during the SSL handshake, for a predetermined length of time. If SSL can locate the + information about a previous connection in the local session cache, it can reestablish the + connection much more quickly than it can without the connection information. + + By default, SSL allocates one session cache. This default cache is called the *client session ID + cache*, (also known as the client session cache, or simply the client cache). The client cache is + used for all sessions where the program handshakes as an SSL client. It is not configurable. You + can initialize the client cache with the function + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`. + + If an application will use SSL sockets that handshake as a server, you must specifically create + and configure a server cache, using either + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851` or + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625`. The server cache is used for all + sessions where the program handshakes as an SSL server. + + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1138601`. Clears all sessions from the client + session cache. Optional. + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`. Sets up parameters for a server + session cache for a single-process application. Required for single-process server + applications. + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1142625`. Sets up parameters for a server + cache for a multi-process application. Required for multi-process server applications. You can + use either this function or :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1143851`, not + both. + +.. _configuration_2: + +` <#configuration_2>`__ Configuration +------------------------------------- + +.. container:: + + The configuration portion of an SSL-enabled application typically begins by opening a new socket + and then importing the new socket into the SSL environment: + + - ``PR_NewTCPSocket``. Opens a new socket. A legal NSPR socket is required to be passed to + ``SSL_ImportFD``, whether it is created with this function or by another method. + - ``SSL_ImportFD``. Makes an NSPR socket into an SSL socket. Required. Brings an ordinary NSPR + socket into the SSL library, returning a new NSPR socket that can be used to make SSL calls. + You can pass this function a *model* file descriptor to create the new SSL socket with the + same configuration state as the model. + + It is also possible for an application to import a socket into SSL after the TCP connection on + that socket has already been established. In this case, initial configuration takes place in the + same way: pass the existing NSPR file descriptor to ``SSL_ImportFD`` and perform any additional + configuration that has not already been determined by the model file descriptor. + + Configuration functions control the configuration of an individual socket. + + - ``PR_GetSocketOption``. Retrieves the socket options currently set for a specified socket. + Optional. + - ``PR_SetSocketOption``. Sets the socket options for a specified socket., including making it + blocking or nonblocking. Optional. + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1086543`. Sets a single configuration + parameter of a specified socket. This function must be called once for each parameter whose + settings you want to change from those established with ``SSL_OptionSetDefault``. Optional. + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1217647`. For servers only. Configures the + socket with the information needed to handshake as an SSL server. Required for servers. + - :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1087792`. For clients only. Records the + target server URL for comparison with the URL specified by the server certificate. Required + for clients. + + Callbacks and helper functions allow you to specify such things as how authentication is + accomplished and what happens if it fails. + + - ``SSL_SetPKCS11PinArg``. Sets the argument passed to the PKCS #11 password callback function. + Required. + - ``SSL_AuthCertificateHook``. Specifies a callback function used to authenticate an incoming + certificate (optional for servers, necessary for clients to avoid "man-in-the-middle" + attacks). Optional. If not specified, SSL uses the default callback function, + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088888`. + - ``SSL_BadCertHook``. Specifies a callback function to deal with a situation where + authentication has failed. Optional. + - ``SSL_GetClientAuthDataHook``. Specifies a callback function for SSL to use when the server + asks for client authentication information. This callback is required if you want to do client + authentication. You can set the callback function to a standard one that is provided, + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1106762`. + - ``SSL_HandshakeCallback``. Specifies a callback function that will be used by SSL to inform + either a client application or a server application when the SSL handshake is completed. + Optional. + +.. _communication_2: + +` <#communication_2>`__ Communication +------------------------------------- + +.. container:: + + At this point the application has set up the socket to communicate using SSL. For simple + encrypted and authenticated communications, no further calls to SSL functions are required. A + variety of additional SSL functions are available, however. These can be used, for example, when + interrupting and restarting socket communications, when the application needs to change socket + parameters, or when an application imports a socket into SSL after the TCP connection on that + socket has already been established. + + Communication between SSL sockets always begins with the SSL handshake. The handshake occurs + automatically the first time communication is requested with a socket read/write or send/receive + call. It is also possible to force the handshake explicitly with + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` or repeat it explicitly with + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052`. + + Once the SSL sockets have been configured, authentication and encryption happen automatically + whenever you use the communication functions from the NSPR library. + + A server application typically uses these functions to establish a connection: + + ``PR_Bind PR_Listen PR_Accept PR_GetSockName`` + + A client application typically uses these functions to establish a connection: + + | ``PR_GetHostByName`` + | ``PR_EnumerateHostEnt`` + | ``PR_Connect`` + | ``PR_GetConnectStatus`` + + When an application imports a socket into SSL after the TCP connection on that socket has already + been established, it must call :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1058001` to + determine whether SSL should behave like an SSL client or an SSL server. Note that this step + would not be necessary if the socket weren't already connected. For an SSL socket that is + configured before it is connected, SSL figures this out when the application calls ``PR_Connect`` + or ``PR_Accept``. If the socket is already connected before SSL gets involved, you must provide + this extra hint. + + Functions that can be used by both clients and servers during communication include the + following: + + | ``PR_Send`` or ``PR_Write`` + | ``PR_Read`` or ``PR_Recv`` + | ``PR_GetError`` + | ``PR_GetPeerName`` + | ``PR_Sleep`` + | ``PR_Malloc`` + | ``PR_Free`` + | ``PR_Poll`` + | ``PR_Now`` + | ``PR_IntervalToMilliseconds`` + | ``PR_MillisecondsToInterval`` + | ``PR_Shutdown`` + | ``PR_Close`` + | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1089420` + + After establishing a connection, an application first calls ``PR_Send``, ``PR_Recv``, + ``PR_Read``, ``PR_Write``, or ``SSL_ForceHandshake`` to initiate the handshake. The application's + protocol (for example, HTTP) determines which end has responsibility to talk first. The end that + has to talk first should call ``PR_Send`` or ``PR_Write``, and the other end should call + ``PR_Read`` or ``PR_Recv``. + + Use :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1133431` when the socket has been prepared + for a handshake but neither end has anything to say immediately. This occurs, for example, when + an HTTPS server has received a request and determines that before it can answer the request, it + needs to request an authentication certificate from the client. At the HTTP protocol level, + nothing more is being said (that is, no HTTP request or response is being sent), so the server + first uses :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1232052` to begin a new handshake and + then call ``SSL_ForceHandshake`` to drive the handshake to completion. + +.. _functions_used_by_callbacks: + +`Functions Used by Callbacks <#functions_used_by_callbacks>`__ +-------------------------------------------------------------- + +.. container:: + + An SSL application typically provides one or more callback functions that are called by the SSL + or PKCS #11 library code under certain circumstances. Numerous functions provided by the NSS + libraries are useful for such application callback functions, including these: + + | ```CERT_CheckCertValidTimes`` <sslcrt.html#1056662>`__ + | ```CERT_GetDefaultCertDB`` <sslcrt.html#1052308>`__ + | ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ + | ```CERT_DupCertificate`` <sslcrt.html#1058344>`__ + | ```CERT_FindCertByName`` <sslcrt.html#1050345>`__ + | ```CERT_FreeNicknames`` <sslcrt.html#1050349>`__ + | ```CERT_GetCertNicknames`` <sslcrt.html#1050346>`__ + | ```CERT_VerifyCertName`` <sslcrt.html#1050342>`__ + | ```CERT_VerifyCertNow`` <sslcrt.html#1058011>`__ + | ```PK11_FindCertFromNickname`` <pkfnc.html#1035673>`__ + | ```PK11_FindKeyByAnyCert`` <pkfnc.html#1026891>`__ + | ```PK11_SetPasswordFunc`` <pkfnc.html#1023128>`__ + | ``PL_strcpy`` + | ``PL_strdup`` + | ``PL_strfree`` + | ``PL_strlen`` + | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1096168` + | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1081175` + | :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1123385` + +.. _cleanup_2: + +` <#cleanup_2>`__ Cleanup +------------------------- + +.. container:: + + This portion of an SSL-enabled application consists primarily of closing the socket and freeing + memory. After these tasks have been performed, call + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1061858` to close the certificate and key + databases opened by :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601`, and ``PR_Cleanup`` + to coordinate a graceful shutdown of NSPR.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/sslkey/index.rst b/security/nss/doc/rst/legacy/ssl_functions/sslkey/index.rst new file mode 100644 index 0000000000..eafd40314b --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/sslkey/index.rst @@ -0,0 +1,107 @@ +.. _mozilla_projects_nss_ssl_functions_sslkey: + +sslkey +====== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to + help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: Key Functions + :name: Key_Functions + + -------------- + +.. _chapter_6_key_functions: + +`Chapter 6 + <#chapter_6_key_functions>`__ Key Functions +-------------------------------------------- + +.. container:: + + This chapter describes two functions used to manipulate private keys and key databases such as + the ``key3.db`` database provided with Communicator. + + | ```SECKEY_GetDefaultKeyDB`` <#1051479>`__ + | ```SECKEY_DestroyPrivateKey`` <#1051017>`__ + + .. rubric:: SECKEY_GetDefaultKeyDB + :name: seckey_getdefaultkeydb + + Returns a handle to the default key database opened by + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601`. + + .. rubric:: Syntax + :name: syntax + + .. code:: + + #include <key.h> + #include <keyt.h> + + .. code:: + + SECKEYKeyDBHandle *SECKEY_GetDefaultKeyDB(void); + + .. rubric:: Returns + :name: returns + + The function returns a handle of type ``SECKEYKeyDBHandle``. + + .. rubric:: Description + :name: description + + :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1067601` opens the certificate, key, and security + module databases that you specify for use with NSS. ``SECKEYKeyDBHandle`` returns a handle to the + key database opened by ``NSS_Init``. + + .. rubric:: SECKEY_DestroyPrivateKey + :name: seckey_destroyprivatekey + + Destroys a private key structure. + + .. rubric:: Syntax + :name: syntax_2 + + .. code:: + + #include <key.h> + #include <keyt.h> + + .. code:: + + void SECKEY_DestroyPrivateKey(SECKEYPrivateKey *key); + + .. rubric:: Parameter + :name: parameter + + This function has the following parameter: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | A pointer to the private key structure to | + | | destroy. | + | key | | + +-------------------------------------------------+-------------------------------------------------+ + + .. rubric:: Description + :name: description_2 + + Certificate and key structures are shared objects. When an application makes a copy of a + particular certificate or key structure that already exists in memory, SSL makes a *shallow* + copy--that is, it increments the reference count for that object rather than making a whole new + copy. When you call ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__ or + ```SECKEY_DestroyPrivateKey`` <#1051017>`__, the function decrements the reference count and, if + the reference count reaches zero as a result, both frees the memory and sets all the bits to + zero. The use of the word "destroy" in function names or in the description of a function implies + reference counting. + + Never alter the contents of a certificate or key structure. If you attempt to do so, the change + affects all the shallow copies of that structure and can cause severe problems.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/ssl_functions/ssltyp/index.rst b/security/nss/doc/rst/legacy/ssl_functions/ssltyp/index.rst new file mode 100644 index 0000000000..1ec221042f --- /dev/null +++ b/security/nss/doc/rst/legacy/ssl_functions/ssltyp/index.rst @@ -0,0 +1,343 @@ +.. _mozilla_projects_nss_ssl_functions_ssltyp: + +ssltyp +====== + +.. container:: + + .. note:: + + - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that + we are migrating into the format described in the `MDN Style + Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are + inclined to help with this migration, your help would be very much appreciated. + + - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` + + .. rubric:: Selected SSL Types and Structures + :name: Selected_SSL_Types_and_Structures + + -------------- + +.. _chapter_3_selected_ssl_types_and_structures: + +`Chapter 3 + <#chapter_3_selected_ssl_types_and_structures>`__ Selected SSL Types and Structures +------------------------------------------------------------------------------------ + +.. container:: + + This chapter describes some of the most important types and structures used with the functions + described in the rest of this document, and how to manage the memory used for them. Additional + types are described with the functions that use them or in the header files. + + | `Types and Structures <#1030559>`__ + | `Managing SECItem Memory <#1029645>`__ + +.. _types_and_structures: + +`Types and Structures <#types_and_structures>`__ +------------------------------------------------ + +.. container:: + + These types and structures are described here: + + | ```CERTCertDBHandle`` <#1028465>`__ + | ```CERTCertificate`` <#1027387>`__ + | ```PK11SlotInfo`` <#1028593>`__ + | ```SECItem`` <#1026076>`__ + | ```SECKEYPrivateKey`` <#1026727>`__ + | ```SECStatus`` <#1026722>`__ + + Additional types used by a single function only are described with the function's entry in each + chapter. Some of these functions also use types defined by NSPR and described in the `NSPR + Reference <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSPR/Reference>`__. + + <a id="> Many of the structures presented here (```CERTCertDBHandle`` <#1028465>`__, + ```CERTCertificate`` <#1027387>`__, ```PK11SlotInfo`` <#1028593>`__, and + ```SECKEYPrivateKey`` <#1026727>`__) are opaque--that is, they are types defined as structures + (for example, ``CERTCertDBHandleStr``) that may change in future releases of Network Security + Services. As long as you use the form shown here, your code will not need revision. + + .. rubric:: CERTCertDBHandle + :name: certcertdbhandle + + An opaque handle structure for open certificate databases. + + .. rubric:: Syntax + :name: syntax + + .. code:: + + #include <certt.h> + + .. code:: + + typedef struct CERTCertDBHandleStr CERTCertDBHandle; + + .. rubric:: CERTCertificate + :name: certcertificate + + An opaque X.509 certificate object. + + .. rubric:: Syntax + :name: syntax_2 + + .. code:: + + #include <certt.h> + + .. code:: + + typedef struct CERTCertificateStr CERTCertificate; + + .. rubric:: Description + :name: description + + Certificate structures are shared objects. When an application makes a copy of a particular + certificate structure that already exists in memory, SSL makes a *shallow* copy--that is, it + increments the reference count for that object rather than making a whole new copy. When you call + ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__, the function decrements the reference + count and, if the reference count reaches zero as a result, frees the memory. The use of the word + "destroy" in function names or in the description of a function often implies reference counting. + + Never alter the contents of a certificate structure. If you attempt to do so, the change affects + all the shallow copies of that structure and can cause severe problems. + + .. rubric:: PK11SlotInfo + :name: pk11slotinfo + + An opaque structure representing a physical or logical PKCS #11 slot. + + .. rubric:: Syntax + :name: syntax_3 + + .. code:: + + #include <pk11expt.h> + + ``typedef struct PK11SlotInfo``\ Str ``PK11SlotInfo``; + + .. rubric:: SECItem + :name: secitem + + A structure that points to other structures. + + .. rubric:: Syntax + :name: syntax_4 + + .. code:: + + #include <seccomon.h> + #include <prtypes.h> + #include <secport.h> + + .. code:: + + typedef enum { + siBuffer, + siClearDataBuffer, + siCipherDataBuffer, + siDERCertBuffer, + siEncodedCertBuffer, + siDERNameBuffer, + siEncodedNameBuffer, + siAsciiNameString, + siAsciiString, + siDEROID + } SECItemType; + + .. code:: + + typedef struct SECItemStr SECItem; + + .. code:: + + struct SECItemStr { + SECItemType type; + unsigned char *data; + unsigned int len; + }; + + .. rubric:: Description + :name: description_2 + + A ``SECItem`` structure can be used to associate your own data with an SSL socket. + + To free a structure pointed to by a ``SECItem``, and, if desired, the ``SECItem`` structure + itself, use one the functions ```SECItem_FreeItem`` <#1030620>`__ or + ```SECItem_ZfreeItem`` <#1030773>`__. + + .. rubric:: SECKEYPrivateKey + :name: seckeyprivatekey + + An opaque, generic key structure. + + .. rubric:: Syntax + :name: syntax_5 + + .. code:: + + #include <keyt.h> + + .. code:: + + typedef struct SECKEYPrivateKeyStr SECKEYPrivateKey; + + .. rubric:: Description + :name: description_3 + + Key structures are not shared objects. When an application makes a copy of a particular key + structure that already exists in memory, SSL makes a *deep* copy--that is, it makes a whole new + copy of that object. When you call ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__, the + function both frees the memory and sets all the bits to zero. + + Never alter the contents of a key structure. Treat the structure as read only. + + .. rubric:: SECStatus + :name: secstatus + + The return value for many SSL functions. + + .. rubric:: Syntax + :name: syntax_6 + + .. code:: + + #include <seccomon.h> + + .. code:: + + typedef enum { + SECWouldBlock = -2, + SECFailure = -1, + SECSuccess = 0 + } SECStatus; + + .. rubric:: Enumerators + :name: enumerators + + The enum includes the following enumerators: + + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | Reserved for internal use. | + | | | + | SECWouldBlock | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The operation failed. To find out why, call | + | | ``PR_GetError``. | + | SECFailure | | + +-------------------------------------------------+-------------------------------------------------+ + | .. code:: | The operation succeeded. In this case the value | + | | returned by ``PR_GetError`` is meaningless. | + | SECSuccess | | + +-------------------------------------------------+-------------------------------------------------+ + +.. _managing_secitem_memory: + +`Managing SECItem Memory <#managing_secitem_memory>`__ +------------------------------------------------------ + +.. container:: + + These functions are available for managing the memory associated with ``SECItem`` structures and + the structures to which they point. + + | ```SECItem_FreeItem`` <#1030620>`__ + | ```SECItem_ZfreeItem`` <#1030773>`__ + + .. rubric:: SECItem_FreeItem + :name: secitem_freeitem + + Frees the memory associated with a ``SECItem`` structure. + + .. rubric:: Syntax + :name: syntax_7 + + .. code:: + + #include <prtypes.h> + + .. code:: + + SECStatus SECItem_FreeItem ( + SECItem *item, + PRBool freeItem) + + .. rubric:: Parameter + :name: parameter + + This function has the following parameter: + + +----------+--------------------------------------------------------------------------------------+ + | ``item`` | A pointer to a ``SECItem`` structure. | + +----------+--------------------------------------------------------------------------------------+ + | freeItem | When ``PR_FALSE``, free only the structure pointed to. Otherwise, free both the | + | | structure pointed to and the ``SECItem`` structure itself. | + +----------+--------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + `PR_GetError <../../../../../nspr/reference/html/prerr.html#26127>`__ to retrieve the error + code. + + .. rubric:: Description + :name: description_4 + + This function frees the memory associated with the structure to which the specified item points, + when that structure is no longer used. When ``freeItem`` is not ``PR_FALSE``, also frees the item + structure itself. + + .. rubric:: SECItem_ZfreeItem + :name: secitem_zfreeitem + + Zeroes and frees the memory associated with a ``SECItem`` structure. + + .. rubric:: Syntax + :name: syntax_8 + + .. code:: + + #include <prtypes.h> + + .. code:: + + SECStatus SECItem_ZfreeItem ( + SECItem *item, + PRBool freeItem) + + .. rubric:: Parameter + :name: parameter_2 + + This function has the following parameter: + + +----------+--------------------------------------------------------------------------------------+ + | ``item`` | A pointer to a ``SECItem`` structure. | + +----------+--------------------------------------------------------------------------------------+ + | freeItem | When ``PR_FALSE``, free only the structure pointed to. Otherwise, free both the | + | | structure pointed to and the ``SECItem`` structure itself. | + +----------+--------------------------------------------------------------------------------------+ + + .. rubric:: Returns + :name: returns_2 + + The function returns one of these value\ ``s``: + + - If successful, ``SECSuccess``. + - If unsuccessful, ``SECFailure``. Use + `PR_GetError <../../../../../nspr/reference/html/prerr.html#26127>`__ to retrieve the error + code. + + .. rubric:: Description + :name: description_5 + + This function is similar to ```SECItem_FreeItem`` <#1030620>`__, except that it overwrites the + structures to be freed with zeroes before it frees them. Zeros and frees the memory associated + with the structure to which the specified item points, when that structure is no longer used. + When ``freeItem`` is not ``PR_FALSE``, also zeroes and frees the item structure itself.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst b/security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst new file mode 100644 index 0000000000..f9a3fc8515 --- /dev/null +++ b/security/nss/doc/rst/legacy/tls_cipher_suite_discovery/index.rst @@ -0,0 +1,114 @@ +.. _mozilla_projects_nss_tls_cipher_suite_discovery: + +TLS Cipher Suite Discovery +========================== + +.. container:: + + | + | In order to communicate securely, an TLS client and TLS server must agree on the cryptographic + algorithms and keys that they will both use on the secured connection. They must agree on these + items: + + - Key Establishment Algorithm (such as RSA, DH, or ECDH) + - Peer Authentication Algorithm (such as RSA, DSA, ECDSA) + - Bulk Data Encryption Algorithm (such as RC4, DES, AES) and key size + - Digest Algorithm for Message Authentication Checking (SHA1, SHA256) + + There are numerous available choices for each of those categories, and the number of possible + combinations of all those choices is large. TLS does not allow all possible combinations of + choices from those categories to be used. Instead, TLS allows only certain well-defined + combinations of those choices, known as Cipher Suites, defined in the IETF RFC standards. + + Each Cipher Suite is represented by a 16-bit number. The number of well-defined cipher suites + grows with time, and no TLS implementation offers all known cipher suites at all times. An + implementation that claimed to offer all defined Cipher Suites would only be able to make that + claim for a short time until another new Cipher Suite was defined. At any time, any real + implementation implements some subset of the complete set of well-defined cipher suites. + + Each new release of a TLS implementation may contain support for new Cipher Suites not supported + in previous versions. When a new version of a TLS Implementation is made available for use by + applications, those applications may wish to immediately use the newly supported Cipher Suites + found in the new version, without the application needing to be modified and re-released to know + about these new cipher suites. To that end, NSS's libSSL offers a way for applications to + discover at run time the set of Cipher Suites supported by that version of libSSL. libSSL + provides enough information about each of the supported cipher suites that the application can + construct a display of that information from which the user can choose which cipher suites his + application will attempt to use. + + Here are the details of how an NSS-based application learns what cipher suites are supported and + obtains the information to display to the user. + + libSSL offers a public table of well defined cipher suite numbers. The cipher suites are listed + in the table in order of preference, from the most preferred cipher suite to the least preferred. + The size of this table varies from release to release, and so libSSL makes the number of entries + in that table publicly available too. The table and the number of entries are declared in + "ssl.h", as follows: + + .. code:: + + /* constant table enumerating all implemented SSL 2 and 3 cipher suites. */ + SSL_IMPORT const PRUint16 SSL_ImplementedCiphers[]; + + /* number of entries in the above table. */ + SSL_IMPORT const PRUint16 SSL_NumImplementedCiphers; + + Of course, the raw integer numbers of the cipher suites are not likely to be known to most users, + so libSSL provides a function by which the application can obtain a wealth of information about + any supported cipher suite, by its number. This function is declared in "ssl.h" as follows: + + .. code:: + + SSL_IMPORT SECStatus + SSL_GetCipherSuiteInfo( + PRUint16 cipherSuite, + SSLCipherSuiteInfo *info, + PRUintn len); + + The application provides + + - the cipher suite number for which it wants information, + - the address of a block of memory allocated to receive that information, and + - the size in bytes of that block of memory. + + ``SSL_GetCipherSuiteInfo`` fills that caller-supplied memory with information from the + ``SSLCipherSuiteInfo`` structure for that cipher suite. The ``SSLCipherSuiteInfo`` structure + contains this information, declared in "sslt.h": + + .. code:: + + typedef struct SSLCipherSuiteInfoStr { + PRUint16 length; + PRUint16 cipherSuite; + + /* Cipher Suite Name */ + const char * cipherSuiteName; + + /* server authentication info */ + const char * authAlgorithmName; + SSLAuthType authAlgorithm; + + /* key exchange algorithm info */ + const char * keaTypeName; + SSLKEAType keaType; + + /* symmetric encryption info */ + const char * symCipherName; + SSLCipherAlgorithm symCipher; + PRUint16 symKeyBits; + PRUint16 symKeySpace; + PRUint16 effectiveKeyBits; + + /* MAC info */ + const char * macAlgorithmName; + SSLMACAlgorithm macAlgorithm; + PRUint16 macBits; + + PRUintn isFIPS : 1; + PRUintn isExportable : 1; + PRUintn nonStandard : 1; + PRUintn reservedBits :29; + + } SSLCipherSuiteInfo; + + (Unfinished, To be completed here)
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/certutil/index.rst b/security/nss/doc/rst/legacy/tools/certutil/index.rst new file mode 100644 index 0000000000..d7d943958e --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/certutil/index.rst @@ -0,0 +1,702 @@ +.. _mozilla_projects_nss_tools_certutil: + +certutil +======== + +.. container:: + + | Name + | certutil — Manage keys and certificate in the NSS database. + | Synopsis + | certutil [options] `arguments <arguments>`__ + | Description + | The Certificate Database Tool, certutil, is a command-line utility that + | can create and modify certificate and key database files. It can also + | list, generate, modify, or delete certificates within the database, create + | or change the password, generate new public and private key pairs, display + | the contents of the key database, or delete key pairs within the key + | database. + | The key and certificate management process generally begins with creating + | keys in the key database, then generating and managing certificates in the + | certificate database. This document discusses certificate and key database + | management. For information security module database management, see the + | modutil manpages. + | Options and Arguments + | Running certutil always requires one (and only one) option to specify the + | type of certificate operation. Each option may take arguments, anywhere + | from none to multiple arguments. Run the command option and -H to see the + | arguments available for each command option. + | Options + | Options specify an action and are uppercase. + | -A + | Add an existing certificate to a certificate database. The + | certificate database should already exist; if one is not present, + | this option will initialize one by default. + | -B + | Run a series of commands from the specified batch file. This + | requires the -i argument. + | -C + | Create a new binary certificate file from a binary certificate + | request file. Use the -i argument to specify the certificate + | request file. If this argument is not used, certutil prompts for a + | filename. + | -D + | Delete a certificate from the certificate database. + | -E + | Add an email certificate to the certificate database. + | -F + | Delete a private key from a key database. Specify the key to + | delete with the -n argument. Specify the database from which to + | delete the key with the -d argument. Use the -k argument to + | specify explicitly whether to delete a DSA, RSA, or ECC key. If + | you don't use the -k argument, the option looks for an RSA key + | matching the specified nickname. + | When you delete keys, be sure to also remove any certificates + | associated with those keys from the certificate database, by using + | -D. Some smart cards (for example, the Litronic card) do not let + | you remove a public key you have generated. In such a case, only + | the private key is deleted from the key pair. You can display the + | public key with the command certutil -K -h tokenname. + | -G + | Generate a new public and private key pair within a key database. + | The key database should already exist; if one is not present, this + | option will initialize one by default. Some smart cards (for + | example, the Litronic card) can store only one key pair. If you + | create a new key pair for such a card, the previous pair is + | overwritten. + | -H + | Display a list of the options and arguments used by the + | Certificate Database Tool. + | -K + | List the key ID of keys in the key database. A key ID is the + | modulus of the RSA key or the publicValue of the DSA key. IDs are + | displayed in hexadecimal ("0x" is not shown). + | -L + | List all the certificates, or display information about a named + | certificate, in a certificate database. Use the -h tokenname + | argument to specify the certificate database on a particular + | hardware or software token. + | -M + | Modify a certificate's trust attributes using the values of the -t + | argument. + | -N + | Create new certificate and key databases. + | -O + | Print the certificate chain. + | -R + | Create a certificate request file that can be submitted to a + | Certificate Authority (CA) for processing into a finished + | certificate. Output defaults to standard out unless you use -o + | output-file argument. Use the -a argument to specify ASCII output. + | -S + | Create an individual certificate and add it to a certificate + | database. + | -T + | Reset the key database or token. + | -U + | List all available modules or print a single named module. + | -V + | Check the validity of a certificate and its attributes. + | -W + | Change the password to a key database. + | --merge + | Merge a source database into the target database. This is used to + | merge legacy NSS databases (cert8.db and key3.db) into the newer + | SQLite databases (cert9.db and key4.db). + | --upgrade-merge + | Upgrade an old database and merge it into a new database. This is + | used to migrate legacy NSS databases (cert8.db and key3.db) into + | the newer SQLite databases (cert9.db and key4.db). + | Arguments + | Option arguments modify an action and are lowercase. + | -a + | Use ASCII format or allow the use of ASCII format for input or + | output. This formatting follows RFC 1113. For certificate + | requests, ASCII output defaults to standard output unless + | redirected. + | -b validity-time + | Specify a time at which a certificate is required to be valid. Use + | when checking certificate validity with the -V option. The format + | of the validity-time argument is YYMMDDHHMMSS[+HHMM|-HHMM|Z], + | which allows offsets to be set relative to the validity end time. + | Specifying seconds (SS) is optional. When specifying an explicit + | time, use a Z at the end of the term, YYMMDDHHMMSSZ, to close it. + | When specifying an offset time, use YYMMDDHHMMSS+HHMM or + | YYMMDDHHMMSS-HHMM for adding or subtracting time, respectively. + | If this option is not used, the validity check defaults to the + | current system time. + | -c issuer + | Identify the certificate of the CA from which a new certificate + | will derive its authenticity. Use the exact nickname or alias of + | the CA certificate, or use the CA's email address. Bracket the + | issuer string with quotation marks if it contains spaces. + | -d [sql:]directory + | Specify the database directory containing the certificate and key + | database files. + | certutil supports two types of databases: the legacy security + | databases (cert8.db, key3.db, and secmod.db) and new SQLite + | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | -e + | Check a certificate's signature during the process of validating a + | certificate. + | -f password-file + | Specify a file that will automatically supply the password to + | include in a certificate or to access a certificate database. This + | is a plain-text file containing one password. Be sure to prevent + | unauthorized access to this file. + | -g keysize + | Set a key size to use when generating new public and private key + | pairs. The minimum is 512 bits and the maximum is 8192 bits. The + | default is 1024 bits. Any size between the minimum and maximum is + | allowed. + | -h tokenname + | Specify the name of a token to use or act on. Unless specified + | otherwise the default token is an internal slot (specifically, + | internal slot 2). This slot can also be explicitly named with the + | string "internal". An internal slots is a virtual slot maintained + | in software, rather than a hardware device. Internal slot 2 is + | used by key and certificate services. Internal slot 1 is used by + | cryptographic services. + | -i input_file + | Pass an input file to the command. Depending on the command + | option, an input file can be a specific certificate, a certificate + | request file, or a batch file of commands. + | -k rsa|dsa|ec|all + | Specify the type of a key. The valid options are RSA, DSA, ECC, or + | all. The default value is rsa. Specifying the type of key can + | avoid mistakes caused by duplicate nicknames. + | -k key-type-or-id + | Specify the type or specific ID of a key. Giving a key type + | generates a new key pair; giving the ID of an existing key reuses + | that key pair (which is required to renew certificates). + | -l + | Display detailed information when validating a certificate with + | the -V option. + | -m serial-number + | Assign a unique serial number to a certificate being created. This + | operation should be performed by a CA. The default serial number + | is 0 (zero). Serial numbers are limited to integers. + | -n nickname + | Specify the nickname of a certificate or key to list, create, add + | to a database, modify, or validate. Bracket the nickname string + | with quotation marks if it contains spaces. + | -o output-file + | Specify the output file name for new certificates or binary + | certificate requests. Bracket the output-file string with + | quotation marks if it contains spaces. If this argument is not + | used the output destination defaults to standard output. + | -P dbPrefix + | Specify the prefix used on the certificate and key database file. + | This option is provided as a special case. Changing the names of + | the certificate and key databases is not recommended. + | -p phone + | Specify a contact telephone number to include in new certificates + | or certificate requests. Bracket this string with quotation marks + | if it contains spaces. + | -q pqgfile + | Read an alternate PQG value from the specified file when + | generating DSA key pairs. If this argument is not used, certutil + | generates its own PQG value. PQG files are created with a separate + | DSA utility. + | -q curve-name + | Set the elliptic curve name to use when generating ECC key pairs. + | A complete list of ECC curves is given in the help (-H). + | -r + | Display a certificate's binary DER encoding when listing + | information about that certificate with the -L option. + | -s subject + | Identify a particular certificate owner for new certificates or + | certificate requests. Bracket this string with quotation marks if + | it contains spaces. The subject identification format follows RFC + | #1485. + | -t trustargs + | Specify the trust attributes to modify in an existing certificate + | or to apply to a certificate when creating it or adding it to a + | database. There are three available trust categories for each + | certificate, expressed in the order SSL, email, object signing for + | each trust setting. In each category position, use none, any, or + | all of the attribute codes: + | o p - Valid peer + | o P - Trusted peer (implies p) + | o c - Valid CA + | o T - Trusted CA to issue client certificates (implies c) + | o C - Trusted CA to issue server certificates (SSL only) + | (implies c) + | o u - Certificate can be used for authentication or signing + | o w - Send warning (use with other attributes to include a + | warning when the certificate is used in that context) + | The attribute codes for the categories are separated by commas, + | and the entire set of attributes enclosed by quotation marks. For + | example: + | -t "TCu,Cu,Tuw" + | Use the -L option to see a list of the current certificates and + | trust attributes in a certificate database. + | -u certusage + | Specify a usage context to apply when validating a certificate + | with the -V option. + | The contexts are the following: + | o C (as an SSL client) + | o V (as an SSL server) + | o S (as an email signer) + | o R (as an email recipient) + | o O (as an OCSP status responder) + | o J (as an object signer) + | -v valid-months + | Set the number of months a new certificate will be valid. The + | validity period begins at the current system time unless an offset + | is added or subtracted with the -w option. If this argument is not + | used, the default validity period is three months. When this + | argument is used, the default three-month period is automatically + | added to any value given in the valid-month argument. For example, + | using this option to set a value of 3 would cause 3 to be added to + | the three-month default, creating a validity period of six months. + | You can use negative values to reduce the default period. For + | example, setting a value of -2 would subtract 2 from the default + | and create a validity period of one month. + | -w offset-months + | Set an offset from the current system time, in months, for the + | beginning of a certificate's validity period. Use when creating + | the certificate or adding it to a database. Express the offset in + | integers, using a minus sign (-) to indicate a negative offset. If + | this argument is not used, the validity period begins at the + | current system time. The length of the validity period is set with + | the -v argument. + | -X + | Force the key and certificate database to open in read-write mode. + | This is used with the -U and -L command options. + | -x + | Use certutil to generate the signature for a certificate being + | created or added to a database, rather than obtaining a signature + | from a separate CA. + | -y exp + | Set an alternate exponent value to use in generating a new RSA + | public key for the database, instead of the default value of + | 65537. The available alternate values are 3 and 17. + | -z noise-file + | Read a seed value from the specified file to generate a new + | private and public key pair. This argument makes it possible to + | use hardware-generated seed values or manually create a value from + | the keyboard. The minimum file size is 20 bytes. + | -0 SSO_password + | Set a site security officer password on a token. + | -1 \| --keyUsage keyword,keyword + | Set a Netscape Certificate Type Extension in the certificate. + | There are several available keywords: + | o digital signature + | o nonRepudiation + | o keyEncipherment + | o dataEncipherment + | o keyAgreement + | o certSigning + | o crlSigning + | o critical + | -2 + | Add a basic constraint extension to a certificate that is being + | created or added to a database. This extension supports the + | certificate chain verification process. certutil prompts for the + | certificate constraint extension to select. + | X.509 certificate extensions are described in RFC 5280. + | -3 + | Add an authority key ID extension to a certificate that is being + | created or added to a database. This extension supports the + | identification of a particular certificate, from among multiple + | certificates associated with one subject name, as the correct + | issuer of a certificate. The Certificate Database Tool will prompt + | you to select the authority key ID extension. + | X.509 certificate extensions are described in RFC 5280. + | -4 + | Add a CRL distribution point extension to a certificate that is + | being created or added to a database. This extension identifies + | the URL of a certificate's associated certificate revocation list + | (CRL). certutil prompts for the URL. + | X.509 certificate extensions are described in RFC 5280. + | -5 \| --nsCertType keyword,keyword + | Add a Netscape certificate type extension to a certificate that is + | being created or added to the database. There are several + | available keywords: + | o sslClient + | o sslServer + | o smime + | o objectSigning + | o sslCA + | o smimeCA + | o objectSigningCA + | o critical + | X.509 certificate extensions are described in RFC 5280. + | -6 \| --extKeyUsage keyword,keyword + | Add an extended key usage extension to a certificate that is being + | created or added to the database. Several keywords are available: + | o serverAuth + | o clientAuth + | o codeSigning + | o emailProtection + | o timeStamp + | o ocspResponder + | o stepUp + | o critical + | X.509 certificate extensions are described in RFC 5280. + | -7 emailAddrs + | Add a comma-separated list of email addresses to the subject + | alternative name extension of a certificate or certificate request + | that is being created or added to the database. Subject + | alternative name extensions are described in Section 4.2.1.7 of + | RFC 3280. + | -8 dns-names + | Add a comma-separated list of DNS names to the subject alternative + | name extension of a certificate or certificate request that is + | being created or added to the database. Subject alternative name + | extensions are described in Section 4.2.1.7 of RFC 3280. + | --extAIA + | Add the Authority Information Access extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extSIA + | Add the Subject Information Access extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extCP + | Add the Certificate Policies extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --extPM + | Add the Policy Mappings extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --extPC + | Add the Policy Constraints extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --extIA + | Add the Inhibit Any Policy Access extension to the certificate. + | X.509 certificate extensions are described in RFC 5280. + | --extSKID + | Add the Subject Key ID extension to the certificate. X.509 + | certificate extensions are described in RFC 5280. + | --source-dir certdir + | Identify the certificate database directory to upgrade. + | --source-prefix certdir + | Give the prefix of the certificate and key databases to upgrade. + | --upgrade-id uniqueID + | Give the unique ID of the database to upgrade. + | --upgrade-token-name name + | Set the name of the token to use while it is being upgraded. + | -@ pwfile + | Give the name of a password file to use for the database being + | upgraded. + | Usage and Examples + | Most of the command options in the examples listed here have more + | arguments available. The arguments included in these examples are the most + | common ones or are used to illustrate a specific scenario. Use the -H + | option to show the complete list of arguments for each command option. + | Creating New Security Databases + | Certificates, keys, and security modules related to managing certificates + | are stored in three related databases: + | o cert8.db or cert9.db + | o key3.db or key4.db + | o secmod.db or pkcs11.txt + | These databases must be created before certificates or keys can be + | generated. + | certutil -N -d [sql:]directory + | Creating a Certificate Request + | A certificate request contains most or all of the information that is used + | to generate the final certificate. This request is submitted separately to + | a certificate authority and is then approved by some mechanism + | (automatically or by human review). Once the request is approved, then the + | certificate is generated. + | $ certutil -R -k key-type-or-id [-q pqgfile|curve-name] -g key-size -s subject [-h tokenname] + -d [sql:]directory [-p phone] [-o output-file] [-a] + | The -R command options requires four arguments: + | o -k to specify either the key type to generate or, when renewing a + | certificate, the existing key pair to use + | o -g to set the keysize of the key to generate + | o -s to set the subject name of the certificate + | o -d to give the security database directory + | The new certificate request can be output in ASCII format (-a) or can be + | written to a specified file (-o). + | For example: + | $ certutil -R -k ec -q nistb409 -g 512 -s "CN=John Smith,O=Example Corp,L=Mountain + View,ST=California,C=US" -d sql:/home/my/sharednssdb -p 650-555-0123 -a -o cert.cer + | Generating key. This may take a few moments... + | Certificate request generated by Netscape + | Phone: 650-555-0123 + | Common Name: John Smith + | Email: (not ed) + | Organization: Example Corp + | State: California + | Country: US + | -----BEGIN NEW CERTIFICATE REQUEST----- + | MIIBIDCBywIBADBmMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEW + | MBQGA1UEBxMNTW91bnRhaW4gVmlldzEVMBMGA1UEChMMRXhhbXBsZSBDb3JwMRMw + | EQYDVQQDEwpKb2huIFNtaXRoMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAMVUpDOZ + | KmHnOx7reP8Cc0Lk+fFWEuYIDX9W5K/BioQOKvEjXyQZhit9aThzBVMoSf1Y1S8J + | CzdUbCg1+IbnXaECAwEAAaAAMA0GCSqGSIb3DQEBBQUAA0EAryqZvpYrUtQ486Ny + | qmtyQNjIi1F8c1Z+TL4uFYlMg8z6LG/J/u1E5t1QqB5e9Q4+BhRbrQjRR1JZx3tB + | 1hP9Gg== + | -----END NEW CERTIFICATE REQUEST----- + | Creating a Certificate + | A valid certificate must be issued by a trusted CA. This can be done by + | specifying a CA certificate (-c) that is stored in the certificate + | database. If a CA key pair is not available, you can create a self-signed + | certificate using the -x argument with the -S command option. + | $ certutil -S -k rsa|dsa|ec -n certname -s subject [-c issuer \|-x] -t trustargs -d + [sql:]directory [-m serial-number] [-v valid-months] [-w offset-months] [-p phone] [-1] [-2] + [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names] [--extAIA] [--extSIA] + [--extCP] [--extPM] [--extPC] [--extIA] [--extSKID] + | The series of numbers and --ext\* options set certificate extensions that + | can be added to the certificate when it is generated by the CA. + | For example, this creates a self-signed certificate: + | $ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m 3650 + | From there, new certificates can reference the self-signed certificate: + | $ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t "u,u,u" -1 -5 -6 -8 + -m 730 + | Generating a Certificate from a Certificate Request + | When a certificate request is created, a certificate can be generated by + | using the request and then referencing a certificate authority signing + | certificate (the issuer specified in the -c argument). The issuing + | certificate must be in the certificate database in the specified + | directory. + | certutil -C -c issuer -i cert-request-file -o output-file [-m serial-number] [-v valid-months] + [-w offset-months] -d [sql:]directory [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 + emailAddress] [-8 dns-names] + | For example: + | $ certutil -C -c "my-ca-cert" -i /home/certs/cert.req -o cert.cer -m 010 -v 12 -w 1 -d + sql:/home/my/sharednssdb -1 nonRepudiation,dataEncipherment -5 sslClient -6 clientAuth -7 + jsmith@example.com + | Generating Key Pairs + | Key pairs are generated automatically with a certificate request or + | certificate, but they can also be generated independently using the -G + | command option. + | certutil -G -d [sql:]directory \| -h tokenname -k key-type -g key-size [-y exponent-value] -q + pqgfile|curve-name + | For example: + | $ certutil -G -h lunasa -k ec -g 256 -q sect193r2 + | Listing Certificates + | The -L command option lists all of the certificates listed in the + | certificate database. The path to the directory (-d) is required. + | $ certutil -L -d sql:/home/my/sharednssdb + | Certificate Nickname Trust Attributes + | SSL,S/MIME,JAR/XPI + | CA Administrator of Instance pki-ca1's Example Domain ID u,u,u + | TPS Administrator's Example Domain ID u,u,u + | Google Internet Authority ,, + | Certificate Authority - Example Domain CT,C,C + | Using additional arguments with -L can return and print the information + | for a single, specific certificate. For example, the -n argument passes + | the certificate name, while the -a argument prints the certificate in + | ASCII format: + | $ certutil -L -d sql:/home/my/sharednssdb -a -n "Certificate Authority - Example Domain" + | -----BEGIN CERTIFICATE----- + | MIIDmTCCAoGgAwIBAgIBATANBgkqhkiG9w0BAQUFADA5MRcwFQYDVQQKEw5FeGFt + | cGxlIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTEw + | MDQyOTIxNTY1OFoXDTEyMDQxODIxNTY1OFowOTEXMBUGA1UEChMORXhhbXBsZSBE + | b21haW4xHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTCCASIwDQYJKoZI + | hvcNAQEBBQADggEPADCCAQoCggEBAO/bqUli2KwqXFKmMMG93KN1SANzNTXA/Vlf + | Tmrih3hQgjvR1ktIY9aG6cB7DSKWmtHp/+p4PUCMqL4ZrSGt901qxkePyZ2dYmM2 + | RnelK+SEUIPiUtoZaDhNdiYsE/yuDE8vQWj0vHCVL0w72qFUcSQ/WZT7FCrnUIUI + | udeWnoPSUn70gLhcj/lvxl7K9BHyD4Sq5CzktwYtFWLiiwV+ZY/Fl6JgbGaQyQB2 + | bP4iRMfloGqsxGuB1evWVDF1haGpFDSPgMnEPSLg3/3dXn+HDJbZ29EU8/xKzQEb + | 3V0AHKbu80zGllLEt2Zx/WDIrgJEN9yMfgKFpcmL+BvIRsmh0VsCAwEAAaOBqzCB + | qDAfBgNVHSMEGDAWgBQATgxHQyRUfKIZtdp55bZlFr+tFzAPBgNVHRMBAf8EBTAD + | AQH/MA4GA1UdDwEB/wQEAwIBxjAdBgNVHQ4EFgQUAE4MR0MkVHyiGbXaeeW2ZRa/ + | rRcwRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vbG9jYWxob3N0 + | LmxvY2FsZG9tYWluOjkxODAvY2Evb2NzcDANBgkqhkiG9w0BAQUFAAOCAQEAi8Gk + | L3XO43u7/TDOeEsWPmq+jZsDZ3GZ85Ajt3KROLWeKVZZZa2E2Hnsvf2uXbk5amKe + | lRxdSeRH9g85pv4KY7Z8xZ71NrI3+K3uwmnqkc6t0hhYb1mw/gx8OAAoluQx3biX + | JBDxjI73Cf7XUopplHBjjiwyGIJUO8BEZJ5L+TF4P38MJz1snLtzZpEAX5bl0U76 + | bfu/tZFWBbE8YAWYtkCtMcalBPj6jn2WD3M01kGozW4mmbvsj1cRB9HnsGsqyHCu + | U0ujlL1H/RWcjn607+CTeKH9jLMUqCIqPJNOa+kq/6F7NhNRRiuzASIbZc30BZ5a + | nI7q5n1USM3eWQlVXw== + | -----END CERTIFICATE----- + | Listing Keys + | Keys are the original material used to encrypt certificate data. The keys + | generated for certificates are stored separately, in the key database. + | To list all keys in the database, use the -K command option and the + | (required) -d argument to give the path to the directory. + | $ certutil -K -d sql:/home/my/sharednssdb + | certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate + Services " + | < 0> rsa 455a6673bde9375c2887ec8bf8016b3f9f35861d Thawte Freemail Member's Thawte + Consulting (Pty) Ltd. ID + | < 1> rsa 40defeeb522ade11090eacebaaf1196a172127df Example Domain Administrator Cert + | < 2> rsa 1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5 John Smith user cert + | There are ways to narrow the keys listed in the search results: + | o To return a specific key, use the -n name argument with the name of + | the key. + | o If there are multiple security devices loaded, then the -h tokenname + | argument can search a specific token or all tokens. + | o If there are multiple key types available, then the -k key-type + | argument can search a specific type of key, like RSA, DSA, or ECC. + | Listing Security Modules + | The devices that can be used to store certificates -- both internal + | databases and external devices like smart cards -- are recognized and used + | by loading security modules. The -U command option lists all of the + | security modules listed in the secmod.db database. The path to the + | directory (-d) is required. + | $ certutil -U -d sql:/home/my/sharednssdb + | slot: NSS User Private Key and Certificate Services + | token: NSS Certificate DB + | slot: NSS Internal Cryptographic Services + | token: NSS Generic Crypto Services + | Adding Certificates to the Database + | Existing certificates or certificate requests can be added manually to the + | certificate database, even if they were generated elsewhere. This uses the + | -A command option. + | certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-file] + | For example: + | $ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/sharednssdb -i + /home/example-certs/cert.cer + | A related command option, -E, is used specifically to add email + | certificates to the certificate database. The -E command has the same + | arguments as the -A command. The trust arguments for certificates have the + | format SSL,S/MIME,Code-signing, so the middle trust settings relate most + | to email certificates (though the others can be set). For example: + | $ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d sql:/home/my/sharednssdb -i + /home/example-certs/email.cer + | Deleting Certificates to the Database + | Certificates can be deleted from a database using the -D option. The only + | required options are to give the security database directory and to + | identify the certificate nickname. + | certutil -D -d [sql:]directory -n "nickname" + | For example: + | $ certutil -D -d sql:/home/my/sharednssdb -n "my-ssl-cert" + | Validating Certificates + | A certificate contains an expiration date in itself, and expired + | certificates are easily rejected. However, certificates can also be + | revoked before they hit their expiration date. Checking whether a + | certificate has been revoked requires validating the certificate. + | Validation can also be used to ensure that the certificate is only used + | for the purposes it was initially issued for. Validation is carried out by + | the -V command option. + | certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d [sql:]directory + | For example, to validate an email certificate: + | $ certutil -V -n "John Smith's Email Cert" -e -u S,R -d sql:/home/my/sharednssdb + | Modifying Certificate Trust Settings + | The trust settings (which relate to the operations that a certificate is + | allowed to be used for) can be changed after a certificate is created or + | added to the database. This is especially useful for CA certificates, but + | it can be performed for any type of certificate. + | certutil -M -n certificate-name -t trust-args -d [sql:]directory + | For example: + | $ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CTu,CTu,CTu" + | Printing the Certificate Chain + | Certificates can be issued in chains because every certificate authority + | itself has a certificate; when a CA issues a certificate, it essentially + | stamps that certificate with its own fingerprint. The -O prints the full + | chain of a certificate, going from the initial CA (the root CA) through + | ever intermediary CA to the actual certificate. For example, for an email + | certificate with two CAs in the chain: + | $ certutil -d sql:/home/my/sharednssdb -O -n "jsmith@example.com" + | "Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@thawte.com,CN=Thawte + Personal Freemail CA,OU=Certification Services Division,O=Thawte Consulting,L=Cape + Town,ST=Western Cape,C=ZA] + | "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte Personal Freemail + Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA] + | "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member] + | Resetting a Token + | The device which stores certificates -- both external hardware devices and + | internal software databases -- can be blanked and reused. This operation + | is performed on the device which stores the data, not directly on the + | security databases, so the location must be referenced through the token + | name (-h) as well as any directory path. If there is no external token + | used, the default value is internal. + | certutil -T -d [sql:]directory -h token-name -0 security-officer-password + | Many networks have dedicated personnel who handle changes to security + | tokens (the security officer). This person must supply the password to + | access the specified token. For example: + | $ certutil -T -d sql:/home/my/sharednssdb -h nethsm -0 secret + | Upgrading or Merging the Security Databases + | Many networks or applications may be using older BerkeleyDB versions of + | the certificate database (cert8.db). Databases can be upgraded to the new + | SQLite version of the database (cert9.db) using the --upgrade-merge + | command option or existing databases can be merged with the new cert9.db + | databases using the ---merge command. + | The --upgrade-merge command must give information about the original + | database and then use the standard arguments (like -d) to give the + | information about the new databases. The command also requires information + | that the tool uses for the process to upgrade and write over the original + | database. + | certutil --upgrade-merge -d [sql:]directory [-P dbprefix] --source-dir directory + --source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ password-file] + | For example: + | $ certutil --upgrade-merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ + --source-prefix serverapp- --upgrade-id 1 --upgrade-token-name internal + | The --merge command only requires information about the location of the + | original database; since it doesn't change the format of the database, it + | can write over information without performing interim step. + | certutil --merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix + dbprefix [-@ password-file] + | For example: + | $ certutil --merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ --source-prefix + serverapp- + | Running certutil Commands from a Batch File + | A series of commands can be run sequentially from a text file with the -B + | command option. The only argument for this specifies the input file. + | $ certutil -B -i /path/to/batch-file + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | BerkeleyDB has performance limitations, though, which prevent it from + | being easily used by multiple applications simultaneously. NSS has some + | flexibility that allows applications to use their own, independent + | database engine while keeping a shared database and working around the + | access issues. Still, NSS requires more flexibility to provide a truly + | shared security database. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | $ certutil -L -d sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | Most applications do not use the shared database by default, but they can + | be configured to use them. For example, this how-to article covers how to + | configure Firefox and Thunderbird to use the new shared NSS databases: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | pk12util (1) + | modutil (1) + | certutil has arguments or operations that use features defined in several + | IETF RFCs. + | o `http://tools.ietf.org/html/rfc5280 <https://datatracker.ietf.org/doc/html/rfc5280>`__ + | o `http://tools.ietf.org/html/rfc1113 <https://datatracker.ietf.org/doc/html/rfc1113>`__ + | o `http://tools.ietf.org/html/rfc1485 <https://datatracker.ietf.org/doc/html/rfc1485>`__ + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/cmsutil/index.rst b/security/nss/doc/rst/legacy/tools/cmsutil/index.rst new file mode 100644 index 0000000000..1a56ff4713 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/cmsutil/index.rst @@ -0,0 +1,111 @@ +.. _mozilla_projects_nss_tools_cmsutil: + +NSS tools : cmsutil +=================== + +.. container:: + + | Name + | cmsutil — Performs basic cryptograpic operations, such as encryption and + | decryption, on Cryptographic Message Syntax (CMS) messages. + | Synopsis + | cmsutil [options] `arguments <arguments>`__ + | Description + | The cmsutil command-line uses the S/MIME Toolkit to perform basic + | operations, such as encryption and decryption, on Cryptographic Message + | Syntax (CMS) messages. + | To run cmsutil, type the command cmsutil option [arguments] where option + | and arguments are combinations of the options and arguments listed in the + | following section. Each command takes one option. Each option may take + | zero or more arguments. To see a usage string, issue the command without + | options. + | Options and Arguments + | Options + | Options specify an action. Option arguments modify an action. The options + | and arguments for the cmsutil command are defined as follows: + | -D + | Decode a message. + | -C + | Encrypt a message. + | -E + | Envelope a message. + | -O + | Create a certificates-only message. + | -S + | Sign a message. + | Arguments + | Option arguments modify an action and are lowercase. + | -c content + | Use this detached content (decode only). + | -d dbdir + | Specify the key/certificate database directory (default is ".") + | -e envfile + | Specify a file containing an enveloped message for a set of + | recipients to which you would like to send an encrypted message. + | If this is the first encrypted message for that set of recipients, + | a new enveloped message will be created that you can then use for + | future messages (encrypt only). + | -G + | Include a signing time attribute (sign only). + | -h num + | Generate email headers with info about CMS message (decode only). + | -i infile + | Use infile as a source of data (default is stdin). + | -N nickname + | Specify nickname of certificate to sign with (sign only). + | -n + | Suppress output of contents (decode only). + | -o outfile + | Use outfile as a destination of data (default is stdout). + | -P + | Include an S/MIME capabilities attribute. + | -p password + | Use password as key database password. + | -r recipient1,recipient2, ... + | Specify list of recipients (email addresses) for an encrypted or + | enveloped message. For certificates-only message, list of + | certificates to send. + | -T + | Suppress content in CMS message (sign only). + | -u certusage + | Set type of cert usage (default is certUsageEmailSigner). + | -Y ekprefnick + | Specify an encryption key preference by nickname. + | Usage + | Encrypt Example + | cmsutil -C [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, . . ." + -e envfile + | Decode Example + | cmsutil -D [-i infile] [-o outfile] [-d dbdir] [-p password] [-c content] [-n] [-h num] + | Envelope Example + | cmsutil -E [-i infile] [-o outfile] [-d dbdir] [-p password] -r "recipient1,recipient2, ..." + | Certificate-only Example + | cmsutil -O [-i infile] [-o outfile] [-d dbdir] [-p password] -r "cert1,cert2, . . ." + | Sign Message Example + | cmsutil -S [-i infile] [-o outfile] [-d dbdir] [-p password] -N nickname[-TGP] [-Y ekprefnick] + | See also + | certutil(1) + | See Also + | Additional Resources + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [1]\ http://pki.fedoraproject.org/wiki/. + | For information specifically about NSS, the NSS project wiki is located at + | + [2]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. http://pki.fedoraproject.org/wiki/ + | 2. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/crlutil/index.rst b/security/nss/doc/rst/legacy/tools/crlutil/index.rst new file mode 100644 index 0000000000..ee68b4dbfb --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/crlutil/index.rst @@ -0,0 +1,229 @@ +.. _mozilla_projects_nss_tools_crlutil: + +NSS tools : crlutil +=================== + +.. container:: + + | Name + | crlutil — List, generate, modify, or delete CRLs within the NSS security + | database file(s) and list, create, modify or delete certificates entries + | in a particular CRL. + | Synopsis + | crlutil [options] `arguments <arguments>`__ + | Description + | The Certificate Revocation List (CRL) Management Tool, crlutil, is a + | command-line utility that can list, generate, modify, or delete CRLs + | within the NSS security database file(s) and list, create, modify or + | delete certificates entries in a particular CRL. + | The key and certificate management process generally begins with creating + | keys in the key database, then generating and managing certificates in the + | certificate database(see certutil tool) and continues with certificates + | expiration or revocation. + | This document discusses certificate revocation list management. For + | information on security module database management, see Using the Security + | Module Database Tool. For information on certificate and key database + | management, see Using the Certificate Database Tool. + | To run the Certificate Revocation List Management Tool, type the command + | crlutil option [arguments] + | where options and arguments are combinations of the options and arguments + | listed in the following section. Each command takes one option. Each + | option may take zero or more arguments. To see a usage string, issue the + | command without options, or with the -H option. + | Options and Arguments + | Options + | Options specify an action. Option arguments modify an action. The options + | and arguments for the crlutil command are defined as follows: + | -G + | Create new Certificate Revocation List(CRL). + | -D + | Delete Certificate Revocation List from cert database. + | -I + | Import a CRL to the cert database + | -E + | Erase all CRLs of specified type from the cert database + | -L + | List existing CRL located in cert database file. + | -M + | Modify existing CRL which can be located in cert db or in + | arbitrary file. If located in file it should be encoded in ASN.1 + | encode format. + | -G + | Arguments + | Option arguments modify an action and are lowercase. + | -B + | Bypass CA signature checks. + | -P dbprefix + | Specify the prefix used on the NSS security database files (for + | example, my_cert8.db and my_key3.db). This option is provided as a + | special case. Changing the names of the certificate and key + | databases is not recommended. + | -a + | Use ASCII format or allow the use of ASCII format for input and + | output. This formatting follows RFC #1113. + | -c crl-gen-file + | Specify script file that will be used to control crl + | generation/modification. See crl-cript-file format below. If + | options -M|-G is used and -c crl-script-file is not specified, + | crlutil will read script data from standard input. + | -d directory + | Specify the database directory containing the certificate and key + | database files. On Unix the Certificate Database Tool defaults to + | $HOME/.netscape (that is, ~/.netscape). On Windows NT the default + | is the current directory. + | The NSS database files must reside in the same directory. + | -i crl-import-file + | Specify the file which contains the CRL to import + | -f password-file + | Specify a file that will automatically supply the password to + | include in a certificate or to access a certificate database. This + | is a plain-text file containing one password. Be sure to prevent + | unauthorized access to this file. + | -l algorithm-name + | Specify a specific signature algorithm. List of possible + | algorithms: MD2 \| MD4 \| MD5 \| SHA1 \| SHA256 \| SHA384 \| SHA512 + | -n nickname + | Specify the nickname of a certificate or key to list, create, add + | to a database, modify, or validate. Bracket the nickname string + | with quotation marks if it contains spaces. + | -o output-file + | Specify the output file name for new CRL. Bracket the output-file + | string with quotation marks if it contains spaces. If this + | argument is not used the output destination defaults to standard + | output. + | -t crl-type + | Specify type of CRL. possible types are: 0 - SEC_KRL_TYPE, 1 - + | SEC_CRL_TYPE. This option is obsolete + | -u url + | Specify the url. + | CRL Generation script syntax + | CRL generation script file has the following syntax: + | \* Line with comments should have # as a first symbol of a line + | \* Set "this update" or "next update" CRL fields: + | update=YYYYMMDDhhmmssZ nextupdate=YYYYMMDDhhmmssZ + | Field "next update" is optional. Time should be in GeneralizedTime format + | (YYYYMMDDhhmmssZ). For example: 20050204153000Z + | \* Add an extension to a CRL or a crl certificate entry: + | addext extension-name critical/non-critical [arg1[arg2 ...]] + | Where: + | extension-name: string value of a name of known extensions. + | critical/non-critical: is 1 when extension is critical and 0 otherwise. + | arg1, arg2: specific to extension type extension parameters + | addext uses the range that was set earlier by addcert and will install an + | extension to every cert entries within the range. + | \* Add certificate entries(s) to CRL: + | addcert range date + | range: two integer values separated by dash: range of certificates that + | will be added by this command. dash is used as a delimiter. Only one cert + | will be added if there is no delimiter. date: revocation date of a cert. + | Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ). + | \* Remove certificate entry(s) from CRL + | rmcert range + | Where: + | range: two integer values separated by dash: range of certificates that + | will be added by this command. dash is used as a delimiter. Only one cert + | will be added if there is no delimiter. + | \* Change range of certificate entry(s) in CRL + | range new-range + | Where: + | new-range: two integer values separated by dash: range of certificates + | that will be added by this command. dash is used as a delimiter. Only one + | cert will be added if there is no delimiter. + | Implemented Extensions + | The extensions defined for CRL provide methods for associating additional + | attributes with CRLs of theirs entries. For more information see RFC #3280 + | \* Add The Authority Key Identifier extension: + | The authority key identifier extension provides a means of identifying the + | public key corresponding to the private key used to sign a CRL. + | authKeyId critical [key-id \| dn cert-serial] + | Where: + | authKeyIdent: identifies the name of an extension critical: value of 1 of + | 0. Should be set to 1 if this extension is critical or 0 otherwise. + | key-id: key identifier represented in octet string. dn:: is a CA + | distinguished name cert-serial: authority certificate serial number. + | \* Add Issuer Alternative Name extension: + | The issuer alternative names extension allows additional identities to be + | associated with the issuer of the CRL. Defined options include an rfc822 + | name (electronic mail address), a DNS name, an IP address, and a URI. + | issuerAltNames non-critical name-list + | Where: + | subjAltNames: identifies the name of an extension should be set to 0 since + | this is non-critical extension name-list: comma separated list of names + | \* Add CRL Number extension: + | The CRL number is a non-critical CRL extension which conveys a + | monotonically increasing sequence number for a given CRL scope and CRL + | issuer. This extension allows users to easily determine when a particular + | CRL supersedes another CRL + | crlNumber non-critical number + | Where: + | crlNumber: identifies the name of an extension critical: should be set to + | 0 since this is non-critical extension number: value of long which + | identifies the sequential number of a CRL. + | \* Add Revocation Reason Code extension: + | The reasonCode is a non-critical CRL entry extension that identifies the + | reason for the certificate revocation. + | reasonCode non-critical code + | Where: + | reasonCode: identifies the name of an extension non-critical: should be + | set to 0 since this is non-critical extension code: the following codes + | are available: + | unspecified (0), keyCompromise (1), cACompromise (2), affiliationChanged + | (3), superseded (4), cessationOfOperation (5), certificateHold (6), + | removeFromCRL (8), privilegeWithdrawn (9), aACompromise (10) + | \* Add Invalidity Date extension: + | The invalidity date is a non-critical CRL entry extension that provides + | the date on which it is known or suspected that the private key was + | compromised or that the certificate otherwise became invalid. + | invalidityDate non-critical date + | Where: + | crlNumber: identifies the name of an extension non-critical: should be set + | to 0 since this is non-critical extension date: invalidity date of a cert. + | Date should be represented in GeneralizedTime format (YYYYMMDDhhmmssZ). + | Usage + | The Certificate Revocation List Management Tool's capabilities are grouped + | as follows, using these combinations of options and arguments. Options and + | arguments in square brackets are optional, those without square brackets + | are required. + | See "Implemented extensions" for more information regarding extensions and + | their parameters. + | \* Creating or modifying a CRL: + | crlutil -G|-M -c crl-gen-file -n nickname [-i crl] [-u url] [-d keydir] [-P dbprefix] [-l alg] + [-a] [-B] + | \* Listing all CRls or a named CRL: + | crlutil -L [-n crl-name] [-d krydir] + | \* Deleting CRL from db: + | crlutil -D -n nickname [-d keydir] [-P dbprefix] + | \* Erasing CRLs from db: + | crlutil -E [-d keydir] [-P dbprefix] + | \* Deleting CRL from db: + | crlutil -D -n nickname [-d keydir] [-P dbprefix] + | \* Erasing CRLs from db: + | crlutil -E [-d keydir] [-P dbprefix] + | \* Import CRL from file: + | crlutil -I -i crl [-t crlType] [-u url] [-d keydir] [-P dbprefix] [-B] + | See also + | certutil(1) + | See Also + | Additional Resources + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [1]\ http://pki.fedoraproject.org/wiki/. + | For information specifically about NSS, the NSS project wiki is located at + | + [2]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. http://pki.fedoraproject.org/wiki/ + | 2. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/index.rst b/security/nss/doc/rst/legacy/tools/index.rst new file mode 100644 index 0000000000..ac7f743339 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/index.rst @@ -0,0 +1,125 @@ +.. _mozilla_projects_nss_tools: + +NSS Tools +========= + +.. _nss_security_tools: + +`NSS Security Tools <#nss_security_tools>`__ +-------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Overview <#overview>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The NSS Security Tools allow developers to test, debug, and manage applications that use NSS. The + `Tools Information <#tools>`__ table below describes both the tools that are currently working + and those that are still under development. The links for each tool take you to the source code, + documentation, plans, and related links for each tool. The links will become active when + information is available. + + Currently, you must download the NSS 3.1 source and build it to create binary files for the NSS + tools. For information about downloading the NSS source, see + :ref:`mozilla_projects_nss_building`. + + If you have feedback or questions, please feel free to post to + `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__. This newsgroup is + the preferred forum for all questions about NSS and NSS tools. + +.. _overall_objectives: + +`Overall Objectives <#overall_objectives>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Provide a tool for analyzing and repairing certificate databases (`dbck <#dbck>`__). + #. Migrate tools from secutil.h interface to PKCS #11 interface. + #. Eliminate redundant functionality in tools. Many tools implement private versions of + PKCS11Init(), OpenCertDB(), etc. + #. Eliminate use of getopt() and replace with NSPR calls to get command options (to eliminate + platform dependencies with getopt()). + +.. _tools_information: + +`Tools information <#tools_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + +--------------+-----------------------------------------+-----------------------------------------+ + | **Tool** | **Description** | **Links** | + +--------------+-----------------------------------------+-----------------------------------------+ + | certutil 2.0 | Manage certificate and key databases | ` | + | | (cert7.db and key3.db). | Source <https://dxr.mozilla.org/mozilla | + | | | /source/security/nss/cmd/certutil/>`__, | + | | | :ref | + | | | :`mozilla_projects_nss_tools_certutil`, | + | | | :ref:`moz | + | | | illa_projects_nss_tools_certutil-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | cmsutil 1.0 | Performs basic CMS operations such as | `So | + | | encrypting, decrypting, and signing | urce <https://dxr.mozilla.org/mozilla/s | + | | messages. | ource/security/nss/cmd/smimetools/>`__, | + | | | :r | + | | | ef:`mozilla_projects_nss_tools_cmsutil` | + +--------------+-----------------------------------------+-----------------------------------------+ + | crlutil | Manage certificate revocation lists | `Source <https://dxr.mozilla.org/mozill | + | | (CRLs). | a/source/security/nss/cmd/crlutil/>`__, | + | | | :re | + | | | f:`mozilla_projects_nss_tools_crlutil`, | + +--------------+-----------------------------------------+-----------------------------------------+ + | dbck 1.0 | Analyze and repair certificate | `Source <https://dxr.mozilla.org/moz | + | | databases (not working in NSS 3.2) | illa/source/security/nss/cmd/dbck/>`__, | + | | | :ref: | + | | | `mozilla_projects_nss_tools_dbck-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | modutil 1.1 | Manage the database of PKCS11 modules | `Source <https://dxr.mozilla.org/mozill | + | | (secmod.db). Add modules and modify the | a/source/security/nss/cmd/modutil/>`__, | + | | properties of existing modules (such as | :re | + | | whether a module is the default | f:`mozilla_projects_nss_tools_modutil`, | + | | provider of some crypto service). | :ref:`mo | + | | | zilla_projects_nss_tools_modutil-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | pk12util 1.0 | Import and export keys and certificates | ` | + | | between the cert/key databases and | Source <https://dxr.mozilla.org/mozilla | + | | files in PKCS12 format. | /source/security/nss/cmd/pk12util/>`__, | + | | | :ref | + | | | :`mozilla_projects_nss_tools_pk12util`, | + | | | :ref:`moz | + | | | illa_projects_nss_tools_pk12util-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | signtool 1.3 | Create digitally-signed jar archives | ` | + | | containing files and/or code. | Source <https://dxr.mozilla.org/mozilla | + | | | /source/security/nss/cmd/signtool/>`__, | + | | | `Do | + | | | cumentation <https://docs.oracle.com/ja | + | | | vase/8/docs/technotes/guides/security/S | + | | | ecurityToolsSummary.html#jarsigner>`__, | + +--------------+-----------------------------------------+-----------------------------------------+ + | signver 1.1 | Verify signatures on digitally-signed | `Source <https://dxr.mozilla.org/mozill | + | | objects. | a/source/security/nss/cmd/signver/>`__, | + | | | `Document | + | | | ation <https://docs.oracle.com/javase/t | + | | | utorial/deployment/jar/verify.html>`__, | + | | | :ref:`mo | + | | | zilla_projects_nss_tools_signver-tasks` | + +--------------+-----------------------------------------+-----------------------------------------+ + | sslstrength | SSL Strength | :ref:` | + | | | mozilla_projects_nss_tools_sslstrength` | + +--------------+-----------------------------------------+-----------------------------------------+ + | ssltap 3.2 | Proxy requests for an SSL server and | `Source <https://dxr.mozilla.org/mozil | + | | display the contents of the messages | la/source/security/nss/cmd/ssltap/>`__, | + | | exchanged between the client and | : | + | | server. The ssltap tool does not | ref:`mozilla_projects_nss_tools_ssltap` | + | | decrypt data, but it shows things like | | + | | the type of SSL message (clientHello, | | + | | serverHello, etc) and connection data | | + | | (protocol version, cipher suite, etc). | | + | | This tool is very useful for debugging. | | + +--------------+-----------------------------------------+-----------------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/modutil/index.rst b/security/nss/doc/rst/legacy/tools/modutil/index.rst new file mode 100644 index 0000000000..b3251735d6 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/modutil/index.rst @@ -0,0 +1,640 @@ +.. _mozilla_projects_nss_tools_modutil: + +NSS tools : modutil +=================== + +.. container:: + + | Name + | modutil — Manage PKCS #11 module information within the security module + | database. + | Synopsis + | modutil [options] `arguments <arguments>`__ + | Description + | The Security Module Database Tool, modutil, is a command-line utility for + | managing PKCS #11 module information both within secmod.db files and + | within hardware tokens. modutil can add and delete PKCS #11 modules, + | change passwords on security databases, set defaults, list module + | contents, enable or disable slots, enable or disable FIPS 140-2 + | compliance, and assign default providers for cryptographic operations. + | This tool can also create certificate, key, and module security database + | files. + | The tasks associated with security module database management are part of + | a process that typically also involves managing key databases and + | certificate databases. + | Options + | Running modutil always requires one (and only one) option to specify the + | type of module operation. Each option may take arguments, anywhere from + | none to multiple arguments. + | Options + | -add modulename + | Add the named PKCS #11 module to the database. Use this option + | with the -libfile, -ciphers, and -mechanisms arguments. + | -changepw tokenname + | Change the password on the named token. If the token has not been + | initialized, this option initializes the password. Use this option + | with the -pwfile and -newpwfile arguments. A password is + | equivalent to a personal identification number (PIN). + | -chkfips + | Verify whether the module is in the given FIPS mode. true means to + | verify that the module is in FIPS mode, while false means to + | verify that the module is not in FIPS mode. + | -create + | Create new certificate, key, and module databases. Use the -dbdir + | directory argument to specify a directory. If any of these + | databases already exist in a specified directory, modutil returns + | an error message. + | -default modulename + | Specify the security mechanisms for which the named module will be + | a default provider. The security mechanisms are specified with the + | -mechanisms argument. + | -delete modulename + | Delete the named module. The default NSS PKCS #11 module cannot be + | deleted. + | -disable modulename + | Disable all slots on the named module. Use the -slot argument to + | disable a specific slot. + | -enable modulename + | Enable all slots on the named module. Use the -slot argument to + | enable a specific slot. + | -fips [true \| false] + | Enable (true) or disable (false) FIPS 140-2 compliance for the + | default NSS module. + | -force + | Disable modutil's interactive prompts so it can be run from a + | script. Use this option only after manually testing each planned + | operation to check for warnings and to ensure that bypassing the + | prompts will cause no security lapses or loss of database + | integrity. + | -jar JAR-file + | Add a new PKCS #11 module to the database using the named JAR + | file. Use this command with the -installdir and -tempdir + | arguments. The JAR file uses the NSS PKCS #11 JAR format to + | identify all the files to be installed, the module's name, the + | mechanism flags, and the cipher flags, as well as any files to be + | installed on the target machine, including the PKCS #11 module + | library file and other files such as documentation. This is + | covered in the JAR installation file section in the man page, + | which details the special script needed to perform an installation + | through a server or with modutil. + | -list [modulename] + | Display basic information about the contents of the secmod.db + | file. Specifying a modulename displays detailed information about + | a particular module and its slots and tokens. + | -rawadd + | Add the module spec string to the secmod.db database. + | -rawlist + | Display the module specs for a specified module or for all + | loadable modules. + | -undefault modulename + | Specify the security mechanisms for which the named module will + | not be a default provider. The security mechanisms are specified + | with the -mechanisms argument. + | Arguments + | MODULE + | Give the security module to access. + | MODULESPEC + | Give the security module spec to load into the security database. + | -ciphers cipher-enable-list + | Enable specific ciphers in a module that is being added to the + | database. The cipher-enable-list is a colon-delimited list of + | cipher names. Enclose this list in quotation marks if it contains + | spaces. + | -dbdir [sql:]directory + | Specify the database directory in which to access or create + | security module database files. + | modutil supports two types of databases: the legacy security + | databases (cert8.db, key3.db, and secmod.db) and new SQLite + | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | --dbprefix prefix + | Specify the prefix used on the database files, such as my\_ for + | my_cert8.db. This option is provided as a special case. Changing + | the names of the certificate and key databases is not recommended. + | -installdir root-installation-directory + | Specify the root installation directory relative to which files + | will be installed by the -jar option. This directory should be one + | below which it is appropriate to store dynamic library files, such + | as a server's root directory. + | -libfile library-file + | Specify a path to a library file containing the implementation of + | the PKCS #11 interface module that is being added to the database. + | -mechanisms mechanism-list + | Specify the security mechanisms for which a particular module will + | be flagged as a default provider. The mechanism-list is a + | colon-delimited list of mechanism names. Enclose this list in + | quotation marks if it contains spaces. + | The module becomes a default provider for the listed mechanisms + | when those mechanisms are enabled. If more than one module claims + | to be a particular mechanism's default provider, that mechanism's + | default provider is undefined. + | modutil supports several mechanisms: RSA, DSA, RC2, RC4, RC5, AES, + | DES, DH, SHA1, SHA256, SHA512, SSL, TLS, MD5, MD2, RANDOM (for + | random number generation), and FRIENDLY (meaning certificates are + | publicly readable). + | -newpwfile new-password-file + | Specify a text file containing a token's new or replacement + | password so that a password can be entered automatically with the + | -changepw option. + | -nocertdb + | Do not open the certificate or key databases. This has several + | effects: + | o With the -create command, only a module security file is + | created; certificate and key databases are not created. + | o With the -jar command, signatures on the JAR file are not + | checked. + | o With the -changepw command, the password on the NSS internal + | module cannot be set or changed, since this password is + | stored in the key database. + | -pwfile old-password-file + | Specify a text file containing a token's existing password so that + | a password can be entered automatically when the -changepw option + | is used to change passwords. + | -secmod secmodname + | Give the name of the security module database (like secmod.db) to + | load. + | -slot slotname + | Specify a particular slot to be enabled or disabled with the + | -enable or -disable options. + | -string CONFIG_STRING + | Pass a configuration string for the module being added to the + | database. + | -tempdir temporary-directory + | Give a directory location where temporary files are created during + | the installation by the -jar option. If no temporary directory is + | specified, the current directory is used. + | Usage and Examples + | Creating Database Files + | Before any operations can be performed, there must be a set of security + | databases available. modutil can be used to create these files. The only + | required argument is the database that where the databases will be + | located. + | modutil -create -dbdir [sql:]directory + | Adding a Cryptographic Module + | Adding a PKCS #11 module means submitting a supporting library file, + | enabling its ciphers, and setting default provider status for various + | security mechanisms. This can be done by supplying all of the information + | through modutil directly or by running a JAR file and install script. For + | the most basic case, simply upload the library: + | modutil -add modulename -libfile library-file [-ciphers cipher-enable-list] [-mechanisms + mechanism-list] + | For example: + | modutil -dbdir sql:/home/my/sharednssdb -add "Example PKCS #11 Module" -libfile + "/tmp/crypto.so" -mechanisms RSA:DSA:RC2:RANDOM + | Using database directory ... + | Module "Example PKCS #11 Module" added to database. + | Installing a Cryptographic Module from a JAR File + | PKCS #11 modules can also be loaded using a JAR file, which contains all + | of the required libraries and an installation script that describes how to + | install the module. The JAR install script is described in more detail in + | [1]the section called “JAR Installation File Format”. + | The JAR installation script defines the setup information for each + | platform that the module can be installed on. For example: + | Platforms { + | Linux:5.4.08:x86 { + | ModuleName { "Example PKCS #11 Module" } + | ModuleFile { crypto.so } + | DefaultMechanismFlags{0x0000} + | CipherEnableFlags{0x0000} + | Files { + | crypto.so { + | Path{ /tmp/crypto.so } + | } + | setup.sh { + | Executable + | Path{ /tmp/setup.sh } + | } + | } + | } + | Linux:6.0.0:x86 { + | EquivalentPlatform { Linux:5.4.08:x86 } + | } + | } + | Both the install script and the required libraries must be bundled in a + | JAR file, which is specified with the -jar argument. + | modutil -dbdir sql:/home/mt"jar-install-filey/sharednssdb -jar install.jar -installdir + sql:/home/my/sharednssdb + | This installation JAR file was signed by: + | ---------------------------------------------- + | **SUBJECT NAME*\* + | C=US, ST=California, L=Mountain View, CN=Cryptorific Inc., OU=Digital ID + | Class 3 - Netscape Object Signing, OU="www.verisign.com/repository/CPS + | Incorp. by Ref.,LIAB.LTD(c)9 6", OU=www.verisign.com/CPS Incorp.by Ref + | . LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3 + | Organization, OU="VeriSign, Inc.", O=VeriSign Trust Network \**ISSUER + | NAME**, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 + | VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization, + | OU="VeriSign, Inc.", O=VeriSign Trust Network + | ---------------------------------------------- + | Do you wish to continue this installation? (y/n) y + | Using installer script "installer_script" + | Successfully parsed installation script + | Current platform is Linux:5.4.08:x86 + | Using installation parameters for platform Linux:5.4.08:x86 + | Installed file crypto.so to /tmp/crypto.so + | Installed file setup.sh to ./pk11inst.dir/setup.sh + | Executing "./pk11inst.dir/setup.sh"... + | "./pk11inst.dir/setup.sh" executed successfully + | Installed module "Example PKCS #11 Module" into module database + | Installation completed successfully + | Adding Module Spec + | Each module has information stored in the security database about its + | configuration and parameters. These can be added or edited using the + | -rawadd command. For the current settings or to see the format of the + | module spec in the database, use the -rawlist option. + | modutil -rawadd modulespec + | Deleting a Module + | A specific PKCS #11 module can be deleted from the secmod.db database: + | modutil -delete modulename -dbdir [sql:]directory + | Displaying Module Information + | The secmod.db database contains information about the PKCS #11 modules + | that are available to an application or server to use. The list of all + | modules, information about specific modules, and database configuration + | specs for modules can all be viewed. + | To simply get a list of modules in the database, use the -list command. + | modutil -list [modulename] -dbdir [sql:]directory + | Listing the modules shows the module name, their status, and other + | associated security databases for certificates and keys. For example: + | modutil -list -dbdir sql:/home/my/sharednssdb + | Listing of PKCS #11 Modules + | ----------------------------------------------------------- + | 1. NSS Internal PKCS #11 Module + | slots: 2 slots attached + | status: loaded + | slot: NSS Internal Cryptographic Services + | token: NSS Generic Crypto Services + | slot: NSS User Private Key and Certificate Services + | token: NSS Certificate DB + | ----------------------------------------------------------- + | Passing a specific module name with the -list returns details information + | about the module itself, like supported cipher mechanisms, version + | numbers, serial numbers, and other information about the module and the + | token it is loaded on. For example: + | modutil -list "NSS Internal PKCS #11 Module" -dbdir sql:/home/my/sharednssdb + | ----------------------------------------------------------- + | Name: NSS Internal PKCS #11 Module + | Library file: \**Internal ONLY module*\* + | Manufacturer: Mozilla Foundation + | Description: NSS Internal Crypto Services + | PKCS #11 Version 2.20 + | Library Version: 3.11 + | Cipher Enable Flags: None + | Default Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + | Slot: NSS Internal Cryptographic Services + | Slot Mechanism Flags: RSA:RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES + | Manufacturer: Mozilla Foundation + | Type: Software + | Version Number: 3.11 + | Firmware Version: 0.0 + | Status: Enabled + | Token Name: NSS Generic Crypto Services + | Token Manufacturer: Mozilla Foundation + | Token Model: NSS 3 + | Token Serial Number: 0000000000000000 + | Token Version: 4.0 + | Token Firmware Version: 0.0 + | Access: Write Protected + | Login Type: Public (no login required) + | User Pin: NOT Initialized + | Slot: NSS User Private Key and Certificate Services + | Slot Mechanism Flags: None + | Manufacturer: Mozilla Foundation + | Type: Software + | Version Number: 3.11 + | Firmware Version: 0.0 + | Status: Enabled + | Token Name: NSS Certificate DB + | Token Manufacturer: Mozilla Foundation + | Token Model: NSS 3 + | Token Serial Number: 0000000000000000 + | Token Version: 8.3 + | Token Firmware Version: 0.0 + | Access: NOT Write Protected + | Login Type: Login required + | User Pin: Initialized + | A related command, -rawlist returns information about the database + | configuration for the modules. (This information can be edited by loading + | new specs using the -rawadd command.) + | modutil -rawlist -dbdir sql:/home/my/sharednssdb + | name="NSS Internal PKCS #11 Module" parameters="configdir=. certPrefix= keyPrefix= + secmod=secmod.db flags=readOnly " NSS="trustOrder=75 cipherOrder=100 + slotParams={0x00000001=[slotFlags=RSA,RC4,RC2,DES,DH,SHA1,MD5,MD2,SSL,TLS,AES,RANDOM askpw=any + timeout=30 ] } Flags=internal,critical" + | Setting a Default Provider for Security Mechanisms + | Multiple security modules may provide support for the same security + | mechanisms. It is possible to set a specific security module as the + | default provider for a specific security mechanism (or, conversely, to + | prohibit a provider from supplying those mechanisms). + | modutil -default modulename -mechanisms mechanism-list + | To set a module as the default provider for mechanisms, use the -default + | command with a colon-separated list of mechanisms. The available + | mechanisms depend on the module; NSS supplies almost all common + | mechanisms. For example: + | modutil -default "NSS Internal PKCS #11 Module" -dbdir -mechanisms RSA:DSA:RC2 + | Using database directory c:\databases... + | Successfully changed defaults. + | Clearing the default provider has the same format: + | modutil -undefault "NSS Internal PKCS #11 Module" -dbdir -mechanisms MD2:MD5 + | Enabling and Disabling Modules and Slots + | Modules, and specific slots on modules, can be selectively enabled or + | disabled using modutil. Both commands have the same format: + | modutil -enable|-disable modulename [-slot slotname] + | For example: + | modutil -enable "NSS Internal PKCS #11 Module" -slot "NSS Internal Cryptographic + Services " -dbdir . + | Slot "NSS Internal Cryptographic Services " enabled. + | Be sure that the appropriate amount of trailing whitespace is after the + | slot name. Some slot names have a significant amount of whitespace that + | must be included, or the operation will fail. + | Enabling and Verifying FIPS Compliance + | The NSS modules can have FIPS 140-2 compliance enabled or disabled using + | modutil with the -fips option. For example: + | modutil -fips true -dbdir sql:/home/my/sharednssdb/ + | FIPS mode enabled. + | To verify that status of FIPS mode, run the -chkfips command with either a + | true or false flag (it doesn't matter which). The tool returns the current + | FIPS setting. + | modutil -chkfips false -dbdir sql:/home/my/sharednssdb/ + | FIPS mode enabled. + | Changing the Password on a Token + | Initializing or changing a token's password: + | modutil -changepw tokenname [-pwfile old-password-file] [-newpwfile new-password-file] + | modutil -dbdir sql:/home/my/sharednssdb -changepw "NSS Certificate DB" + | Enter old password: + | Incorrect password, try again... + | Enter old password: + | Enter new password: + | Re-enter new password: + | Token "Communicator Certificate DB" password changed successfully. + | JAR Installation File Format + | When a JAR file is run by a server, by modutil, or by any program that + | does not interpret JavaScript, a special information file must be included + | to install the libraries. There are several things to keep in mind with + | this file: + | o It must be declared in the JAR archive's manifest file. + | o The script can have any name. + | o The metainfo tag for this is Pkcs11_install_script. To declare + | meta-information in the manifest file, put it in a file that is passed + | to signtool. + | Sample Script + | For example, the PKCS #11 installer script could be in the file + | pk11install. If so, the metainfo file for signtool includes a line such as + | this: + | + Pkcs11_install_script: pk11install + | The script must define the platform and version number, the module name + | and file, and any optional information like supported ciphers and + | mechanisms. Multiple platforms can be defined in a single install file. + | ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc } + | Platforms { + | WINNT::x86 { + | ModuleName { "Example Module" } + | ModuleFile { win32/fort32.dll } + | DefaultMechanismFlags{0x0001} + | DefaultCipherFlags{0x0001} + | Files { + | win32/setup.exe { + | Executable + | RelativePath { %temp%/setup.exe } + | } + | win32/setup.hlp { + | RelativePath { %temp%/setup.hlp } + | } + | win32/setup.cab { + | RelativePath { %temp%/setup.cab } + | } + | } + | } + | WIN95::x86 { + | EquivalentPlatform {WINNT::x86} + | } + | SUNOS:5.5.1:sparc { + | ModuleName { "Example UNIX Module" } + | ModuleFile { unix/fort.so } + | DefaultMechanismFlags{0x0001} + | CipherEnableFlags{0x0001} + | Files { + | unix/fort.so { + | RelativePath{%root%/lib/fort.so} + | AbsolutePath{/usr/local/netscape/lib/fort.so} + | FilePermissions{555} + | } + | xplat/instr.html { + | RelativePath{%root%/docs/inst.html} + | AbsolutePath{/usr/local/netscape/docs/inst.html} + | FilePermissions{555} + | } + | } + | } + | IRIX:6.2:mips { + | EquivalentPlatform { SUNOS:5.5.1:sparc } + | } + | } + | Script Grammar + | The script is basic Java, allowing lists, key-value pairs, strings, and + | combinations of all of them. + | --> valuelist + | valuelist --> value valuelist + | <null> + | value ---> key_value_pair + | string + | key_value_pair --> key { valuelist } + | key --> string + | string --> simple_string + | "complex_string" + | simple_string --> [^ \\t\n\""{""}"]+ + | complex_string --> ([^\"\\\r\n]|(\\\")|(\\\\))+ + | Quotes and backslashes must be escaped with a backslash. A complex string + | must not include newlines or carriage returns.Outside of complex strings, + | all white space (for example, spaces, tabs, and carriage returns) is + | considered equal and is used only to delimit tokens. + | Keys + | The Java install file uses keys to define the platform and module + | information. + | ForwardCompatible gives a list of platforms that are forward compatible. + | If the current platform cannot be found in the list of supported + | platforms, then the ForwardCompatible list is checked for any platforms + | that have the same OS and architecture in an earlier version. If one is + | found, its attributes are used for the current platform. + | Platforms (required) Gives a list of platforms. Each entry in the list is + | itself a key-value pair: the key is the name of the platform and the value + | list contains various attributes of the platform. The platform string is + | in the format system name:OS release:architecture. The installer obtains + | these values from NSPR. OS release is an empty string on non-Unix + | operating systems. NSPR supports these platforms: + | o AIX (rs6000) + | o BSDI (x86) + | o FREEBSD (x86) + | o HPUX (hppa1.1) + | o IRIX (mips) + | o LINUX (ppc, alpha, x86) + | o MacOS (PowerPC) + | o NCR (x86) + | o NEC (mips) + | o OS2 (x86) + | o OSF (alpha) + | o ReliantUNIX (mips) + | o SCO (x86) + | o SOLARIS (sparc) + | o SONY (mips) + | o SUNOS (sparc) + | o UnixWare (x86) + | o WIN16 (x86) + | o WIN95 (x86) + | o WINNT (x86) + | For example: + | IRIX:6.2:mips + | SUNOS:5.5.1:sparc + | Linux:2.0.32:x86 + | WIN95::x86 + | The module information is defined independently for each platform in the + | ModuleName, ModuleFile, and Files attributes. These attributes must be + | given unless an EquivalentPlatform attribute is specified. + | Per-Platform Keys + | Per-platform keys have meaning only within the value list of an entry in + | the Platforms list. + | ModuleName (required) gives the common name for the module. This name is + | used to reference the module by servers and by the modutil tool. + | ModuleFile (required) names the PKCS #11 module file for this platform. + | The name is given as the relative path of the file within the JAR archive. + | Files (required) lists the files that need to be installed for this + | module. Each entry in the file list is a key-value pair. The key is the + | path of the file in the JAR archive, and the value list contains + | attributes of the file. At least RelativePath or AbsolutePath must be + | specified for each file. + | DefaultMechanismFlags specifies mechanisms for which this module is the + | default provider; this is equivalent to the -mechanism option with the + | -add command. This key-value pair is a bitstring specified in hexadecimal + | (0x) format. It is constructed as a bitwise OR. If the + | DefaultMechanismFlags entry is omitted, the value defaults to 0x0. + | RSA: 0x00000001 + | DSA: 0x00000002 + | RC2: 0x00000004 + | RC4: 0x00000008 + | DES: 0x00000010 + | DH: 0x00000020 + | FORTEZZA: 0x00000040 + | RC5: 0x00000080 + | SHA1: 0x00000100 + | MD5: 0x00000200 + | MD2: 0x00000400 + | RANDOM: 0x08000000 + | FRIENDLY: 0x10000000 + | OWN_PW_DEFAULTS: 0x20000000 + | DISABLE: 0x40000000 + | CipherEnableFlags specifies ciphers that this module provides that NSS + | does not provide (so that the module enables those ciphers for NSS). This + | is equivalent to the -cipher argument with the -add command. This key is a + | bitstring specified in hexadecimal (0x) format. It is constructed as a + | bitwise OR. If the CipherEnableFlags entry is omitted, the value defaults + | to 0x0. + | EquivalentPlatform specifies that the attributes of the named platform + | should also be used for the current platform. This makes it easier when + | more than one platform uses the same settings. + | Per-File Keys + | Some keys have meaning only within the value list of an entry in a Files + | list. + | Each file requires a path key the identifies where the file is. Either + | RelativePath or AbsolutePath must be specified. If both are specified, the + | relative path is tried first, and the absolute path is used only if no + | relative root directory is provided by the installer program. + | RelativePath specifies the destination directory of the file, relative to + | some directory decided at install time. Two variables can be used in the + | relative path: %root% and %temp%. %root% is replaced at run time with the + | directory relative to which files should be installed; for example, it may + | be the server's root directory. The %temp% directory is created at the + | beginning of the installation and destroyed at the end. The purpose of + | %temp% is to hold executable files (such as setup programs) or files that + | are used by these programs. Files destined for the temporary directory are + | guaranteed to be in place before any executable file is run; they are not + | deleted until all executable files have finished. + | AbsolutePath specifies the destination directory of the file as an + | absolute path. + | Executable specifies that the file is to be executed during the course of + | the installation. Typically, this string is used for a setup program + | provided by a module vendor, such as a self-extracting setup executable. + | More than one file can be specified as executable, in which case the files + | are run in the order in which they are specified in the script file. + | FilePermissions sets permissions on any referenced files in a string of + | octal digits, according to the standard Unix format. This string is a + | bitwise OR. + | user read: 0400 + | user write: 0200 + | user execute: 0100 + | group read: 0040 + | group write: 0020 + | group execute: 0010 + | other read: 0004 + | other write: 0002 + | other execute: 0001 + | Some platforms may not understand these permissions. They are applied only + | insofar as they make sense for the current platform. If this attribute is + | omitted, a default of 777 is assumed. + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | BerkeleyDB has performance limitations, though, which prevent it from + | being easily used by multiple applications simultaneously. NSS has some + | flexibility that allows applications to use their own, independent + | database engine while keeping a shared database and working around the + | access issues. Still, NSS requires more flexibility to provide a truly + | shared security database. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | modutil -create -dbdir sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | Most applications do not use the shared database by default, but they can + | be configured to use them. For example, this how-to article covers how to + | configure Firefox and Thunderbird to use the new shared NSS databases: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | certutil (1) + | pk12util (1) + | signtool (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [2]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. JAR Installation File Format + | ``file:///tmp/xmlto.6gGxS0/modutil.pro...r-install-file`` + | 2. https://www.mozilla.org/projects/security/pki/nss/
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_certutil-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_certutil-tasks/index.rst new file mode 100644 index 0000000000..f3ea257f2c --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_certutil-tasks/index.rst @@ -0,0 +1,32 @@ +.. _mozilla_projects_nss_tools_nss_tools_certutil-tasks: + +NSS Tools certutil-tasks +======================== + +.. container:: + + .. rubric:: NSS Security Tools: certutil Tasks + :name: NSS_Security_Tools_certutil_Tasks + + | Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + .. rubric:: Task List + :name: Task_List + + #. Better error reporting. Most certutil errors provide no detail. Mistakes with command-line + options just print a usage message. + #. Improve certificate listings. Allow for sorting by name and trust. Sorting by trust will + return CA certs first. + #. Allow listing and lookup of keys by index and nickname. + #. Improve coherence of key and certificate nicknames. + #. Remove keys "stranded" without a certificate (except for the imminent (????) encryption key + for password files). + #. Support importing keys from a file. + #. Improve hardware token support. + #. (bugfix) Some certificate extensions cause certutil to crash. + #. (bugfix) Certificate entries require a serial number; one should be generated automatically if + not provided. + #. (bugfix) Null password is given to new ``key3.db``; should prompt user for an initial + password. + #. (bugfix) Listing provate keys does not work: requires password authentication. + #. (bugfix) Listing certificate extensions has typos and does not provide much information.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_certutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_certutil/index.rst new file mode 100644 index 0000000000..06a8f0022d --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_certutil/index.rst @@ -0,0 +1,666 @@ +.. _mozilla_projects_nss_tools_nss_tools_certutil: + +NSS Tools certutil +================== + +.. _using_the_certificate_database_tool: + +`Using the Certificate Database Tool <#using_the_certificate_database_tool>`__ +------------------------------------------------------------------------------ + +.. container:: + + The Certificate Database Tool is a command-line utility that can create and modify the Netscape + Communicator ``cert8.db`` and ``key3.db``\ database files. It can also list, generate, modify, or + delete certificates within the ``cert8.db``\ file and create or change the password, generate new + public and private key pairs, display the contents of the key database, or delete key pairs + within the ``key3.db`` file. + + Starting from NSS 3.35, the database format was upgraded to support SQLite as described in this + `document <https://wiki.mozilla.org/NSS_Shared_DB>`__. It means that ``cert9.db`` and ``key4.db`` + files may be targeted instead. + + The key and certificate management process generally begins with creating keys in the key + database, then generating and managing certificates in the certificate database. + + This document discusses certificate and key database management. For information security module + database management, see :ref:`mozilla_projects_nss_reference_nss_tools_:_modutil` + +`Availability <#availability>`__ +-------------------------------- + +.. container:: + + See the release notes for the platforms this tool is available on. + +`Syntax <#syntax>`__ +-------------------- + +.. container:: + + To run the Certificate Database Tool, type the command + + .. code:: + + certutil option [arguments ] + + where *options* and *arguments* are combinations of the options and arguments listed in the + following section. Each command takes one option. Each option may take zero or more arguments. To + see a usage string, issue the command without options, or with the ``-H`` option. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action and are uppercase. Option arguments modify an action and are lowercase. + Certificate Database Tool command options and their arguments are defined as follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-N`` | Create new certificate and key databases. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-S`` | Create an individual certificate and add it to | + | | a certificate database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-R`` | Create a certificate-request file that can be | + | | submitted to a Certificate Authority (CA) for | + | | processing into a finished certificate. Output | + | | defaults to standard out unless you use | + | | ``-o``\ *output-file* argument. Use the ``-a`` | + | | argument to specify ASCII output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-C`` | Create a new binary certificate file from a | + | | binary certificate-request file. Use the ``-i`` | + | | argument to specify the certificate-request | + | | file. If this argument is not used Certificate | + | | Database Tool prompts for a filename. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-G`` | Generate a new public and private key pair | + | | within a key database. The key database should | + | | already exist; if one is not present, this | + | | option will initialize one by default. Some | + | | smart cards (for example, the Litronic card) | + | | can store only one key pair. If you create a | + | | new key pair for such a card, the previous pair | + | | is overwritten. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-F`` | Delete a private key from a key database. | + | | Specify the key to delete with the ``-n`` | + | | argument. Specify the database from which to | + | | delete the key with the ``-d`` argument. | + | | | + | | Use the ``-k`` argument to specify explicitly | + | | whether to delete a DSA or an RSA key. If you | + | | don't use the ``-k`` argument, the option looks | + | | for an RSA key matching the specified nickname. | + | | | + | | When you delete keys, be sure to also remove | + | | any certificates associated with those keys | + | | from the certificate database, by using ``-D``. | + | | | + | | Some smart cards (for example, the Litronic | + | | card) do not let you remove a public key you | + | | have generated. In such a case, only the | + | | private key is deleted from the key pair. You | + | | can display the public key with the command | + | | ``certutil -K -h``\ *tokenname* . | + +-------------------------------------------------+-------------------------------------------------+ + | ``-K`` | List the keyID of keys in the key database. A | + | | keyID is the modulus of the RSA key or the | + | | ``publicValue`` of the DSA key. IDs are | + | | displayed in hexadecimal ("0x" is not shown). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-A`` | Add an existing certificate to a certificate | + | | database. The certificate database should | + | | already exist; if one is not present, this | + | | option will initialize one by default. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-D`` | Delete a certificate from the certificate | + | | database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-L`` | List all the certificates, or display | + | | information about a named certificate, in a | + | | certificate database. | + | | | + | | Use the ``-h``\ *tokenname* argument to specify | + | | the certificate database on a particular | + | | hardware or software token. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-V`` | Check the validity of a certificate and its | + | | attributes. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-M`` | Modify a certificate's trust attributes using | + | | the values of the ``-t`` argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-H`` | Display a list of the options and arguments | + | | used by the Certificate Database Tool. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-W`` | Change the password to a key database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-U`` | List all available modules or print a single | + | | named module. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-a`` | Use ASCII format or allow the use of ASCII | + | | format for input or output. This formatting | + | | follows `RFC | + | | 1113 <https://tools.ietf.org/html/rfc1113>`__. | + | | For certificate requests, ASCII output defaults | + | | to standard output unless redirected. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-b``\ *validity-time* | Specify a time at which a certificate is | + | | required to be valid. Use when checking | + | | certificate validity with the ``-V`` option. | + | | The format of the\ *validity-time* argument is | + | | "YYMMDDHHMMSS[+HHMM|-HHMM|Z]". Specifying | + | | seconds (SS) is optional. When specifying an | + | | explicit time, use "YYMMDDHHMMSSZ". When | + | | specifying an offset time, use | + | | "YYMMDDHHMMSS+HHMM" or "YYMMDDHHMMSS-HHMM". If | + | | this option is not used, the validity check | + | | defaults to the current system time. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-c``\ *issuer* | Identify the certificate of the CA from which a | + | | new certificate will derive its authenticity. | + | | Use the exact nickname or alias of the CA | + | | certificate, or use the CA's email address. | + | | Bracket the\ *issuer* string with quotation | + | | marks if it contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-d``\ *directory* | Specify the database directory containing the | + | | certificate and key database files. On Unix the | + | | Certificate Database Tool defaults to | + | | ``$HOME/.netscape`` (that is, ``~/.netscape``). | + | | On Windows NT the default is the current | + | | directory. | + | | | + | | The ``cert8.db`` and ``key3.db`` database files | + | | must reside in the same directory. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-P``\ *dbprefix* | Specify the prefix used on the ``cert8.db`` and | + | | ``key3.db`` files (for example, ``my_cert8.db`` | + | | and ``my_key3.db``). This option is provided as | + | | a special case. Changing the names of the | + | | certificate and key databases is not | + | | recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-e`` | Check a certificate's signature during the | + | | process of validating a certificate. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-f``\ *password-file* | Specify a file that will automatically supply | + | | the password to include in a certificate or to | + | | access a certificate database. This is a | + | | plain-text file containing one password. Be | + | | sure to prevent unauthorized access to this | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-g``\ *keysize* | Set a key size to use when generating new | + | | public and private key pairs. The minimum is | + | | 512 bits and the maximum is 8192 bits. The | + | | default is 1024 bits. Any size that is a | + | | multiple of 8 between the minimum and maximum | + | | is allowed. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-h``\ *tokenname* | Specify the name of a token to use or act on. | + | | Unless specified otherwise the default token is | + | | an internal slot (specifically, internal slot | + | | 2). This slot can also be explicitly named with | + | | the string ``"internal"``. An internal slots is | + | | a virtual slot maintained in software, rather | + | | than a hardware device. Internal slot 2 is used | + | | by key and certificate services. Internal slot | + | | 1 is used by cryptographic services. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-i``\ *cert|cert-request-file* | Specify a specific certificate, or a | + | | certificate-request file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-k rsa|dsa|all`` | Specify the type of a key: RSA, DSA or both. | + | | The default value is ``rsa``. By specifying the | + | | type of key you can avoid mistakes caused by | + | | duplicate nicknames. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l`` | Display detailed information when validating a | + | | certificate with the ``-V`` option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-m``\ *serial-number* | Assign a unique serial number to a certificate | + | | being created. This operation should be | + | | performed by a CA. The default serial number is | + | | 0 (zero). Serial numbers are limited to | + | | integers. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n``\ *nickname* | Specify the nickname of a certificate or key to | + | | list, create, add to a database, modify, or | + | | validate. Bracket the *nickname* string with | + | | quotation marks if it contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-o``\ *output-file* | Specify the output file name for new | + | | certificates or binary certificate requests. | + | | Bracket the\ *output-file* string with | + | | quotation marks if it contains spaces. If this | + | | argument is not used the output destination | + | | defaults to standard output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-p``\ *phone* | Specify a contact telephone number to include | + | | in new certificates or certificate requests. | + | | Bracket this string with quotation marks if it | + | | contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-q``\ *pqgfile* | Read an alternate PQG value from the specified | + | | file when generating DSA key pairs. If this | + | | argument is not used, the Key Database Tool | + | | generates its own PQG value. PQG files are | + | | created with a separate DSA utility. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-r`` | Display a certificate's binary DER encoding | + | | when listing information about that certificate | + | | with the ``-L`` option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-s``\ *subject* | Identify a particular certificate owner for new | + | | certificates or certificate requests. Bracket | + | | this string with quotation marks if it contains | + | | spaces. The subject identification format | + | | follows `RFC | + | | 1485 <https://tools.ietf.org/html/rfc1485>`__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-t``\ *trustargs* | Specify the trust attributes to modify in an | + | | existing certificate or to apply to a | + | | certificate when creating it or adding it to a | + | | database. | + | | | + | | There are three available trust categories for | + | | each certificate, expressed in this order: | + | | "*SSL* ,\ *email* ,\ *object signing* ". In | + | | each category position use zero or more of the | + | | following attribute codes: | + | | | + | | | ``p`` prohibited (explicitly distrusted) | + | | | ``P`` Trusted peer | + | | | ``c`` Valid CA | + | | | ``T`` Trusted CA to issue client | + | | certificates (implies ``c``) | + | | | ``C`` Trusted CA to issue server | + | | certificates (SSL only) | + | | | (implies ``c``) | + | | | ``u`` Certificate can be used for | + | | authentication or signing | + | | | ``w`` Send warning (use with other | + | | attributes to include a warning when the | + | | certificate is used in that context) | + | | | + | | The attribute codes for the categories are | + | | separated by commas, and the entire set of | + | | attributes enclosed by quotation marks. For | + | | example: | + | | | + | | ``-t "TCu,Cu,Tuw"`` | + | | | + | | Use the ``-L`` option to see a list of the | + | | current certificates and trust attributes in a | + | | certificate database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-u``\ *certusage* | Specify a usage context to apply when | + | | validating a certificate with the ``-V`` | + | | option. The contexts are the following: | + | | | + | | | ``C`` (as an SSL client) | + | | | ``V`` (as an SSL server) | + | | | ``S`` (as an email signer) | + | | | ``R`` (as an email recipient) | + +-------------------------------------------------+-------------------------------------------------+ + | ``-v``\ *valid-months* | Set the number of months a new certificate will | + | | be valid. The validity period begins at the | + | | current system time unless an offset is added | + | | or subtracted with the ``-w`` option. If this | + | | argument is not used, the default validity | + | | period is three months. When this argument is | + | | used, the default three-month period is | + | | automatically added to any value given in | + | | the\ *valid-month* argument. For example, using | + | | this option to set a value of ``3`` would cause | + | | 3 to be added to the three-month default, | + | | creating a validity period of six months. You | + | | can use negative values to reduce the default | + | | period. For example, setting a value of ``-2`` | + | | would subtract 2 from the default and create a | + | | validity period of one month. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-w``\ *offset-months* | Set an offset from the current system time, in | + | | months, for the beginning of a certificate's | + | | validity period. Use when creating the | + | | certificate or adding it to a database. Express | + | | the offset in integers, using a minus sign | + | | (``-``) to indicate a negative offset. If this | + | | argument is not used, the validity period | + | | begins at the current system time. The length | + | | of the validity period is set with the ``-v`` | + | | argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-x`` | Use the Certificate Database Tool to generate | + | | the signature for a certificate being created | + | | or added to a database, rather than obtaining a | + | | signature from a separate CA. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-y``\ *exp* | Set an alternate exponent value to use in | + | | generating a new RSA public key for the | + | | database, instead of the default value of | + | | 65537. The available alternate values are 3 and | + | | 17. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-z``\ *noise-file* | Read a seed value from the specified binary | + | | file to use in generating a new RSA private and | + | | public key pair. This argument makes it | + | | possible to use hardware-generated seed values | + | | and unnecessary to manually create a value from | + | | the keyboard. The minimum file size is 20 | + | | bytes. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-1`` | Add a key usage extension to a certificate that | + | | is being created or added to a database. This | + | | extension allows a certificate's key to be | + | | dedicated to supporting specific operations | + | | such as SSL server or object signing. The | + | | Certificate Database Tool will prompt you to | + | | select a particular usage for the certificate's | + | | key. These usages are described under `Standard | + | | X.509 v3 Certificate | + | | Extensions <https://a | + | | ccess.redhat.com/documentation/en-US/Red_Hat_Ce | + | | rtificate_System/9/html/Administration_Guide/St | + | | andard_X.509_v3_Certificate_Extensions.html>`__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-2`` | Add a basic constraint extension to a | + | | certificate that is being created or added to a | + | | database. This extension supports the | + | | certificate chain verification process. The | + | | Certificate Database Tool will prompt you to | + | | select the certificate constraint extension. | + | | Constraint extensions are described in | + | | `Standard X.509 v3 Certificate | + | | Extensions <https://a | + | | ccess.redhat.com/documentation/en-US/Red_Hat_Ce | + | | rtificate_System/9/html/Administration_Guide/St | + | | andard_X.509_v3_Certificate_Extensions.html>`__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-3`` | Add an authority keyID extension to a | + | | certificate that is being created or added to a | + | | database. This extension supports the | + | | identification of a particular certificate, | + | | from among multiple certificates associated | + | | with one subject name, as the correct issuer of | + | | a certificate. The Certificate Database Tool | + | | will prompt you to select the authority keyID | + | | extension. Authority key ID extensions are | + | | described under `Standard X.509 v3 Certificate | + | | Extensions <http | + | | s://access.redhat.com/documentation/en-us/red_h | + | | at_certificate_system/9/html/administration_gui | + | | de/standard_x.509_v3_certificate_extensions>`__ | + | | in Appendix B.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-4`` | Add a CRL distribution point extension to a | + | | certificate that is being created or added to a | + | | database. This extension identifies the URL of | + | | a certificate's associated certificate | + | | revocation list (CRL). The Certificate Database | + | | Tool prompts you to enter the URL. CRL | + | | distribution point extensions are described in | + | | `Standard X.509 v3 Certificate | + | | Extensions <https://a | + | | ccess.redhat.com/documentation/en-US/Red_Hat_Ce | + | | rtificate_System/9/html/Administration_Guide/St | + | | andard_X.509_v3_Certificate_Extensions.html>`__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-5`` | Add a Netscape certificate type extension to a | + | | certificate that is being created or added to | + | | the database. Netscape certificate type | + | | extensions are described in `Standard X.509 v3 | + | | Certificate | + | | Extensions <https://a | + | | ccess.redhat.com/documentation/en-US/Red_Hat_Ce | + | | rtificate_System/9/html/Administration_Guide/St | + | | andard_X.509_v3_Certificate_Extensions.html>`__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-6`` | Add an extended key usage extension to a | + | | certificate that is being created or added to | + | | the database. Extended key usage extensions are | + | | described in `Standard X.509 v3 Certificate | + | | Extensions <https://a | + | | ccess.redhat.com/documentation/en-US/Red_Hat_Ce | + | | rtificate_System/9/html/Administration_Guide/St | + | | andard_X.509_v3_Certificate_Extensions.html>`__ | + | | in Appendix A.3 of the\ *Red Hat Certificate | + | | System Administration Guide.* | + +-------------------------------------------------+-------------------------------------------------+ + | ``-7``\ *emailAddrs* | Add a comma-separated list of email addresses | + | | to the subject alternative name extension of a | + | | certificate or certificate request that is | + | | being created or added to the database. Subject | + | | alternative name extensions are described in | + | | Section 4.2.1.7 of `RFC | + | | 3 | + | | 2800 <https://tools.ietf.org/html/rfc32800>`__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-8``\ *dns-names* | Add a comma-separated list of DNS names to the | + | | subject alternative name extension of a | + | | certificate or certificate request that is | + | | being created or added to the database. Subject | + | | alternative name extensions are described in | + | | Section 4.2.1.7 of `RFC | + | | 32800 <https://tools.ietf.org/html/rfc32800>`__ | + +-------------------------------------------------+-------------------------------------------------+ + +`Usage <#usage>`__ +------------------ + +.. container:: + + The Certificate Database Tool's capabilities are grouped as follows, using these combinations of + options and arguments. Options and arguments in square brackets are optional, those without + square brackets are required. + + .. code:: + + -N [-d certdir ] + + .. code:: + + -S -k rsa|dsa -n certname -s subject + [-c issuer |-x] -t trustargs [-h tokenname ] + [-m serial-number ] [-v valid-months ] [-w offset-months ] + [-d certdir ] [-p phone ] [-f password-file ] [-1] [-2] [-3] [-4] + + .. code:: + + -R -k rsa|dsa -s subject [-h tokenname ] + [-d certdir ] [-p phone ] [-o output-file ] [-f password-file ] + + .. code:: + + -C -c issuer [-f password-file ] + [-h tokenname ] -i cert-request-file -o output-file [-m serial-number ] + [-v valid-months ] [-w offset-months ] [-d certdir ] [-1] [-2] [-3] + [-4] + + .. code:: + + -A -n certname -t trustargs [-h tokenname ] [-d certdir ] [-a] + [-i cert-request-file ] + + .. code:: + + -L [-n certname ] [-d certdir ] [-r] [-a] + + .. code:: + + -V -n certname -b validity-time -u certusage [-e] [-l] [-d certdir ] + + .. code:: + + -M -n certname -t trustargs [-d certdir ] + + .. code:: + + -H + + - Creating a new ``cert8.db`` file: + - Creating a new certificate and adding it to the database with one command: + - Making a separate certificate request: + - Creating a new binary certificate from a binary certificate request: + - Adding a certificate to an existing database: + - Listing all certificates or a named certificate: + - Validating a certificate: + - Modifying a certificate's trust attribute: + - Displaying a list of the options and arguments used by the Certificate Database Tool: + +`Examples <#examples>`__ +------------------------ + +.. container:: + +.. _creating_a_new_certificate_database: + +`Creating a New Certificate Database <#creating_a_new_certificate_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example creates a new certificate database (``cert8.db`` file) in the specified directory: + + .. code:: + + certutil -N -d certdir + + You must generate the associated ``key3.db`` and ``secmod.db`` files by using the Key Database + Tool or other tools. + +.. _listing_certificates_in_a_database: + +`Listing Certificates in a Database <#listing_certificates_in_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example lists all the certificates in the ``cert8.db`` file in the specified directory: + + .. code:: + + certutil -L -d certdir + + The Certificate Database Tool displays output similar to the following: + + | ``Certificate Name Trust Attributes`` + | ``Uptime Group Plc. Class 1 CA C,C, VeriSign Class 1 Primary CA ,C, VeriSign Class 2 Primary CA C,C,C AT&T Certificate Services C,C, GTE CyberTrust Secure Server CA C,, Verisign/RSA Commercial CA C,C, AT&T Directory Services C,C, BelSign Secure Server CA C,, Verisign/RSA Secure Server CA C,C, GTE CyberTrust Root CA C,C, Uptime Group Plc. Class 4 CA ,C, VeriSign Class 3 Primary CA C,C,C Canada Post Corporation CA C,C, Integrion CA C,C,C IBM World Registry CA C,C,C GTIS/PWGSC, Canada Gov. Web CA C,C, GTIS/PWGSC, Canada Gov. Secure CA C,C,C MCI Mall CA C,C, VeriSign Class 4 Primary CA C,C,C KEYWITNESS, Canada CA C,C, BelSign Object Publishing CA ,,C BBN Certificate Services CA Root 1 C,C, p prohibited (explicitly distrusted) P Trusted peer c Valid CA T Trusted CA to issue client certs (implies c) C Trusted CA to issue server certs(for ssl only) (implies c) u User cert w Send warning`` + +.. _creating_a_certificate_request: + +`Creating a Certificate Request <#creating_a_certificate_request>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example generates a binary certificate request file named ``e95c.req`` in the specified + directory: + + .. code:: + + certutil -R -s "CN=John Smith, O=Netscape, L=Mountain View, ST=California, C=US" -p "650-555-8888" -o mycert.req -d certdir + + Before it creates the request file, the Certificate Database Tool prompts you for a password: + + .. code:: + + Enter Password or Pin for "Communicator Certificate DB": + +.. _creating_a_certificate: + +`Creating a Certificate <#creating_a_certificate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A valid certificate must be issued by a trusted CA. If a CA key pair is not available, you can + create a self-signed certificate (for purposes of illustration) with the ``-x`` argument. This + example creates a new binary, self-signed CA certificate named ``myissuer``, in the specified + directory. + + .. code:: + + certutil -S -s "CN=My Issuer" -n myissuer -x -t "C,C,C" -1 -2 -5 -m 1234 -f password-file -d certdir + + The following example creates a new binary certificate named ``mycert.crt``, from a binary + certificate request named ``mycert.req``, in the specified directory. It is issued by the + self-signed certificate created above, ``myissuer``. + + .. code:: + + certutil -C -m 2345 -i mycert.req -o mycert.crt -c myissuer -d certdir + +.. _adding_a_certificate_to_the_database: + +`Adding a Certificate to the Database <#adding_a_certificate_to_the_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example adds a certificate to the certificate database: + + .. code:: + + certutil -A -n jsmith@netscape.com -t "p,p,p" -i mycert.crt -d certdir + + You can see this certificate in the database with this command: + + .. code:: + + certutil -L -n jsmith@netscape.com -d certdir + + The Certificate Database Tool displays output similar to the following: + + | ``Certificate: Data: Version: 3 (0x2) Serial Number: 0 (0x0) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: CN=John Smith, O=Netscape, L=Mountain View, ST=California, C=US Validity: Not Before: Thu Mar 12 00:10:40 1998 Not After: Sat Sep 12 00:10:40 1998 Subject: CN=John Smith, O=Netscape, L=Mountain View, ST=California, C=US`` + | ``Subject Public Key Info: Public Key Algorithm: PKCS #1 RSA Encryption RSA Public Key: Modulus: 00:da:53:23:58:00:91:6a:d1:a2:39:26:2f:06:3a: 38:eb:d4:c1:54:a3:62:00:b9:f0:7f:d6:00:76:aa: 18:da:6b:79:71:5b:d9:8a:82:24:07:ed:49:5b:33: bf:c5:79:7c:f6:22:a7:18:66:9f:ab:2d:33:03:ec: 63:eb:9d:0d:02:1b:da:32:ae:6c:d4:40:95:9f:b3: 44:8b:8e:8e:a3:ae:ad:08:38:4f:2e:53:e9:e1:3f: 8e:43:7f:51:61:b9:0f:f3:a6:25:1e:0b:93:74:8f: c6:13:a3:cd:51:40:84:0e:79:ea:b7:6b:d1:cc:6b: 78:d0:5d:da:be:2b:57:c2:6f Exponent: 65537 (0x10001) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Signature: 44:15:e5:ae:c4:30:2c:cd:60:89:f1:1d:22:ed:5e:5b:10:c8: 7e:5f:56:8c:b4:00:12:ed:5f:a4:6a:12:c3:0d:01:03:09:f2: 2f:e7:fd:95:25:47:80:ea:c1:25:5a:33:98:16:52:78:24:80: c9:53:11:40:99:f5:bd:b8:e9:35:0e:5d:3e:38:6a:5c:10:d1: c6:f9:54:af:28:56:62:f4:2f:b3:9b:50:e1:c3:a2:ba:27:ee: 07:9f:89:2e:78:5c:6d:46:b6:5e:99:de:e6:9d:eb:d9:ff:b2: 5f:c6:f6:c6:52:4a:d4:67:be:8d:fc:dd:52:51:8e:a2:d7:15: 71:3e`` + | ``Certificate Trust Flags: SSL Flags: Valid CA Trusted CA Email Flags: Valid CA Trusted CA Object Signing Flags: Valid CA Trusted CA`` + +.. _validating_a_certificate: + +`Validating a Certificate <#validating_a_certificate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example validates a certificate: + + .. code:: + + certutil -V -n jsmith@netscape.com -b 9803201212Z -u SR -e -l -d certdir + + The Certificate Database Tool shows results similar to + + .. code:: + + Certificate:'jsmith@netscape.com' is valid. + + or + + .. code:: + + UID=jsmith, E=jsmith@netscape.com, CN=John Smith, O=Netscape Communications Corp., C=US : Expired certificate + + or + + .. code:: + + UID=jsmith, E=jsmith@netscape.com, CN=John Smith, O=Netscape Communications Corp., C=US : Certificate not approved for this operation
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_cmsutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_cmsutil/index.rst new file mode 100644 index 0000000000..9697bce4f5 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_cmsutil/index.rst @@ -0,0 +1,119 @@ +.. _mozilla_projects_nss_tools_nss_tools_cmsutil: + +NSS Tools cmsutil +================= + +.. _using_cmsutil: + +`Using cmsutil <#using_cmsutil>`__ +---------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + The cmsutil command-line utility uses the `S/MIME Toolkit <../smime/>`__ to perform basic + operations, such as encryption and decryption, on `Cryptographic Message + Syntax (CMS) <http://www.ietf.org/rfc/rfc2630.txt>`__ messages. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run cmsutil, type the command ``cmsutil``\ *option*\ ``[``\ *arguments*\ ``]`` where *option* + and *arguments* are combinations of the options and arguments listed in the following section. + Each command takes one option. Each option may take zero or more arguments. To see a usage + string, issue the command without options. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action. Option arguments modify an action. The options and arguments for the + ``cmsutil`` command are defined as follows: + + +------------------------------------------------+------------------------------------------------+ + | **Options** | | + +------------------------------------------------+------------------------------------------------+ + | ``-D`` | Decode a message. | + +------------------------------------------------+------------------------------------------------+ + | ``-C`` | Encrypt a message. | + +------------------------------------------------+------------------------------------------------+ + | ``-E`` | Envelope a message. | + +------------------------------------------------+------------------------------------------------+ + | ``-O`` | Create a certificates-only message. | + +------------------------------------------------+------------------------------------------------+ + | ``-S`` | Sign a message. | + +------------------------------------------------+------------------------------------------------+ + | **Arguments** | | + +------------------------------------------------+------------------------------------------------+ + | ``-c`` *content* | Use this detached content (decode only). | + +------------------------------------------------+------------------------------------------------+ + | ``-d`` *dbdir* | Specify the key/certificate database directory | + | | (default is ".") | + +------------------------------------------------+------------------------------------------------+ + | ``-e`` *envfile* | Specify a file containing an enveloped message | + | | for a set of recipients to which you would | + | | like to send an encrypted message. If this is | + | | the first encrypted message for that set of | + | | recipients, a new enveloped message will be | + | | created that you can then use for future | + | | messages (encrypt only). | + +------------------------------------------------+------------------------------------------------+ + | ``-G`` | Include a signing time attribute (sign only). | + +------------------------------------------------+------------------------------------------------+ + | ``-h`` *num* | Generate email headers with info about CMS | + | | message (decode only). | + +------------------------------------------------+------------------------------------------------+ + | ``-i`` *infile* | Use *infile* as a source of data (default is | + | | stdin). | + +------------------------------------------------+------------------------------------------------+ + | ``-N`` *nickname* | Specify nickname of certificate to sign with | + | | (sign only). | + +------------------------------------------------+------------------------------------------------+ + | ``-n`` | Suppress output of contents (decode only). | + +------------------------------------------------+------------------------------------------------+ + | ``-o`` *outfile* | Use outfile as a destination of data (default | + | | is stdout). | + +------------------------------------------------+------------------------------------------------+ + | ``-P`` | Include an S/MIME capabilities attribute. | + +------------------------------------------------+------------------------------------------------+ + | -p *password* | Use password as key database password. | + +------------------------------------------------+------------------------------------------------+ + | - | Specify list of recipients (email addresses) | + | r \ *recipient1*,\ *recipient2, . . .* | for an encrypted or enveloped message. For | + | | certificates-only message, list of | + | | certificates to send. | + +------------------------------------------------+------------------------------------------------+ + | -T | Suppress content in CMS message (sign only). | + +------------------------------------------------+------------------------------------------------+ + | -u *certusage* | Set type of cert usage (default is | + | | <tt>certUsageEmailSigner)</tt>. | + +------------------------------------------------+------------------------------------------------+ + | <-Y *ekprefnick* | Specify an encryption key preference by | + | | nickname. | + +------------------------------------------------+------------------------------------------------+ + +`Usage <#usage>`__ +------------------ + +.. container:: + + cmsutil -C [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -r + "*recipient1*,\ *recipient2*, . . ." -e *envfile* + cmsutil -D [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] [-c *content*] [-n] [-h + *num*] + + cmsutil -E [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -r + "*recipient1*,\ *recipient2*, . . ." + + cmsutil -O [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -r + "*cert1*,\ *cert2*, . . ." + + cmsutil -S [-i *infile*] [-o *outfile*] [-d *dbdir*] [-p *password*] -N *nickname*\ [-TGP] [-Y + *ekprefnick*]
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_crlutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_crlutil/index.rst new file mode 100644 index 0000000000..d190e576e9 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_crlutil/index.rst @@ -0,0 +1,441 @@ +.. _mozilla_projects_nss_tools_nss_tools_crlutil: + +NSS Tools crlutil +================= + +.. _using_the_certificate_revocation_list_management_tool: + +`Using the Certificate Revocation List Management Tool <#using_the_certificate_revocation_list_management_tool>`__ +------------------------------------------------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + The Certificate Revocation List (CRL) Management Tool is a command-line utility that can list, + generate, modify, or delete CRLs within the NSS security database file(s) and list, create, + modify or delete certificates entries in a particular CRL. + + The key and certificate management process generally begins with creating keys in the key + database, then generating and managing certificates in the certificate database(see ``certutil`` + tool) and continues with certificates expiration or revocation. + + This document discusses certificate revocation list management. For information on security + module database management, see `Using the Security Module Database Tool <NSS_Tools_modutil>`__. + For information on certificate and key database management, see `Using the Certificate Database + Tool <NSS_Tools_certutil>`__. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + See the :ref:`mozilla_projects_nss_releases` for the platforms this tool is available on. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run the Certificate Revocation List Management Tool, type the command + + ``crlutil`` *option*\ ``[``\ *arguments*\ ``]`` + + where *options* and *arguments* are combinations of the options and arguments listed in the + following section. Each command takes one option. Each option may take zero or more arguments. To + see a usage string, issue the command without options, or with the ``-H`` option. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action and are uppercase. Option arguments modify an action and are lowercase. + Certificate Revocation List Management Tool command options and their arguments are defined as + follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-G`` | Create new Certificate Revocation List(CRL). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-D`` | Delete Certificate Revocation List from cert | + | | database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-I`` | Import a CRL to the cert database | + +-------------------------------------------------+-------------------------------------------------+ + | ``-E`` | Erase all CRLs of specified type from the cert | + | | database | + +-------------------------------------------------+-------------------------------------------------+ + | ``-L`` | List existing CRL located in cert database | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-M`` | Modify existing CRL which can be located in | + | | cert db or in arbitrary file. If located in | + | | file it should be encoded in ASN.1 encode | + | | format. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-B`` | Bypass CA signature checks. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-P``\ *dbprefix* | Specify the prefix used on the | + | | ``NSS security database`` files (for example, | + | | ``my_cert8.db`` and ``my_key3.db``). This | + | | option is provided as a special case. Changing | + | | the names of the certificate and key databases | + | | is not recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-a`` | Use ASCII format or allow the use of ASCII | + | | format for input and output. This formatting | + | | follows `RFC | + | | #1113 <http | + | | ://andrew2.andrew.cmu.edu/rfc/rfc1113.html>`__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-c``\ *crl-gen-file* | Specify script file that will be used to | + | | control crl generation/modification. See | + | | crl-cript-file `format <#10232455>`__ below. If | + | | options *-M|-G* is used and *-c | + | | crl-script-file* is not specified, crlutil will | + | | read script data from standard input. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-d``\ *directory* | Specify the database directory containing the | + | | certificate and key database files. On Unix the | + | | Certificate Database Tool defaults to | + | | ``$HOME/.netscape`` (that is, ``~/.netscape``). | + | | On Windows NT the default is the current | + | | directory. | + | | | + | | The ``NSS database`` files must reside in the | + | | same directory. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-i``\ *crl-import-file* | Specify the file which contains the CRL to | + | | import | + +-------------------------------------------------+-------------------------------------------------+ + | ``-f``\ *password-file* | Specify a file that will automatically supply | + | | the password to include in a certificate or to | + | | access a certificate database. This is a | + | | plain-text file containing one password. Be | + | | sure to prevent unauthorized access to this | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l``\ *algorithm-name* | Specify a specific signature algorithm. List of | + | | possible algorithms: MD2 \| MD4 \| MD5 \| SHA1 | + | | \| SHA256 \| SHA384 \| SHA512 | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n``\ *nickname* | Specify the nickname of a certificate or key to | + | | list, create, add to a database, modify, or | + | | validate. Bracket the *nickname* string with | + | | quotation marks if it contains spaces. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-o``\ *output-file* | Specify the output file name for new CRL. | + | | Bracket the *output-file* string with quotation | + | | marks if it contains spaces. If this argument | + | | is not used the output destination defaults to | + | | standard output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-t``\ *crl-type* | Specify type of CRL. possible types are: 0 - | + | | SEC_KRL_TYPE, 1 - SEC_CRL_TYPE. **This option | + | | is obsolete** | + +-------------------------------------------------+-------------------------------------------------+ + | ``-u``\ *url* | Specify the url. | + +-------------------------------------------------+-------------------------------------------------+ + + +---+ + | | + +---+ + +.. _crl_generation_script_syntax: + +`CRL Generation script syntax: <#crl_generation_script_syntax>`__ +----------------------------------------------------------------- + +.. container:: + + CRL generation script file has the following syntax: + + - Line with comments should have <bold>\ *#*\ </bold> as a first symbol of a line + + - Set *"this update"* or *"next update"* CRL fields: + + ``update=YYYYMMDDhhmmssZ`` + ``nextupdate=YYYYMMDDhhmmssZ`` + + | Field "next update" is optional. Time should be in *GeneralizedTime* format + (YYYYMMDDhhmmssZ). + | For example: ``20050204153000Z`` + + - Add an extension to a CRL or a crl certificate entry: + + ``addext``\ *extension-name* *critical/non-critical*\ ``[``\ *arg1*\ ``[``\ *arg2* + ``...]]`` + + | Where: + + ``extension-name``: string value of a name of known extensions. + ``critical/non-critical``: is 1 when extension is critical and 0 otherwise. + ``arg1, arg2``: specific to extension type extension parameters + + ``addext`` uses the range that was set earlier by ``addcert`` and will install an extension to + every cert entries within the range. + + See `"Implemented extensions" <#3543811>`__ for more information regarding extensions and + theirs parameters. + + - Add certificate entries(s) to CRL: + + ``addcert``\ *range* *date* + + | Where: + + ``range``: two integer values separated by ``dash``: range of certificates that will be + added by this command. ``dash`` is used as a delimiter. Only one cert will be added if + there is no delimiter. + ``date``: revocation date of a cert. Date should be represented in GeneralizedTime format + (YYYYMMDDhhmmssZ). + + - Remove certificate entry(s) from CRL + + ``rmcert`` *range* + + | Where: + + ``range``: two integer values separated by ``dash``: range of certificates that will be + added by this command. ``dash`` is used as a delimiter. Only one cert will be added if + there is no delimiter. + + - Change range of certificate entry(s) in CRL + + ``range`` *new-range* + + | Where: + + ``new-range``: two integer values separated by ``dash``: range of certificates that will be + added by this command. ``dash`` is used as a delimiter. Only one cert will be added if + there is no delimiter. + +.. _implemented_extensions: + +`Implemented Extensions <#implemented_extensions>`__ +---------------------------------------------------- + +.. container:: + + The extensions defined for CRL provide methods for associating additional attributes with CRLs of + theirs entries. For more information see `RFC #3280 <http://www.faqs.org/rfcs/rfc3280.html>`__ + + - Add The Authority Key Identifier extension: + + The authority key identifier extension provides a means of identifying the public key + corresponding to the private key used to sign a CRL. + + ``authKeyId`` *critical* [*key-id* \| *dn* *cert-serial*] + + | Where: + + ``authKeyIdent``: identifies the name of an extension + ``critical``: value of 1 of 0. Should be set to 1 if this extension is critical or 0 + otherwise. + ``key-id``: key identifier represented in octet string. ``dn:``: is a CA distinguished name + ``cert-serial``: authority certificate serial number. + + - Add Issuer Alternative Name extension: + + The issuer alternative names extension allows additional identities to be associated with the + issuer of the CRL. Defined options include an rfc822 name (electronic mail address), a DNS + name, an IP address, and a URI. + + ``issuerAltNames`` *non-critical* *name-list* + + | Where: + + ``subjAltNames``: identifies the name of an extension + should be set to 0 since this is non-critical extension + ``name-list``: comma separated list of names + + - Add CRL Number extension: + + The CRL number is a non-critical CRL extension which conveys a monotonically increasing + sequence number for a given CRL scope and CRL issuer. This extension allows users to easily + determine when a particular CRL supersedes another CRL + + ``crlNumber`` *non-critical* *number* + + | Where: + + ``crlNumber``: identifies the name of an extension + ``critical``: should be set to 0 since this is non-critical extension + ``number``: value of ``long`` which identifies the sequential number of a CRL. + + - Add Revocation Reason Code extension: + + The reasonCode is a non-critical CRL entry extension that identifies the reason for the + certificate revocation. + + ``reasonCode`` *non-critical* *code* + + | Where: + + | ``reasonCode``: identifies the name of an extension + | ``non-critical``: should be set to 0 since this is non-critical extension + | ``code``: the following codes are available: + + unspecified (0), + keyCompromise (1), + cACompromise (2), + affiliationChanged (3), + superseded (4), + cessationOfOperation (5), + certificateHold (6), + removeFromCRL (8), + privilegeWithdrawn (9), + aACompromise (10) + + - Add Invalidity Date extension: + + The invalidity date is a non-critical CRL entry extension that provides the date on which it + is known or suspected that the private key was compromised or that the certificate otherwise + became invalid. + + invalidityDate *non-critical* *date* + + | Where: + + ``crlNumber``: identifies the name of an extension + ``non-critical``: should be set to 0 since this is non-critical extension ``date``: + invalidity date of a cert. Date should be represented in GeneralizedTime format + (YYYYMMDDhhmmssZ). + +.. _usage_2: + +` <#usage_2>`__ Usage +--------------------- + +.. container:: + + The Certificate Revocation List Management Tool's capabilities are grouped as follows, using + these combinations of options and arguments. Options and arguments in square brackets are + optional, those without square brackets are required. + + ``-G|-M -c crl-gen-file -n nickname [-i``\ *crl*\ ``] [-u``\ *url*\ ``] [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``] [-l``\ *alg*\ ``] [-a] [-B]`` + + .. + + ``-L [-n``\ *crl-name*\ ``] [-d``\ *krydir*\ ``]`` + + ``crlutil -D -n nickname [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``]`` + + .. + + ``crlutil -E [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``]`` + + ``crlutil -I -i crl [-t``\ *crlType*\ ``] [-u``\ *url*\ ``] [-d``\ *keydir*\ ``] [-P``\ *dbprefix*\ ``] [-B]`` + + - Creating or modifying a CRL: + - Listing all CRls or a named CRL: + - Deleting CRL from db: + - Erasing CRLs from db: + - Import CRL from file: + +.. _examples_2: + +` <#examples_2>`__ Examples +--------------------------- + +.. container:: + + | `Creating a New CRL <NSS_Tools_certutil#1028724>`__ + | `Listing CRLs in a Database <NSS_Tools_certutil#1034026>`__ + | `Deleting CRL from a Database <NSS_Tools_certutil#1034026>`__ + | `Importing CRL into a Database <NSS_Tools_certutil#1034026>`__ + | `Modifiying CRL in a Database <NSS_Tools_certutil#1034026>`__ + +.. _creating_a_new_crl: + +`Creating a New CRL <#creating_a_new_crl>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example creates a new CRL and importing it in to a Database in the specified directory: + + ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``-c``\ *crl-script-file* + + or + + ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``<<EOF update=20050204153000Z addcert 34-40 20050104153000Z EOF`` + + Where *cert-nickname* is the name the new CRL will be signed with. + +.. _listing_crls_in_a_database: + +`Listing CRLs in a Database <#listing_crls_in_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example lists all the CRLs in the ``NSS database`` in the specified directory: + + ``crlutil -L -d``\ *certdir* + + The CRL Management Tool displays output similar to the following: + + ``CRL Name CRL Type`` + + ``CN=NSS Test CA,O=BOGUS NSS,L=Mountain View,ST=California,C=US CRL CN=John Smith,O=Netscape,L=Mountain View,ST=California,C=US CRL`` + + | To view a particular CRL user should specify *-n nickname* parameter. + | ``crlutil -L -d``\ *certdir*\ ``-n`` *nickname* + + ``CRL Info: : Version: 2 (0x1) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: "CN=NSS Test CA,O=BOGUS NSS,L=Mountain View,ST=California,C=US" This Update: Wed Feb 23 12:08:38 2005 Entry (1): Serial Number: 40 (0x28) Revocation Date: Wed Feb 23 12:08:10 2005 Entry (2): Serial Number: 42 (0x2a) Revocation Date: Wed Feb 23 12:08:40 2005`` + +.. _deleting_crl_from_a_database: + +`Deleting CRL from a Database <#deleting_crl_from_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example deletes CRL from a database in the specified directory: + + ``crlutil -D -n``\ *nickname*\ ``-d``\ *certdir* + +.. _importing_crl_into_a_database: + +`Importing CRL into a Database <#importing_crl_into_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example imports CRL into a database: + + ``crlutil -I -i``\ *crl-file*\ ``-d``\ *certdir* + + File should has binary format of ASN.1 encoded CRL data. + +.. _modifying_crl_in_a_database: + +`Modifying CRL in a Database <#modifying_crl_in_a_database>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example modifies a new CRL and importing it in to a Database in the specified directory: + + ``crlutil -G -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``-c``\ *crl-script-file* + + or + + ``crlutil -M -d``\ *certdir*\ ``-n``\ *cert-nickname*\ ``<<EOF update=20050204153000Z addcert 40-60 20050105153000Z EOF`` + + The CRL Management Tool extracts existing CRL from a database, will modify and sign with + certificate *cert-nickname* and will store it in database. To modify while importing CRL from + file user should supply ``-i``\ *import-crl-file* option. + + --------------
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_dbck-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_dbck-tasks/index.rst new file mode 100644 index 0000000000..a9e8af546a --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_dbck-tasks/index.rst @@ -0,0 +1,28 @@ +.. _mozilla_projects_nss_tools_nss_tools_dbck-tasks: + +NSS Tools dbck-tasks +==================== + +.. _nss_security_tools_dbck_tasks: + +`NSS Security Tools: dbck Tasks <#nss_security_tools_dbck_tasks>`__ +------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. In analyze mode, there should be an option to create a file containing a graph of the + certificate database without any information about the user's certificates (no common names, + email addresses, etc.). This file could be mailed to a mail alias to assist in finding the + source of database corruption. + #. The dbck tool should be able to repair a currupted database. There should be command-line + options and, perhaps, an interactive mode to allow determine which certificates to keep. + #. The dbck tool should be able to update a databa
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_modutil-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_modutil-tasks/index.rst new file mode 100644 index 0000000000..ee10f77faa --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_modutil-tasks/index.rst @@ -0,0 +1,24 @@ +.. _mozilla_projects_nss_tools_nss_tools_modutil-tasks: + +NSS Tools modutil-tasks +======================= + +.. _nss_security_tools_modutil_tasks: + +`NSS Security Tools: modutil Tasks <#nss_security_tools_modutil_tasks>`__ +------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. The jar installation script is very fragile with respect to platform definitions (especially + version numbers). A fix was made for "HPUX B.11.00," but issues may still arise for platforms + like "Linux 2.2.12-20." Documentation needs to be explicit about the use of Fo
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_modutil/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_modutil/index.rst new file mode 100644 index 0000000000..58c9ab29a4 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_modutil/index.rst @@ -0,0 +1,912 @@ +.. _mozilla_projects_nss_tools_nss_tools_modutil: + +NSS Tools modutil +================= + +.. _using_the_security_module_database_(modutil): + +`Using the Security Module Database (modutil) <#using_the_security_module_database_(modutil)>`__ +------------------------------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + The Security Module Database Tool is a command-line utility for managing PKCS #11 module + information within ``secmod.db`` files or within hardware tokens. You can use the tool to add and + delete PKCS #11 modules, change passwords, set defaults, list module contents, enable or disable + slots, enable or disable FIPS 140-2 compliance, and assign default providers for cryptographic + operations. This tool can also create ``key3.db``, ``cert8.db``, and ``secmod.db`` security + database files. + + The tasks associated with security module database management are part of a process that + typically also involves managing key databases (``key3.db`` files) and certificate databases + (``cert8.db`` files). The key, certificate, and PKCS #11 module management process generally + begins with creating the keys and key database necessary to generate and manage certificates and + the certificate database. This document discusses security module database management. For + information on certificate database and key database management, see `Using the Certificate + Database Tool <certutil.html>`__. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + This tool is known to build on Solaris 2.5.1 (SunOS 5.5.1) and Windows NT 4.0. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run the Security Module Database Tool, type the command + ``modutil``\ *option*\ ``[``\ *arguments*\ ``]`` where *option* and *arguments* are combinations + of the options and arguments listed in the following section. Each command takes one option. Each + option may take zero or more arguments. To see a usage string, issue the command without options. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Options specify an action. Option arguments modify an action. The options and arguments for the + ``modutil`` command are defined as follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-create`` | Create new ``secmod.db``, ``key3.db``, and | + | | ``cert8.db`` files. Use the ``-dbdir`` | + | | *directory* argument to specify a directory. If | + | | any of these databases already exist in a | + | | specified directory, the Security Module | + | | Database Tool displays an error message. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-list [``\ *modulename*\ ``]`` | Display basic information about the contents of | + | | the ``secmod.db`` file. Use *modulename* to | + | | display detailed information about a particular | + | | module and its slots and tokens. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-add``\ *modulename* | Add the named PKCS #11 module to the database. | + | | Use this option with the ``-libfile``, | + | | ``-ciphers``, and ``-mechanisms`` arguments. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-jar``\ *JAR-file* | Add a new PKCS #11 module to the database using | + | | the named JAR file. Use this option with the | + | | ``-installdir`` and ``-tempdir`` arguments. The | + | | JAR file uses the Netscape Server PKCS #11 JAR | + | | format to identify all the files to be | + | | installed, the module's name, the mechanism | + | | flags, and the cipher flags. The JAR file | + | | should also contain any files to be installed | + | | on the target machine, including the PKCS #11 | + | | module library file and other files such as | + | | documentation. See the section `JAR | + | | Installation File <modutil.html#1043224>`__ for | + | | information on creating the special script | + | | needed to perform an installation through a | + | | server or with the Security Module Database | + | | Tool (that is, in environments without | + | | JavaScript support). For general installation | + | | instructions and to install a module in | + | | environments where JavaScript support is | + | | available (as in Netscape Communicator), see | + | | the document `Using the JAR Installation | + | | Manager to Install a PKCS #11 Cryptographic | + | | Module <http://developer.netscape.co | + | | m/docs/manuals/security/jmpkcs/jimpkcs.htm>`__. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-delete``\ *modulename* | Delete the named module. Note that you cannot | + | | delete the Netscape Communicator internal PKCS | + | | #11 module. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-changepw``\ *tokenname* | Change the password on the named token. If the | + | | token has not been initialized, this option | + | | initializes the password. Use this option with | + | | the ``-pwfile`` and ``-newpwfile`` arguments. | + | | In this context, the term "password" is | + | | equivalent to a personal identification number | + | | (PIN). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-default``\ *modulename* | Specify the security mechanisms for which the | + | | named module will be a default provider. The | + | | security mechanisms are specified with the | + | | ``-mechanisms`` *mechanism-list* argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-undefault``\ *modulename* | Specify the security mechanisms for which the | + | | named module will *not* be a default provider. | + | | The security mechanisms are specified with | + | | the\ ``-mechanisms`` *mechanism-list* argument. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-enable``\ *modulename* | Enable all slots on the named module. Use the | + | | ``[-slot``\ *slotname*\ ``]``\ argument to | + | | enable a specific slot. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-disable``\ *modulename* | Disable all slots on the named module. Use the | + | | ``[-slot``\ *slotname*\ ``]``\ argument to | + | | disable a specific slot. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-fips [true | false]`` | Enable (``true``) or disable (``false``) FIPS | + | | 140-2 compliance for the Netscape Communicator | + | | internal module. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-force`` | Disable the Security Module Database Tool's | + | | interactive prompts so it can be run from a | + | | script. Use this option only after manually | + | | testing each planned operation to check for | + | | warnings and to ensure that bypassing the | + | | prompts will cause no security lapses or loss | + | | of database integrity. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-dbdir``\ *directory* | Specify the database directory in which to | + | | access or create security module database | + | | files. On Unix, the Security Module Database | + | | Tool defaults to the user's Netscape directory. | + | | Windows NT has no default directory, so | + | | ``-dbdir`` must be used to specify a directory. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-dbprefix`` *prefix* | Specify the prefix used on the ``cert8.db`` and | + | | ``key3.db`` files (for example, ``my_cert8.db`` | + | | and ``my_key3.db``). This option is provided as | + | | a special case. Changing the names of the | + | | certificate and key databases is not | + | | recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-libfile``\ *library-file* | Specify a path to the DLL or other library file | + | | containing the implementation of the PKCS #11 | + | | interface module that is being added to the | + | | database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-ciphers``\ *cipher-enable-list* | Enable specific ciphers in a module that is | + | | being added to the database. The | + | | *cipher-enable-list* is a colon-delimited list | + | | of cipher names. Enclose this list in quotation | + | | marks if it contains spaces. The following | + | | cipher is currently available: ``FORTEZZA``. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-mechanisms``\ *mechanism-list* | Specify the security mechanisms for which a | + | | particular module will be flagged as a default | + | | provider. The *mechanism-list* is a | + | | colon-delimited list of mechanism names. | + | | Enclose this list in quotation marks if it | + | | contains spaces. The module becomes a default | + | | provider for the listed mechanisms when those | + | | mechanisms are enabled. If more than one module | + | | claims to be a particular mechanism's default | + | | provider, that mechanism's default provider is | + | | undefined. The following mechanisms are | + | | currently available: ``RSA``, ``DSA``, ``RC2``, | + | | ``RC4``, ``RC5``, ``DES``, ``DH``, | + | | ``FORTEZZA``, ``SHA1``, ``MD5``, ``MD2``, | + | | ``RANDOM`` (for random number generation), and | + | | ``FRIENDLY`` (meaning certificates are publicly | + | | readable). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-installdir``\ *root-installation-directory* | Specify the root installation directory | + | | relative to which files will be installed by | + | | the ``-jar`` *JAR-file* option. This directory | + | | should be one below which it is appropriate to | + | | store dynamic library files (for example, a | + | | server's root directory or the Netscape | + | | Communicator root directory). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-tempdir``\ *temporary-directory* | The temporary directory is the location where | + | | temporary files will be created in the course | + | | of installation by the ``-jar`` *JAR-file* | + | | option. If no temporary directory is specified, | + | | the current directory will be used. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-pwfile``\ *old-password-file* | Specify a text file containing a token's | + | | existing password so that a password can be | + | | entered automatically when the ``-changepw`` | + | | *tokenname* option is used to change passwords. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-newpwfile``\ *new-password-file* | Specify a text file containing a token's new or | + | | replacement password so that a password can be | + | | entered automatically with the ``-changepw`` | + | | *tokenname* option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-slot``\ *slotname* | Specify a particular slot to be enabled or | + | | disabled with the ``-enable`` *modulename* or | + | | ``-disable`` *modulename* options. | + +-------------------------------------------------+-------------------------------------------------+ + | -nocertdb | Do not open the certificate or key databases. | + | | This has several effects: | + | | | + | | - With the ``-create`` command, only a | + | | ``secmod.db`` file will be created; | + | | ``cert8.db`` and ``key3.db`` will not be | + | | created. | + | | - With the ``-jar`` command, signatures on the | + | | JAR file will not be checked. | + | | - With the ``-changepw`` command, the password | + | | on the Netscape internal module cannot be | + | | set or changed, since this password is | + | | stored in ``key3.db``. | + +-------------------------------------------------+-------------------------------------------------+ + +.. _usage_2: + +` <#usage_2>`__ Usage +--------------------- + +.. container:: + + The Security Module Database Tool's capabilities are grouped as follows, using these combinations + of options and arguments. The options and arguments in square brackets are optional, those + without square brackets are required. + + - Creating a set of security management database files (``key3.db``, ``cert8.db``, and + ``secmod.db``): + + ``-create`` + + - Displaying basic module information or detailed information about the contents of a given + module: + + ``-list [``\ *modulename*\ ``]`` + + - Adding a PKCS #11 module, which includes setting a supporting library file, enabling ciphers, + and setting default provider status for various security mechanisms: + + ``-add``\ *modulename*\ ``-libfile``\ *library-file* + ``[-ciphers``\ *cipher-enable-list*\ ``] [-mechanisms``\ *mechanism-list*\ ``]`` + + - Adding a PKCS #11 module from an existing JAR file: + + ``-jar``\ *JAR-file* ``-installdir``\ *root-installation-directory* + ``[-tempdir``\ *temporary-directory*\ ``]`` + + - Deleting a specific PKCS #11 module from a security module database: + + ``-delete``\ *modulename* + + - Initializing or changing a token's password: + + ``-changepw``\ *tokenname* + ``[-pwfile``\ *old-password-file*\ ``] [-newpwfile``\ *new-password-file*\ ``]`` + + - Setting the default provider status of various security mechanisms in an existing PKCS #11 + module: + + ``-default``\ *modulename* ``-mechanisms``\ *mechanism-list* + + - Clearing the default provider status of various security mechanisms in an existing PKCS #11 + module: + + ``-undefault``\ *modulename* ``-mechanisms``\ *mechanism-list* + + - Enabling a specific slot or all slots within a module: + + ``-enable``\ *modulename* ``[-slot``\ *slotname*\ ``]`` + + - Disabling a specific slot or all slots within a module: + + ``-disable``\ *modulename* ``[-slot``\ *slotname*\ ``]`` + + - Enabling or disabling FIPS 140-2 compliance within the Netscape Communicator internal module: + + ``-fips [true | false]`` + + - Disabling interactive prompts for the Security Module Database Tool, to support scripted + operation: + + ``-force`` + +.. _jar_installation_file: + +`JAR Installation File <#jar_installation_file>`__ +-------------------------------------------------- + +.. container:: + + When a JAR file is run by a server, by the Security Module Database Tool, or by any program that + does not interpret JavaScript, a special information file must be included in the format + described below. This information file contains special scripting and must be declared in the JAR + archive's manifest file. The script can have any name. The metainfo tag for this is + ``Pkcs11_install_script``. To declare meta-information in the manifest file, put it in a file + that is passed to the `Netscape Signing + Tool <http://developer.netscape.com/docs/manuals/signedobj/signtool/index.htm>`__. + +.. _sample_script: + +`Sample Script <#sample_script>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + For example, the PKCS #11 installer script could be in the file ``pk11install.`` If so, the + metainfo file for the `Netscape Signing + Tool <http://developer.netscape.com/docs/manuals/signedobj/signtool/index.htm>`__ would include a + line such as this: + .. code:: + + + Pkcs11_install_script: pk11install + + The sample script file could contain the following: + .. code:: + + ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc } + Platforms { + WINNT::x86 { + ModuleName { "Fortezza Module" } + ModuleFile { win32/fort32.dll } + DefaultMechanismFlags{0x0001} + DefaultCipherFlags{0x0001} + Files { + win32/setup.exe { + Executable + RelativePath { %temp%/setup.exe } + } + win32/setup.hlp { + RelativePath { %temp%/setup.hlp } + } + win32/setup.cab { + RelativePath { %temp%/setup.cab } + } + } + } + WIN95::x86 { + EquivalentPlatform {WINNT::x86} + } + SUNOS:5.5.1:sparc { + ModuleName { "Fortezza UNIX Module" } + ModuleFile { unix/fort.so } + DefaultMechanismFlags{0x0001} + CipherEnableFlags{0x0001} + Files { + unix/fort.so { + RelativePath{%root%/lib/fort.so} + AbsolutePath{/usr/local/netscape/lib/fort.so} + FilePermissions{555} + } + xplat/instr.html { + RelativePath{%root%/docs/inst.html} + AbsolutePath{/usr/local/netscape/docs/inst.html} + FilePermissions{555} + } + } + } + IRIX:6.2:mips { + EquivalentPlatform { SUNOS:5.5.1:sparc } + } + } + +.. _script_grammar: + +`Script Grammar <#script_grammar>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The script file grammar is as follows: + .. code:: + + --> valuelist + + .. code:: + + valuelist --> value valuelist + <null> + + .. code:: + + value ---> key_value_pair + string + + .. code:: + + key_value_pair --> key { valuelist } + + .. code:: + + key --> string + + .. code:: + + string --> simple_string + "complex_string" + + .. code:: + + simple_string --> [^ \t\n\""{""}"]+ + (No whitespace, quotes, or braces.) + + .. code:: + + complex_string --> ([^\"\\\r\n]|(\\\")|(\\\\))+ (Quotes and + backslashes must be escaped with a backslash. A complex string must not + include newlines or carriage returns.) + + Outside of complex strings, all white space (for example, spaces, tabs, and carriage returns) is + considered equal and is used only to delimit tokens. + +`Keys <#keys>`__ +~~~~~~~~~~~~~~~~ + +.. container:: + + Keys are case-insensitive. This section discusses the following keys: `Global + Keys <modutil.html#1042778>`__ + `Per-Platform Keys <modutil.html#1040459>`__ + `Per-File Keys <modutil.html#1040510>`__ + .. rubric:: Global Keys + :name: global_keys + + ``ForwardCompatible`` Gives a list of platforms that are forward compatible. If the current + platform cannot be found in the list of supported platforms, then the ``ForwardCompatible`` list + is checked for any platforms that have the same OS and architecture in an earlier version. If one + is found, its attributes are used for the current platform. ``Platforms`` (required) Gives a list + of platforms. Each entry in the list is itself a key-value pair: the key is the name of the + platform and the value list contains various attributes of the platform. The ``ModuleName``, + ``ModuleFile``, and ``Files`` attributes must be specified for each platform unless an + ``EquivalentPlatform`` attribute is specified. The platform string is in the following format: + *system name*\ ``:``\ *OS release*\ ``:``\ *architecture*. The installer obtains these values + from NSPR. *OS release* is an empty string on non-Unix operating systems. The following system + names and platforms are currently defined by NSPR: + + - AIX (rs6000) + - BSDI (x86) + - FREEBSD (x86) + - HPUX (hppa1.1) + - IRIX (mips) + - LINUX (ppc, alpha, x86) + - MacOS (PowerPC) + - NCR (x86) + - NEC (mips) + - OS2 (x86) + - OSF (alpha) + - ReliantUNIX (mips) + - SCO (x86) + - SOLARIS (sparc) + - SONY (mips) + - SUNOS (sparc) + - UnixWare (x86) + - WIN16 (x86) + - WIN95 (x86) + - WINNT (x86) + + Here are some examples of valid platform strings: + .. code:: + + IRIX:6.2:mips + SUNOS:5.5.1:sparc + Linux:2.0.32:x86 + WIN95::x86. + + .. rubric:: Per-Platform Keys + :name: per-platform_keys + + These keys have meaning only within the value list of an entry in the ``Platforms`` list. + ``ModuleName`` (required) Gives the common name for the module. This name will be used to + reference the module from Netscape Communicator, the Security Module Database tool (``modutil``), + servers, or any other program that uses the Netscape security module database. ``ModuleFile`` + (required) Names the PKCS #11 module file (DLL or ``.so``) for this platform. The name is given + as the relative path of the file within the JAR archive. ``Files`` (required) Lists the files + that need to be installed for this module. Each entry in the file list is a key-value pair: the + key is the path of the file in the JAR archive, and the value list contains attributes of the + file. At least ``RelativePath`` or ``AbsolutePath`` must be specified for each file. + ``DefaultMechanismFlags`` Specifies mechanisms for which this module will be a default provider. + This key-value pair is a bitstring specified in hexadecimal (0x) format. It is constructed as a + bitwise OR of the following constants. If the ``DefaultMechanismFlags`` entry is omitted, the + value defaults to 0x0. + .. code:: + + RSA: 0x00000001 + DSA: 0x00000002 + RC2: 0x00000004 + RC4: 0x00000008 + DES: 0x00000010 + DH: 0x00000020 + FORTEZZA: 0x00000040 + RC5: 0x00000080 + SHA1: 0x00000100 + MD5: 0x00000200 + MD2: 0x00000400 + RANDOM: 0x08000000 + FRIENDLY: 0x10000000 + OWN_PW_DEFAULTS: 0x20000000 + DISABLE: 0x40000000 + + ``CipherEnableFlags`` Specifies ciphers that this module provides but Netscape Communicator does + not, so that Communicator can enable them. This key is a bitstring specified in hexadecimal (0x) + format. It is constructed as a bitwise OR of the following constants. If the + ``CipherEnableFlags`` entry is omitted, the value defaults to 0x0. + .. code:: + + FORTEZZA: 0x0000 0001 + + ``EquivalentPlatform`` Specifies that the attributes of the named platform should also be used + for the current platform. Saves typing when there is more than one platform using the same + settings. + .. rubric:: Per-File Keys + :name: per-file_keys + + These keys have meaning only within the value list of an entry in a ``Files`` list. At least one + of ``RelativePath`` and ``AbsolutePath`` must be specified. If both are specified, the relative + path is tried first, and the absolute path is used only if no relative root directory is provided + by the installer program. ``RelativePath`` Specifies the destination directory of the file, + relative to some directory decided at install time. Two variables can be used in the relative + path: "``%root%``" and "``%temp%``". "``%root%``" is replaced at run time with the directory + relative to which files should be installed; for example, it may be the server's root directory + or the Netscape Communicator root directory. The "``%temp%``" directory is created at the + beginning of the installation and destroyed at the end. The purpose of "``%temp%``" is to hold + executable files (such as setup programs) or files that are used by these programs. For example, + a Windows installation might consist of a ``setup.exe`` installation program, a help file, and a + ``.cab`` file containing compressed information. All these files could be installed in the + temporary directory. Files destined for the temporary directory are guaranteed to be in place + before any executable file is run; they are not deleted until all executable files have finished. + ``AbsolutePath`` Specifies the destination directory of the file as an absolute path. If both + ``RelativePath`` and ``AbsolutePath`` are specified, the installer attempts to use the relative + path; if it is unable to determine a relative path, it uses the absolute path. ``Executable`` + Specifies that the file is to be executed during the course of the installation. Typically this + string would be used for a setup program provided by a module vendor, such as a self-extracting + ``setup.exe``. More than one file can be specified as executable, in which case the files are run + in the order in which they are specified in the script file. ``FilePermissions`` Interpreted as a + string of octal digits, according to the standard Unix format. This string is a bitwise OR of the + following constants: + .. code:: + + user read: 0400 + user write: 0200 + user execute: 0100 + group read: 0040 + group write: 0020 + group execute: 0010 + other read: 0004 + other write: 0002 + other execute: 0001 + + Some platforms may not understand these permissions. They are applied only insofar as they make + sense for the current platform. If this attribute is omitted, a default of 777 is assumed. + +.. _examples_2: + +` <#examples_2>`__ Examples +--------------------------- + +.. container:: + + `Creating Database Files <modutil.html#1028724>`__ + `Displaying Module Information <modutil.html#1034026>`__ + `Setting a Default Provider <modutil.html#1028731>`__ + `Enabling a Slot <modutil.html#1034020>`__ + `Enabling FIPS Compliance <modutil.html#1034010>`__ + `Adding a Cryptographic Module <modutil.html#1042489>`__ + `Installing a Cryptographic Module from a JAR File <modutil.html#1042502>`__ + `Changing the Password on a Token <modutil.html#1043961>`__ + +.. _creating_database_files: + +`Creating Database Files <#creating_database_files>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example creates a set of security management database files in the specified directory: + .. code:: + + modutil -create -dbdir c:\databases + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q <enter>' to abort, or <enter> to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Creating "c:\databases\key3.db"...done. + Creating "c:\databases\cert8.db"...done. + Creating "c:\databases\secmod.db"...done. + +.. _displaying_module_information: + +`Displaying Module Information <#displaying_module_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example gives detailed information about the specified module: + .. code:: + + modutil -list "Netscape Internal PKCS #11 Module" -dbdir c:\databases + + The Security Module Database Tool displays information similar to this: + .. code:: + + Using database directory c:\databases... + -------------------------------------------------------- + Name: Netscape Internal PKCS #11 Module + Library file: **Internal ONLY module** + Manufacturer: Netscape Communications Corp + Description: Communicator Internal Crypto Svc + PKCS #11 Version 2.0 + Library Version: 4.0 + Cipher Enable Flags: None + Default Mechanism Flags: RSA:DSA:RC2:RC4:DES:SHA1:MD5:MD2 + + .. code:: + + Slot: Communicator Internal Cryptographic Services Version 4.0 + Manufacturer: Netscape Communications Corp + Type: Software + Version Number: 4.1 + Firmware Version: 0.0 + Status: Enabled + Token Name: Communicator Generic Crypto Svcs + Token Manufacturer: Netscape Communications Corp + Token Model: Libsec 4.0 + Token Serial Number: 0000000000000000 + Token Version: 4.0 + Token Firmware Version: 0.0 + Access: Write Protected + Login Type: Public (no login required) + User Pin: NOT Initialized + + .. code:: + + Slot: Communicator User Private Key and Certificate Services + Manufacturer: Netscape Communications Corp + Type: Software + Version Number: 3.0 + Firmware Version: 0.0 + Status: Enabled + Token Name: Communicator Certificate DB + Token Manufacturer: Netscape Communications Corp + Token Model: Libsec 4.0 + Token Serial Number: 0000000000000000 + Token Version: 7.0 + Token Firmware Version: 0.0 + Access: NOT Write Protected + Login Type: Login required + User Pin: NOT Initialized + +.. _setting_a_default_provider: + +`Setting a Default Provider <#setting_a_default_provider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example makes the specified module a default provider for the RSA, DSA, and RC2 security + mechanisms: + .. code:: + + modutil -default "Cryptographic Module" -dbdir + c:\databases -mechanisms RSA:DSA:RC2 + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q <enter>' to abort, or <enter> to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + + .. code:: + + Successfully changed defaults. + +.. _enabling_a_slot: + +`Enabling a Slot <#enabling_a_slot>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example enables a particular slot in the specified module: + .. code:: + + modutil -enable "Cryptographic Module" -slot + "Cryptographic Reader" -dbdir c:\databases + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q <enter>' to abort, or <enter> to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + + .. code:: + + Slot "Cryptographic Reader" enabled. + +.. _enabling_fips_compliance: + +`Enabling FIPS Compliance <#enabling_fips_compliance>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example enables FIPS 140-2 compliance in Communicator's internal module: + .. code:: + + modutil -dbdir "C:\databases" -fips true + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while the browser is running could cause + corruption of your security databases. If the browser is currently running, + you should exit browser before continuing this operation. Type + 'q <enter>' to abort, or <enter> to continue: + + After you press Enter, the tool displays the following: + .. code:: + + FIPS mode enabled. + +.. _adding_a_cryptographic_module: + +`Adding a Cryptographic Module <#adding_a_cryptographic_module>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example adds a new cryptographic module to the database: + .. code:: + + C:\modutil> modutil -dbdir "C:\databases" -add "Cryptorific Module" - + libfile "C:\winnt\system32\crypto.dll" -mechanisms RSA:DSA:RC2:RANDOM + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q <enter>' to abort, or <enter> to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory C:\databases... + Module "Cryptorific Module" added to database. + C:\modutil> + +.. _installing_a_cryptographic_module_from_a_jar_file: + +`Installing a Cryptographic Module from a JAR File <#installing_a_cryptographic_module_from_a_jar_file>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example installs a cryptographic module from the following sample installation script. + .. code:: + + Platforms { + WinNT::x86 { + ModuleName { "Cryptorific Module" } + ModuleFile { crypto.dll } + DefaultMechanismFlags{0x0000} + CipherEnableFlags{0x0000} + Files { + crypto.dll { + RelativePath{ %root%/system32/crypto.dll } + } + setup.exe { + Executable + RelativePath{ %temp%/setup.exe } + } + } + } + Win95::x86 { + EquivalentPlatform { Winnt::x86 } + } + } + + To install from the script, use the following command. The root directory should be the Windows + root directory (for example, ``c:\\windows``, or ``c:\\winnt``). + .. code:: + + C:\modutil> modutil -dbdir "c:\databases" -jar + install.jar -installdir "C:/winnt" + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q <enter>' to abort, or <enter> to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + + .. code:: + + This installation JAR file was signed by: + ---------------------------------------------- + + .. code:: + + **SUBJECT NAME** + + .. code:: + + C=US, ST=California, L=Mountain View, CN=Cryptorific Inc., OU=Digital ID + Class 3 - Netscape Object Signing, OU="www.verisign.com/repository/CPS + Incorp. by Ref.,LIAB.LTD(c)9 6", OU=www.verisign.com/CPS Incorp.by Ref + . LIABILITY LTD.(c)97 VeriSign, OU=VeriSign Object Signing CA - Class 3 + Organization, OU="VeriSign, Inc.", O=VeriSign Trust Network **ISSUER + NAME**, OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 + VeriSign, OU=VeriSign Object Signing CA - Class 3 Organization, + OU="VeriSign, Inc.", O=VeriSign Trust Network + ---------------------------------------------- + + .. code:: + + Do you wish to continue this installation? (y/n) y + Using installer script "installer_script" + Successfully parsed installation script + Current platform is WINNT::x86 + Using installation parameters for platform WinNT::x86 + Installed file crypto.dll to C:/winnt/system32/crypto.dll + Installed file setup.exe to ./pk11inst.dir/setup.exe + Executing "./pk11inst.dir/setup.exe"... + "./pk11inst.dir/setup.exe" executed successfully + Installed module "Cryptorific Module" into module database + + .. code:: + + Installation completed successfully + C:\modutil> + +.. _changing_the_password_on_a_token: + +`Changing the Password on a Token <#changing_the_password_on_a_token>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This example changes the password for a token on an existing module. + .. code:: + + C:\modutil> modutil -dbdir "c:\databases" -changepw + "Communicator Certificate DB" + + The Security Module Database Tool displays a warning: + .. code:: + + WARNING: Performing this operation while Communicator is running could + cause corruption of your security databases. If Communicator is + currently running, you should exit Communicator before continuing this + operation. Type 'q <enter>' to abort, or <enter> to continue: + + After you press Enter, the tool displays the following: + .. code:: + + Using database directory c:\databases... + Enter old password: + Incorrect password, try again... + Enter old password: + Enter new password: + Re-enter new password: + Token "Communicator Certificate DB" password changed successfully. + C:\modutil> + + -------------- diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_pk12util-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util-tasks/index.rst new file mode 100644 index 0000000000..f7eae7a4a8 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util-tasks/index.rst @@ -0,0 +1,23 @@ +.. _mozilla_projects_nss_tools_nss_tools_pk12util-tasks: + +NSS Tools pk12util-tasks +======================== + +.. _nss_security_tools_pk12util_tasks: + +`NSS Security Tools: pk12util Tasks <#nss_security_tools_pk12util_tasks>`__ +--------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Need to migrate code to use an up-to-date version of NSS. + #. Use NSS functions in pcertdb for handling older database
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_pk12util/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util/index.rst new file mode 100644 index 0000000000..245173e02b --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_pk12util/index.rst @@ -0,0 +1,217 @@ +.. _mozilla_projects_nss_tools_nss_tools_pk12util: + +NSS Tools pk12util +================== + +.. _using_the_pkcs_12_tool_(pk12util): + +`Using the PKCS #12 Tool (pk12util) <#using_the_pkcs_12_tool_(pk12util)>`__ +--------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + The PKCS #12 utility makes sharing of certificates among Enterprise server 3.x and any server + (Netscape products or non-Netscape products) that supports PKCS#12 possible. The tool allows you + to import certificates and keys from pkcs #12 files into NSS or export them and also list + certificates and keys in such files. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + See the `release notes <../release_notes.html>`__ for the platforms this tool is available on. + +`Synopsis <#synopsis>`__ +------------------------ + +.. container:: + + **pk12util** ``-i p12File [-h tokenname] [-v] [common-options]`` + or + **pk12util** + ``-o p12File -n certname [-c keyCipher] [-C certCipher] [-m | --key_len keyLen] [-n | --cert_key_len certKeyLen] [common-options]`` + or + **pk12util** ``-l p12File [-h tokenname] [-r] [common-options]`` + where + **[common-options]** = + ``[-d dir] [-P dbprefix] [-k slotPasswordFile | -K slotPassword] [-w p12filePasswordFile | -W p12filePassword]`` + +`Syntax <#syntax>`__ +-------------------- + +.. container:: + + To run the PKCS #12 Tool, type the command ``pk12util`` *option*\ ``[``\ *arguments*\ ``]`` where + *option* and *arguments* are combinations of the options and arguments listed in the following + section. Three of the options, -i, -o, and -l, should be considered commands of the pk12util + invocation. Each command takes several options. Options may take zero or more arguments. To see a + usage string, issue the pkcs12util command without any options. + +.. _options_and_arguments: + +`Options and Arguments <#options_and_arguments>`__ +-------------------------------------------------- + +.. container:: + + Options specify an action. Option arguments modify an action. The options and arguments for the + ``pk12util`` command are defined as follows: + + +-------------------------------------------------+-------------------------------------------------+ + | **Options** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-i`` *p12file* | Import a certificate and private key from the | + | | p12file into the database. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-o`` *p12file* | Export certificate and private key, specified | + | | by the -n option, from the database to the p12 | + | | file. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l`` *p12file* | List certificate and private key from the | + | | ``p12file`` file. | + +-------------------------------------------------+-------------------------------------------------+ + | **Arguments** | | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n`` *certname* | Specify the nickname of the cert and private | + | | key to export. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-d`` *dir* | Specify the database directory into which to | + | | import to or export from certificates and keys. | + | | If not specified the directory defaults to | + | | $HOME/.netscape (when $HOME exists in the | + | | environment), or to ./.netscape (when $HOME | + | | does not exist in the environment). | + +-------------------------------------------------+-------------------------------------------------+ + | ``-P`` *prefix* | Specify the prefix used on the ``cert8.db`` and | + | | ``key3.db`` files (for example, ``my_cert8.db`` | + | | and ``my_key3.db``). This option is provided as | + | | a special case. Changing the names of the | + | | certificate and key databases is not | + | | recommended. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-h`` *tokenname* | Specify the name of the token to import into or | + | | export from | + +-------------------------------------------------+-------------------------------------------------+ + | ``-v`` | Enable debug logging when importing | + +-------------------------------------------------+-------------------------------------------------+ + | ``-k`` *slotPasswordFile* | Specify the text file containing the slot's | + | | password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-K`` *slotPassword* | Specify a slot's password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-w`` *p12filePasswordFile* | Specify the text file containing the pkcs 12 | + | | file's password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-W`` *p12filePassword* | Specify the pkcs 12 file's password | + +-------------------------------------------------+-------------------------------------------------+ + | ``-c`` *key-cipher* | Specify the key encryption algorithm | + +-------------------------------------------------+-------------------------------------------------+ + | ``-C`` *certCipher* | Specify the PFX encryption algorithm | + +-------------------------------------------------+-------------------------------------------------+ + | ``-m | --key_len`` * | Specify the desired length of the symmetric key | + | keyLen* | to be used to encrypt the private key | + +-------------------------------------------------+-------------------------------------------------+ + | ``-n | --cert_key_len`` * | Specify the desired length of the symmetric key | + | certLeyLen* | to be used to encrypt the top level protocol | + | | data unit | + +-------------------------------------------------+-------------------------------------------------+ + + +---+ + | | + +---+ + +.. _password_based_encryption: + +` <#password_based_encryption>`__ Password Based Encryption +----------------------------------------------------------- + +.. container:: + + PKCS #12 provides for not only the protection of the private keys but also the certificate and + meta-data associated with the keys. Password based encryption is used to protect private keys on + export to a PKCS #12 file and also the entire package when allowed. If no algorithm is specified, + the tool defaults to using "PKCS12 V2 PBE With SHA1 And 3KEY Triple DES-cbc" for private key + encryption. For historical export control reasons "PKCS12 V2 PBE With SHA1 And 40 Bit RC4" is the + default for the overall package encryption when not in FIPS mode and no package encryption when + in FIPS mode. The private key is always protected with strong encryption by default. A list of + ciphers follows. + + - symmetric CBC ciphers for PKCS #5 V2: + + - "DES_CBC" + - "RC2-CBC" + - "RC5-CBCPad" + - "DES-EDE3-CBC" + --- default for key encryption + - "AES-128-CBC" + - "AES-192-CBC" + - "AES-256-CBC" + - "CAMELLIA-128-CBC" + - "CAMELLIA-192-CBC" + - "CAMELLIA-256-CBC" + + - PKCS #12 PBE Ciphers: + + - "PKCS #12 PBE With Sha1 and 128 Bit RC4" + - "PKCS #12 PBE With Sha1 and 40 Bit RC4" + - "PKCS #12 PBE With Sha1 and Triple DES CBC" + - "PKCS #12 PBE With Sha1 and 128 Bit RC2 CBC" + - "PKCS #12 PBE With Sha1 and 40 Bit RC2 CBC" + - "PKCS12 V2 PBE With SHA1 And 128 Bit RC4" + - "PKCS12 V2 PBE With SHA1 And 40 Bit RC4" + --- default for PFX encryption in non-fips mode, no encryption on fips mode + - "PKCS12 V2 PBE With SHA1 And 3KEY Triple DES-cbc" + - "PKCS12 V2 PBE With SHA1 And 2KEY Triple DES-cbc" + - "PKCS12 V2 PBE With SHA1 And 128 Bit RC2 CBC" + - "PKCS12 V2 PBE With SHA1 And 40 Bit RC2 CBC" + + - PKCS #5 PBE Ciphers: + + - "PKCS #5 Password Based Encryption with MD2 and DES CBC" + - "PKCS #5 Password Based Encryption with MD5 and DES CBC" + - "PKCS #5 Password Based Encryption with SHA1 and DES CBC" + + It should be noted that the crypto provider may be the softtoken module or an external hardware + module. It may be the case that the cryptographic module does not support the requested algorithm + and a best fit will be selected, likely to be the default. If no suitable replacement for the + desired algorithm can be found a "no security module can perform the requested operation" will + appear on the error message. + +.. _error_codes: + +` <#error_codes>`__ Error Codes +------------------------------- + +.. container:: + + **pk12util** can return the following values: + | **0** - No error + | **1** - User Cancelled + | **2** - Usage error + | **6** - NLS init error + | **8** - Certificate DB open error + | **9** - Key DB open error + | **10** - File initialization error + | **11** - Unicode conversion error + | **12** - Temporary file creation error + | **13** - PKCS11 get slot error + | **14** - PKCS12 decoder start error + | **15** - error read from import file + | **16** - pkcs12 decode error + | **17** - pkcs12 decoder verify error + | **18** - pkcs12 decoder validate bags error + | **19** - pkcs12 decoder import bags error + | **20** - key db conversion version 3 to version 2 error + | **21** - cert db conversion version 7 to version 5 error + | **22** - cert and key dbs patch error + | **23** - get default cert db error + | **24** - find cert by nickname error + | **25** - create export context error + | **26** - PKCS12 add password itegrity error + | **27** - cert and key Safes creation error + | **28** - PKCS12 add cert and key error + | **29** - PKCS12 encode error
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_signver-tasks/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_signver-tasks/index.rst new file mode 100644 index 0000000000..f8a29cd4e6 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_signver-tasks/index.rst @@ -0,0 +1,22 @@ +.. _mozilla_projects_nss_tools_nss_tools_signver-tasks: + +NSS Tools signver-tasks +======================= + +.. _nss_security_tools_signver_tasks: + +`NSS Security Tools: signver Tasks <#nss_security_tools_signver_tasks>`__ +------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +.. _task_list: + +`Task List <#task_list>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. Remove private hash algortihms and replace with code in lib/hash, lib/crypto, and
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_sslstrength/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_sslstrength/index.rst new file mode 100644 index 0000000000..b1b6b5dd50 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_sslstrength/index.rst @@ -0,0 +1,87 @@ +.. _mozilla_projects_nss_tools_nss_tools_sslstrength: + +NSS Tools sslstrength +===================== + +`sslstrength <#sslstrength>`__ +------------------------------ + +.. container:: + +`Summary <#summary>`__ +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A simple command-line client which connects to an SSL-server, and reports back the encryption + cipher and strength used. + +`Synopsis <#synopsis>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + 1) sslstrength ciphers + + 2) sslstrength hostname[:port] [ciphers=xyz] [debug] [verbose] [policy=export|domestic] + +`Description <#description>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The first form simple lists out the possible ciphers. The letter in the first column of the + output is used to identify the cipher preferences in the ciphers= command. + + The second form attempts to connect to the named ssl host. The hostname argument must be present. + However, the port number is an optional argument, and if not given, will default to the https + port (443). + + .. rubric:: Restricting Ciphers + :name: restricting_ciphers + + By default, sslstrength assumes that all the preferences are on, so it will use any preferences + in your policy. The enabled ciphersuites will always be printed out before the connection is + made. If you want to test out a particular cipher, there are two ways to affect which ciphers are + available. Firstly, you can set **policy** to be either domestic or export. This restricts the + available ciphers to the same set used by Communicator. In addition to this, the **ciphers** + command can be used to further restrict the ciphers available. The argument to the ciphers + command is a string of characters, where each single character represents a cipher. You can + obtain this list of character->cipher mappings by doing 'sslstrength ciphers'. For example, + + ** ciphers=bfi** will turn on these cipher preferences and turn off all others. + + ** policy=export** or **policy=domestic** will set your policies appropriately. + + | ** policy** will default to domestic if not specified. + | + + .. rubric:: Step-up + :name: step-up + + Step up is a mode where the connection starts out with 40-bit encryption, but due to a + 'change-cipher-spec' handshake, changes to 128-bit encryption. This is only done in 'export + mode', with servers with a special certificate. You can tell if you stepped-up, because the + output will says 'using export policy', and you'll find the secret key size was 128-bits. + +`Prerequisites <#prerequisites>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + | You should have a cert7.db in the directory in which you run sslstrength. + | + +`Other <#other>`__ +~~~~~~~~~~~~~~~~~~ + +.. container:: + + | For references, here is a table of well-known SSL port numbers: + | + + ===== === + HTTPS 443 + IMAPS 993 + NNTPS 563 + ===== ===
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/nss_tools_ssltap/index.rst b/security/nss/doc/rst/legacy/tools/nss_tools_ssltap/index.rst new file mode 100644 index 0000000000..61544ea830 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/nss_tools_ssltap/index.rst @@ -0,0 +1,621 @@ +.. _mozilla_projects_nss_tools_nss_tools_ssltap: + +NSS Tools ssltap +================ + +.. _using_the_ssl_debugging_tool_(ssltap): + +`Using the SSL Debugging Tool (ssltap) <#using_the_ssl_debugging_tool_(ssltap)>`__ +---------------------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + The SSL Debugging Tool is an SSL-aware command-line proxy. It watches TCP connections and + displays the data going by. If a connection is SSL, the data display includes interpreted SSL + records and handshaking. + +.. _availability_2: + +` <#availability_2>`__ Availability +----------------------------------- + +.. container:: + + This tool is known to build on Solaris 2.5.1 (SunOS 5.5.1) and Windows NT 4.0. + +.. _description_2: + +` <#description_2>`__ Description +--------------------------------- + +.. container:: + + The ``ssltap`` command opens a socket on a rendezvous port and waits for an incoming connection + from the client side. Once this connection arrives, the tool makes another connection to the + specified host name and port on the server side. It passes any data sent by the client to the + server and vice versa. The tool also displays the data to the shell window from which it was + called. It can do this for plain HTTP connections or any TCP protocol, as well as for SSL + streams, as described here. The tool cannot and does not decrypt any encrypted message data. You + use the tool to look at the plain text and binary data that are part of the handshake procedure, + before the secure connection is established. + +.. _syntax_2: + +` <#syntax_2>`__ Syntax +----------------------- + +.. container:: + + To run the SSL Debugging Tool, type this command in a command shell: ``ssltap`` [``-vhfsxl``] + [``-p`` *port*] *hostname*:*port* + +` <#options>`__ Options +~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The command does not require any options other than *hostname:port*, but you normally use them to + control the connection interception and output. The options for the command are the following: + + +-------------------------------------------------+-------------------------------------------------+ + | ``-v`` | Print a version string for the tool. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-h`` | Turn on hex/ASCII printing. Instead of | + | | outputting raw data, the command interprets | + | | each record as a numbered line of hex values, | + | | followed by the same data as ASCII characters. | + | | The two parts are separated by a vertical bar. | + | | Nonprinting characters are replaced by dots. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-f`` | Turn on fancy printing. Output is printed in | + | | colored HTML. Data sent from the client to the | + | | server is in blue; the server's reply is in | + | | red. When used with looping mode, the different | + | | connections are separated with horizontal | + | | lines. You can use this option to upload the | + | | output into a browser. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-s`` | Turn on SSL parsing and decoding. The tool does | + | | not automatically detect SSL sessions. If you | + | | are intercepting an SSL connection, use this | + | | option so that the tool can detect and decode | + | | SSL structures. | + | | | + | | If the tool detects a certificate chain, it | + | | saves the DER-encoded certificates into files | + | | in the current directory. The files are named | + | | ``cert.0``\ *x*, where *x* is the sequence | + | | number of the certificate. | + | | | + | | If the ``-s`` option is used with ``-h``, two | + | | separate parts are printed for each record: the | + | | plain hex/ASCII output, and the parsed SSL | + | | output. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-x`` | Turn on hex/ASCII printing of undecoded data | + | | inside parsed SSL records. Used only with the | + | | ``-s`` option. This option uses the same output | + | | format as the ``-h`` option. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-l`` | Turn on looping; that is, continue to accept | + | | connections rather than stopping after the | + | | first connection is complete. | + +-------------------------------------------------+-------------------------------------------------+ + | ``-p``\ *port* | Change the default rendezvous port (1924) to | + | | another port. The following are well-known port | + | | numbers: | + | | | + | | HTTP 80 | + | | | + | | HTTPS 443 | + | | | + | | SMTP 25 | + | | | + | | FTP 21 | + | | | + | | IMAP 143 | + | | | + | | IMAPS 993 (IMAP over SSL) | + | | | + | | NNTP 119 | + | | | + | | NNTPS 563 (NNTP over SSL) | + +-------------------------------------------------+-------------------------------------------------+ + +.. _examples_2: + +` <#examples_2>`__ Examples +--------------------------- + +.. container:: + + You can use the SSL Debugging Tool to intercept any connection information. Although you can run + the tool at its most basic by issuing the ``ssltap`` command with no options other than + *hostname:port*, the information you get in this way is not very useful. For example, assume your + development machine is called ``intercept``. The simplest way to use the debugging tool is to + execute the following command from a command shell: + .. code:: + + ssltap www.netscape.com:80 + + The program waits for an incoming connection on the default port 1924. In your browser window, + enter the URL ``http://intercept:1924``. The browser retrieves the requested page from the server + at ``www.netscape.com``, but the page is intercepted and passed on to the browser by the + debugging tool on ``intercept``. On its way to the browser, the data is printed to the command + shell from which you issued the command. Data sent from the client to the server is surrounded by + the following symbols: ``--> [``\ *data*\ ``]`` Data sent from the server to the client is + surrounded by the following symbols: ``<-- [``\ *data*\ ``]`` The raw data stream is sent to + standard output and is not interpreted in any way. This can result in peculiar effects, such as + sounds, flashes, and even crashes of the command shell window. To output a basic, printable + interpretation of the data, use the ``-h`` option, or, if you are looking at an SSL connection, + the ``-s`` option. You will notice that the page you retrieved looks incomplete in the browser. + This is because, by default, the tool closes down after the first connection is complete, so the + browser is not able to load images. To make the tool continue to accept connections, switch on + looping mode with the ``-l`` option. The following examples show the output from commonly used + combinations of options. + .. rubric:: Example 1 + :name: example_1 + + The ``s`` and ``x`` options in this example turn on SSL parsing and show undecoded values in + hex/ASCII format. The output is routed to a text file. + .. rubric:: Command + :name: command + + .. code:: + + ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt + + .. rubric:: Output + :name: output + + Output + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + alloclen = 66 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher-specs-length = 39 (0x27) + sid-length = 0 (0x00) + challenge-length = 16 (0x10) + cipher-suites = { + + .. code:: + + (0x010080) SSL2/RSA/RC4-128/MD5 + (0x020080) SSL2/RSA/RC4-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x040080) SSL2/RSA/RC2CBC40/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + (0x000004) SSL3/RSA/RC4-128/MD5 + (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4-40/MD5 + (0x000006) SSL3/RSA/RC2CBC40/MD5 + } + session-id = { } + challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 + + .. code:: + + 0x2592 } + } + ] + <-- [ + SSLRecord { + 0: 16 03 00 03 e5 |..... + type = 22 (handshake) + version = { 3,0 } + length = 997 (0x3e5) + handshake { + 0: 02 00 00 46 |...F + type = 2 (server_hello) + length = 70 (0x000046) + ServerHello { + server_version = {3, 0} + random = {...} + 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 | + wn&l.ì..XOG.-.E + 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f | + + .. code:: + + \.uC§L.Ç.d<PAHO. + session ID = { + length = 32 + + .. code:: + + contents = {..} + 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 | ...¨*1.)..@7W.§2 + 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 | VoRbþ=³e±...R£È. + } + cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + } + 0: 0b 00 02 c5 |...Å + type = 11 (certificate) + length = 709 (0x0002c5) + CertificateChain { + chainlength = 706 (0x02c2) + Certificate { + size = 703 (0x02bf) + data = { saved in file 'cert.001' } + } + } + 0: 0c 00 00 ca |.... + type = 12 (server_key_exchange) + length = 202 (0x0000ca) + 0: 0e 00 00 00 |.... + type = 14 (server_hello_done) + length = 0 (0x000000) + } + } + ] + --> [ + SSLRecord { + 0: 16 03 00 00 44 |....D + type = 22 (handshake) + version = { 3,0 } + length = 68 (0x44) + handshake { + 0: 10 00 00 40 |...@ + type = 16 (client_key_exchange) + length = 64 (0x000040) + ClientKeyExchange { + message = {...} + } + } + } + ] + --> [ + SSLRecord { + 0: 14 03 00 00 01 |..... + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + 0: 01 |. + } + SSLRecord { + 0: 16 03 00 00 38 |....8 + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + + .. code:: + + } + ] + <-- [ + SSLRecord { + 0: 14 03 00 00 01 |..... + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + 0: 01 |. + } + ] + <-- [ + SSLRecord { + 0: 16 03 00 00 38 |....8 + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + + .. code:: + + } + ] + --> [ + SSLRecord { + 0: 17 03 00 01 1f |..... + type = 23 (application_data) + version = { 3,0 } + length = 287 (0x11f) + < encrypted > + } + ] + <-- [ + SSLRecord { + 0: 17 03 00 00 a0 |.... + type = 23 (application_data) + version = { 3,0 } + length = 160 (0xa0) + < encrypted > + + .. code:: + + } + ] + <-- [ + SSLRecord { + 0: 17 03 00 00 df |....ß + type = 23 (application_data) + version = { 3,0 } + length = 223 (0xdf) + < encrypted > + + .. code:: + + } + SSLRecord { + 0: 15 03 00 00 12 |..... + type = 21 (alert) + version = { 3,0 } + length = 18 (0x12) + < encrypted > + } + ] + Server socket closed. + + .. rubric:: Example 2 + :name: example_2 + + The ``-s`` option turns on SSL parsing. Because the ``-x`` option is not used in this example, + undecoded values are output as raw data. The output is routed to a text file. + .. rubric:: Command + :name: command_2 + + .. code:: + + ssltap.exe -s -p 444 interzone.mcom.com:443 > s.txt + + .. rubric:: Output + :name: output_2 + + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + alloclen = 63 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher-specs-length = 36 (0x24) + sid-length = 0 (0x00) + challenge-length = 16 (0x10) + cipher-suites = { + (0x010080) SSL2/RSA/RC4-128/MD5 + (0x020080) SSL2/RSA/RC4-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + (0x000004) SSL3/RSA/RC4-128/MD5 + (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4-40/MD5 + } + session-id = { } + challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c + 0x3fd0 } + ] + <-- [ + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 997 (0x3e5) + handshake { + type = 2 (server_hello) + length = 70 (0x000046) + ServerHello { + server_version = {3, 0} + random = {...} + session ID = { + length = 32 + contents = {..} + } + cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + } + type = 11 (certificate) + length = 709 (0x0002c5) + CertificateChain { + chainlength = 706 (0x02c2) + Certificate { + size = 703 (0x02bf) + data = { saved in file 'cert.001' } + } + } + type = 12 (server_key_exchange) + length = 202 (0x0000ca) + type = 14 (server_hello_done) + length = 0 (0x000000) + } + } + ] + --> [ + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 68 (0x44) + handshake { + type = 16 (client_key_exchange) + length = 64 (0x000040) + ClientKeyExchange { + message = {...} + } + } + } + ] + --> [ + SSLRecord { + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + } + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + } + ] + <-- [ + SSLRecord { + type = 20 (change_cipher_spec) + version = { 3,0 } + length = 1 (0x1) + } + ] + <-- [ + SSLRecord { + type = 22 (handshake) + version = { 3,0 } + length = 56 (0x38) + < encrypted > + } + ] + --> [ + SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 287 (0x11f) + < encrypted > + } + ] + [ + SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 160 (0xa0) + < encrypted > + } + ] + <-- [ + SSLRecord { + type = 23 (application_data) + version = { 3,0 } + length = 223 (0xdf) + < encrypted > + } + SSLRecord { + type = 21 (alert) + version = { 3,0 } + length = 18 (0x12) + < encrypted > + } + ] + Server socket closed. + + .. rubric:: Example 3 + :name: example_3 + + In this example, the ``-h`` option turns hex/ASCII format. There is no SSL parsing or decoding. + The output is routed to a text file. + .. rubric:: Command + :name: command_3 + + .. code:: + + ssltap.exe -h -p 444 interzone.mcom.com:443 > h.txt + + .. rubric:: Output + :name: output_3 + + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 | .@....'......... + 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@...... + 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 | ........á....... + 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 | ..þ[V.I.\xd9 ...º¹R + 40: 6f 2d |o- + ] + <-- [ + 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d | ........F....... + 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b | h.:y`..<..³.Òi; + 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 | x.K.¦R.KFè. ... + 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 | MR.ý..QH.....¶vw + 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b | *ô..¡.a¢d...... + 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 | ..Å......0...0.. + 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 | $ .......60...*. + 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 | H.÷......0w1.0.. + 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 | .U....US1,0*..U. + 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d | ..#Netscape Comm + a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f | unications Corpo + b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 | ration1.0...U... + c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 | .Hardcore1'0%..U + d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 | ....Hardcore Cer + e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 | tificate Server + f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 | II0...9805160103 + <additional data lines> + ] + <additional records in same format> + Server socket closed. + + .. rubric:: Example 4 + :name: example_4 + + In this example, the ``-s`` option turns on SSL parsing, and the ``-h`` options turns on + hex/ASCII format. Both formats are shown for each record. The output is routed to a text file. + .. rubric:: Command + :name: command_4 + + .. code:: + + ssltap.exe -hs -p 444 interzone.mcom.com:443 > hs.txt + + .. rubric:: Output + :name: output_4 + + .. code:: + + Connected to interzone.mcom.com:443 + --> [ + 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 | .=....$......... + 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 | .........@...... + 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 | ........á....... + 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 |U..yÇ\xb0 ,.x.]µÏé + alloclen = 63 bytes + [ssl2] ClientHelloV2 { + version = {0x03, 0x00} + cipher-specs-length = 36 (0x24) + sid-length = 0 (0x00) + challenge-length = 16 (0x10) + cipher-suites = { + (0x010080) SSL2/RSA/RC4-128/MD5 + (0x020080) SSL2/RSA/RC4-40/MD5 + (0x030080) SSL2/RSA/RC2CBC128/MD5 + (0x040080) SSL2/RSA/RC2CBC40/MD5 + (0x060040) SSL2/RSA/DES64CBC/MD5 + (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + (0x000004) SSL3/RSA/RC4-128/MD5 + (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + (0x000009) SSL3/RSA/DES64CBC/SHA + (0x000003) SSL3/RSA/RC4-40/MD5 + } + session-id = { } + challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db + + 0xcfe9 } + } + ] + <additional records in same formats> + Server socket closed. + +.. _usage_tips: + +`Usage Tips <#usage_tips>`__ +---------------------------- + +.. container:: + + - When SSL restarts a previous session, it makes use of cached information to do a partial + handshake. If you wish to capture a full SSL handshake, restart the browser to clear the + session id cache. + - If you run the tool on a machine other than the SSL server to which you are trying to connect, + the browser will complain that the host name you are trying to connect to is different from + the certificate. If you are using the default BadCert callback, you can still connect through + a dialog. If you are not using the default BadCert callback, the one you supply must allow for + this possibility. + + --------------
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/pk12util/index.rst b/security/nss/doc/rst/legacy/tools/pk12util/index.rst new file mode 100644 index 0000000000..b08da3276f --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/pk12util/index.rst @@ -0,0 +1,282 @@ +.. _mozilla_projects_nss_tools_pk12util: + +NSS tools : pk12util +==================== + +.. container:: + + | Name + | pk12util — Export and import keys and certificate to or from a PKCS #12 + | file and the NSS database + | Synopsis + | pk12util [-i p12File [-h tokenname] [-v] [common-options] ] [ -l p12File + | [-h tokenname] [-r] [common-options] ] [ -o p12File -n certname [-c + | keyCipher] [-C certCipher] [-m|--key_len keyLen] [-n|--cert_key_len + | certKeyLen] [common-options] ] [ common-options are: [-d [sql:]directory] + | [-P dbprefix] [-k slotPasswordFile|-K slotPassword] [-w + | p12filePasswordFile|-W p12filePassword] ] + | Description + | The PKCS #12 utility, pk12util, enables sharing certificates among any + | server that supports PKCS#12. The tool can import certificates and keys + | from PKCS#12 files into security databases, export certificates, and list + | certificates and keys. + | Options and Arguments + | Options + | -i p12file + | Import keys and certificates from a PKCS#12 file into a security + | database. + | -l p12file + | List the keys and certificates in PKCS#12 file. + | -o p12file + | Export keys and certificates from the security database to a + | PKCS#12 file. + | Arguments + | -n certname + | Specify the nickname of the cert and private key to export. + | -d [sql:]directory + | Specify the database directory into which to import to or export + | from certificates and keys. + | pk12util supports two types of databases: the legacy security + | databases (cert8.db, key3.db, and secmod.db) and new SQLite + | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | -P prefix + | Specify the prefix used on the certificate and key databases. This + | option is provided as a special case. Changing the names of the + | certificate and key databases is not recommended. + | -h tokenname + | Specify the name of the token to import into or export from. + | -v + | Enable debug logging when importing. + | -k slotPasswordFile + | Specify the text file containing the slot's password. + | -K slotPassword + | Specify the slot's password. + | -w p12filePasswordFile + | Specify the text file containing the pkcs #12 file password. + | -W p12filePassword + | Specify the pkcs #12 file password. + | -c keyCipher + | Specify the key encryption algorithm. + | -C certCipher + | Specify the key cert (overall package) encryption algorithm. + | -m \| --key-len keyLength + | Specify the desired length of the symmetric key to be used to + | encrypt the private key. + | -n \| --cert-key-len certKeyLength + | Specify the desired length of the symmetric key to be used to + | encrypt the certificates and other meta-data. + | -r + | Dumps all of the data in raw (binary) form. This must be saved as + | a DER file. The default is to return information in a pretty-print + | ASCII format, which displays the information about the + | certificates and public keys in the p12 file. + | Return Codes + | o 0 - No error + | o 1 - User Cancelled + | o 2 - Usage error + | o 6 - NLS init error + | o 8 - Certificate DB open error + | o 9 - Key DB open error + | o 10 - File initialization error + | o 11 - Unicode conversion error + | o 12 - Temporary file creation error + | o 13 - PKCS11 get slot error + | o 14 - PKCS12 decoder start error + | o 15 - error read from import file + | o 16 - pkcs12 decode error + | o 17 - pkcs12 decoder verify error + | o 18 - pkcs12 decoder validate bags error + | o 19 - pkcs12 decoder import bags error + | o 20 - key db conversion version 3 to version 2 error + | o 21 - cert db conversion version 7 to version 5 error + | o 22 - cert and key dbs patch error + | o 23 - get default cert db error + | o 24 - find cert by nickname error + | o 25 - create export context error + | o 26 - PKCS12 add password itegrity error + | o 27 - cert and key Safes creation error + | o 28 - PKCS12 add cert and key error + | o 29 - PKCS12 encode error + | Examples + | Importing Keys and Certificates + | The most basic usage of pk12util for importing a certificate or key is the + | PKCS#12 input file (-i) and some way to specify the security database + | being accessed (either -d for a directory or -h for a token). + | pk12util -i p12File [-h tokenname] [-v] [-d [sql:]directory] [-P dbprefix] [-k + slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] + | For example: + | # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb + | Enter a password which will be used to encrypt your keys. + | The password should be at least 8 characters long, + | and should contain at least one non-alphabetic character. + | Enter new password: + | Re-enter password: + | Enter password for PKCS12 file: + | pk12util: PKCS12 IMPORT SUCCESSFUL + | Exporting Keys and Certificates + | Using the pk12util command to export certificates and keys requires both + | the name of the certificate to extract from the database (-n) and the + | PKCS#12-formatted output file to write to. There are optional parameters + | that can be used to encrypt the file to protect the certificate material. + | pk12util -o p12File -n certname [-c keyCipher] [-C certCipher] [-m|--key_len keyLen] + [-n|--cert_key_len certKeyLen] [-d [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K + slotPassword] [-w p12filePasswordFile|-W p12filePassword] + | For example: + | # pk12util -o certs.p12 -n Server-Cert -d sql:/home/my/sharednssdb + | Enter password for PKCS12 file: + | Re-enter password: + | Listing Keys and Certificates + | The information in a .p12 file are not human-readable. The certificates + | and keys in the file can be printed (listed) in a human-readable + | pretty-print format that shows information for every certificate and any + | public keys in the .p12 file. + | pk12util -l p12File [-h tokenname] [-r] [-d [sql:]directory] [-P dbprefix] [-k + slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] + | For example, this prints the default ASCII output: + | # pk12util -l certs.p12 + | Enter password for PKCS12 file: + | Key(shrouded): + | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID + | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC + | Parameters: + | Salt: + | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f + | Iteration Count: 1 (0x1) + | Certificate: + | Data: + | Version: 3 (0x2) + | Serial Number: 13 (0xd) + | Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption + | Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C + | A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T + | own,ST=Western Cape,C=ZA" + | .... + | Alternatively, the -r prints the certificates and then exports them into + | separate DER binary files. This allows the certificates to be fed to + | another application that supports .p12 files. Each certificate is written + | to a sequentially-number file, beginning with file0001.der and continuing + | through file000N.der, incrementing the number for every certificate: + | # pk12util -l test.p12 -r + | Enter password for PKCS12 file: + | Key(shrouded): + | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID + | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC + | Parameters: + | Salt: + | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f + | Iteration Count: 1 (0x1) + | Certificate Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting + | Certificate Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID + | Password Encryption + | PKCS#12 provides for not only the protection of the private keys but also + | the certificate and meta-data associated with the keys. Password-based + | encryption is used to protect private keys on export to a PKCS#12 file + | and, optionally, the entire package. If no algorithm is specified, the + | tool defaults to using PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc for + | private key encryption. PKCS12 V2 PBE with SHA1 and 40 Bit RC4 is the + | default for the overall package encryption when not in FIPS mode. When in + | FIPS mode, there is no package encryption. + | The private key is always protected with strong encryption by default. + | Several types of ciphers are supported. + | Symmetric CBC ciphers for PKCS#5 V2 + | DES_CBC + | o RC2-CBC + | o RC5-CBCPad + | o DES-EDE3-CBC (the default for key encryption) + | o AES-128-CBC + | o AES-192-CBC + | o AES-256-CBC + | o CAMELLIA-128-CBC + | o CAMELLIA-192-CBC + | o CAMELLIA-256-CBC + | PKCS#12 PBE ciphers + | PKCS #12 PBE with Sha1 and 128 Bit RC4 + | o PKCS #12 PBE with Sha1 and 40 Bit RC4 + | o PKCS #12 PBE with Sha1 and Triple DES CBC + | o PKCS #12 PBE with Sha1 and 128 Bit RC2 CBC + | o PKCS #12 PBE with Sha1 and 40 Bit RC2 CBC + | o PKCS12 V2 PBE with SHA1 and 128 Bit RC4 + | o PKCS12 V2 PBE with SHA1 and 40 Bit RC4 (the default for + | non-FIPS mode) + | o PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc + | o PKCS12 V2 PBE with SHA1 and 2KEY Triple DES-cbc + | o PKCS12 V2 PBE with SHA1 and 128 Bit RC2 CBC + | o PKCS12 V2 PBE with SHA1 and 40 Bit RC2 CBC + | PKCS#5 PBE ciphers + | PKCS #5 Password Based Encryption with MD2 and DES CBC + | o PKCS #5 Password Based Encryption with MD5 and DES CBC + | o PKCS #5 Password Based Encryption with SHA1 and DES CBC + | With PKCS#12, the crypto provider may be the soft token module or an + | external hardware module. If the cryptographic module does not support the + | requested algorithm, then the next best fit will be selected (usually the + | default). If no suitable replacement for the desired algorithm can be + | found, the tool returns the error no security module can perform the + | requested operation. + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | BerkeleyDB has performance limitations, though, which prevent it from + | being easily used by multiple applications simultaneously. NSS has some + | flexibility that allows applications to use their own, independent + | database engine while keeping a shared database and working around the + | access issues. Still, NSS requires more flexibility to provide a truly + | shared security database. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | Most applications do not use the shared database by default, but they can + | be configured to use them. For example, this how-to article covers how to + | configure Firefox and Thunderbird to use the new shared NSS databases: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | certutil (1) + | modutil (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/signtool/index.rst b/security/nss/doc/rst/legacy/tools/signtool/index.rst new file mode 100644 index 0000000000..5e67407793 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/signtool/index.rst @@ -0,0 +1,547 @@ +.. _mozilla_projects_nss_tools_signtool: + +NSS tools : signtool +==================== + +.. container:: + + | Name + | signtool — Digitally sign objects and files. + | Synopsis + | signtool [-k keyName] `-h <-h>`__ `-H <-H>`__ `-l <-l>`__ `-L <-L>`__ `-M <-M>`__ + `-v <-v>`__ `-w <-w>`__ + | `-G nickname <-G_nickname>`__ `-s size <--keysize>`__ `-b basename <-b_basename>`__ [[-c + Compression + | Level] ] [[-d cert-dir] ] [[-i installer script] ] [[-m metafile] ] [[-x + | name] ] [[-f filename] ] [[-t|--token tokenname] ] [[-e extension] ] [[-o] + | ] [[-z] ] [[-X] ] [[--outfile] ] [[--verbose value] ] [[--norecurse] ] + | [[--leavearc] ] [[-j directory] ] [[-Z jarfile] ] [[-O] ] [[-p password] ] + | [directory-tree] [archive] + | Description + | The Signing Tool, signtool, creates digital signatures and uses a Java + | Archive (JAR) file to associate the signatures with files in a directory. + | Electronic software distribution over any network involves potential + | security problems. To help address some of these problems, you can + | associate digital signatures with the files in a JAR archive. Digital + | signatures allow SSL-enabled clients to perform two important operations: + | \* Confirm the identity of the individual, company, or other entity whose + | digital signature is associated with the files + | \* Check whether the files have been tampered with since being signed + | If you have a signing certificate, you can use Netscape Signing Tool to + | digitally sign files and package them as a JAR file. An object-signing + | certificate is a special kind of certificate that allows you to associate + | your digital signature with one or more files. + | An individual file can potentially be signed with multiple digital + | signatures. For example, a commercial software developer might sign the + | files that constitute a software product to prove that the files are + | indeed from a particular company. A network administrator manager might + | sign the same files with an additional digital signature based on a + | company-generated certificate to indicate that the product is approved for + | use within the company. + | The significance of a digital signature is comparable to the significance + | of a handwritten signature. Once you have signed a file, it is difficult + | to claim later that you didn't sign it. In some situations, a digital + | signature may be considered as legally binding as a handwritten signature. + | Therefore, you should take great care to ensure that you can stand behind + | any file you sign and distribute. + | For example, if you are a software developer, you should test your code to + | make sure it is virus-free before signing it. Similarly, if you are a + | network administrator, you should make sure, before signing any code, that + | it comes from a reliable source and will run correctly with the software + | installed on the machines to which you are distributing it. + | Before you can use Netscape Signing Tool to sign files, you must have an + | object-signing certificate, which is a special certificate whose + | associated private key is used to create digital signatures. For testing + | purposes only, you can create an object-signing certificate with Netscape + | Signing Tool 1.3. When testing is finished and you are ready to + | disitribute your software, you should obtain an object-signing certificate + | from one of two kinds of sources: + | \* An independent certificate authority (CA) that authenticates your + | identity and charges you a fee. You typically get a certificate from an + | independent CA if you want to sign software that will be distributed over + | the Internet. + | \* CA server software running on your corporate intranet or extranet. + | Netscape Certificate Management System provides a complete management + | solution for creating, deploying, and managing certificates, including CAs + | that issue object-signing certificates. + | You must also have a certificate for the CA that issues your signing + | certificate before you can sign files. If the certificate authority's + | certificate isn't already installed in your copy of Communicator, you + | typically install it by clicking the appropriate link on the certificate + | authority's web site, for example on the page from which you initiated + | enrollment for your signing certificate. This is the case for some test + | certificates, as well as certificates issued by Netscape Certificate + | Management System: you must download the CA certificate in addition to + | obtaining your own signing certificate. CA certificates for several + | certificate authorities are preinstalled in the Communicator certificate + | database. + | When you receive an object-signing certificate for your own use, it is + | automatically installed in your copy of the Communicator client software. + | Communicator supports the public-key cryptography standard known as PKCS + | #12, which governs key portability. You can, for example, move an + | object-signing certificate and its associated private key from one + | computer to another on a credit-card-sized device called a smart card. + | Options + | -b basename + | Specifies the base filename for the .rsa and .sf files in the + | META-INF directory to conform with the JAR format. For example, -b + | signatures causes the files to be named signatures.rsa and + | signatures.sf. The default is signtool. + | -c# + | Specifies the compression level for the -J or -Z option. The + | symbol # represents a number from 0 to 9, where 0 means no + | compression and 9 means maximum compression. The higher the level + | of compression, the smaller the output but the longer the + | operation takes. If the -c# option is not used with either the -J + | or the -Z option, the default compression value used by both the + | -J and -Z options is 6. + | -d certdir + | Specifies your certificate database directory; that is, the + | directory in which you placed your key3.db and cert7.db files. To + | specify the current directory, use "-d." (including the period). + | The Unix version of signtool assumes ~/.netscape unless told + | otherwise. The NT version of signtool always requires the use of + | the -d option to specify where the database files are located. + | -e extension + | Tells signtool to sign only files with the given extension; for + | example, use -e".class" to sign only Java class files. Note that + | with Netscape Signing Tool version 1.1 and later this option can + | appear multiple times on one command line, making it possible to + | specify multiple file types or classes to include. + | -f commandfile + | Specifies a text file containing Netscape Signing Tool options and + | arguments in keyword=value format. All options and arguments can + | be expressed through this file. For more information about the + | syntax used with this file, see "Tips and Techniques". + | -i scriptname + | Specifies the name of an installer script for SmartUpdate. This + | script installs files from the JAR archive in the local system + | after SmartUpdate has validated the digital signature. For more + | details, see the description of -m that follows. The -i option + | provides a straightforward way to provide this information if you + | don't need to specify any metadata other than an installer script. + | -j directory + | Specifies a special JavaScript directory. This option causes the + | specified directory to be signed and tags its entries as inline + | JavaScript. This special type of entry does not have to appear in + | the JAR file itself. Instead, it is located in the HTML page + | containing the inline scripts. When you use signtool -v, these + | entries are displayed with the string NOT PRESENT. + | -k key ... directory + | Specifies the nickname (key) of the certificate you want to sign + | with and signs the files in the specified directory. The directory + | to sign is always specified as the last command-line argument. + | Thus, it is possible to write signtool -k MyCert -d . signdir You + | may have trouble if the nickname contains a single quotation mark. + | To avoid problems, escape the quotation mark using the escape + | conventions for your platform. It's also possible to use the -k + | option without signing any files or specifying a directory. For + | example, you can use it with the -l option to get detailed + | information about a particular signing certificate. + | -G nickname + | Generates a new private-public key pair and corresponding + | object-signing certificate with the given nickname. The newly + | generated keys and certificate are installed into the key and + | certificate databases in the directory specified by the -d option. + | With the NT version of Netscape Signing Tool, you must use the -d + | option with the -G option. With the Unix version of Netscape + | Signing Tool, omitting the -d option causes the tool to install + | the keys and certificate in the Communicator key and certificate + | databases. If you are installing the keys and certificate in the + | Communicator databases, you must exit Communicator before using + | this option; otherwise, you risk corrupting the databases. In all + | cases, the certificate is also output to a file named x509.cacert, + | which has the MIME-type application/x-x509-ca-cert. Unlike + | certificates normally used to sign finished code to be distributed + | over a network, a test certificate created with -G is not signed + | by a recognized certificate authority. Instead, it is self-signed. + | In addition, a single test signing certificate functions as both + | an object-signing certificate and a CA. When you are using it to + | sign objects, it behaves like an object-signing certificate. When + | it is imported into browser software such as Communicator, it + | behaves like an object-signing CA and cannot be used to sign + | objects. The -G option is available in Netscape Signing Tool 1.0 + | and later versions only. By default, it produces only RSA + | certificates with 1024-byte keys in the internal token. However, + | you can use the -s option specify the required key size and the -t + | option to specify the token. For more information about the use of + | the -G option, see "Generating Test Object-Signing + | Certificates""Generating Test Object-Signing Certificates" on page + | 1241. + | -l + | Lists signing certificates, including issuing CAs. If any of your + | certificates are expired or invalid, the list will so specify. + | This option can be used with the -k option to list detailed + | information about a particular signing certificate. The -l option + | is available in Netscape Signing Tool 1.0 and later versions only. + | -J + | Signs a directory of HTML files containing JavaScript and creates + | as many archive files as are specified in the HTML tags. Even if + | signtool creates more than one archive file, you need to supply + | the key database password only once. The -J option is available + | only in Netscape Signing Tool 1.0 and later versions. The -J + | option cannot be used at the same time as the -Z option. If the + | -c# option is not used with the -J option, the default compression + | value is 6. Note that versions 1.1 and later of Netscape Signing + | Tool correctly recognizes the CODEBASE attribute, allows paths to + | be expressed for the CLASS and SRC attributes instead of filenames + | only, processes LINK tags and parses HTML correctly, and offers + | clearer error messages. + | -L + | Lists the certificates in your database. An asterisk appears to + | the left of the nickname for any certificate that can be used to + | sign objects with signtool. + | --leavearc + | Retains the temporary .arc (archive) directories that the -J + | option creates. These directories are automatically erased by + | default. Retaining the temporary directories can be an aid to + | debugging. + | -m metafile + | Specifies the name of a metadata control file. Metadata is signed + | information attached either to the JAR archive itself or to files + | within the archive. This metadata can be any ASCII string, but is + | used mainly for specifying an installer script. The metadata file + | contains one entry per line, each with three fields: field #1: + | file specification, or + if you want to specify global metadata + | (that is, metadata about the JAR archive itself or all entries in + | the archive) field #2: the name of the data you are specifying; + | for example: Install-Script field #3: data corresponding to the + | name in field #2 For example, the -i option uses the equivalent of + | this line: + Install-Script: script.js This example associates a + | MIME type with a file: movie.qt MIME-Type: video/quicktime For + | information about the way installer script information appears in + | the manifest file for a JAR archive, see The JAR Format on + | Netscape DevEdge. + | -M + | Lists the PKCS #11 modules available to signtool, including smart + | cards. The -M option is available in Netscape Signing Tool 1.0 and + | later versions only. For information on using Netscape Signing + | Tool with smart cards, see "Using Netscape Signing Tool with Smart + | Cards". For information on using the -M option to verify + | FIPS-140-1 validated mode, see "Netscape Signing Tool and + | FIPS-140-1". + | --norecurse + | Blocks recursion into subdirectories when signing a directory's + | contents or when parsing HTML. + | -o + | Optimizes the archive for size. Use this only if you are signing + | very large archives containing hundreds of files. This option + | makes the manifest files (required by the JAR format) considerably + | smaller, but they contain slightly less information. + | --outfile outputfile + | Specifies a file to receive redirected output from Netscape + | Signing Tool. + | -p password + | Specifies a password for the private-key database. Note that the + | password entered on the command line is displayed as plain text. + | -s keysize + | Specifies the size of the key for generated certificate. Use the + | -M option to find out what tokens are available. The -s option can + | be used with the -G option only. + | -t token + | Specifies which available token should generate the key and + | receive the certificate. Use the -M option to find out what tokens + | are available. The -t option can be used with the -G option only. + | -v archive + | Displays the contents of an archive and verifies the cryptographic + | integrity of the digital signatures it contains and the files with + | which they are associated. This includes checking that the + | certificate for the issuer of the object-signing certificate is + | listed in the certificate database, that the CA's digital + | signature on the object-signing certificate is valid, that the + | relevant certificates have not expired, and so on. + | --verbosity value + | Sets the quantity of information Netscape Signing Tool generates + | in operation. A value of 0 (zero) is the default and gives full + | information. A value of -1 suppresses most messages, but not error + | messages. + | -w archive + | Displays the names of signers of any files in the archive. + | -x directory + | Excludes the specified directory from signing. Note that with + | Netscape Signing Tool version 1.1 and later this option can appear + | multiple times on one command line, making it possible to specify + | several particular directories to exclude. + | -z + | Tells signtool not to store the signing time in the digital + | signature. This option is useful if you want the expiration date + | of the signature checked against the current date and time rather + | than the time the files were signed. + | -Z jarfile + | Creates a JAR file with the specified name. You must specify this + | option if you want signtool to create the JAR file; it does not do + | so automatically. If you don't specify -Z, you must use an + | external ZIP tool to create the JAR file. The -Z option cannot be + | used at the same time as the -J option. If the -c# option is not + | used with the -Z option, the default compression value is 6. + | The Command File Format + | Entries in a Netscape Signing Tool command file have this general format: + | keyword=value Everything before the = sign on a single line is a keyword, + | and everything from the = sign to the end of line is a value. The value + | may include = signs; only the first = sign on a line is interpreted. Blank + | lines are ignored, but white space on a line with keywords and values is + | assumed to be part of the keyword (if it comes before the equal sign) or + | part of the value (if it comes after the first equal sign). Keywords are + | case insensitive, values are generally case sensitive. Since the = sign + | and newline delimit the value, it should not be quoted. + | Subsection + | basename + | Same as -b option. + | compression + | Same as -c option. + | certdir + | Same as -d option. + | extension + | Same as -e option. + | generate + | Same as -G option. + | installscript + | Same as -i option. + | javascriptdir + | Same as -j option. + | htmldir + | Same as -J option. + | certname + | Nickname of certificate, as with -k and -l -k options. + | signdir + | The directory to be signed, as with -k option. + | list + | Same as -l option. Value is ignored, but = sign must be present. + | listall + | Same as -L option. Value is ignored, but = sign must be present. + | metafile + | Same as -m option. + | modules + | Same as -M option. Value is ignored, but = sign must be present. + | optimize + | Same as -o option. Value is ignored, but = sign must be present. + | password + | Same as -p option. + | keysize + | Same as -s option. + | token + | Same as -t option. + | verify + | Same as -v option. + | who + | Same as -w option. + | exclude + | Same as -x option. + | notime + | Same as -z option. value is ignored, but = sign must be present. + | jarfile + | Same as -Z option. + | outfile + | Name of a file to which output and error messages will be + | redirected. This option has no command-line equivalent. + | Extended Examples + | The following example will do this and that + | Listing Available Signing Certificates + | You use the -L option to list the nicknames for all available certificates + | and check which ones are signing certificates. + | signtool -L + | using certificate directory: /u/jsmith/.netscape + | S Certificates + | - ------------ + | BBN Certificate Services CA Root 1 + | IBM World Registry CA + | VeriSign Class 1 CA - Individual Subscriber - VeriSign, Inc. + | GTE CyberTrust Root CA + | Uptime Group Plc. Class 4 CA + | \* Verisign Object Signing Cert + | Integrion CA + | GTE CyberTrust Secure Server CA + | AT&T Directory Services + | \* test object signing cert + | Uptime Group Plc. Class 1 CA + | VeriSign Class 1 Primary CA + | - ------------ + | Certificates that can be used to sign objects have \*'s to their left. + | Two signing certificates are displayed: Verisign Object Signing Cert and + | test object signing cert. + | You use the -l option to get a list of signing certificates only, + | including the signing CA for each. + | signtool -l + | using certificate directory: /u/jsmith/.netscape + | Object signing certificates + | --------------------------------------- + | Verisign Object Signing Cert + | Issued by: VeriSign, Inc. - Verisign, Inc. + | Expires: Tue May 19, 1998 + | test object signing cert + | Issued by: test object signing cert (Signtool 1.0 Testing + | Certificate (960187691)) + | Expires: Sun May 17, 1998 + | --------------------------------------- + | For a list including CAs, use the -L option. + | Signing a File + | 1. Create an empty directory. + | mkdir signdir + | 2. Put some file into it. + | echo boo > signdir/test.f + | 3. Specify the name of your object-signing certificate and sign the + | directory. + | signtool -k MySignCert -Z testjar.jar signdir + | using key "MySignCert" + | using certificate directory: /u/jsmith/.netscape + | Generating signdir/META-INF/manifest.mf file.. + | --> test.f + | adding signdir/test.f to testjar.jar + | Generating signtool.sf file.. + | Enter Password or Pin for "Communicator Certificate DB": + | adding signdir/META-INF/manifest.mf to testjar.jar + | adding signdir/META-INF/signtool.sf to testjar.jar + | adding signdir/META-INF/signtool.rsa to testjar.jar + | tree "signdir" signed successfully + | 4. Test the archive you just created. + | signtool -v testjar.jar + | using certificate directory: /u/jsmith/.netscape + | archive "testjar.jar" has passed crypto verification. + | status path + | ------------ ------------------- + | verified test.f + | Using Netscape Signing Tool with a ZIP Utility + | To use Netscape Signing Tool with a ZIP utility, you must have the utility + | in your path environment variable. You should use the zip.exe utility + | rather than pkzip.exe, which cannot handle long filenames. You can use a + | ZIP utility instead of the -Z option to package a signed archive into a + | JAR file after you have signed it: + | cd signdir + | zip -r ../myjar.jar \* + | adding: META-INF/ (stored 0%) + | adding: META-INF/manifest.mf (deflated 15%) + | adding: META-INF/signtool.sf (deflated 28%) + | adding: META-INF/signtool.rsa (stored 0%) + | adding: text.txt (stored 0%) + | Generating the Keys and Certificate + | The signtool option -G generates a new public-private key pair and + | certificate. It takes the nickname of the new certificate as an argument. + | The newly generated keys and certificate are installed into the key and + | certificate databases in the directory specified by the -d option. With + | the NT version of Netscape Signing Tool, you must use the -d option with + | the -G option. With the Unix version of Netscape Signing Tool, omitting + | the -d option causes the tool to install the keys and certificate in the + | Communicator key and certificate databases. In all cases, the certificate + | is also output to a file named x509.cacert, which has the MIME-type + | application/x-x509-ca-cert. + | Certificates contain standard information about the entity they identify, + | such as the common name and organization name. Netscape Signing Tool + | prompts you for this information when you run the command with the -G + | option. However, all of the requested fields are optional for test + | certificates. If you do not enter a common name, the tool provides a + | default name. In the following example, the user input is in boldface: + | signtool -G MyTestCert + | using certificate directory: /u/someuser/.netscape + | Enter certificate information. All fields are optional. Acceptable + | characters are numbers, letters, spaces, and apostrophes. + | certificate common name: Test Object Signing Certificate + | organization: Netscape Communications Corp. + | organization unit: Server Products Division + | state or province: California + | country (must be exactly 2 characters): US + | username: someuser + | email address: someuser@netscape.com + | Enter Password or Pin for "Communicator Certificate DB": [Password will not echo] + | generated public/private key pair + | certificate request generated + | certificate has been signed + | certificate "MyTestCert" added to database + | Exported certificate to x509.raw and x509.cacert. + | The certificate information is read from standard input. Therefore, the + | information can be read from a file using the redirection operator (<) in + | some operating systems. To create a file for this purpose, enter each of + | the seven input fields, in order, on a separate line. Make sure there is a + | newline character at the end of the last line. Then run signtool with + | standard input redirected from your file as follows: + | signtool -G MyTestCert inputfile + | The prompts show up on the screen, but the responses will be automatically + | read from the file. The password will still be read from the console + | unless you use the -p option to give the password on the command line. + | Using the -M Option to List Smart Cards + | You can use the -M option to list the PKCS #11 modules, including smart + | cards, that are available to signtool: + | signtool -d "c:\netscape\users\jsmith" -M + | using certificate directory: c:\netscape\users\username + | Listing of PKCS11 modules + | ----------------------------------------------- + | 1. Netscape Internal PKCS #11 Module + | (this module is internally loaded) + | slots: 2 slots attached + | status: loaded + | slot: Communicator Internal Cryptographic Services Version 4.0 + | token: Communicator Generic Crypto Svcs + | slot: Communicator User Private Key and Certificate Services + | token: Communicator Certificate DB + | 2. CryptOS + | (this is an external module) + | DLL name: core32 + | slots: 1 slots attached + | status: loaded + | slot: Litronic 210 + | token: + | ----------------------------------------------- + | Using Netscape Signing Tool and a Smart Card to Sign Files + | The signtool command normally takes an argument of the -k option to + | specify a signing certificate. To sign with a smart card, you supply only + | the fully qualified name of the certificate. + | To see fully qualified certificate names when you run Communicator, click + | the Security button in Navigator, then click Yours under Certificates in + | the left frame. Fully qualified names are of the format smart + | card:certificate, for example "MyCard:My Signing Cert". You use this name + | with the -k argument as follows: + | signtool -k "MyCard:My Signing Cert" directory + | Verifying FIPS Mode + | Use the -M option to verify that you are using the FIPS-140-1 module. + | signtool -d "c:\netscape\users\jsmith" -M + | using certificate directory: c:\netscape\users\jsmith + | Listing of PKCS11 modules + | ----------------------------------------------- + | 1. Netscape Internal PKCS #11 Module + | (this module is internally loaded) + | slots: 2 slots attached + | status: loaded + | slot: Communicator Internal Cryptographic Services Version 4.0 + | token: Communicator Generic Crypto Svcs + | slot: Communicator User Private Key and Certificate Services + | token: Communicator Certificate DB + | ----------------------------------------------- + | This Unix example shows that Netscape Signing Tool is using a FIPS-140-1 + | module: + | signtool -d "c:\netscape\users\jsmith" -M + | using certificate directory: c:\netscape\users\jsmith + | Enter Password or Pin for "Communicator Certificate DB": [password will not echo] + | Listing of PKCS11 modules + | ----------------------------------------------- + | 1. Netscape Internal FIPS PKCS #11 Module + | (this module is internally loaded) + | slots: 1 slots attached + | status: loaded + | slot: Netscape Internal FIPS-140-1 Cryptographic Services + | token: Communicator Certificate DB + | ----------------------------------------------- + | See Also + | signver (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/signver/index.rst b/security/nss/doc/rst/legacy/tools/signver/index.rst new file mode 100644 index 0000000000..18fa331bd7 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/signver/index.rst @@ -0,0 +1,118 @@ +.. _mozilla_projects_nss_tools_signver: + +NSS tools : signver +=================== + +.. container:: + + | Name + | signver — Verify a detached PKCS#7 signature for a file. + | Synopsis + | signtool -A \| -V -d directory [-a] [-i input_file] [-o output_file] [-s + | signature_file] [-v] + | Description + | The Signature Verification Tool, signver, is a simple command-line utility + | that unpacks a base-64-encoded PKCS#7 signed object and verifies the + | digital signature using standard cryptographic techniques. The Signature + | Verification Tool can also display the contents of the signed object. + | Options + | -A + | Displays all of the information in the PKCS#7 signature. + | -V + | Verifies the digital signature. + | -d [sql:]directory + | Specify the database directory which contains the certificates and + | keys. + | signver supports two types of databases: the legacy security + | databases (cert8.db, key3.db, and secmod.db) and new SQLite + | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: + | is not used, then the tool assumes that the given databases are in + | the old format. + | -a + | Sets that the given signature file is in ASCII format. + | -i input_file + | Gives the input file for the object with signed data. + | -o output_file + | Gives the output file to which to write the results. + | -s signature_file + | Gives the input file for the digital signature. + | -v + | Enables verbose output. + | Extended Examples + | Verifying a Signature + | The -V option verifies that the signature in a given signature file is + | valid when used to sign the given object (from the input file). + | signver -V -s signature_file -i signed_file -d sql:/home/my/sharednssdb + | signatureValid=yes + | Printing Signature Data + | The -A option prints all of the information contained in a signature file. + | Using the -o option prints the signature file information to the given + | output file rather than stdout. + | signver -A -s signature_file -o output_file + | NSS Database Types + | NSS originally used BerkeleyDB databases to store security information. + | The last versions of these legacy databases are: + | o cert8.db for certificates + | o key3.db for keys + | o secmod.db for PKCS #11 module information + | BerkeleyDB has performance limitations, though, which prevent it from + | being easily used by multiple applications simultaneously. NSS has some + | flexibility that allows applications to use their own, independent + | database engine while keeping a shared database and working around the + | access issues. Still, NSS requires more flexibility to provide a truly + | shared security database. + | In 2009, NSS introduced a new set of databases that are SQLite databases + | rather than BerkleyDB. These new databases provide more accessibility and + | performance: + | o cert9.db for certificates + | o key4.db for keys + | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained + | in a new subdirectory in the security databases directory + | Because the SQLite databases are designed to be shared, these are the + | shared database type. The shared database type is preferred; the legacy + | format is included for backward compatibility. + | By default, the tools (certutil, pk12util, modutil) assume that the given + | security databases follow the more common legacy type. Using the SQLite + | databases must be manually specified by using the sql: prefix with the + | given security directory. For example: + | # signver -A -s signature -d sql:/home/my/sharednssdb + | To set the shared database type as the default type for the tools, set the + | NSS_DEFAULT_DB_TYPE environment variable to sql: + | export NSS_DEFAULT_DB_TYPE="sql" + | This line can be set added to the ~/.bashrc file to make the change + | permanent. + | Most applications do not use the shared database by default, but they can + | be configured to use them. For example, this how-to article covers how to + | configure Firefox and Thunderbird to use the new shared NSS databases: + | o https://wiki.mozilla.org/NSS_Shared_DB_Howto + | For an engineering draft on the changes in the shared NSS databases, see + | the NSS project wiki: + | o https://wiki.mozilla.org/NSS_Shared_DB + | See Also + | signtool (1) + | The NSS wiki has information on the new database design and how to + | configure applications to use it. + | o Setting up the shared NSS database + | https://wiki.mozilla.org/NSS_Shared_DB_Howto + | o Engineering and technical information about the shared NSS database + | https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/ssltap/index.rst b/security/nss/doc/rst/legacy/tools/ssltap/index.rst new file mode 100644 index 0000000000..3c63acc5c2 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/ssltap/index.rst @@ -0,0 +1,495 @@ +.. _mozilla_projects_nss_tools_ssltap: + +NSS tools : ssltap +================== + +.. container:: + + | Name + | ssltap — Tap into SSL connections and display the data going by + | Synopsis + | libssltap [-vhfsxl] [-p port] [hostname:port] + | Description + | The SSL Debugging Tool ssltap is an SSL-aware command-line proxy. It + | watches TCP connections and displays the data going by. If a connection is + | SSL, the data display includes interpreted SSL records and handshaking + | Options + | -v + | Print a version string for the tool. + | -h + | Turn on hex/ASCII printing. Instead of outputting raw data, the + | command interprets each record as a numbered line of hex values, + | followed by the same data as ASCII characters. The two parts are + | separated by a vertical bar. Nonprinting characters are replaced + | by dots. + | -f + | Turn on fancy printing. Output is printed in colored HTML. Data + | sent from the client to the server is in blue; the server's reply + | is in red. When used with looping mode, the different connections + | are separated with horizontal lines. You can use this option to + | upload the output into a browser. + | -s + | Turn on SSL parsing and decoding. The tool does not automatically + | detect SSL sessions. If you are intercepting an SSL connection, + | use this option so that the tool can detect and decode SSL + | structures. + | If the tool detects a certificate chain, it saves the DER-encoded + | certificates into files in the current directory. The files are + | named cert.0x, where x is the sequence number of the certificate. + | If the -s option is used with -h, two separate parts are printed + | for each record: the plain hex/ASCII output, and the parsed SSL + | output. + | -x + | Turn on hex/ASCII printing of undecoded data inside parsed SSL + | records. Used only with the -s option. This option uses the same + | output format as the -h option. + | -l prefix + | Turn on looping; that is, continue to accept connections rather + | than stopping after the first connection is complete. + | -p port + | Change the default rendezvous port (1924) to another port. + | The following are well-known port numbers: + | \* HTTP 80 + | \* HTTPS 443 + | \* SMTP 25 + | \* FTP 21 + | \* IMAP 143 + | \* IMAPS 993 (IMAP over SSL) + | \* NNTP 119 + | \* NNTPS 563 (NNTP over SSL) + | Usage and Examples + | You can use the SSL Debugging Tool to intercept any connection + | information. Although you can run the tool at its most basic by issuing + | the ssltap command with no options other than hostname:port, the + | information you get in this way is not very useful. For example, assume + | your development machine is called intercept. The simplest way to use the + | debugging tool is to execute the following command from a command shell: + | $ ssltap www.netscape.com + | The program waits for an incoming connection on the default port 1924. In + | your browser window, enter the URL http://intercept:1924. The browser + | retrieves the requested page from the server at www.netscape.com, but the + | page is intercepted and passed on to the browser by the debugging tool on + | intercept. On its way to the browser, the data is printed to the command + | shell from which you issued the command. Data sent from the client to the + | server is surrounded by the following symbols: --> [ data ] Data sent from + | the server to the client is surrounded by the following symbols: "left + | arrow"-- [ data ] The raw data stream is sent to standard output and is + | not interpreted in any way. This can result in peculiar effects, such as + | sounds, flashes, and even crashes of the command shell window. To output a + | basic, printable interpretation of the data, use the -h option, or, if you + | are looking at an SSL connection, the -s option. You will notice that the + | page you retrieved looks incomplete in the browser. This is because, by + | default, the tool closes down after the first connection is complete, so + | the browser is not able to load images. To make the tool continue to + | accept connections, switch on looping mode with the -l option. The + | following examples show the output from commonly used combinations of + | options. + | Example 1 + | $ ssltap.exe -sx -p 444 interzone.mcom.com:443 > sx.txt + | Output + | Connected to interzone.mcom.com:443 + | -->; [ + | alloclen = 66 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 39 (0x27) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | (0x000006) SSL3/RSA/RC2CBC40/MD5 + | } + | session-id = { } + | challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 + | 0x2592 } + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 03 e5 \|..... + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | 0: 02 00 00 46 \|...F + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | 0: 77 8c 6e 26 6c 0c ec c0 d9 58 4f 47 d3 2d 01 45 \| + | wn&l.ì..XOG.-.E + | 10: 5c 17 75 43 a7 4c 88 c7 88 64 3c 50 41 48 4f 7f \| + | \.uC§L.Ç.d<PAHO. + | session ID = { + | length = 32 + | contents = {..} + | 0: 14 11 07 a8 2a 31 91 29 11 94 40 37 57 10 a7 32 \| ...¨*1.)..@7W.§2 + | 10: 56 6f 52 62 fe 3d b3 65 b1 e4 13 0f 52 a3 c8 f6 \| VoRbþ=³e±...R£È. + | } + | cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + | } + | 0: 0b 00 02 c5 \|...Å + | type = 11 (certificate) + | length = 709 (0x0002c5) + | CertificateChain { + | chainlength = 706 (0x02c2) + | Certificate { + | size = 703 (0x02bf) + | data = { saved in file 'cert.001' } + | } + | } + | 0: 0c 00 00 ca \|.... + | type = 12 (server_key_exchange) + | length = 202 (0x0000ca) + | 0: 0e 00 00 00 \|.... + | type = 14 (server_hello_done) + | length = 0 (0x000000) + | } + | } + | ] + | --> [ + | SSLRecord { + | 0: 16 03 00 00 44 \|....D + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | 0: 10 00 00 40 \|...@ + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 14 03 00 00 01 \|..... + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | 0: 01 \|. + | } + | ] + | <-- [ + | SSLRecord { + | 0: 16 03 00 00 38 \|....8 + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | < encrypted > + | } + | ] + | --> [ + | SSLRecord { + | 0: 17 03 00 01 1f \|..... + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 a0 \|.... + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | < encrypted > + | } + | ] + | <-- [ + | SSLRecord { + | 0: 17 03 00 00 df \|....ß + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | < encrypted > + | } + | SSLRecord { + | 0: 15 03 00 00 12 \|..... + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | < encrypted > + | } + | ] + | Server socket closed. + | Example 2 + | The -s option turns on SSL parsing. Because the -x option is not used in + | this example, undecoded values are output as raw data. The output is + | routed to a text file. + | $ ssltap -s -p 444 interzone.mcom.com:443 > s.txt + | Output + | Connected to interzone.mcom.com:443 + | --> [ + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x713c 0x9338 0x30e1 0xf8d6 0xb934 0x7351 0x200c + | 0x3fd0 } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 997 (0x3e5) + | handshake { + | type = 2 (server_hello) + | length = 70 (0x000046) + | ServerHello { + | server_version = {3, 0} + | random = {...} + | session ID = { + | length = 32 + | contents = {..} + | } + | cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 + | } + | type = 11 (certificate) + | length = 709 (0x0002c5) + | CertificateChain { + | chainlength = 706 (0x02c2) + | Certificate { + | size = 703 (0x02bf) + | data = { saved in file 'cert.001' } + | } + | } + | type = 12 (server_key_exchange) + | length = 202 (0x0000ca) + | type = 14 (server_hello_done) + | length = 0 (0x000000) + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 68 (0x44) + | handshake { + | type = 16 (client_key_exchange) + | length = 64 (0x000040) + | ClientKeyExchange { + | message = {...} + | } + | } + | } + | ] + | --> [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 20 (change_cipher_spec) + | version = { 3,0 } + | length = 1 (0x1) + | } + | ] + | >-- [ + | SSLRecord { + | type = 22 (handshake) + | version = { 3,0 } + | length = 56 (0x38) + | > encrypted > + | } + | ] + | --> [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 287 (0x11f) + | > encrypted > + | } + | ] + | [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 160 (0xa0) + | > encrypted > + | } + | ] + | >-- [ + | SSLRecord { + | type = 23 (application_data) + | version = { 3,0 } + | length = 223 (0xdf) + | > encrypted > + | } + | SSLRecord { + | type = 21 (alert) + | version = { 3,0 } + | length = 18 (0x12) + | > encrypted > + | } + | ] + | Server socket closed. + | Example 3 + | In this example, the -h option turns hex/ASCII format. There is no SSL + | parsing or decoding. The output is routed to a text file. + | $ ssltap -h -p 444 interzone.mcom.com:443 > h.txt + | Output + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 40 01 03 00 00 27 00 00 00 10 01 00 80 02 00 \| .@....'......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 00 \| ........á....... + | 30: 00 06 9b fe 5b 56 96 49 1f 9f ca dd d5 ba b9 52 \| ..þ[V.I.\xd9 ...º¹R + | 40: 6f 2d \|o- + | ] + | <-- [ + | 0: 16 03 00 03 e5 02 00 00 46 03 00 7f e5 0d 1b 1d \| ........F....... + | 10: 68 7f 3a 79 60 d5 17 3c 1d 9c 96 b3 88 d2 69 3b \| h.:y`..<..³.Òi; + | 20: 78 e2 4b 8b a6 52 12 4b 46 e8 c2 20 14 11 89 05 \| x.K.¦R.KFè. ... + | 30: 4d 52 91 fd 93 e0 51 48 91 90 08 96 c1 b6 76 77 \| MR.ý..QH.....¶vw + | 40: 2a f4 00 08 a1 06 61 a2 64 1f 2e 9b 00 03 00 0b \| \*ô..¡.a¢d...... + | 50: 00 02 c5 00 02 c2 00 02 bf 30 82 02 bb 30 82 02 \| ..Å......0...0.. + | 60: 24 a0 03 02 01 02 02 02 01 36 30 0d 06 09 2a 86 \| $ .......60...*. + | 70: 48 86 f7 0d 01 01 04 05 00 30 77 31 0b 30 09 06 \| H.÷......0w1.0.. + | 80: 03 55 04 06 13 02 55 53 31 2c 30 2a 06 03 55 04 \| .U....US1,0*..U. + | 90: 0a 13 23 4e 65 74 73 63 61 70 65 20 43 6f 6d 6d \| ..#Netscape Comm + | a0: 75 6e 69 63 61 74 69 6f 6e 73 20 43 6f 72 70 6f \| unications Corpo + | b0: 72 61 74 69 6f 6e 31 11 30 0f 06 03 55 04 0b 13 \| ration1.0...U... + | c0: 08 48 61 72 64 63 6f 72 65 31 27 30 25 06 03 55 \| .Hardcore1'0%..U + | d0: 04 03 13 1e 48 61 72 64 63 6f 72 65 20 43 65 72 \| ....Hardcore Cer + | e0: 74 69 66 69 63 61 74 65 20 53 65 72 76 65 72 20 \| tificate Server + | f0: 49 49 30 1e 17 0d 39 38 30 35 31 36 30 31 30 33 \| II0...9805160103 + | <additional data lines> + | ] + | <additional records in same format> + | Server socket closed. + | Example 4 + | In this example, the -s option turns on SSL parsing, and the -h option + | turns on hex/ASCII format. Both formats are shown for each record. The + | output is routed to a text file. + | $ ssltap -hs -p 444 interzone.mcom.com:443 > hs.txt + | Output + | Connected to interzone.mcom.com:443 + | --> [ + | 0: 80 3d 01 03 00 00 24 00 00 00 10 01 00 80 02 00 \| .=....$......... + | 10: 80 03 00 80 04 00 80 06 00 40 07 00 c0 00 00 04 \| .........@...... + | 20: 00 ff e0 00 00 0a 00 ff e1 00 00 09 00 00 03 03 \| ........á....... + | 30: 55 e6 e4 99 79 c7 d7 2c 86 78 96 5d b5 cf e9 \|U..yÇ\xb0 ,.x.]µÏé + | alloclen = 63 bytes + | [ssl2] ClientHelloV2 { + | version = {0x03, 0x00} + | cipher-specs-length = 36 (0x24) + | sid-length = 0 (0x00) + | challenge-length = 16 (0x10) + | cipher-suites = { + | (0x010080) SSL2/RSA/RC4-128/MD5 + | (0x020080) SSL2/RSA/RC4-40/MD5 + | (0x030080) SSL2/RSA/RC2CBC128/MD5 + | (0x040080) SSL2/RSA/RC2CBC40/MD5 + | (0x060040) SSL2/RSA/DES64CBC/MD5 + | (0x0700c0) SSL2/RSA/3DES192EDE-CBC/MD5 + | (0x000004) SSL3/RSA/RC4-128/MD5 + | (0x00ffe0) SSL3/RSA-FIPS/3DES192EDE-CBC/SHA + | (0x00000a) SSL3/RSA/3DES192EDE-CBC/SHA + | (0x00ffe1) SSL3/RSA-FIPS/DES64CBC/SHA + | (0x000009) SSL3/RSA/DES64CBC/SHA + | (0x000003) SSL3/RSA/RC4-40/MD5 + | } + | session-id = { } + | challenge = { 0x0355 0xe6e4 0x9979 0xc7d7 0x2c86 0x7896 0x5db + | 0xcfe9 } + | } + | ] + | <additional records in same formats> + | Server socket closed. + | Usage Tips + | When SSL restarts a previous session, it makes use of cached information + | to do a partial handshake. If you wish to capture a full SSL handshake, + | restart the browser to clear the session id cache. + | If you run the tool on a machine other than the SSL server to which you + | are trying to connect, the browser will complain that the host name you + | are trying to connect to is different from the certificate. If you are + | using the default BadCert callback, you can still connect through a + | dialog. If you are not using the default BadCert callback, the one you + | supply must allow for this possibility. + | See Also + | The NSS Security Tools are also documented at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + | Additional Resources + | NSS is maintained in conjunction with PKI and security-related projects + | through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, + | with a project wiki at [2]\ http://pki.fedoraproject.org/wiki/. + | For information specifically about NSS, the NSS project wiki is located at + | + [3]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: pki-devel@redhat.com and pki-users@redhat.com + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape and + | now with Red Hat and Sun. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/secu.../pki/nss/tools <https://www.mozilla.org/projects/security/pki/nss/tools>`__ + | 2. http://pki.fedoraproject.org/wiki/ + | 3. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/vfychain/index.rst b/security/nss/doc/rst/legacy/tools/vfychain/index.rst new file mode 100644 index 0000000000..ffd1cdf86a --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/vfychain/index.rst @@ -0,0 +1,92 @@ +.. _mozilla_projects_nss_tools_vfychain: + +NSS tools : vfychain +==================== + +.. container:: + + | Name + | vfychain — vfychain [options] [revocation options] certfile [[options] + | certfile] ... + | Synopsis + | vfychain + | Description + | The verification Tool, vfychain, verifies certificate chains. modutil can + | add and delete PKCS #11 modules, change passwords on security databases, + | set defaults, list module contents, enable or disable slots, enable or + | disable FIPS 140-2 compliance, and assign default providers for + | cryptographic operations. This tool can also create certificate, key, and + | module security database files. + | The tasks associated with security module database management are part of + | a process that typically also involves managing key databases and + | certificate databases. + | Options + | -a + | the following certfile is base64 encoded + | -b YYMMDDHHMMZ + | Validate date (default: now) + | -d directory + | database directory + | -f + | Enable cert fetching from AIA URL + | -o oid + | Set policy OID for cert validation(Format OID.1.2.3) + | -p + | Use PKIX Library to validate certificate by calling: + | \* CERT_VerifyCertificate if specified once, + | \* CERT_PKIXVerifyCert if specified twice and more. + | -r + | Following certfile is raw binary DER (default) + | -t + | Following cert is explicitly trusted (overrides db trust) + | -u usage + | 0=SSL client, 1=SSL server, 2=SSL StepUp, 3=SSL CA, 4=Email + | signer, 5=Email recipient, 6=Object signer, + | 9=ProtectedObjectSigner, 10=OCSP responder, 11=Any CA + | -v + | Verbose mode. Prints root cert subject(double the argument for + | whole root cert info) + | -w password + | Database password + | -W pwfile + | Password file + | Revocation options for PKIX API (invoked with -pp options) is a + | collection of the following flags: [-g type [-h flags] [-m type + | [-s flags]] ...] ... + | Where: + | -g test-type + | Sets status checking test type. Possible values are "leaf" or + | "chain" + | -g test type + | Sets status checking test type. Possible values are "leaf" or + | "chain". + | -h test flags + | Sets revocation flags for the test type it follows. Possible + | flags: "testLocalInfoFirst" and "requireFreshInfo". + | -m method type + | Sets method type for the test type it follows. Possible types are + | "crl" and "ocsp". + | -s method flags + | Sets revocation flags for the method it follows. Possible types + | are "doNotUse", "forbidFetching", "ignoreDefaultSrc", + | "requireInfo" and "failIfNoInfo". + | Additional Resources + | For information about NSS and other tools related to NSS (like JSS), check + | out the NSS project wiki at + | + [1]\ `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__. + The NSS site relates + | directly to NSS code changes and releases. + | Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto + | IRC: Freenode at #dogtag-pki + | Authors + | The NSS tools were written and maintained by developers with Netscape, Red + | Hat, and Sun. + | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey + | <dlackey@redhat.com>. + | Copyright + | (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + | Visible links + | 1. + `http://www.mozilla.org/projects/security/pki/nss/ <https://www.mozilla.org/projects/security/pki/nss/>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/tools/vfyserv/index.rst b/security/nss/doc/rst/legacy/tools/vfyserv/index.rst new file mode 100644 index 0000000000..13ad4245fc --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/vfyserv/index.rst @@ -0,0 +1,8 @@ +.. _mozilla_projects_nss_tools_vfyserv: + +NSS tools : vfyserv +=================== + +.. container:: + + Coming soon
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/troubleshooting/index.rst b/security/nss/doc/rst/legacy/troubleshooting/index.rst new file mode 100644 index 0000000000..f6cd297120 --- /dev/null +++ b/security/nss/doc/rst/legacy/troubleshooting/index.rst @@ -0,0 +1,11 @@ +.. _mozilla_projects_nss_troubleshooting: + +NSS troubleshooting +=================== + +.. container:: + + On this page, let's collect information on how to troubleshoot NSS at runtime. Debugging tips, + how to enable tracing of the various modules, etc. + + - :ref:`mozilla_projects_nss_reference_nss_environment_variables`
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/utility_functions/index.rst b/security/nss/doc/rst/legacy/utility_functions/index.rst new file mode 100644 index 0000000000..0d383be594 --- /dev/null +++ b/security/nss/doc/rst/legacy/utility_functions/index.rst @@ -0,0 +1,427 @@ +.. _mozilla_projects_nss_utility_functions: + +Utility functions +================= + +.. container:: + + The public functions listed here perform initialization tasks and other services. + + If documentation is available for a function listed below, the function name is linked to either + its MDC wiki page or its entry in the + :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference`. The `Mozilla Cross + Reference <http://mxr.mozilla.org/>`__ (MXR) link for each function provides access to the + function definition, prototype definition, and source code references. The NSS version column + indicates which versions of NSS support the function. + + +-----------------------------------------+-------------+-----------------------------------------+ + | Function name/documentation | Source code | NSS versions | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``ATOB_AsciiToData`` | MXR | Deprecated 3.2 use | + | | | NSSBase64_DecodeBuffer | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``ATOB_ConvertAsciiToItem`` | MXR | Deprecated 3.2 use | + | | | NSSBase64_DecodeBuffer | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``BTOA_ConvertItemToAscii`` | MXR | Deprecated 3.2 use NSSBase64_EncodeItem | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``BTOA_DataToAscii`` | MXR | Deprecated 3.2 use NSSBase64_EncodeItem | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_AsciiToTime`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_DecodeTimeChoice`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_Encode`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_EncodeTimeChoice`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_GeneralizedTimeToTime`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_GetInteger`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_GeneralizedDayToAscii`` | MXR | 3.11.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_Lengths`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_TimeToUTCTime`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_TimeChoiceDayToAscii`` | MXR | 3.11.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_TimeToGeneralizedTime`` | MXR | 3.11.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_TimeToGeneralizedTimeArena`` | MXR | 3.11.7 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_UTCDayToAscii`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_UTCTimeToAscii`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DER_UTCTimeToTime`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DSAU_DecodeDerSig`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DSAU_DecodeDerSigToLen`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DSAU_EncodeDerSig`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``DSAU_EncodeDerSigWithLen`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_Begin`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_Clone`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_Create`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_Destroy`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_End`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_GetHashObject`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_GetHashObjectByOidTag`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_GetHashTypeByOidTag`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_GetType`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_HashBuf`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_ResultLen`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_ResultLenByOidTag`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_ResultLenContext`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``HASH_Update`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslfnc#1067601` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSS_Initialize`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslfnc#1237143` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSS_InitWithMerge`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSS_IsInitialized`` | MXR | 3.9.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslfnc#1234224` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSS_PutEnv`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSS_RegisterShutdown`` | MXR | 3.11.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | :ref:`mozilla_pro | MXR | 3.2 and later | + | jects_nss_ssl_functions_sslfnc#1061858` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSS_UnregisterShutdown`` | MXR | 3.11.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSS_VersionCheck`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64_DecodeBuffer`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64Decoder_Create`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64Decoder_Destroy`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64Decoder_Update`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64_EncodeItem`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64Encoder_Create`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64Encoder_Destroy`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSBase64Encoder_Update`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSRWLock_Destroy`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSRWLock_HaveWriteLock`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSRWLock_LockRead`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSRWLock_LockWrite`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSRWLock_New`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSRWLock_UnlockRead`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSRWLock_UnlockWrite`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``NSSSMIME_VersionCheck`` | MXR | 3.2.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_Alloc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ArenaAlloc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ArenaGrow`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ArenaMark`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ArenaRelease`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ArenaStrdup`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ArenaUnmark`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ArenaZAlloc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_Free`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_FreeArena`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_GetError`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_NewArena`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_Realloc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_SetError`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ` | MXR | 3.2 and later | + | `PORT_SetUCS2_ASCIIConversionFunction`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_SetUCS2_UTF8ConversionFunction`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_SetUCS4_UTF8ConversionFunction`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_Strdup`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_UCS2_ASCIIConversion`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_UCS2_UTF8Conversion`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ZAlloc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``PORT_ZFree`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``RSA_FormatBlock`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1Decode`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecodeInteger`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecodeItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderAbort`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderClearFilterProc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderClearNotifyProc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderFinish`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderSetFilterProc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderSetNotifyProc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderStart`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1DecoderUpdate`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1Encode`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncodeInteger`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncodeItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderAbort`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderClearNotifyProc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderClearStreaming`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderClearTakeFromBuf`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderFinish`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderSetNotifyProc`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderSetStreaming`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderSetTakeFromBuf`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderStart`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncoderUpdate`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1EncodeUnsignedInteger`` | MXR | 3.11.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_ASN1LengthLength`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_DupCrl`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_GetSignatureAlgorithmOidTag`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_GetRegisteredHttpClient`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_PKCS5GetCryptoAlgorithm`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_PKCS5GetKeyLength`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_PKCS5GetPBEAlgorithm`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_PKCS5IsAlgorithmPBEAlg`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_PKCS5IsAlgorithmPBEAlgTag`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_RegisterDefaultHttpClient`` | MXR | 3.11.1 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_SignData`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SEC_StringToOID`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_AllocItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_ArenaDupItem`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_CompareItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_CopyItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_DupItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_FreeItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_ItemsAreEqual`` | MXR | 3.8 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECITEM_ZfreeItem`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CopyEncryptedPrivateKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CopyPrivateKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_CreateRSAPrivateKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | `` | MXR | 3.2 and later | + | SECKEY_DestroyEncryptedPrivateKeyInfo`` | | | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_DestroyPrivateKeyInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_DestroyPublicKey`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_PublicKeyStrength`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECKEY_UpdateCertPQG`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_AddNewModule`` | MXR | 3.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_AddNewModuleEx`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_DeleteModuleEx`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_CancelWait`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_CanDeleteInternalModule`` | MXR | 3.5 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_CreateModule`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_DeleteModule`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_FindModule`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_FindSlot`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_FreeModuleSpecList`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_GetDBModuleList`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_GetDeadModuleList`` | MXR | 3.9 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_GetModuleSpecList`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_HasRemovableSlots`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_IsModulePresent`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_LoadModule`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_LoadUserModule`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_LookupSlot`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_PubCipherFlagstoInternal`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_PubMechFlagstoInternal`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_UnloadUserModule`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_UpdateModule`` | MXR | 3.4 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_UpdateSlotList`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECMOD_WaitForAnyTokenEvent`` | MXR | 3.9.3 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_AddEntry`` | MXR | 3.10 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_CompareAlgorithmID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_CopyAlgorithmID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_DestroyAlgorithmID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_FindOID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_FindOIDByTag`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_FindOIDTag`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_FindOIDTagDescription`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_GetAlgorithmTag`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SECOID_SetAlgorithmID`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_Begin`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_CompareDigestInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_CopyDigestInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_CreateDigestInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_DestroyContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_DestroyDigestInfo`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_Digest`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_End`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_NewContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``SGN_Update`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_Begin`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_CreateContext`` | MXR | Deprecated 3.12 use | + | | | VFY_CreateContextDirect or | + | | | VFY_CreateContextWithAlgorithmID | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_CreateContextDirect`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_CreateContextWithAlgorithmID`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_DestroyContext`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_End`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_Update`` | MXR | 3.2 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_VerifyData`` | MXR | Deprecated 3.12 use | + | | | VFY_VerifyDataDirect or | + | | | VFY_VerifyDataWithAlgorithmID | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_VerifyDataDirect`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_DataWithAlgorithmID`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_VerifyDigest`` | MXR | Deprecated 3.12 use | + | | | VFY_VerifyDigestDirect or | + | | | VFY_VerifyDigestWithAlgorithmID | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_VerifyDigestDirect`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+ + | ``VFY_VerifyDigestWithAlgorithmID`` | MXR | 3.12 and later | + +-----------------------------------------+-------------+-----------------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/more.rst b/security/nss/doc/rst/more.rst new file mode 100644 index 0000000000..1585a23977 --- /dev/null +++ b/security/nss/doc/rst/more.rst @@ -0,0 +1,153 @@ +.. _more_documentation: + +.. 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. + +More 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>`__ + +.. _Related_Topics: + +Related Topics +~~~~~~~~~~~~~~ + +- `Security <https://developer.mozilla.org/en-US/docs/Security>`__ + diff --git a/security/nss/doc/rst/releases/index.rst b/security/nss/doc/rst/releases/index.rst new file mode 100644 index 0000000000..5ac6cb4bb0 --- /dev/null +++ b/security/nss/doc/rst/releases/index.rst @@ -0,0 +1,99 @@ +.. _mozilla_projects_nss_releases: + +Releases +======== + +.. toctree:: + :maxdepth: 0 + :glob: + :hidden: + + nss_3_98.rst + nss_3_97.rst + nss_3_96_1.rst + nss_3_96.rst + nss_3_95.rst + nss_3_94.rst + nss_3_93.rst + nss_3_92.rst + nss_3_91_0.rst + nss_3_90_0.rst + nss_3_89_1.rst + nss_3_89.rst + nss_3_88_1.rst + nss_3_88.rst + nss_3_87_1.rst + nss_3_87.rst + nss_3_86.rst + nss_3_85.rst + nss_3_84.rst + nss_3_83.rst + nss_3_82.rst + nss_3_81.rst + nss_3_80.rst + nss_3_79_4.rst + nss_3_79_3.rst + nss_3_79_2.rst + nss_3_79_1.rst + nss_3_79.rst + nss_3_78_1.rst + nss_3_78.rst + nss_3_77.rst + nss_3_76_1.rst + nss_3_76.rst + nss_3_75.rst + nss_3_74.rst + nss_3_73_1.rst + nss_3_73.rst + nss_3_72_1.rst + nss_3_72.rst + nss_3_71.rst + nss_3_70.rst + nss_3_69_1.rst + nss_3_69.rst + nss_3_68_4.rst + nss_3_68_3.rst + nss_3_68_2.rst + nss_3_68_1.rst + nss_3_68.rst + nss_3_67.rst + nss_3_66.rst + nss_3_65.rst + nss_3_64.rst + +.. note:: + + **NSS 3.98** is the latest version of NSS. + Complete release notes are available here: :ref:`mozilla_projects_nss_nss_3_98_release_notes` + + **NSS 3.90.2 (ESR)** is the latest version of NSS. + Complete release notes are available here: :ref:`mozilla_projects_nss_nss_3_90_2_release_notes` + +.. container:: + + Changes in 3.98 included in this release: + + - Bug 1780432 - (CVE-2023-5388) Timing attack against RSA decryption in TLS. + - Bug 1879513 - Certificate Compression: enabling the check that the compression was advertised. + - Bug 1831552 - Move Windows workers to nss-1/b-win2022-alpha. + - Bug 1879945 - Remove Email trust bit from OISTE WISeKey Global Root GC CA. + - Bug 1877344 - Replace `distutils.spawn.find_executable` with `shutil.which` within `mach` in `nss`. + - Bug 1548723 - Certificate Compression: Updating nss_bogo_shim to support Certificate compression. + - Bug 1548723 - TLS Certificate Compression (RFC 8879) Implementation. + - Bug 1875356 - Add valgrind annotations to freebl kyber operations for constant-time execution tests. + - Bug 1870673 - Set nssckbi version number to 2.66. + - Bug 1874017 - Add Telekom Security roots. + - Bug 1873095 - Add D-Trust 2022 S/MIME roots. + - Bug 1865450 - Remove expired Security Communication RootCA1 root. + - Bug 1876179 - move keys to a slot that supports concatenation in PK11_ConcatSymKeys. + - Bug 1876800 - remove unmaintained tls-interop tests. + - Bug 1874937 - bogo: add support for the -ipv6 and -shim-id shim flags. + - Bug 1874937 - bogo: add support for the -curves shim flag and update Kyber expectations. + - Bug 1874937 - bogo: adjust expectation for a key usage bit test. + - Bug 1757758 - mozpkix: add option to ignore invalid subject alternative names. + - Bug 1841029 - Fix selfserv not stripping `publicname:` from -X value. + - Bug 1876390 - take ownership of ecckilla shims. + - Bug 1874458 - add valgrind annotations to freebl/ec.c. + - Bug 864039 - PR_INADDR_ANY needs PR_htonl before assignment to inet.ip. + - Bug 1875965 - Update zlib to 1.3.1. + diff --git a/security/nss/doc/rst/releases/nss_3_64.rst b/security/nss/doc/rst/releases/nss_3_64.rst new file mode 100644 index 0000000000..ee5e36f08a --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_64.rst @@ -0,0 +1,69 @@ +.. _mozilla_projects_nss_nss_3_64_release_notes: + +NSS 3.64 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.64 was released on **15 April 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_64_RTM. NSS 3.64 requires NSPR 4.30 or newer. + + NSS 3.64 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_64_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_nss_releases`. + +.. _bugs_fixed_in_nss_3.64: + +`Bugs fixed in NSS 3.64 <#bugs_fixed_in_nss_3.64>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1705286 - Properly detect mips64. + - Bug 1687164 - Introduce NSS_DISABLE_CRYPTO_VSX and disable_crypto_vsx. + - Bug 1698320 - replace \__builtin_cpu_supports("vsx") with ppc_crypto_support() for clang. + - Bug 1613235 - Add POWER ChaCha20 stream cipher vector acceleration. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.64 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.64 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + This version of NSS contains a number of contributions for "unsupported platforms". We would like + to thank the authors and the reviewers for their contributions to NSS. + + Discussions about moving the documentation are still ongoing. (See discussion in the 3.62 release + notes.)
\ No newline at end of file diff --git a/security/nss/doc/rst/releases/nss_3_65.rst b/security/nss/doc/rst/releases/nss_3_65.rst new file mode 100644 index 0000000000..7548aecc24 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_65.rst @@ -0,0 +1,77 @@ +.. _mozilla_projects_nss_nss_3_65_release_notes: + +NSS 3.65 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.65 was released on **13 May 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_65_RTM. NSS 3.65 requires NSPR 4.30 or newer. + + NSS 3.65 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_65_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _bugs_fixed_in_nss_3.65: + +`Bugs fixed in NSS 3.65 <#bugs_fixed_in_nss_3.65>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1709654 - Update for NetBSD configuration. + - Bug 1709750 - Disable HPKE test when fuzzing. + - Bug 1566124 - Optimize AES-GCM for ppc64le. + - Bug 1699021 - Add AES-256-GCM to HPKE. + - Bug 1698419 - ECH -10 updates. + - Bug 1692930 - Update HPKE to final version. + - Bug 1707130 - NSS should use modern algorithms in PKCS#12 files by default. + - Bug 1703936 - New coverity/cpp scanner errors. + - Bug 1697303 - NSS needs to update it's csp clearing to FIPS 180-3 standards. + - Bug 1702663 - Need to support RSA PSS with Hashing PKCS #11 Mechanisms. + - Bug 1705119 - Deadlock when using GCM and non-thread safe tokens. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.65 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.65 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + Due to some changes in the Firefox release cycle, NSS 3.67 has yet to be added + to the NSS release schedule (3.66 is not affected). I will announce the date to + this list once defined. + + Best, + Benjamin diff --git a/security/nss/doc/rst/releases/nss_3_66.rst b/security/nss/doc/rst/releases/nss_3_66.rst new file mode 100644 index 0000000000..4198d0a623 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_66.rst @@ -0,0 +1,79 @@ +.. _mozilla_projects_nss_nss_3_66_release_notes: + +NSS 3.66 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.66 was released on **27 May 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_66_RTM. NSS 3.66 requires NSPR 4.30 or newer. + + NSS 3.66 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_66_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _bugs_fixed_in_nss_3.66: + +`Bugs fixed in NSS 3.66 <#bugs_fixed_in_nss_3.66>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1710716 - Remove Expired Sonera Class2 CA from NSS. + - Bug 1710716 - Remove Expired Root Certificates from NSS - QuoVadis Root Certification Authority. + - Bug 1708307 - Remove Trustis FPS Root CA from NSS. + - Bug 1707097 - Add Certum Trusted Root CA to NSS. + - Bug 1707097 - Add Certum EC-384 CA to NSS. + - Bug 1703942 - Add ANF Secure Server Root CA to NSS. + - Bug 1697071 - Add GLOBALTRUST 2020 root cert to NSS. + - Bug 1712184 - NSS tools manpages need to be updated to reflect that sqlite is the default database. + - Bug 1712230 - Don't build ppc-gcm.s with clang integrated assembler. + - Bug 1712211 - Strict prototype error when trying to compile nss code that includes blapi.h. + - Bug 1710773 - NSS needs FIPS 180-3 FIPS indicators. + - Bug 1709291 - Add VerifyCodeSigningCertificateChain. + - Use GNU tar for the release helper script. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.66 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.66 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + To realign the NSS and Firefox release schedules, the next cycle for + NSS 3.67 will be very short and the release happen on June 10th. + https://wiki.mozilla.org/NSS:Release_Versions + + Bug 1712230 introduced a correctness issue for GCM on ppcle64, the fix will + be part of NSS 3.67. diff --git a/security/nss/doc/rst/releases/nss_3_67.rst b/security/nss/doc/rst/releases/nss_3_67.rst new file mode 100644 index 0000000000..3cc065e63c --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_67.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_nss_3_67_release_notes: + +NSS 3.67 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.67 was released on **10 June 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_67_RTM. NSS 3.67 requires NSPR 4.30 or newer. + + NSS 3.67 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_67_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _bugs_fixed_in_nss_3.67: + +`Bugs fixed in NSS 3.67 <#bugs_fixed_in_nss_3.67>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1683710 - Add a means to disable ALPN. + - Bug 1715720 - Fix nssckbi version number in NSS 3.67 (was supposed to be incremented in 3.66). + - Bug 1714719 - Set NSS_USE_64 on riscv64 target when using GYP/Ninja. + - Bug 1566124 - Fix counter increase in ppc-gcm-wrap.c + - Bug 1566124 - Fix AES_GCM mode on ppc64le for messages of length more than 255-byte. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.67 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.67 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + This version of NSS contains a number of contributions for "unsupported platforms". We would like + to thank the authors and the reviewers for their contributions to NSS. + + Discussions about moving the documentation are still ongoing. (See discussion in the 3.62 release + notes.) diff --git a/security/nss/doc/rst/releases/nss_3_68.rst b/security/nss/doc/rst/releases/nss_3_68.rst new file mode 100644 index 0000000000..ed719477e8 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_68.rst @@ -0,0 +1,61 @@ +.. _mozilla_projects_nss_nss_3_68_release_notes: + +NSS 3.68 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.68 was released on **8 July 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_68_RTM. NSS 3.68 requires NSPR 4.32 or newer. + + NSS 3.68 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_68_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _bugs_fixed_in_nss_3.68: + +`Bugs fixed in NSS 3.68 <#bugs_fixed_in_nss_3.68>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1713562 - Fix test leak. + - Bug 1717452 - NSS 3.68 should depend on NSPR 4.32. + - Bug 1693206 - Implement PKCS8 export of ECDSA keys. + - Bug 1712883 - DTLS 1.3 draft-43. + - Bug 1655493 - Support SHA2 HW acceleration using Intel SHA Extension. + - Bug 1713562 - Validate ECH public names. + - Bug 1717610 - Add function to get seconds from epoch from pkix::Time. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.68 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.68 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_68_1.rst b/security/nss/doc/rst/releases/nss_3_68_1.rst new file mode 100644 index 0000000000..8461b5b6ba --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_68_1.rst @@ -0,0 +1,62 @@ +.. _mozilla_projects_nss_nss_3_68_1_release_notes: + +NSS 3.68.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.68.1 (ESR) was released on **1 December 2021**. + + **This release contains an important security fix for CVE-2021-43527:** + + https://www.mozilla.org/en-US/security/advisories/mfsa2021-51/ + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_68_1_RTM. NSS 3.68.1 requires NSPR 4.32 or newer. + + NSS 3.68.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_68_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.68.1: + +`Changes in NSS 3.68.1 <#changes_in_nss_3.68.1>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1735028 - Check for missing signedData field. + - Bug 1737470 - Ensure DER encoded signatures are within size limits. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.68.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_68_2.rst b/security/nss/doc/rst/releases/nss_3_68_2.rst new file mode 100644 index 0000000000..967da2f349 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_68_2.rst @@ -0,0 +1,57 @@ +.. _mozilla_projects_nss_nss_3_68_2_release_notes: + +NSS 3.68.2 (ESR) release notes +============================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.68.2 (ESR) was released on **15 December 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_68_2_RTM. NSS 3.68.2 requires NSPR 4.32 or newer. + + NSS 3.68.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_68_2_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.68.2: + +`Changes in NSS 3.68.2 <#changes_in_nss_3.68.2>`__ +---------------------------------------------------- + +.. container:: + + - Bug 966856 - Add SHA-2 support to mozilla::pkix's OCSP implementation. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.68.2 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_68_3.rst b/security/nss/doc/rst/releases/nss_3_68_3.rst new file mode 100644 index 0000000000..857953c541 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_68_3.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_nss_3_68_3_release_notes: + +NSS 3.68.3 (ESR) release notes +============================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.68.3 (ESR) was released on **28 March 2022**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_68_3_RTM. NSS 3.68.3 requires NSPR 4.32 or newer. + + NSS 3.68.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_68_3_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.68.3: + +`Changes in NSS 3.68.3 <#changes_in_nss_3.68.3>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1756271 - Remove token member from NSSSlot struct. + - Bug 1755555 - Hold tokensLock through nssToken_GetSlot calls in nssTrustDomain_GetActiveSlots. + - Bug 1370866 - Check return value of PK11Slot_GetNSSToken. + + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.68.3 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + + +`Notes <#notes>`__ +------------------ + +.. container:: + + This release improves the stability of NSS when used in a multi-threaded + environment. In particular, it fixes memory safety violations that can occur + when PKCS#11 tokens are removed while in use (CVE-2022-1097). We presume + that with enough effort these memory safety violations are exploitable. + diff --git a/security/nss/doc/rst/releases/nss_3_68_4.rst b/security/nss/doc/rst/releases/nss_3_68_4.rst new file mode 100644 index 0000000000..670e221dd7 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_68_4.rst @@ -0,0 +1,59 @@ +.. _mozilla_projects_nss_nss_3_68_4_release_notes: + +NSS 3.68.4 (ESR) release notes +============================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.68.4 (ESR) was released on **31 May 2022**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_68_4_RTM. NSS 3.68.4 requires NSPR 4.32 or newer. + + NSS 3.68.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_68_4_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.68.4: + +`Changes in NSS 3.68.4 <#changes_in_nss_3.68.4>`__ +---------------------------------------------------- + +.. container:: + + - ug 1767590 - Initialize pointers passed to NSS_CMSDigestContext_FinishMultiple. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.68.4 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + + diff --git a/security/nss/doc/rst/releases/nss_3_69.rst b/security/nss/doc/rst/releases/nss_3_69.rst new file mode 100644 index 0000000000..e6e5b9f27e --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_69.rst @@ -0,0 +1,64 @@ +.. _mozilla_projects_nss_nss_3_69_release_notes: + +NSS 3.69 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.69 was released on **5 August 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_69_RTM. NSS 3.69 requires NSPR 4.32 or newer. + + NSS 3.69 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_69_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _bugs_fixed_in_nss_3.69: + +`Bugs fixed in NSS 3.69 <#bugs_fixed_in_nss_3.69>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1722613 - Disable DTLS 1.0 and 1.1 by default + - Bug 1720226 - integrity checks in key4.db not happening on private components with AES_CBC + - Bug 1720235 - SSL handling of signature algorithms ignores environmental invalid algorithms. + - Bug 1721476 - sqlite 3.34 changed it's open semantics, causing nss failures. + - Bug 1720230 - Gtest update changed the gtest reports, losing gtest details in all.sh reports. + - Bug 1720228 - NSS incorrectly accepting 1536 bit DH primes in FIPS mode + - Bug 1720232 - SQLite calls could timeout in starvation situations. + - Bug 1720225 - Coverity/cpp scanner errors found in nss 3.67 + - Bug 1709817 - Import the NSS documentation from MDN in nss/doc. + - Bug 1720227 - NSS using a tempdir to measure sql performance not active + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.69 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.69 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_69_1.rst b/security/nss/doc/rst/releases/nss_3_69_1.rst new file mode 100644 index 0000000000..75ed1b6f6e --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_69_1.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_nss_3_69_1_release_notes: + +NSS 3.69.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.69.1 was released on **26 August 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_69_1_RTM. NSS 3.69.1 requires NSPR 4.32 or newer. + + NSS 3.69.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_69_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_3.69.1: + +`Changes in NSS 3.69.1 <#changes_3.69.1>`__ +------------------------------------------- + +.. container:: + + - Bug 1722613 (Backout) - Disable DTLS 1.0 and 1.1 by default + - Bug 1720226 (Backout) - integrity checks in key4.db not happening on private components with AES_CBC + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.69.1 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.69.1 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + NSS 3.69.1 is a dot release based on the content of Firefox 92. Due to some issues with + the process for bringing NSS releases to Firefox, commits for 1722613 and 1720226 were absent + from the Firefox 92 branch which was associated to NSS 3.69. Due to time constraints a decision + was made to align the content of 3.69.1 with the Fx92 branch by backing out these changes instead + of restoring these commits. + + Note that Bug 1720226 was also known to introduce a performance regression that has been fixed + in the main/default branch of NSS (Bug 1726022). Since the change has been backed out in this + release, 3.69.1 does not suffer from that performance regression. + + This fix is not in 3.69 (which is affected) but will be in the 3.70 branch, which benefits from + both the change and the fix for the regression. + + The NSS 3.70 release is on schedule and will happen on September 2nd. diff --git a/security/nss/doc/rst/releases/nss_3_70.rst b/security/nss/doc/rst/releases/nss_3_70.rst new file mode 100644 index 0000000000..3c0e453ff9 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_70.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_nss_3_70_release_notes: + +NSS 3.70 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.70 was released on **5 August 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_70_RTM. NSS 3.70 requires NSPR 4.32 or newer. + + NSS 3.70 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_70_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.70: + +`Changes in NSS 3.70 <#changes_in_nss_3.70>`__ +---------------------------------------------------- + +.. container:: + + - Documentation: release notes for NSS 3.70. + - Documentation: release notes for NSS 3.69.1. + - Bug 1726022 - Update test case to verify fix. + - Bug 1714579 - Explicitly disable downgrade check in TlsConnectStreamTls13.EchOuterWith12Max + - Bug 1714579 - Explicitly disable downgrade check in TlsConnectTest.DisableFalseStartOnFallback + - Formatting for lib/util + - Bug 1681975 - Avoid using a lookup table in nssb64d. + - Bug 1724629 - Use HW accelerated SHA2 on AArch64 Big Endian. + - Bug 1714579 Change default value of enableHelloDowngradeCheck to true. + - Formatting for gtests/pk11_gtest/pk11_hpke_unittest.cc + - Bug 1726022 Cache additional PBE entries. + - Bug 1709750 - Read HPKE vectors from official JSON. + - Documentation: update for NSS 3.69 release. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.70 shared libraries are backwards-compatible with all older NSS 3.x shared libraries. A + program linked with older NSS 3.x shared libraries will work with NSS 3.70 shared libraries + without recompiling or relinking. Furthermore, applications that restrict their use of NSS APIs + to the functions listed in NSS Public Functions will remain compatible with future versions of + the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_71.rst b/security/nss/doc/rst/releases/nss_3_71.rst new file mode 100644 index 0000000000..ef1d5dfb8a --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_71.rst @@ -0,0 +1,63 @@ +.. _mozilla_projects_nss_nss_3_71_release_notes: + +NSS 3.71 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.71 was released on **30 September 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_71_RTM. NSS 3.71 requires NSPR 4.32 or newer. + + NSS 3.71 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_71_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.71: + +`Changes in NSS 3.71 <#changes_in_nss_3.71>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1717716 - Set nssckbi version number to 2.52. + - Bug 1667000 - Respect server requirements of tlsfuzzer/test-tls13-signature-algorithms.py + - Bug 1373716 - Import of PKCS#12 files with Camellia encryption is not supported + - Bug 1717707 - Add HARICA Client ECC Root CA 2021. + - Bug 1717707 - Add HARICA Client RSA Root CA 2021. + - Bug 1717707 - Add HARICA TLS ECC Root CA 2021. + - Bug 1717707 - Add HARICA TLS RSA Root CA 2021. + - Bug 1728394 - Add TunTrust Root CA certificate to NSS. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.71 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_72.rst b/security/nss/doc/rst/releases/nss_3_72.rst new file mode 100644 index 0000000000..56581dcfe2 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_72.rst @@ -0,0 +1,60 @@ +.. _mozilla_projects_nss_nss_3_72_release_notes: + +NSS 3.72 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.72 was released on **28 October 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_72_RTM. NSS 3.72 requires NSPR 4.32 or newer. + + NSS 3.72 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_72_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.72: + +`Changes in NSS 3.72 <#changes_in_nss_3.72>`__ +---------------------------------------------------- + +.. container:: + + - Documentation: release notes for NSS 3.72 + - Documentation: release notes for NSS 3.71 + - Remove newline at the end of coreconf.dep + - Bug 1731911 - Fix nsinstall parallel failure. + - Bug 1729930 - Increase KDF cache size to mitigate perf regression in about:logins. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.72 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_72_1.rst b/security/nss/doc/rst/releases/nss_3_72_1.rst new file mode 100644 index 0000000000..2392b32bcd --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_72_1.rst @@ -0,0 +1,57 @@ +.. _mozilla_projects_nss_nss_3_72_1_release_notes: + +NSS 3.72.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.72.1 was released on **15 December 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_72_1_RTM. NSS 3.72.1 requires NSPR 4.32 or newer. + + NSS 3.72.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_72_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.72.1: + +`Changes in NSS 3.72.1 <#changes_in_nss_3.72.1>`__ +---------------------------------------------------- + +.. container:: + + - Bug 966856 - Add SHA-2 support to mozilla::pkix's OCSP implementation. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.72.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_73.rst b/security/nss/doc/rst/releases/nss_3_73.rst new file mode 100644 index 0000000000..411d381973 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_73.rst @@ -0,0 +1,65 @@ +.. _mozilla_projects_nss_nss_3_73_release_notes: + +NSS 3.73 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.73 was released on **1 December 2021**. + + **This release contains an important security fix for CVE-2021-43527:** + + https://www.mozilla.org/en-US/security/advisories/mfsa2021-51/ + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_73_RTM. NSS 3.73 requires NSPR 4.32 or newer. + + NSS 3.73 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_73_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.73: + +`Changes in NSS 3.73 <#changes_in_nss_3.73>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1735028 - Check for missing signedData field. + - Bug 1737470 - Ensure DER encoded signatures are within size limits. + - Bug 1729550 - NSS needs FiPS 140-3 version indicators. + - Bug 1692132 - pkix_CacheCert_Lookup doesn't return cached certs. + - Bug 1738600 - Sunset Coverity from NSS. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.73 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_73_1.rst b/security/nss/doc/rst/releases/nss_3_73_1.rst new file mode 100644 index 0000000000..72b9d8c133 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_73_1.rst @@ -0,0 +1,57 @@ +.. _mozilla_projects_nss_nss_3_73_1_release_notes: + +NSS 3.73.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.73.1 was released on **15 December 2021**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_73_1_RTM. NSS 3.73.1 requires NSPR 4.32 or newer. + + NSS 3.73.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_73_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.73.1: + +`Changes in NSS 3.73.1 <#changes_in_nss_3.73.1>`__ +---------------------------------------------------- + +.. container:: + + - Bug 966856 - Add SHA-2 support to mozilla::pkix's OCSP implementation. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.73.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_74.rst b/security/nss/doc/rst/releases/nss_3_74.rst new file mode 100644 index 0000000000..40d8243eeb --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_74.rst @@ -0,0 +1,77 @@ +.. _mozilla_projects_nss_nss_3_74_release_notes: + +NSS 3.74 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.74 was released on **6 January 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_74_RTM. NSS 3.74 requires NSPR 4.32 or newer. + + NSS 3.74 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_74_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.74: + +`Changes in NSS 3.74 <#changes_in_nss_3.74>`__ +---------------------------------------------------- + +.. container:: + + - Bug 966856 - mozilla::pkix: support SHA-2 hashes in CertIDs in OCSP responses. + - Bug 1553612 - Ensure clients offer consistent ciphersuites after HRR. + - Bug 1721426 - NSS does not properly restrict server keys based on policy. + - Bug 1733003 - Set nssckbi version number to 2.54. + - Bug 1735407 - Replace Google Trust Services LLC (GTS) R4 root certificate in NSS. + - Bug 1735407 - Replace Google Trust Services LLC (GTS) R3 root certificate in NSS. + - Bug 1735407 - Replace Google Trust Services LLC (GTS) R2 root certificate in NSS. + - Bug 1735407 - Replace Google Trust Services LLC (GTS) R1 root certificate in NSS. + - Bug 1735407 - Replace GlobalSign ECC Root CA R4 in NSS. + - Bug 1733560 - Remove Expired Root Certificates from NSS - DST Root CA X3. + - Bug 1740807 - Remove Expiring Cybertrust Global Root and GlobalSign root certificates from NSS. + - Bug 1741930 - Add renewed Autoridad de Certificacion Firmaprofesional CIF A62634068 root certificate to NSS. + - Bug 1740095 - Add iTrusChina ECC root certificate to NSS. + - Bug 1740095 - Add iTrusChina RSA root certificate to NSS. + - Bug 1738805 - Add ISRG Root X2 root certificate to NSS. + - Bug 1733012 - Add Chunghwa Telecom's HiPKI Root CA - G1 root certificate to NSS. + - Bug 1738028 - Avoid a clang 13 unused variable warning in opt build. + - Bug 1735028 - Check for missing signedData field. + - Bug 1737470 - Ensure DER encoded signatures are within size limits. + + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.74 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_75.rst b/security/nss/doc/rst/releases/nss_3_75.rst new file mode 100644 index 0000000000..29d2c30fb8 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_75.rst @@ -0,0 +1,89 @@ +.. _mozilla_projects_nss_nss_3_75_release_notes: + +NSS 3.75 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.75 was released on **3 February 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_75_RTM. NSS 3.75 requires NSPR 4.32 or newer. + + NSS 3.75 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_75_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.75: + +`Changes in NSS 3.75 <#changes_in_nss_3.75>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1749030 - This patch adds gcc-9 and gcc-10 to the CI. + - Bug 1749794 - Make DottedOIDToCode.py compatible with python3. + - Bug 1749475 - Avoid undefined shift in SSL_CERT_IS while fuzzing. + - Bug 1748386 - Remove redundant key type check. + - Bug 1749869 - Update ABI expectations to match ECH changes. + - Bug 1748386 - Enable CKM_CHACHA20. + - Bug 1747327 - check return on NSS_NoDB_Init and NSS_Shutdown. + - Bug 1747310 - real move assignment operator. + - Bug 1748245 - Run ECDSA test vectors from bltest as part of the CI tests. + - Bug 1743302 - Add ECDSA test vectors to the bltest command line tool. + - Bug 1747772 - Allow to build using clang's integrated assembler. + - Bug 1321398 - Allow to override python for the build. + - Bug 1747317 - test HKDF output rather than input. + - Bug 1747316 - Use ASSERT macros to end failed tests early. + - Bug 1747310 - move assignment operator for DataBuffer. + - Bug 1712879 - Add test cases for ECH compression and unexpected extensions in SH. + - Bug 1725938 - Update tests for ECH-13. + - Bug 1725938 - Tidy up error handling. + - Bug 1728281 - Add tests for ECH HRR Changes. + - Bug 1728281 - Server only sends GREASE HRR extension if enabled by preference. + - Bug 1725938 - Update generation of the Associated Data for ECH-13. + - Bug 1712879 - When ECH is accepted, reject extensions which were only advertised in the Outer Client Hello. + - Bug 1712879 - Allow for compressed, non-contiguous, extensions. + - Bug 1712879 - Scramble the PSK extension in CHOuter. + - Bug 1712647 - Split custom extension handling for ECH. + - Bug 1728281 - Add ECH-13 HRR Handling. + - Bug 1677181 - Client side ECH padding. + - Bug 1725938 - Stricter ClientHelloInner Decompression. + - Bug 1725938 - Remove ECH_inner extension, use new enum format. + - Bug 1725938 - Update the version number for ECH-13 and adjust the ECHConfig size. + + + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.75 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_76.rst b/security/nss/doc/rst/releases/nss_3_76.rst new file mode 100644 index 0000000000..866bbcb0de --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_76.rst @@ -0,0 +1,63 @@ +.. _mozilla_projects_nss_nss_3_76_release_notes: + +NSS 3.76 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.76 was released on **3 March 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_76_RTM. NSS 3.76 requires NSPR 4.32 or newer. + + NSS 3.76 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_76_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.76: + +`Changes in NSS 3.76 <#changes_in_nss_3.76>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1755555 - Hold tokensLock through nssToken_GetSlot calls in nssTrustDomain_GetActiveSlots. r=rrelyea + - Bug 1370866 - Check return value of PK11Slot_GetNSSToken. r=djackson + - Bug 1747957 - Use Wycheproof JSON for RSASSA-PSS, r=nss-reviewers,bbeurdouche + - Bug 1679803 - Add SHA256 fingerprint comments to old certdata.txt entries. r=nss-reviewers,bbeurdouche + - Bug 1753505 - Avoid truncating files in nss-release-helper.py. r=bbeurdouche + - Bug 1751157 - Throw illegal_parameter alert for illegal extensions in handshake message. r=djackson + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.76 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_76_1.rst b/security/nss/doc/rst/releases/nss_3_76_1.rst new file mode 100644 index 0000000000..30ead57935 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_76_1.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_nss_3_76_1_release_notes: + +NSS 3.76.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.76.1 was released on **28 March 2022**. + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_76_1_RTM. NSS 3.76.1 requires NSPR 4.32 or newer. + + NSS 3.76.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_76_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.76.1: + +`Changes in NSS 3.76.1 <#changes_in_nss_3.76.1>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1756271 - Remove token member from NSSSlot struct. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.76.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + This release improves the stability of NSS when used in a multi-threaded + environment. In particular, it fixes memory safety violations that can occur + when PKCS#11 tokens are removed while in use (CVE-2022-1097). We presume + that with enough effort these memory safety violations are exploitable. + diff --git a/security/nss/doc/rst/releases/nss_3_77.rst b/security/nss/doc/rst/releases/nss_3_77.rst new file mode 100644 index 0000000000..46b37c4557 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_77.rst @@ -0,0 +1,92 @@ +.. _mozilla_projects_nss_nss_3_77_release_notes: + +NSS 3.77 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.77 was released on **31 March 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_77_RTM. NSS 3.77 requires NSPR 4.32 or newer. + + NSS 3.77 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_77_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.77: + +`Changes in NSS 3.77 <#changes_in_nss_3.77>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1762244 - resolve mpitests build failure on Windows. + - Bug 1761779 - Fix link to TLS page on wireshark wiki + - Bug 1754890 - Add two D-TRUST 2020 root certificates. + - Bug 1751298 - Add Telia Root CA v2 root certificate. + - Bug 1751305 - Remove expired explicitly distrusted certificates from certdata.txt. + - Bug 1005084 - support specific RSA-PSS parameters in mozilla::pkix + - Bug 1753535 - Remove obsolete stateEnd check in SEC_ASN1DecoderUpdate. + - Bug 1756271 - Remove token member from NSSSlot struct. + - Bug 1602379 - Provide secure variants of mpp_pprime and mpp_make_prime. + - Bug 1757279 - Support UTF-8 library path in the module spec string. + - Bug 1396616 - Update nssUTF8_Length to RFC 3629 and fix buffer overrun. + - Bug 1760827 - Add a CI Target for gcc-11. + - Bug 1760828 - Change to makefiles for gcc-4.8. + - Bug 1741688 - Update googletest to 1.11.0 + - Bug 1759525 - Add SetTls13GreaseEchSize to experimental API. + - Bug 1755264 - TLS 1.3 Illegal legacy_version handling/alerts. + - Bug 1755904 - Fix calculation of ECH HRR Transcript. + - Bug 1758741 - Allow ld path to be set as environment variable. + - Bug 1760653 - Ensure we don't read uninitialized memory in ssl gtests. + - Bug 1758478 - Fix DataBuffer Move Assignment. + - Bug 1552254 - internal_error alert on Certificate Request with sha1+ecdsa in TLS 1.3 + - Bug 1755092 - rework signature verification in mozilla::pkix + + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.77 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). + +`Notes <#notes>`__ +------------------ + +.. container:: + + For users upgrading from NSS < 3.76.1 or NSS < 3.68.3, this release improves + the stability of NSS when used in a multi-threaded environment. In + particular, it fixes memory safety violations that can occur when PKCS#11 + tokens are removed while in use (CVE-2022-1097). We presume that with enough + effort these memory safety violations are exploitable. + diff --git a/security/nss/doc/rst/releases/nss_3_78.rst b/security/nss/doc/rst/releases/nss_3_78.rst new file mode 100644 index 0000000000..f12224e793 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_78.rst @@ -0,0 +1,64 @@ +.. _mozilla_projects_nss_nss_3_78_release_notes: + +NSS 3.78 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.78 was released on **28 April 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_78_RTM. NSS 3.78 requires NSPR 4.32 or newer. + + NSS 3.78 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_78_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.78: + +`Changes in NSS 3.78 <#changes_in_nss_3.78>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1755264 - Added TLS 1.3 zero-length inner plaintext checks and tests, zero-length record/fragment handling tests. + - Bug 1294978 - Reworked overlong record size checks and added TLS1.3 specific boundaries. + - Bug 1763120 - Add ECH Grease Support to tstclnt + - Bug 1765003 - Add a strict variant of moz::pkix::CheckCertHostname. + - Bug 1166338 - Change SSL_REUSE_SERVER_ECDHE_KEY default to false. + - Bug 1760813 - Make SEC_PKCS12EnableCipher succeed + - Bug 1762489 - Update zlib in NSS to 1.2.12. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.78 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_78_1.rst b/security/nss/doc/rst/releases/nss_3_78_1.rst new file mode 100644 index 0000000000..08e3a1b230 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_78_1.rst @@ -0,0 +1,59 @@ +.. _mozilla_projects_nss_nss_3_78_release_notes: + +NSS 3.78 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.78.1 was released on **31 May 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_78_1_RTM. NSS 3.78.1 requires NSPR 4.32 or newer. + + NSS 3.78.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_78_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.78.1: + +`Changes in NSS 3.78.1 <#changes_in_nss_3.78.1>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1767590 - Initialize pointers passed to NSS_CMSDigestContext_FinishMultiple. + - Bug 1766978 - improve error handling after nssCKFWInstance_CreateObjectHandle. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.78.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_79.rst b/security/nss/doc/rst/releases/nss_3_79.rst new file mode 100644 index 0000000000..835fd36a92 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_79.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_nss_3_79_release_notes: + +NSS 3.79 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.79 was released on **31 May 2022**. NSS 3.79 is an ESR release. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_79_RTM. NSS 3.79 requires NSPR 4.34 or newer. + + NSS 3.79 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_79_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.79: + +`Changes in NSS 3.79 <#changes_in_nss_3.79>`__ +---------------------------------------------- + +.. container:: + + - Bug 205717 - Use PK11_GetSlotInfo instead of raw C_GetSlotInfo calls. + - Bug 1766907 - Update mercurial in clang-format docker image. + - Bug 1454072 - Use of uninitialized pointer in lg_init after alloc fail. + - Bug 1769295 - selfserv and tstclnt should use PR_GetPrefLoopbackAddrInfo. + - Bug 1753315 - Add SECMOD_LockedModuleHasRemovableSlots. + - Bug 1387919 - Fix secasn1d parsing of indefinite SEQUENCE inside indefinite GROUP. + - Bug 1765753 - Added RFC8422 compliant TLS <= 1.2 undefined/compressed ECPointFormat extension alerts. + - Bug 1765753 - TLS 1.3 Server: Send protocol_version alert on unsupported ClientHello.legacy_version. + - Bug 1764788 - Correct invalid record inner and outer content type alerts. + - Bug 1757075 - NSS does not properly import or export pkcs12 files with large passwords and pkcs5v2 encoding. + - Bug 1766978 - improve error handling after nssCKFWInstance_CreateObjectHandle. + - Bug 1767590 - Initialize pointers passed to NSS_CMSDigestContext_FinishMultiple. + - Bug 1769302 - NSS 3.79 should depend on NSPR 4.34 + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.79 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_79_1.rst b/security/nss/doc/rst/releases/nss_3_79_1.rst new file mode 100644 index 0000000000..5b47b0628d --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_79_1.rst @@ -0,0 +1,62 @@ +.. _mozilla_projects_nss_nss_3_79_1_release_notes: + +NSS 3.79.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.79.1 was released on **18 August 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_79_1_RTM. NSS 3.79.1 requires NSPR 4.34 or newer. + + NSS 3.79.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_79_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.79.1: + +`Changes in NSS 3.79.1 <#changes_in_nss_3.79.1>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1366464 - compare signature and signatureAlgorithm fields in legacy certificate verifier. + - Bug 1771498 - Uninitialized value in cert_ComputeCertType. + - Bug 1759794 - protect SFTKSlot needLogin with slotLock. + - Bug 1760998 - avoid data race on primary password change. + - Bug 1330271 - check for null template in sec_asn1{d,e}_push_state. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.79.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_79_2.rst b/security/nss/doc/rst/releases/nss_3_79_2.rst new file mode 100644 index 0000000000..1cfe6ad77a --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_79_2.rst @@ -0,0 +1,59 @@ +.. _mozilla_projects_nss_nss_3_79_2_release_notes: + +NSS 3.79.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.79.2 was released on **25 October 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_79_2_RTM. NSS 3.79.2 requires NSPR 4.34.1 or newer. + + NSS 3.79.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_79_2_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.79.2: + +`Changes in NSS 3.79.2 <#changes_in_nss_3.79.2>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1785846 - Bump minimum NSPR version to 4.34.1. + - Bug 1777672 - Gracefully handle null nickname in CERT_GetCertNicknameWithValidity. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.79.2 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_79_3.rst b/security/nss/doc/rst/releases/nss_3_79_3.rst new file mode 100644 index 0000000000..fc613b930c --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_79_3.rst @@ -0,0 +1,58 @@ +.. _mozilla_projects_nss_nss_3_79_3_release_notes: + +NSS 3.79.3 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.79.3 was released on **10 January 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_79_3_RTM. NSS 3.79.3 requires NSPR 4.34.1 or newer. + + NSS 3.79.3 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_79_3_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.79.3: + +`Changes in NSS 3.79.3 <#changes_in_nss_3.79.3>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1803453 - Set CKA_NSS_SERVER_DISTRUST_AFTER and CKA_NSS_EMAIL_DISTRUST_AFTER for 3 TrustCor Root Certificates + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.79.3 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_79_4.rst b/security/nss/doc/rst/releases/nss_3_79_4.rst new file mode 100644 index 0000000000..5cc99c5437 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_79_4.rst @@ -0,0 +1,58 @@ +.. _mozilla_projects_nss_nss_3_79_4_release_notes: + +NSS 3.79.4 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.79.4 was released on **9 February 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_79_4_RTM. NSS 3.79.4 requires NSPR 4.34.1 or newer. + + NSS 3.79.4 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_79_4_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.79.4: + +`Changes in NSS 3.79.4 <#changes_in_nss_3.79.4>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1804640 - improve handling of unknown PKCS#12 safe bag types. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.79.4 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_80.rst b/security/nss/doc/rst/releases/nss_3_80.rst new file mode 100644 index 0000000000..e283c4b57c --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_80.rst @@ -0,0 +1,75 @@ +.. _mozilla_projects_nss_nss_3_80_release_notes: + +NSS 3.80 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.80 was released on **23 June 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_80_RTM. NSS 3.80 requires NSPR 4.34 or newer. + + NSS 3.80 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_80_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.80: + +`Changes in NSS 3.80 <#changes_in_nss_3.80>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1774720 - Fix SEC_ERROR_ALGORITHM_MISMATCH entry in SECerrs.h. + - Bug 1617956 - Add support for asynchronous client auth hooks. + - Bug 1497537 - nss-policy-check: make unknown keyword check optional. + - Bug 1765383 - GatherBuffer: Reduced plaintext buffer allocations by allocating it on initialization. Replaced redundant code with assert. Debug builds: Added buffer freeing/allocation for each record. + - Bug 1773022 - Mark 3.79 as an ESR release. + - Bug 1764206 - Bump nssckbi version number for June. + - Bug 1759815 - Remove Hellenic Academic 2011 Root. + - Bug 1770267 - Add E-Tugra Roots. + - Bug 1768970 - Add Certainly Roots. + - Bug 1764392 - Add DigitCert Roots. + - Bug 1759794 - Protect SFTKSlot needLogin with slotLock. + - Bug 1366464 - Compare signature and signatureAlgorithm fields in legacy certificate verifier. + - Bug 1771497 - Uninitialized value in cert_VerifyCertChainOld. + - Bug 1771495 - Unchecked return code in sec_DecodeSigAlg. + - Bug 1771498 - Uninitialized value in cert_ComputeCertType. + - Bug 1760998 - Avoid data race on primary password change. + - Bug 1769063 - Replace ppc64 dcbzl intrinisic. + - Bug 1771036 - Allow LDFLAGS override in makefile builds. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.80 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_81.rst b/security/nss/doc/rst/releases/nss_3_81.rst new file mode 100644 index 0000000000..91053fc348 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_81.rst @@ -0,0 +1,60 @@ +.. _mozilla_projects_nss_nss_3_81_release_notes: + +NSS 3.81 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.81 was released on **21 July 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_81_RTM. NSS 3.81 requires NSPR 4.34 or newer. + + NSS 3.81 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_81_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.81: + +`Changes in NSS 3.81 <#changes_in_nss_3.81>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1762831: Enable aarch64 hardware crypto support on OpenBSD. + - Bug 1775359 - make NSS_SecureMemcmp 0/1 valued. + - Bug 1779285: Add no_application_protocol alert handler and test client error code is set. + - Bug 1777672 - Gracefully handle null nickname in CERT_GetCertNicknameWithValidity. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.81 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_82.rst b/security/nss/doc/rst/releases/nss_3_82.rst new file mode 100644 index 0000000000..da18519de4 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_82.rst @@ -0,0 +1,61 @@ +.. _mozilla_projects_nss_nss_3_82_release_notes: + +NSS 3.82 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.82 was released on **18 August 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_82_RTM. NSS 3.82 requires NSPR 4.34 or newer. + + NSS 3.82 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_82_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.82: + +`Changes in NSS 3.82 <#changes_in_nss_3.82>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1330271 - check for null template in sec_asn1{d,e}_push_state + - Bug 1735925 - QuickDER: Forbid NULL tags with non-zero length + - Bug 1784724 - Initialize local variables in TlsConnectTestBase::ConnectAndCheckCipherSuite + - Bug 1784191 - Cast the result of GetProcAddress + - Bug 1681099 - pk11wrap: Tighten certificate lookup based on PKCS #11 URI + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.82 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_83.rst b/security/nss/doc/rst/releases/nss_3_83.rst new file mode 100644 index 0000000000..d8a7b01827 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_83.rst @@ -0,0 +1,74 @@ +.. _mozilla_projects_nss_nss_3_83_release_notes: + +NSS 3.83 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.83 was released on **15 September 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_83_RTM. NSS 3.83 requires NSPR 4.34.1 or newer. + + NSS 3.83 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_83_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.83: + +`Changes in NSS 3.83 <#changes_in_nss_3.83>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1788875 - Remove set-but-unused variables from SEC_PKCS12DecoderValidateBags + - Bug 1563221 - remove older oses that are unused part3/ BeOS + - Bug 1563221 - remove older unix support in NSS part 3 Irix + - Bug 1563221 - remove support for older unix in NSS part 2 DGUX + - Bug 1563221 - remove support for older unix in NSS part 1 OSF + - Bug 1778413 - Set nssckbi version number to 2.58 + - Bug 1785297 - Add two SECOM root certificates to NSS + - Bug 1787075 - Add two DigitalSign root certificates to NSS + - Bug 1778412 - Remove Camerfirma Global Chambersign Root from NSS + - Bug 1771100 - Added bug reference and description to disabled UnsolicitedServerNameAck bogo ECH test + - Bug 1779361 - Removed skipping of ECH on equality of private and public SNI server name + - Bug 1779357 - Added comment and bug reference to ECHRandomHRRExtension bogo test + - Bug 1779370 - Added Bogo shim client HRR test support. Fixed overwriting of CHInner.random on HRR + - Bug 1779234 - Added check for server only sending ECH extension with retry configs in EncryptedExtensions and if not accepting ECH. Changed config setting behavior to skip configs with unsupported mandatory extensions instead of failing + - Bug 1771100 - Added ECH client support to BoGo shim. Changed CHInner creation to skip TLS 1.2 only extensions to comply with BoGo + - Bug 1771100 - Added ECH server support to BoGo shim. Fixed NSS ECH server accept_confirmation bugs + - Bug 1771100 - Update BoGo tests to recent BoringSSL version + - Bug 1785846 - Bump minimum NSPR version to 4.34.1 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.83 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_84.rst b/security/nss/doc/rst/releases/nss_3_84.rst new file mode 100644 index 0000000000..72ac886c0b --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_84.rst @@ -0,0 +1,58 @@ +.. _mozilla_projects_nss_nss_3_84_release_notes: + +NSS 3.84 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.84 was released on **13 October 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_84_RTM. NSS 3.84 requires NSPR 4.35 or newer. + + NSS 3.84 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_84_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.84: + +`Changes in NSS 3.84 <#changes_in_nss_3.84>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1791699 - Bump minimum NSPR version to 4.35. + - Bug 1792103 - Add a flag to disable building libnssckbi. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.84 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_85.rst b/security/nss/doc/rst/releases/nss_3_85.rst new file mode 100644 index 0000000000..0ad6398956 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_85.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_nss_3_85_release_notes: + +NSS 3.85 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.85 was released on **10 November 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_85_RTM. NSS 3.85 requires NSPR 4.35 or newer. + + NSS 3.85 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_85_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.85: + +`Changes in NSS 3.85 <#changes_in_nss_3.85>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1792821 - Modification of the primes.c and dhe-params.c in order to have better looking tables. + - Bug 1796815 - Update zlib in NSS to 1.2.13. + - Bug 1796504 - Skip building modutil and shlibsign when building in Firefox. + - Bug 1796504 - Use __STDC_VERSION__ rather than __STDC__ as a guard. + - Bug 1796407 - Fix -Wunused-but-set-variable warning from clang 15. + - Bug 1796308 - Fix -Wtautological-constant-out-of-range-compare and -Wtype-limits warnings. + - Bug 1796281 - Followup: add missing stdint.h include. + - Bug 1796281 - Fix -Wint-to-void-pointer-cast warnings. + - Bug 1796280 - Fix -Wunused-{function,variable,but-set-variable} warnings on Windows. + - Bug 1796079 - Fix -Wstring-conversion warnings. + - Bug 1796075 - Fix -Wempty-body warnings. + - Bug 1795242 - Fix unused-but-set-parameter warning. + - Bug 1795241 - Fix unreachable-code warnings. + - Bug 1795222 - Mark _nss_version_c unused on clang-cl. + - Bug 1795668 - Remove redundant variable definitions in lowhashtest. + - No bug - Add note about python executable to build instructions. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.85 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_86.rst b/security/nss/doc/rst/releases/nss_3_86.rst new file mode 100644 index 0000000000..3b02b19fa3 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_86.rst @@ -0,0 +1,72 @@ +.. _mozilla_projects_nss_nss_3_86_release_notes: + +NSS 3.86 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.86 was released on **8 December 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_86_RTM. NSS 3.86 requires NSPR 4.35 or newer. + + NSS 3.86 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_86_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.86: + +`Changes in NSS 3.86 <#changes_in_nss_3.86>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1803190 - conscious language removal in NSS. + - Bug 1794506 - Set nssckbi version number to 2.60. + - Bug 1803453 - Set CKA_NSS_SERVER_DISTRUST_AFTER and CKA_NSS_EMAIL_DISTRUST_AFTER for 3 TrustCor Root Certificates. + - Bug 1799038 - Remove Staat der Nederlanden EV Root CA from NSS. + - Bug 1797559 - Remove EC-ACC root cert from NSS. + - Bug 1794507 - Remove SwissSign Platinum CA - G2 from NSS. + - Bug 1794495 - Remove Network Solutions Certificate Authority. + - Bug 1802331 - compress docker image artifact with zstd. + - Bug 1799315 - Migrate nss from AWS to GCP. + - Bug 1800989 - Enable static builds in the CI. + - Bug 1765759 - Removing SAW docker from the NSS build system. + - Bug 1783231 - Initialising variables in the rsa blinding code. + - Bug 320582 - Implementation of the double-signing of the message for ECDSA. + - Bug 1783231 - Adding exponent blinding for RSA. + + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.86 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_87.rst b/security/nss/doc/rst/releases/nss_3_87.rst new file mode 100644 index 0000000000..7cb6690c5d --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_87.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_nss_3_87_release_notes: + +NSS 3.87 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.87 was released on **5 January 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_87_RTM. NSS 3.87 requires NSPR 4.35 or newer. + + NSS 3.87 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_87_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.87: + +`Changes in NSS 3.87 <#changes_in_nss_3.87>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1803226 - NULL password encoding incorrect. + - Bug 1804071 - Fix rng stub signature for fuzzing builds. + - Bug 1803595 - Updating the compiler parsing for build. + - Bug 1749030 - Modification of supported compilers. + - Bug 1774654 tstclnt crashes when accessing gnutls server without a user cert in the database. + - Bug 1751707 - Add configuration option to enable source-based coverage sanitizer. + - Bug 1751705 - Update ECCKiila generated files. + - Bug 1730353 - Add support for the LoongArch 64-bit architecture. + - Bug 1798823 - add checks for zero-length RSA modulus to avoid memory errors and failed assertions later. + - Bug 1798823 - Additional zero-length RSA modulus checks. + + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.87 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_87_1.rst b/security/nss/doc/rst/releases/nss_3_87_1.rst new file mode 100644 index 0000000000..342d89aec7 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_87_1.rst @@ -0,0 +1,57 @@ +.. _mozilla_projects_nss_nss_3_87_1_release_notes: + +NSS 3.87.1 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.87.1 was released on **9 February 2022**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_87_RTM. NSS 3.87 requires NSPR 4.35 or newer. + + NSS 3.87.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_87_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.87.1: + +`Changes in NSS 3.87.1 <#changes_in_nss_3.87.1>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1804640 - improve handling of unknown PKCS#12 safe bag types. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.87.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_88.rst b/security/nss/doc/rst/releases/nss_3_88.rst new file mode 100644 index 0000000000..15ed04931e --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_88.rst @@ -0,0 +1,82 @@ +.. _mozilla_projects_nss_nss_3_88_release_notes: + +NSS 3.88 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.88 was released on *9 February 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_88_RTM. NSS 3.88 requires NSPR 4.35 or newer. + + NSS 3.88 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_88_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.88: + +`Changes in NSS 3.88 <#changes_in_nss_3.88>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1815870 - use a different treeherder symbol for each docker image build task. + - Bug 1815868 - pin an older version of the ubuntu:18.04 and 20.04 docker images + - Bug 1810702 - remove nested table in rst doc + - Bug 1815246 - Export NSS_CMSSignerInfo_GetDigestAlgTag. + - Bug 1812671 - build failure while implicitly casting SECStatus to PRUInt32. r=nss-reviewers,mt + - Bug 1212915 - Add check for ClientHello SID max length. This is tested by Bogo tests + - Bug 1771100 - Added EarlyData ALPN test support to BoGo shim. + - Bug 1790357 - ECH client - Discard resumption TLS < 1.3 Session(IDs|Tickets) if ECH configs are setup. + - Bug 1714245 - On HRR skip PSK incompatible with negotiated ciphersuites hash algorithm. + - Bug 1789410 - ECH client: Send ech_required alert on server negotiating TLS 1.2. Fixed misleading Gtest, enabled corresponding BoGo test. + - Bug 1771100 - Added Bogo ECH rejection test support. + - Bug 1771100 - Added ECH 0Rtt support to BoGo shim. + - Bug 1747957 - RSA OAEP Wycheproof JSON + - Bug 1747957 - RSA decrypt Wycheproof JSON + - Bug 1747957 - ECDSA Wycheproof JSON + - Bug 1747957 - ECDH Wycheproof JSON + - Bug 1747957 - PKCS#1v1.5 wycheproof json + - Bug 1747957 - Use X25519 wycheproof json + - Bug 1766767 - Move scripts to python3 + - Bug 1809627 - Properly link FuzzingEngine for oss-fuzz. + - Bug 1805907 - Extending RSA-PSS bltest test coverage (Adding SHA-256 and SHA-384) + - Bug 1804091 NSS needs to move off of DSA for integrity checks + - Bug 1805815 - Add initial testing with ACVP vector sets using acvp-rust + - Bug 1806369 - Don't clone libFuzzer, rely on clang instead + + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.88 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_88_1.rst b/security/nss/doc/rst/releases/nss_3_88_1.rst new file mode 100644 index 0000000000..63d5bb12e1 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_88_1.rst @@ -0,0 +1,58 @@ +.. _mozilla_projects_nss_nss_3_88_1_release_notes: + +NSS 3.88.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.88.1 was released on *9 February 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_88_1_RTM. NSS 3.88.1 requires NSPR 4.35 or newer. + + NSS 3.88.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_88_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.88.1: + +`Changes in NSS 3.88.1 <#changes_in_nss_3.88.1>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1804640 - improve handling of unknown PKCS#12 safe bag types. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.88.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_89.rst b/security/nss/doc/rst/releases/nss_3_89.rst new file mode 100644 index 0000000000..b523dd8b2f --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_89.rst @@ -0,0 +1,83 @@ +.. _mozilla_projects_nss_nss_3_89_release_notes: + +NSS 3.89 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.89 was released on *9 March 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_89_RTM. NSS 3.89 requires NSPR 4.35 or newer. + + NSS 3.89 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_89_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.89: + +`Changes in NSS 3.89 <#changes_in_nss_3.89>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1820834 - revert freebl/softoken RSA_MIN_MODULUS_BITS increase. + - Bug 1820175 - PR_STATIC_ASSERT is cursed. + - Bug 1767883 - Need to add policy control to keys lengths for signatures. + - Bug 1820175 - Fix unreachable code warning in fuzz builds. + - Bug 1820175 - Fix various compiler warnings in NSS. + - Bug 1820175 - Enable various compiler warnings for clang builds. + - Bug 1815136 - set PORT error after sftk_HMACCmp failure. + - Bug 1767883 - Need to add policy control to keys lengths for signatures. + - Bug 1804662 - remove data length assertion in sec_PKCS7Decrypt. + - Bug 1804660 - Make high tag number assertion failure an error. + - Bug 1817513 - CKM_SHA384_KEY_DERIVATION correction maximum key length from 284 to 384. + - Bug 1815167 - Tolerate certificate_authorities xtn in ClientHello. + - Bug 1789436 - Fix build failure on Windows. + - Bug 1811337 - migrate Win 2012 tasks to Azure. + - Bug 1810702 - fix title length in doc. + - Bug 1570615 - Add interop tests for HRR and PSK to GREASE suite. + - Bug 1570615 - Add presence/absence tests for TLS GREASE. + - Bug 1804688 - Correct addition of GREASE value to ALPN xtn. + - Bug 1789436 - CH extension permutation. + - Bug 1570615 - TLS GREASE (RFC8701). + - Bug 1804640 - improve handling of unknown PKCS#12 safe bag types. + - Bug 1815870 - use a different treeherder symbol for each docker image build task. + - Bug 1815868 - pin an older version of the ubuntu:18.04 and 20.04 docker images. + - Bug 1810702 - remove nested table in rst doc. + - Bug 1815246 - Export NSS_CMSSignerInfo_GetDigestAlgTag. + - Bug 1812671 - build failure while implicitly casting SECStatus to PRUInt32. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.89 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_89_1.rst b/security/nss/doc/rst/releases/nss_3_89_1.rst new file mode 100644 index 0000000000..b168b30ec0 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_89_1.rst @@ -0,0 +1,59 @@ +.. _mozilla_projects_nss_nss_3_89_1_release_notes: + +NSS 3.89.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.89.1 was released on *5th May 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_89_1_RTM. NSS 3.89.1 requires NSPR 4.35 or newer. + + NSS 3.89.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_89_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.89.1: + +`Changes in NSS 3.89.1 <#changes_in_nss_3.89.1>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1804505 - Update the technical constraints for KamuSM. + - Bug 1822921 - Add BJCA Global Root CA1 and CA2 root certificates. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.89.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_90.rst b/security/nss/doc/rst/releases/nss_3_90.rst new file mode 100644 index 0000000000..5b3623a8f9 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_90.rst @@ -0,0 +1,89 @@ +.. _mozilla_projects_nss_nss_3_90_release_notes: + +NSS 3.90 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.90 was released on *4 June 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_90_RTM. NSS 3.90 requires NSPR 4.35 or newer. + + NSS 3.90 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_90_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.90: + +`Changes in NSS 3.90 <#changes_in_nss_3.90>`__ +---------------------------------------------------- + +.. container:: + + +- Bug 1623338 - ride along: remove a duplicated doc page +- Bug 1623338 - remove a reference to IRC +- Bug 1831983 - clang-format lib/freebl/stubs.c +- Bug 1831983 - Add a constant time select function +- Bug 1774657 - Updating an old dbm with lots of certs with keys to sql results in a database that is slow to access. +- Bug 1830973 - output early build errors by default +- Bug 1804505 - Update the technical constraints for KamuSM +- Bug 1822921 - Add BJCA Global Root CA1 and CA2 root certificates +- Bug 1790763 - Enable default UBSan Checks +- Bug 1786018 - Add explicit handling of zero length records +- Bug 1829391 - Tidy up DTLS ACK Error Handling Path +- Bug 1786018 - Refactor zero length record tests +- Bug 1829112 - Fix compiler warning via correct assert +- Bug 1755267 - run linux tests on nss-t/t-linux-xlarge-gcp +- Bug 1806496 - In FIPS mode, nss should reject RSASSA-PSS salt lengths larger than the output size of the hash function used, or provide an indicator +- Bug 1784163 - Fix reading raw negative numbers +- Bug 1748237 - Repairing unreachable code in clang built with gyp +- Bug 1783647 - Integrate Vale Curve25519 +- Bug 1799468 - Removing unused flags for Hacl* +- Bug 1748237 - Adding a better error message +- Bug 1727555 - Update HACL* till 51a72a953a4ee6f91e63b2816ae5c4e62edf35d6 +- Bug 1782980 - Fall back to the softokn when writing certificate trust +- Bug 1806010 - FIPS-104-3 requires we restart post programmatically +- Bug 1826650 - cmd/ecperf: fix dangling pointer warning on gcc 13 +- Bug 1818766 - Update ACVP dockerfile for compatibility with debian package changes +- Bug 1815796 - Add a CI task for tracking ECCKiila code status, update whitespace in ECCKiila files +- Bug 1819958 - Removed deprecated sprintf function and replaced with snprintf +- Bug 1822076 - fix rst warnings in nss doc +- Bug 1821997 - Fix incorrect pygment style +- Bug 1821292 - Change GYP directive to apply across platforms +- Add libsmime3 abi-check exception for NSS_CMSSignerInfo_GetDigestAlgTag + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.90 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_90_1.rst b/security/nss/doc/rst/releases/nss_3_90_1.rst new file mode 100644 index 0000000000..807020f243 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_90_1.rst @@ -0,0 +1,59 @@ +.. _mozilla_projects_nss_nss_3_90_1_release_notes: + +NSS 3.90.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.90.1 was released on *10th November 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_90_1_RTM. NSS 3.90.1 requires NSPR 4.35 or newer. + + NSS 3.90.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_90_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.90.1: + +`Changes in NSS 3.90.1 <#changes_in_nss_3.90.1>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1813401 - regenerate NameConstraints test certificates. + - Bug 1854795 - add OSXSAVE and XCR0 tests to AVX2 detection. + + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.90.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_90_2.rst b/security/nss/doc/rst/releases/nss_3_90_2.rst new file mode 100644 index 0000000000..6210183540 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_90_2.rst @@ -0,0 +1,56 @@ +.. _mozilla_projects_nss_nss_3_90_2_release_notes: + +NSS 3.90.2 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.90.2 was released on *15th February 2024**. + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_90_2_RTM. NSS 3.90.2 requires NSPR 4.35 or newer. + + NSS 3.90.2 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_90_2_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.90.2: + +`Changes in NSS 3.90.2 <#changes_in_nss_3.90.2>`__ +-------------------------------------------------- + +.. container:: + + - Bug 1780432 - (CVE-2023-5388) Timing attack against RSA decryption in TLS. + - Bug 1867408 - add a defensive check for large ssl_DefSend return values. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.90.2 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_91.rst b/security/nss/doc/rst/releases/nss_3_91.rst new file mode 100644 index 0000000000..8c13ae1736 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_91.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_nss_3_91_release_notes: + +NSS 3.91 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.91 was released on *9 March 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_91_RTM. NSS 3.91 requires NSPR 4.35 or newer. + + NSS 3.91 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_91_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.91: + +`Changes in NSS 3.91 <#changes_in_nss_3.91>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1837431 - Implementation of the HW support check for ADX instruction + - Bug 1836925 - Removing the support of Curve25519 + - Bug 1839795 - Fix comment about the addition of ticketSupportsEarlyData. + - Bug 1839327 - Adding args to enable-legacy-db build + - Bug 1835357 dbtests.sh failure in "certutil dump keys with explicit default trust flags" + - Bug 1837617: Initialize flags in slot structures + - Bug 1835425: Improve the length check of RSA input to avoid heap overflow + - Bug 1829112 - Followup Fixes + - Bug 1784253: avoid processing unexpected inputs by checking for m_exptmod base sign + - Bug 1826652: add a limit check on order_k to avoid infinite loop + - Bug 1834851 - Update HACL* to commit 5f6051d2. + - Bug 1753026 - add SHA3 to cryptohi and softoken. + - Bug 1753026: HACL SHA3 + - Bug 1836781 - Disabling ASM C25519 for A but X86_64 + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.91 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_92.rst b/security/nss/doc/rst/releases/nss_3_92.rst new file mode 100644 index 0000000000..e49a6a8660 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_92.rst @@ -0,0 +1,66 @@ +.. _mozilla_projects_nss_nss_3_92_release_notes: + +NSS 3.92 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.92 was released on *27 July 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_92_RTM. NSS 3.92 requires NSPR 4.35 or newer. + + NSS 3.92 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_92_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.92: + +`Changes in NSS 3.92 <#changes_in_nss_3.92>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1822935 - Set nssckbi version number to 2.62. + - Bug 1833270 - Add 4 Atos TrustedRoot Root CA certificates to NSS. + - Bug 1839992 - Add 4 SSL.com Root CA certificates. + - Bug 1840429 - Add Sectigo E46 and R46 Root CA certificates. + - Bug 1840437 - Add LAWtrust Root CA2 (4096). + - Bug 1822936 - Remove E-Tugra Certification Authority root. + - Bug 1827224 - Remove Camerfirma Chambers of Commerce Root. + - Bug 1840505 - Remove Hongkong Post Root CA 1. + - Bug 1842928 - Remove E-Tugra Global Root CA ECC v3 and RSA v3. + - Bug 1842937 - Avoid redefining BYTE_ORDER on hppa Linux. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.92 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_93.rst b/security/nss/doc/rst/releases/nss_3_93.rst new file mode 100644 index 0000000000..fedd5eb006 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_93.rst @@ -0,0 +1,59 @@ +.. _mozilla_projects_nss_nss_3_93_release_notes: + +NSS 3.93 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.93 was released on *25 August 2023**. + + + + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_93_RTM. NSS 3.93 requires NSPR 4.35 or newer. + + NSS 3.93 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_93_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.93: + +`Changes in NSS 3.93 <#changes_in_nss_3.93>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1849471 - Update zlib in NSS to 1.3. + - Bug 1848183 - softoken: iterate hashUpdate calls for long inputs. + - Bug 1813401 - regenerate NameConstraints test certificates. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.93 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_94.rst b/security/nss/doc/rst/releases/nss_3_94.rst new file mode 100644 index 0000000000..4c44a4a2ae --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_94.rst @@ -0,0 +1,65 @@ +.. _mozilla_projects_nss_nss_3_94_release_notes: + +NSS 3.94 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.94 was released on *2nd October 2023**. + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_94_RTM. NSS 3.94 requires NSPR 4.35 or newer. + + NSS 3.94 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_94_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.94: + +`Changes in NSS 3.94 <#changes_in_nss_3.94>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1853737 - Updated code and commit ID for HACL*. + - Bug 1840510 - update ACVP fuzzed test vector: refuzzed with current NSS + - Bug 1827303 - Softoken C_ calls should use system FIPS setting to select NSC_ or FC_ variants. + - Bug 1774659 - NSS needs a database tool that can dump the low level representation of the database. + - Bug 1852179 - declare string literals using char in pkixnames_tests.cpp. + - Bug 1852179 - avoid implicit conversion for ByteString. + - Bug 1818766 - update rust version for acvp docker. + - Bug 1852011 - Moving the init function of the mpi_ints before clean-up in ec.c + - Bug 1615555 - P-256 ECDH and ECDSA from HACL*. + - Bug 1840510 - Add ACVP test vectors to the repository + - Bug 1849077 - Stop relying on std::basic_string<uint8_t>. + - Bug 1847845 - Transpose the PPC_ABI check from Makefile to gyp. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.94 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_95.rst b/security/nss/doc/rst/releases/nss_3_95.rst new file mode 100644 index 0000000000..85fec9c208 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_95.rst @@ -0,0 +1,70 @@ +.. _mozilla_projects_nss_nss_3_95_release_notes: + +NSS 3.95 release notes +====================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.95 was released on *16th November 2023**. + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_95_RTM. NSS 3.95 requires NSPR 4.35 or newer. + + NSS 3.95 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_95_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.95: + +`Changes in NSS 3.95 <#changes_in_nss_3.95>`__ +---------------------------------------------------- + +.. container:: + + - Bug 1842932 - Bump builtins version number. + - Bug 1851044: Remove Email trust bit from Autoridad de Certificacion Firmaprofesional CIF A62634068 root cert. + - Bug 1855318: Remove 4 DigiCert (Symantec/Verisign) Root Certificates from NSS. + - Bug 1851049: Remove 3 TrustCor Root Certificates from NSS. + - Bug 1850982 - Remove Camerfirma root certificates from NSS. + - Bug 1842935 - Remove old Autoridad de Certificacion Firmaprofesional Certificate. + - Bug 1860670 - Add four Commscope root certificates to NSS. + - Bug 1850598 - Add TrustAsia Global Root CA G3 and G4 root certificates. + - Bug 1863605 - Include P-384 and P-521 Scalar Validation from HACL* + - Bug 1861728 - Include P-256 Scalar Validation from HACL*. + - Bug 1861265 After the HACL 256 ECC patch, NSS incorrectly encodes 256 ECC without DER wrapping at the softoken level + - Bug 1837987:Add means to provide library parameters to C_Initialize + - Bug 1573097 - clang format + - Bug 1854795 - add OSXSAVE and XCR0 tests to AVX2 detection. + - Bug 1858241 - Typo in ssl3_AppendHandshakeNumber + - Bug 1858241 - Introducing input check of ssl3_AppendHandshakeNumber + - Bug 1573097 - Fix Invalid casts in instance.c + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.95 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_96.rst b/security/nss/doc/rst/releases/nss_3_96.rst new file mode 100644 index 0000000000..b58db91e98 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_96.rst @@ -0,0 +1,17 @@ +.. _mozilla_projects_nss_nss_3_96_release_notes: + +NSS 3.96 release notes +====================== + +Unfortunately due to issues with the release process we have inconsistent +source code between the 3.96.0 tag in the NSS repo and the code that is on the FTP. +The code for 3.96.0 available on the FTP contains some changes planned for the +next release (namely DTLS 1.3). + +As we cannot change what has been published on the FTP easily, and to avoid further +confusion, we published a dot release... + +As part of our roadmap to improve release automation, we will design things to be +resilient against this divergence in the future. + +NSS 3.96.1 is available consistently in the FTP, the repo and Firefox as expected. diff --git a/security/nss/doc/rst/releases/nss_3_96_1.rst b/security/nss/doc/rst/releases/nss_3_96_1.rst new file mode 100644 index 0000000000..45aa2607cc --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_96_1.rst @@ -0,0 +1,58 @@ +.. _mozilla_projects_nss_nss_3_96_1_release_notes: + +NSS 3.96.1 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.96.1 was released on *18th December 2023**. + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_96_1_RTM. NSS 3.96.1 requires NSPR 4.35 or newer. + + NSS 3.96.1 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_96_1_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.96.1: + +`Changes in NSS 3.96.1 (from NSS 3.95) <#changes_in_nss_3.96.1>`__ +------------------------------------------------------------------ + +.. container:: + + - Bug 1869408 - Use pypi dependencies for MacOS worker in ./build_gyp.sh + - Bug 1830978 - p7sign: add -a hash and -u certusage (also p7verify cleanups). + - Bug 1867408 - add a defensive check for large ssl_DefSend return values. + - Bug 1869378 - Add dependency to the taskcluster script for Darwin + - Bug 1869378 - Upgrade version of the MacOS worker for the CI + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.96.1 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_97.rst b/security/nss/doc/rst/releases/nss_3_97.rst new file mode 100644 index 0000000000..ee0320ed9d --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_97.rst @@ -0,0 +1,68 @@ +.. _mozilla_projects_nss_nss_3_97_release_notes: + +NSS 3.97 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.97 was released on *22nd January 2024**. + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_97_RTM. NSS 3.97 requires NSPR 4.35 or newer. + + NSS 3.97 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_97_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.97: + +`Changes in NSS 3.97 <#changes_in_nss_3.97>`__ +------------------------------------------------------------------ + +.. container:: + + - Bug 1875506 - make Xyber768d00 opt-in by policy. + - Bug 1871631 - add libssl support for xyber768d00. + - Bug 1871630 - add PK11_ConcatSymKeys. + - Bug 1775046 - add Kyber and a PKCS#11 KEM interface to softoken. + - Bug 1871152 - add a FreeBL API for Kyber. + - Bug 1826451 - part 2: vendor github.com/pq-crystals/kyber/commit/e0d1c6ff. + - Bug 1826451 - part 1: add a script for vendoring kyber from pq-crystals repo. + - Bug 1835828 - Removing the calls to RSA Blind from loader.* + - Bug 1874111 - fix worker type for level3 mac tasks. + - Bug 1835828 - RSA Blind implementation. + - Bug 1869642 - Remove DSA selftests. + - Bug 1873296 - read KWP testvectors from JSON. + - Bug 1822450 - Backed out changeset dcb174139e4f + - Bug 1822450 - Fix CKM_PBE_SHA1_DES2_EDE_CBC derivation. + - Bug 1871219 - Wrap CC shell commands in gyp expansions. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.97 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). diff --git a/security/nss/doc/rst/releases/nss_3_98.rst b/security/nss/doc/rst/releases/nss_3_98.rst new file mode 100644 index 0000000000..4a4a415a12 --- /dev/null +++ b/security/nss/doc/rst/releases/nss_3_98.rst @@ -0,0 +1,76 @@ +.. _mozilla_projects_nss_nss_3_98_release_notes: + +NSS 3.98 release notes +======================== + +`Introduction <#introduction>`__ +-------------------------------- + +.. container:: + + Network Security Services (NSS) 3.98 was released on *15th February 2024**. + +`Distribution Information <#distribution_information>`__ +-------------------------------------------------------- + +.. container:: + + The HG tag is NSS_3_98_RTM. NSS 3.98 requires NSPR 4.35 or newer. + + NSS 3.98 source distributions are available on ftp.mozilla.org for secure HTTPS download: + + - Source tarballs: + https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_98_RTM/src/ + + Other releases are available :ref:`mozilla_projects_nss_releases`. + +.. _changes_in_nss_3.98: + +`Changes in NSS 3.98 <#changes_in_nss_3.98>`__ +------------------------------------------------------------------ + +.. container:: + + - Bug 1780432 - (CVE-2023-5388) Timing attack against RSA decryption in TLS. + - Bug 1879513 - Certificate Compression: enabling the check that the compression was advertised. + - Bug 1831552 - Move Windows workers to nss-1/b-win2022-alpha. + - Bug 1879945 - Remove Email trust bit from OISTE WISeKey Global Root GC CA. + - Bug 1877344 - Replace `distutils.spawn.find_executable` with `shutil.which` within `mach` in `nss`. + - Bug 1548723 - Certificate Compression: Updating nss_bogo_shim to support Certificate compression. + - Bug 1548723 - TLS Certificate Compression (RFC 8879) Implementation. + - Bug 1875356 - Add valgrind annotations to freebl kyber operations for constant-time execution tests. + - Bug 1870673 - Set nssckbi version number to 2.66. + - Bug 1874017 - Add Telekom Security roots. + - Bug 1873095 - Add D-Trust 2022 S/MIME roots. + - Bug 1865450 - Remove expired Security Communication RootCA1 root. + - Bug 1876179 - move keys to a slot that supports concatenation in PK11_ConcatSymKeys. + - Bug 1876800 - remove unmaintained tls-interop tests. + - Bug 1874937 - bogo: add support for the -ipv6 and -shim-id shim flags. + - Bug 1874937 - bogo: add support for the -curves shim flag and update Kyber expectations. + - Bug 1874937 - bogo: adjust expectation for a key usage bit test. + - Bug 1757758 - mozpkix: add option to ignore invalid subject alternative names. + - Bug 1841029 - Fix selfserv not stripping `publicname:` from -X value. + - Bug 1876390 - take ownership of ecckilla shims. + - Bug 1874458 - add valgrind annotations to freebl/ec.c. + - Bug 864039 - PR_INADDR_ANY needs PR_htonl before assignment to inet.ip. + - Bug 1875965 - Update zlib to 1.3.1. + +`Compatibility <#compatibility>`__ +---------------------------------- + +.. container:: + + NSS 3.98 shared libraries are backwards-compatible with all older NSS 3.x shared + libraries. A program linked with older NSS 3.x shared libraries will work with + this new version of the shared libraries without recompiling or + relinking. Furthermore, applications that restrict their use of NSS APIs to the + functions listed in NSS Public Functions will remain compatible with future + versions of the NSS shared libraries. + +`Feedback <#feedback>`__ +------------------------ + +.. container:: + + Bugs discovered should be reported by filing a bug report on + `bugzilla.mozilla.org <https://bugzilla.mozilla.org/enter_bug.cgi?product=NSS>`__ (product NSS). |