summaryrefslogtreecommitdiffstats
path: root/security/nss/doc/rst/legacy/pkcs11_functions
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/doc/rst/legacy/pkcs11_functions')
-rw-r--r--security/nss/doc/rst/legacy/pkcs11_functions/index.rst554
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