Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 554 insertions, 0 deletions

diff --git a/security/nss/doc/rst/legacy/pkcs11_functions/index.rst b/security/nss/doc/rst/legacy/pkcs11_functions/index.rst
new file mode 100644
index 0000000000..13b9301c08
--- /dev/null
+++ b/security/nss/doc/rst/legacy/pkcs11_functions/index.rst
@@ -0,0 +1,554 @@
+.. _mozilla_projects_nss_pkcs11_functions:
+
+NSS PKCS11 Functions
+====================
+
+.. _pkcs_.2311_functions:
+
+`PKCS #11 Functions <#pkcs_.2311_functions>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   This chapter describes the core PKCS #11 functions that an application needs for communicating
+   with cryptographic modules. In particular, these functions are used for obtaining certificates,
+   keys, and passwords. This was converted from `"Chapter 7: PKCS #11
+   Functions" <https://www.mozilla.org/projects/security/pki/nss/ref/ssl/pkfnc.html>`__.
+
+   -  :ref:`mozilla_projects_nss_reference`
+   -  `SECMOD_LoadUserModule <#secmod_loadusermodule>`__
+   -  `SECMOD_UnloadUserModule <#secmod_unloadusermodule>`__
+   -  `SECMOD_OpenUserDB <#secmod_openuserdb>`__
+   -  `SECMOD_CloseUserDB <#secmod_closeuserdb>`__
+   -  `PK11_FindCertFromNickname <#pk11_findcertfromnickname>`__
+   -  `PK11_FindKeyByAnyCert <#pk11_findkeybyanycert>`__
+   -  `PK11_GetSlotName <#pk11_getslotname>`__
+   -  `PK11_GetTokenName <#pk11_gettokenname>`__
+   -  `PK11_IsHW <#pk11_ishw>`__
+   -  `PK11_IsPresent <#pk11_ispresent>`__
+   -  `PK11_IsReadOnly <#pk11_isreadonly>`__
+   -  `PK11_SetPasswordFunc <#pk11_setpasswordfunc>`__
+
+   .. rubric:: SECMOD_LoadUserModule
+      :name: secmod_loadusermodule
+
+   Load a new PKCS #11 module based on a moduleSpec.
+
+   .. rubric:: Syntax
+      :name: syntax
+
+   .. code::
+
+       #include "secmod.h"
+
+       extern SECMODModule *SECMOD_LoadUserModule(char *moduleSpec, SECMODModule *parent, PRBool recurse);
+
+   .. rubric:: Parameters
+      :name: parameters
+
+   This function has the following parameters:
+
+   *moduleSpec* is a pkcs #11 moduleSpec. *parent* is the moduleDB that presented this module spec.
+   For applications this value should be NULL. *recurse* is a boolean indicates whether or not the
+   module should also launch additional pkcs #11 modules. This is only applicable if the loaded
+   module is actually a moduleDB rather than a PKCS #11 module (see
+   :ref:`mozilla_projects_nss_pkcs11_module_specs`).
+
+   .. rubric:: Returns
+      :name: returns
+
+   The function returns one of these values:
+
+   -  If successful, a pointer to a SECMODModule. Caller owns the reference
+   -  If unsuccessful, NULL.
+
+   .. rubric:: Description
+      :name: description
+
+   SECMOD_LoadUserModule loads a new PKCS #11 module into NSS and connects it to the current NSS
+   trust infrastructure. Once the module has been successfully loaded, other NSS calls will use it
+   in the normal course of searching.
+
+   *modulespec* specifies how the module should be loaded. More information about module spec is
+   available at :ref:`mozilla_projects_nss_pkcs11_module_specs`. NSS parameters may be specified in
+   module specs used by SECMOD_LoadUserModule.
+
+   Module will continue to function in the NSS infrastructure until unloaded with
+   SECMOD_UnloadUserModule.
+
+   .. rubric:: SECMOD_UnloadUserModule
+      :name: secmod_unloadusermodule
+
+   Unload a PKCS #11 module.
+
+   .. rubric:: Syntax
+      :name: syntax_2
+
+   .. code::
+
+       #include "secmod.h"
+
+       extern SECStatus SECMOD_UnloadUserModule(SECMODModule *module);
+
+   .. rubric:: Parameters
+      :name: parameters_2
+
+   This function has the following parameters:
+
+   *module* is the module to be unloaded.
+
+   .. rubric:: Returns
+      :name: returns_2
+
+   The function returns one of these values:
+
+   -  If successful, SECSuccess.
+   -  If unsuccessful, SECFailure.
+
+   .. rubric:: Description
+      :name: description_2
+
+   SECMOD_UnloadUserModule detaches a module from the nss trust domain and unloads it. The module
+   should have previously been loaded by SECMOD_LoadUserModule.
+
+   .. rubric:: SECMOD_CloseUserDB
+      :name: secmod_closeuserdb
+
+   Close an already opened user database. NOTE: the database must be in the internal token, and must
+   be one created with SECMOD_OpenUserDB(). Once the database is closed, the slot will remain as an
+   empty slot until it's used again with SECMOD_OpenUserDB().
+
+   .. rubric:: Syntax
+      :name: syntax_3
+
+   .. code::
+
+       #include <pk11pub.h>
+
+       SECStatus SECMOD_CloseUserDB(PK11SlotInfo *slot)
+
+   .. rubric:: Parameters
+      :name: parameters_3
+
+   This function has the following parameter:
+
+   *slot* A pointer to a slot info structure. This slot must a slot created by SECMOD_OpenUserDB()
+   at some point in the past.
+
+   .. rubric:: Returns
+      :name: returns_3
+
+   The function returns one of these values:
+
+   -  If successful, SECSuccess).
+   -  If unsuccessful, SECFailure.
+
+   .. rubric:: SECMOD_OpenUserDB
+      :name: secmod_openuserdb
+
+   Open a new database using the softoken.
+
+   .. rubric:: Syntax
+      :name: syntax_4
+
+   .. code::
+
+       #include "pk11pub.h"
+
+       PK11SlotInfo *SECMOD_OpenUserDB(const char *moduleSpec)
+
+   .. rubric:: Parameters
+      :name: parameters_4
+
+   This function has the following parameters:
+
+   *moduleSpec* is the same data that you would pass to softoken at initialization time under the
+   'tokens' options.
+
+   .. rubric:: Returns
+      :name: returns_4
+
+   The function returns one of these values:
+
+   -  If successful, a pointer to a slot.
+   -  If unsuccessful, NULL.
+
+   .. rubric:: Description
+      :name: description_3
+
+   Open a new database using the softoken. The caller is responsible for making sure the module spec
+   is correct and usable. The caller should ask for one new database per call if the caller wants to
+   get meaningful information about the new database.
+
+   moduleSpec is the same data that you would pass to softoken at initialization time under the
+   'tokens' options. For example, if you would normally specify *tokens=<0x4=[configdir='./mybackup'
+   tokenDescription='Backup']>* to softoken if you at init time, then you could specify
+   "*configdir='./mybackup' tokenDescription='Backup'*" as your module spec here to open the
+   database ./mybackup on the fly. The slot ID will be calculated for you by SECMOD_OpenUserDB().
+
+   Typical parameters here are configdir, tokenDescription and flags. a Full list is below:
+
+   *configDir* The location of the databases for this token. If configDir is not specified, and
+   noCertDB and noKeyDB is not specified, the load will fail.
+
+   *certPrefix* Cert prefix for this token.
+
+   *keyPrefix* Prefix for the key database for this token. (if not specified, certPrefix will be
+   used).
+
+   *tokenDescription* The label value for this token returned in the CK_TOKEN_INFO structure with an
+   internationalize string (UTF8). This value will be truncated at 32 bytes (no NULL, partial UTF8
+   characters dropped). You should specify a user friendly name here as this is the value the token
+   will be referred to in most application UI's. You should make sure tokenDescription is unique.
+
+   *slotDescription* The slotDescription value for this token returned in the CK_SLOT_INFO structure
+   with an internationalize string (UTF8). This value will be truncated at 64 bytes (no NULL,
+   partialUTF8 characters dropped). This name will not change after thedatabase is closed. It should
+   have some number to make this unique.
+
+   *minPWLen* Then minimum password length for this token.
+
+   | *flags* A comma separated list of flag values, parsed case-insensitive.
+   | Valid flags are:
+
+   -  *readOnly* - Databases should be opened read only.
+   -  *noCertDB* - Don't try to open a certificate database.
+   -  *noKeyDB* - Don't try to open a key database.
+   -  *forceOpen* - Don't fail to initialize the token if thedatabases could not be opened.
+   -  *passwordRequired* - zero length passwords are not acceptable(valid only if there is a keyDB).
+   -  *optimizeSpace* - allocate smaller hash tables and lock tables.When this flag is not
+      specified, Softoken will allocatelarge tables to prevent lock contention.
+
+   For more info on module strings see :ref:`mozilla_projects_nss_pkcs11_module_specs`.
+
+   This function will return a reference to a slot. The caller is responsible for freeing the slot
+   reference when it is through. Freeing the slot reference will not unload the slot. That happens
+   with the corresponding SECMOD_CloseUserDB() function. Until the SECMOD_CloseUserDB function is
+   called, the newly opened database will be visible to any NSS calls search for keys or certs.
+
+   .. rubric:: PK11_FindCertFromNickname
+      :name: pk11_findcertfromnickname
+
+   Finds a certificate from its nickname.
+
+   .. rubric:: Syntax
+      :name: syntax_5
+
+   .. code::
+
+       #include <pk11pub.h>
+       #include <certt.h>
+
+       CERTCertificate *PK11_FindCertFromNickname(
+         char *nickname,
+         void *passwordArg);
+
+   .. rubric:: Parameters
+      :name: parameters_5
+
+   This function has the following parameters:
+
+   *nickname* A pointer to the nickname in the certificate database or to the nickname in the token.
+
+   *passwordArg* A pointer to application data for the password callback function. This pointer is
+   set with SSL_SetPKCS11PinArg during SSL configuration. To retrieve its current value, use
+   SSL_RevealPinArg.
+
+   .. rubric:: Returns
+      :name: returns_5
+
+   The function returns one of these values:
+
+   -  If successful, a pointer to a certificate structure.
+   -  If unsuccessful, NULL.
+
+   .. rubric:: Description
+      :name: description_4
+
+   When you are finished with the certificate structure returned by PK11_FindCertFromNickname, you
+   must free it by calling CERT_DestroyCertificate.
+
+   The PK11_FindCertFromNickname function calls the password callback function set with
+   PK11_SetPasswordFunc and passes it the pointer specified by the wincx parameter.
+
+   .. rubric:: PK11_FindKeyByAnyCert
+      :name: pk11_findkeybyanycert
+
+   Finds the private key associated with a specified certificate in any available slot.
+
+   .. rubric:: Syntax
+      :name: syntax_6
+
+   .. code::
+
+       #include <pk11pub.h>
+       #include <certt.h>
+       #include <keyt.h>
+
+       SECKEYPrivateKey *PK11_FindKeyByAnyCert(
+         CERTCertificate *cert,
+         void *passwordArg);
+
+   .. rubric:: Parameters
+      :name: parameters_6
+
+   This function has the following parameters:
+
+   *cert* A pointer to a certificate structure in the certificate database.
+
+   *passwordArg* A pointer to application data for the password callback function. This pointer is
+   set with SSL_SetPKCS11PinArg during SSL configuration. To retrieve its current value, use
+   SSL_RevealPinArg.
+
+   .. rubric:: Returns
+      :name: returns_6
+
+   The function returns one of these values:
+
+   -  If successful, a pointer to a private key structure.
+   -  If unsuccessful, NULL.
+
+   .. rubric:: Description
+      :name: description_5
+
+   When you are finished with the private key structure returned by PK11_FindKeyByAnyCert, you must
+   free it by calling SECKEY_DestroyPrivateKey.
+
+   The PK11_FindKeyByAnyCert function calls the password callback function set with
+   PK11_SetPasswordFunc and passes it the pointer specified by the wincx parameter.
+
+   .. rubric:: PK11_GetSlotName
+      :name: pk11_getslotname
+
+   Gets the name of a slot.
+
+   .. rubric:: Syntax
+      :name: syntax_7
+
+   .. code::
+
+       #include <pk11pub.h>
+
+       char *PK11_GetSlotName(PK11SlotInfo *slot);
+
+   .. rubric:: Parameters
+      :name: parameters_7
+
+   This function has the following parameter:
+
+   *slot* A pointer to a slot info structure.
+
+   .. rubric:: Returns
+      :name: returns_7
+
+   The function returns one of these values:
+
+   -  If successful, a pointer to the name of the slot (a string).
+   -  If unsuccessful, NULL.
+
+   .. rubric:: Description
+      :name: description_6
+
+   If the slot is freed, the string with the slot name may also be freed. If you want to preserve
+   it, copy the string before freeing the slot. Do not try to free the string yourself.
+
+   .. rubric:: PK11_GetTokenName
+      :name: pk11_gettokenname
+
+   Gets the name of the token.
+
+   .. rubric:: Syntax
+      :name: syntax_8
+
+   .. code::
+
+       #include <pk11pub.h>
+
+       char *PK11_GetTokenName(PK11SlotInfo *slot);
+
+   .. rubric:: Parameters
+      :name: parameters_8
+
+   This function has the following parameter:
+
+   *slot* A pointer to a slot info structure.
+
+   .. rubric:: Returns
+      :name: returns_8
+
+   The function returns one of these values:
+
+   -  If successful, a pointer to the name of the token (a string).
+   -  If unsuccessful, NULL.
+
+   .. rubric:: Description
+      :name: description_7
+
+   If the slot is freed, the string with the token name may also be freed. If you want to preserve
+   it, copy the string before freeing the slot. Do not try to free the string yourself.
+
+   .. rubric:: PK11_IsHW
+      :name: pk11_ishw
+
+   Finds out whether a slot is implemented in hardware or software.
+
+   .. rubric:: Syntax
+      :name: syntax_9
+
+   .. code::
+
+       #include <pk11pub.h>
+       #include <prtypes.h>
+
+       PRBool PK11_IsHW(PK11SlotInfo *slot);
+
+   .. rubric:: Parameters
+      :name: parameters_9
+
+   This function has the following parameter:
+
+   *slot* A pointer to a slot info structure.
+
+   .. rubric:: Returns
+      :name: returns_9
+
+   The function returns one of these values:
+
+   -  If the slot is implemented in hardware, PR_TRUE.
+   -  If the slot is implemented in software, PR_FALSE.
+
+   .. rubric:: PK11_IsPresent
+      :name: pk11_ispresent
+
+   Finds out whether the token for a slot is available.
+
+   .. rubric:: Syntax
+      :name: syntax_10
+
+   .. code::
+
+       #include <pk11pub.h>
+       #include <prtypes.h>
+
+       PRBool PK11_IsPresent(PK11SlotInfo *slot);
+
+   .. rubric:: Parameters
+      :name: parameters_10
+
+   This function has the following parameter:
+
+   *slot* A pointer to a slot info structure.
+
+   .. rubric:: Returns
+      :name: returns_10
+
+   The function returns one of these values:
+
+   -  If token is available, PR_TRUE.
+   -  If token is disabled or missing, PR_FALSE.
+
+   .. rubric:: PK11_IsReadOnly
+      :name: pk11_isreadonly
+
+   Finds out whether a slot is read-only.
+
+   .. rubric:: Syntax
+      :name: syntax_11
+
+   .. code::
+
+       #include <pk11pub.h>
+       #include <prtypes.h>
+
+       PRBool PK11_IsReadOnly(PK11SlotInfo *slot);
+
+   .. rubric:: Parameters
+      :name: parameters_11
+
+   This function has the following parameter:
+
+   *slot* A pointer to a slot info structure.
+
+   .. rubric:: Returns
+      :name: returns_11
+
+   The function returns one of these values:
+
+   -  If slot is read-only, PR_TRUE.
+   -  Otherwise, PR_FALSE.
+
+   .. rubric:: PK11_SetPasswordFunc
+      :name: pk11_setpasswordfunc
+
+   Defines a callback function used by the NSS libraries whenever information protected by a
+   password needs to be retrieved from the key or certificate databases.
+
+   .. rubric:: Syntax
+      :name: syntax_12
+
+   .. code::
+
+       #include <pk11pub.h>
+       #include <prtypes.h>
+
+       void PK11_SetPasswordFunc(PK11PasswordFunc func);
+
+   .. rubric:: Parameter
+      :name: parameter
+
+   This function has the following parameter:
+
+   *func* A pointer to the callback function to set.
+
+   .. rubric:: Description
+      :name: description_8
+
+   During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11
+   token (either a smart card or soft token) to access protected information, such as a private key.
+   Such information is protected with a password that can be retrieved by calling an
+   application-supplied callback function. The callback function is identified in a call to
+   PK11_SetPasswordFunc that takes place during NSS initialization.
+
+   The callback function set up by PK11_SetPasswordFunc has the following prototype:
+
+   .. code::
+
+      typedef char *(*PK11PasswordFunc)(
+        PK11SlotInfo *slot,
+        PRBool retry,
+        void *arg);
+
+   This callback function has the following parameters:
+
+   *slot* A pointer to a slot info structure.
+
+   *retry* Set to PR_TRUE if this is a retry. This implies that the callback has previously returned
+   the wrong password.
+
+   *arg* A pointer supplied by the application that can be used to pass state information. Can be
+   NULL.
+
+   This callback function returns one of these values:
+
+   -  If successful, a pointer to the password. This memory must have been allocated with PR_Malloc
+      or PL_strdup.
+   -  If unsuccessful, returns NULL.
+
+   Many tokens keep track of the number of attempts to enter a password and do not allow further
+   attempts after a certain point. Therefore, if the retry argument is PR_TRUE, indicating that the
+   password was tried and is wrong, the callback function should return NULL to indicate that it is
+   unsuccessful, rather than attempting to return the same password again. Failing to terminate when
+   the retry argument is PR_TRUE can result in an endless loop.
+
+   Several functions in the NSS libraries use the password callback function to obtain the password
+   before performing operations that involve the protected information. The third parameter to the
+   password callback function is application-defined and can be used for any purpose. For example,
+   Mozilla uses the parameter to pass information about which window is associated with the modal
+   dialog box requesting the password from the user. When NSS SSL libraries call the password
+   callback function, the value they pass in the third parameter is determined by
+   SSL_SetPKCS11PinArg.
+
+   .. rubric:: See Also
+      :name: see_also
+
+   For examples of password callback functions, see the samples in the Samples directory.
\ No newline at end of file