index.rst (17490B)
1 .. _mozilla_projects_nss_pkcs11_functions: 2 3 NSS PKCS11 Functions 4 ==================== 5 6 .. _pkcs_.2311_functions: 7 8 `PKCS #11 Functions <#pkcs_.2311_functions>`__ 9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 10 11 .. container:: 12 13 This chapter describes the core PKCS #11 functions that an application needs for communicating 14 with cryptographic modules. In particular, these functions are used for obtaining certificates, 15 keys, and passwords. This was converted from `"Chapter 7: PKCS #11 16 Functions" <https://www.mozilla.org/projects/security/pki/nss/ref/ssl/pkfnc.html>`__. 17 18 - :ref:`mozilla_projects_nss_reference` 19 - `SECMOD_LoadUserModule <#secmod_loadusermodule>`__ 20 - `SECMOD_UnloadUserModule <#secmod_unloadusermodule>`__ 21 - `SECMOD_OpenUserDB <#secmod_openuserdb>`__ 22 - `SECMOD_CloseUserDB <#secmod_closeuserdb>`__ 23 - `PK11_FindCertFromNickname <#pk11_findcertfromnickname>`__ 24 - `PK11_FindKeyByAnyCert <#pk11_findkeybyanycert>`__ 25 - `PK11_GetSlotName <#pk11_getslotname>`__ 26 - `PK11_GetTokenName <#pk11_gettokenname>`__ 27 - `PK11_IsHW <#pk11_ishw>`__ 28 - `PK11_IsPresent <#pk11_ispresent>`__ 29 - `PK11_IsReadOnly <#pk11_isreadonly>`__ 30 - `PK11_SetPasswordFunc <#pk11_setpasswordfunc>`__ 31 32 .. rubric:: SECMOD_LoadUserModule 33 :name: secmod_loadusermodule 34 35 Load a new PKCS #11 module based on a moduleSpec. 36 37 .. rubric:: Syntax 38 :name: syntax 39 40 .. code:: 41 42 #include "secmod.h" 43 44 extern SECMODModule *SECMOD_LoadUserModule(char *moduleSpec, SECMODModule *parent, PRBool recurse); 45 46 .. rubric:: Parameters 47 :name: parameters 48 49 This function has the following parameters: 50 51 *moduleSpec* is a pkcs #11 moduleSpec. *parent* is the moduleDB that presented this module spec. 52 For applications this value should be NULL. *recurse* is a boolean indicates whether or not the 53 module should also launch additional pkcs #11 modules. This is only applicable if the loaded 54 module is actually a moduleDB rather than a PKCS #11 module (see 55 :ref:`mozilla_projects_nss_pkcs11_module_specs`). 56 57 .. rubric:: Returns 58 :name: returns 59 60 The function returns one of these values: 61 62 - If successful, a pointer to a SECMODModule. Caller owns the reference 63 - If unsuccessful, NULL. 64 65 .. rubric:: Description 66 :name: description 67 68 SECMOD_LoadUserModule loads a new PKCS #11 module into NSS and connects it to the current NSS 69 trust infrastructure. Once the module has been successfully loaded, other NSS calls will use it 70 in the normal course of searching. 71 72 *modulespec* specifies how the module should be loaded. More information about module spec is 73 available at :ref:`mozilla_projects_nss_pkcs11_module_specs`. NSS parameters may be specified in 74 module specs used by SECMOD_LoadUserModule. 75 76 Module will continue to function in the NSS infrastructure until unloaded with 77 SECMOD_UnloadUserModule. 78 79 .. rubric:: SECMOD_UnloadUserModule 80 :name: secmod_unloadusermodule 81 82 Unload a PKCS #11 module. 83 84 .. rubric:: Syntax 85 :name: syntax_2 86 87 .. code:: 88 89 #include "secmod.h" 90 91 extern SECStatus SECMOD_UnloadUserModule(SECMODModule *module); 92 93 .. rubric:: Parameters 94 :name: parameters_2 95 96 This function has the following parameters: 97 98 *module* is the module to be unloaded. 99 100 .. rubric:: Returns 101 :name: returns_2 102 103 The function returns one of these values: 104 105 - If successful, SECSuccess. 106 - If unsuccessful, SECFailure. 107 108 .. rubric:: Description 109 :name: description_2 110 111 SECMOD_UnloadUserModule detaches a module from the nss trust domain and unloads it. The module 112 should have previously been loaded by SECMOD_LoadUserModule. 113 114 .. rubric:: SECMOD_CloseUserDB 115 :name: secmod_closeuserdb 116 117 Close an already opened user database. NOTE: the database must be in the internal token, and must 118 be one created with SECMOD_OpenUserDB(). Once the database is closed, the slot will remain as an 119 empty slot until it's used again with SECMOD_OpenUserDB(). 120 121 .. rubric:: Syntax 122 :name: syntax_3 123 124 .. code:: 125 126 #include <pk11pub.h> 127 128 SECStatus SECMOD_CloseUserDB(PK11SlotInfo *slot) 129 130 .. rubric:: Parameters 131 :name: parameters_3 132 133 This function has the following parameter: 134 135 *slot* A pointer to a slot info structure. This slot must a slot created by SECMOD_OpenUserDB() 136 at some point in the past. 137 138 .. rubric:: Returns 139 :name: returns_3 140 141 The function returns one of these values: 142 143 - If successful, SECSuccess). 144 - If unsuccessful, SECFailure. 145 146 .. rubric:: SECMOD_OpenUserDB 147 :name: secmod_openuserdb 148 149 Open a new database using the softoken. 150 151 .. rubric:: Syntax 152 :name: syntax_4 153 154 .. code:: 155 156 #include "pk11pub.h" 157 158 PK11SlotInfo *SECMOD_OpenUserDB(const char *moduleSpec) 159 160 .. rubric:: Parameters 161 :name: parameters_4 162 163 This function has the following parameters: 164 165 *moduleSpec* is the same data that you would pass to softoken at initialization time under the 166 'tokens' options. 167 168 .. rubric:: Returns 169 :name: returns_4 170 171 The function returns one of these values: 172 173 - If successful, a pointer to a slot. 174 - If unsuccessful, NULL. 175 176 .. rubric:: Description 177 :name: description_3 178 179 Open a new database using the softoken. The caller is responsible for making sure the module spec 180 is correct and usable. The caller should ask for one new database per call if the caller wants to 181 get meaningful information about the new database. 182 183 moduleSpec is the same data that you would pass to softoken at initialization time under the 184 'tokens' options. For example, if you would normally specify *tokens=<0x4=[configdir='./mybackup' 185 tokenDescription='Backup']>* to softoken if you at init time, then you could specify 186 "*configdir='./mybackup' tokenDescription='Backup'*" as your module spec here to open the 187 database ./mybackup on the fly. The slot ID will be calculated for you by SECMOD_OpenUserDB(). 188 189 Typical parameters here are configdir, tokenDescription and flags. a Full list is below: 190 191 *configDir* The location of the databases for this token. If configDir is not specified, and 192 noCertDB and noKeyDB is not specified, the load will fail. 193 194 *certPrefix* Cert prefix for this token. 195 196 *keyPrefix* Prefix for the key database for this token. (if not specified, certPrefix will be 197 used). 198 199 *tokenDescription* The label value for this token returned in the CK_TOKEN_INFO structure with an 200 internationalize string (UTF8). This value will be truncated at 32 bytes (no NULL, partial UTF8 201 characters dropped). You should specify a user friendly name here as this is the value the token 202 will be referred to in most application UI's. You should make sure tokenDescription is unique. 203 204 *slotDescription* The slotDescription value for this token returned in the CK_SLOT_INFO structure 205 with an internationalize string (UTF8). This value will be truncated at 64 bytes (no NULL, 206 partialUTF8 characters dropped). This name will not change after thedatabase is closed. It should 207 have some number to make this unique. 208 209 *minPWLen* Then minimum password length for this token. 210 211 | *flags* A comma separated list of flag values, parsed case-insensitive. 212 | Valid flags are: 213 214 - *readOnly* - Databases should be opened read only. 215 - *noCertDB* - Don't try to open a certificate database. 216 - *noKeyDB* - Don't try to open a key database. 217 - *forceOpen* - Don't fail to initialize the token if thedatabases could not be opened. 218 - *passwordRequired* - zero length passwords are not acceptable(valid only if there is a keyDB). 219 - *optimizeSpace* - allocate smaller hash tables and lock tables.When this flag is not 220 specified, Softoken will allocatelarge tables to prevent lock contention. 221 222 For more info on module strings see :ref:`mozilla_projects_nss_pkcs11_module_specs`. 223 224 This function will return a reference to a slot. The caller is responsible for freeing the slot 225 reference when it is through. Freeing the slot reference will not unload the slot. That happens 226 with the corresponding SECMOD_CloseUserDB() function. Until the SECMOD_CloseUserDB function is 227 called, the newly opened database will be visible to any NSS calls search for keys or certs. 228 229 .. rubric:: PK11_FindCertFromNickname 230 :name: pk11_findcertfromnickname 231 232 Finds a certificate from its nickname. 233 234 .. rubric:: Syntax 235 :name: syntax_5 236 237 .. code:: 238 239 #include <pk11pub.h> 240 #include <certt.h> 241 242 CERTCertificate *PK11_FindCertFromNickname( 243 char *nickname, 244 void *passwordArg); 245 246 .. rubric:: Parameters 247 :name: parameters_5 248 249 This function has the following parameters: 250 251 *nickname* A pointer to the nickname in the certificate database or to the nickname in the token. 252 253 *passwordArg* A pointer to application data for the password callback function. This pointer is 254 set with SSL_SetPKCS11PinArg during SSL configuration. To retrieve its current value, use 255 SSL_RevealPinArg. 256 257 .. rubric:: Returns 258 :name: returns_5 259 260 The function returns one of these values: 261 262 - If successful, a pointer to a certificate structure. 263 - If unsuccessful, NULL. 264 265 .. rubric:: Description 266 :name: description_4 267 268 When you are finished with the certificate structure returned by PK11_FindCertFromNickname, you 269 must free it by calling CERT_DestroyCertificate. 270 271 The PK11_FindCertFromNickname function calls the password callback function set with 272 PK11_SetPasswordFunc and passes it the pointer specified by the wincx parameter. 273 274 .. rubric:: PK11_FindKeyByAnyCert 275 :name: pk11_findkeybyanycert 276 277 Finds the private key associated with a specified certificate in any available slot. 278 279 .. rubric:: Syntax 280 :name: syntax_6 281 282 .. code:: 283 284 #include <pk11pub.h> 285 #include <certt.h> 286 #include <keyt.h> 287 288 SECKEYPrivateKey *PK11_FindKeyByAnyCert( 289 CERTCertificate *cert, 290 void *passwordArg); 291 292 .. rubric:: Parameters 293 :name: parameters_6 294 295 This function has the following parameters: 296 297 *cert* A pointer to a certificate structure in the certificate database. 298 299 *passwordArg* A pointer to application data for the password callback function. This pointer is 300 set with SSL_SetPKCS11PinArg during SSL configuration. To retrieve its current value, use 301 SSL_RevealPinArg. 302 303 .. rubric:: Returns 304 :name: returns_6 305 306 The function returns one of these values: 307 308 - If successful, a pointer to a private key structure. 309 - If unsuccessful, NULL. 310 311 .. rubric:: Description 312 :name: description_5 313 314 When you are finished with the private key structure returned by PK11_FindKeyByAnyCert, you must 315 free it by calling SECKEY_DestroyPrivateKey. 316 317 The PK11_FindKeyByAnyCert function calls the password callback function set with 318 PK11_SetPasswordFunc and passes it the pointer specified by the wincx parameter. 319 320 .. rubric:: PK11_GetSlotName 321 :name: pk11_getslotname 322 323 Gets the name of a slot. 324 325 .. rubric:: Syntax 326 :name: syntax_7 327 328 .. code:: 329 330 #include <pk11pub.h> 331 332 char *PK11_GetSlotName(PK11SlotInfo *slot); 333 334 .. rubric:: Parameters 335 :name: parameters_7 336 337 This function has the following parameter: 338 339 *slot* A pointer to a slot info structure. 340 341 .. rubric:: Returns 342 :name: returns_7 343 344 The function returns one of these values: 345 346 - If successful, a pointer to the name of the slot (a string). 347 - If unsuccessful, NULL. 348 349 .. rubric:: Description 350 :name: description_6 351 352 If the slot is freed, the string with the slot name may also be freed. If you want to preserve 353 it, copy the string before freeing the slot. Do not try to free the string yourself. 354 355 .. rubric:: PK11_GetTokenName 356 :name: pk11_gettokenname 357 358 Gets the name of the token. 359 360 .. rubric:: Syntax 361 :name: syntax_8 362 363 .. code:: 364 365 #include <pk11pub.h> 366 367 char *PK11_GetTokenName(PK11SlotInfo *slot); 368 369 .. rubric:: Parameters 370 :name: parameters_8 371 372 This function has the following parameter: 373 374 *slot* A pointer to a slot info structure. 375 376 .. rubric:: Returns 377 :name: returns_8 378 379 The function returns one of these values: 380 381 - If successful, a pointer to the name of the token (a string). 382 - If unsuccessful, NULL. 383 384 .. rubric:: Description 385 :name: description_7 386 387 If the slot is freed, the string with the token name may also be freed. If you want to preserve 388 it, copy the string before freeing the slot. Do not try to free the string yourself. 389 390 .. rubric:: PK11_IsHW 391 :name: pk11_ishw 392 393 Finds out whether a slot is implemented in hardware or software. 394 395 .. rubric:: Syntax 396 :name: syntax_9 397 398 .. code:: 399 400 #include <pk11pub.h> 401 #include <prtypes.h> 402 403 PRBool PK11_IsHW(PK11SlotInfo *slot); 404 405 .. rubric:: Parameters 406 :name: parameters_9 407 408 This function has the following parameter: 409 410 *slot* A pointer to a slot info structure. 411 412 .. rubric:: Returns 413 :name: returns_9 414 415 The function returns one of these values: 416 417 - If the slot is implemented in hardware, PR_TRUE. 418 - If the slot is implemented in software, PR_FALSE. 419 420 .. rubric:: PK11_IsPresent 421 :name: pk11_ispresent 422 423 Finds out whether the token for a slot is available. 424 425 .. rubric:: Syntax 426 :name: syntax_10 427 428 .. code:: 429 430 #include <pk11pub.h> 431 #include <prtypes.h> 432 433 PRBool PK11_IsPresent(PK11SlotInfo *slot); 434 435 .. rubric:: Parameters 436 :name: parameters_10 437 438 This function has the following parameter: 439 440 *slot* A pointer to a slot info structure. 441 442 .. rubric:: Returns 443 :name: returns_10 444 445 The function returns one of these values: 446 447 - If token is available, PR_TRUE. 448 - If token is disabled or missing, PR_FALSE. 449 450 .. rubric:: PK11_IsReadOnly 451 :name: pk11_isreadonly 452 453 Finds out whether a slot is read-only. 454 455 .. rubric:: Syntax 456 :name: syntax_11 457 458 .. code:: 459 460 #include <pk11pub.h> 461 #include <prtypes.h> 462 463 PRBool PK11_IsReadOnly(PK11SlotInfo *slot); 464 465 .. rubric:: Parameters 466 :name: parameters_11 467 468 This function has the following parameter: 469 470 *slot* A pointer to a slot info structure. 471 472 .. rubric:: Returns 473 :name: returns_11 474 475 The function returns one of these values: 476 477 - If slot is read-only, PR_TRUE. 478 - Otherwise, PR_FALSE. 479 480 .. rubric:: PK11_SetPasswordFunc 481 :name: pk11_setpasswordfunc 482 483 Defines a callback function used by the NSS libraries whenever information protected by a 484 password needs to be retrieved from the key or certificate databases. 485 486 .. rubric:: Syntax 487 :name: syntax_12 488 489 .. code:: 490 491 #include <pk11pub.h> 492 #include <prtypes.h> 493 494 void PK11_SetPasswordFunc(PK11PasswordFunc func); 495 496 .. rubric:: Parameter 497 :name: parameter 498 499 This function has the following parameter: 500 501 *func* A pointer to the callback function to set. 502 503 .. rubric:: Description 504 :name: description_8 505 506 During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11 507 token (either a smart card or soft token) to access protected information, such as a private key. 508 Such information is protected with a password that can be retrieved by calling an 509 application-supplied callback function. The callback function is identified in a call to 510 PK11_SetPasswordFunc that takes place during NSS initialization. 511 512 The callback function set up by PK11_SetPasswordFunc has the following prototype: 513 514 .. code:: 515 516 typedef char *(*PK11PasswordFunc)( 517 PK11SlotInfo *slot, 518 PRBool retry, 519 void *arg); 520 521 This callback function has the following parameters: 522 523 *slot* A pointer to a slot info structure. 524 525 *retry* Set to PR_TRUE if this is a retry. This implies that the callback has previously returned 526 the wrong password. 527 528 *arg* A pointer supplied by the application that can be used to pass state information. Can be 529 NULL. 530 531 This callback function returns one of these values: 532 533 - If successful, a pointer to the password. This memory must have been allocated with PR_Malloc 534 or PL_strdup. 535 - If unsuccessful, returns NULL. 536 537 Many tokens keep track of the number of attempts to enter a password and do not allow further 538 attempts after a certain point. Therefore, if the retry argument is PR_TRUE, indicating that the 539 password was tried and is wrong, the callback function should return NULL to indicate that it is 540 unsuccessful, rather than attempting to return the same password again. Failing to terminate when 541 the retry argument is PR_TRUE can result in an endless loop. 542 543 Several functions in the NSS libraries use the password callback function to obtain the password 544 before performing operations that involve the protected information. The third parameter to the 545 password callback function is application-defined and can be used for any purpose. For example, 546 Mozilla uses the parameter to pass information about which window is associated with the modal 547 dialog box requesting the password from the user. When NSS SSL libraries call the password 548 callback function, the value they pass in the third parameter is determined by 549 SSL_SetPKCS11PinArg. 550 551 .. rubric:: See Also 552 :name: see_also 553 554 For examples of password callback functions, see the samples in the Samples directory.