diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
| commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
| tree | f435a8308119effd964b339f76abb83a57c29483 /security/nss/doc/rst/legacy/reference | |
| parent | Initial commit. (diff) | |
| download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip | |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'security/nss/doc/rst/legacy/reference')
95 files changed, 11780 insertions, 0 deletions
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 |