index.rst (17397B)
1 .. _mozilla_projects_nss_ssl_functions_pkfnc: 2 3 pkfnc 4 ===== 5 6 .. container:: 7 8 .. note:: 9 10 - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that 11 we are migrating into the format described in the `MDN Style 12 Guide <https://developer.mozilla.org/en-US/docs/MDN/Guidelines>`__. If you are inclined to 13 help with this migration, your help would be very much appreciated. 14 15 - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` 16 17 .. rubric:: PKCS #11 Functions 18 :name: PKCS_11_Functions 19 20 -------------- 21 22 .. _chapter_7_pkcs_11_functions: 23 24 `Chapter 7 25 PKCS #11 Functions <#chapter_7_pkcs_11_functions>`__ 26 ---------------------------------------------------- 27 28 .. container:: 29 30 This chapter describes the core PKCS #11 functions that an application needs for communicating 31 with cryptographic modules. In particular, these functions are used for obtaining certificates, 32 keys, and passwords. 33 34 | ```PK11_FindCertFromNickname`` <#1035673>`__ 35 | ```PK11_FindKeyByAnyCert`` <#1026891>`__ 36 | ```PK11_GetSlotName`` <#1030779>`__ 37 | ```PK11_GetTokenName`` <#1026964>`__ 38 | ```PK11_IsHW`` <#1026762>`__ 39 | ```PK11_IsPresent`` <#1022948>`__ 40 | ```PK11_IsReadOnly`` <#1022991>`__ 41 | ```PK11_SetPasswordFunc`` <#1023128>`__ 42 43 .. rubric:: PK11_FindCertFromNickname 44 :name: pk11_findcertfromnickname 45 46 Finds a certificate from its nickname. 47 48 .. rubric:: Syntax 49 :name: syntax 50 51 .. code:: 52 53 #include <pk11func.h> 54 #include <certt.h> 55 56 .. code:: 57 58 CERTCertificate *PK11_FindCertFromNickname( 59 char *nickname, 60 void *wincx); 61 62 .. rubric:: Parameters 63 :name: parameters 64 65 This function has the following parameters: 66 67 +-------------------------------------------------+-------------------------------------------------+ 68 | .. code:: | A pointer to the nickname in the certificate | 69 | | database or to the nickname in the token. | 70 | nickname | | 71 +-------------------------------------------------+-------------------------------------------------+ 72 | .. code:: | A pointer to application data for the password | 73 | | callback function. This pointer is set with | 74 | wincx | :ref:`moz | 75 | | illa_projects_nss_ssl_functions_sslfnc#1088040` | 76 | | during SSL configuration. To retrieve its | 77 | | current value, use | 78 | | :ref:`mozi | 79 | | lla_projects_nss_ssl_functions_sslfnc#1123385`. | 80 +-------------------------------------------------+-------------------------------------------------+ 81 82 .. rubric:: Returns 83 :name: returns 84 85 The function returns one of these values: 86 87 - If successful, a pointer to a certificate structure. 88 - If unsuccessful, ``NULL``. 89 90 .. rubric:: Description 91 :name: description 92 93 A nickname is an alias for a certificate subject. There may be multiple certificates with the 94 same subject, and hence the same nickname. This function will return the newest certificate that 95 matches the subject, based on the NotBefore / NotAfter fields of the certificate. When you are 96 finished with the certificate structure returned by ``PK11_FindCertFromNickname``, you must free 97 it by calling ```CERT_DestroyCertificate`` <sslcrt.html#1050532>`__. 98 99 The ``PK11_FindCertFromNickname`` function calls the password callback function set with 100 ```PK11_SetPasswordFunc`` <#1023128>`__ and passes it the pointer specified by the ``wincx`` 101 parameter. 102 103 .. rubric:: PK11_FindKeyByAnyCert 104 :name: pk11_findkeybyanycert 105 106 Finds the private key associated with a specified certificate in any available slot. 107 108 .. rubric:: Syntax 109 :name: syntax_2 110 111 .. code:: 112 113 #include <pk11func.h> 114 #include <certt.h> 115 #include <keyt.h> 116 117 .. code:: 118 119 SECKEYPrivateKey *PK11_FindKeyByAnyCert( 120 CERTCertificate *cert, 121 void *wincx); 122 123 .. rubric:: Parameters 124 :name: parameters_2 125 126 This function has the following parameters: 127 128 +-------------------------------------------------+-------------------------------------------------+ 129 | .. code:: | A pointer to a certificate structure in the | 130 | | certificate database. | 131 | cert | | 132 +-------------------------------------------------+-------------------------------------------------+ 133 | .. code:: | A pointer to application data for the password | 134 | | callback function. This pointer is set with | 135 | wincx | :ref:`moz | 136 | | illa_projects_nss_ssl_functions_sslfnc#1088040` | 137 | | during SSL configuration. To retrieve its | 138 | | current value, use | 139 | | :ref:`mozi | 140 | | lla_projects_nss_ssl_functions_sslfnc#1123385`. | 141 +-------------------------------------------------+-------------------------------------------------+ 142 143 .. rubric:: Returns 144 :name: returns_2 145 146 The function returns one of these values: 147 148 - If successful, a pointer to a private key structure. 149 - If unsuccessful, ``NULL``. 150 151 .. rubric:: Description 152 :name: description_2 153 154 When you are finished with the private key structure returned by ``PK11_FindKeyByAnyCert``, you 155 must free it by calling ```SECKEY_DestroyPrivateKey`` <sslkey.html#1051017>`__. 156 157 The ``PK11_FindKeyByAnyCert`` function calls the password callback function set with 158 ```PK11_SetPasswordFunc`` <#1023128>`__ and passes it the pointer specified by the ``wincx`` 159 parameter. 160 161 .. rubric:: PK11_GetSlotName 162 :name: pk11_getslotname 163 164 Gets the name of a slot. 165 166 .. rubric:: Syntax 167 :name: syntax_3 168 169 .. code:: 170 171 #include <pk11func.h> 172 173 .. code:: 174 175 char *PK11_GetSlotName(PK11SlotInfo *slot); 176 177 .. rubric:: Parameters 178 :name: parameters_3 179 180 This function has the following parameter: 181 182 +-------------------------------------------------+-------------------------------------------------+ 183 | .. code:: | A pointer to a slot info structure. | 184 | | | 185 | slot | | 186 +-------------------------------------------------+-------------------------------------------------+ 187 188 .. rubric:: Returns 189 :name: returns_3 190 191 The function returns one of these values: 192 193 - If successful, a pointer to the name of the slot (a string). 194 - If unsuccessful, ``NULL``. 195 196 .. rubric:: Description 197 :name: description_3 198 199 If the slot is freed, the string with the slot name may also be freed. If you want to preserve 200 it, copy the string before freeing the slot. Do not try to free the string yourself. 201 202 .. rubric:: PK11_GetTokenName 203 :name: pk11_gettokenname 204 205 Gets the name of the token. 206 207 .. rubric:: Syntax 208 :name: syntax_4 209 210 .. code:: 211 212 #include <pk11func.h> 213 214 .. code:: 215 216 char *PK11_GetTokenName(PK11SlotInfo *slot); 217 218 .. rubric:: Parameters 219 :name: parameters_4 220 221 This function has the following parameter: 222 223 +-------------------------------------------------+-------------------------------------------------+ 224 | .. code:: | A pointer to a slot info structure. | 225 | | | 226 | slot | | 227 +-------------------------------------------------+-------------------------------------------------+ 228 229 .. rubric:: Returns 230 :name: returns_4 231 232 The function returns one of these values: 233 234 - If successful, a pointer to the name of the token (a string). 235 - If unsuccessful, ``NULL``. 236 237 .. rubric:: Description 238 :name: description_4 239 240 If the slot is freed, the string with the token name may also be freed. If you want to preserve 241 it, copy the string before freeing the slot. Do not try to free the string yourself. 242 243 .. rubric:: PK11_IsHW 244 :name: pk11_ishw 245 246 Finds out whether a slot is implemented in hardware or software. 247 248 .. rubric:: Syntax 249 :name: syntax_5 250 251 .. code:: 252 253 #include <pk11func.h> 254 #include <prtypes.h> 255 256 .. code:: 257 258 PRBool PK11_IsHW(PK11SlotInfo *slot); 259 260 .. rubric:: Parameters 261 :name: parameters_5 262 263 This function has the following parameter: 264 265 +-------------------------------------------------+-------------------------------------------------+ 266 | .. code:: | A pointer to a slot info structure. | 267 | | | 268 | slot | | 269 +-------------------------------------------------+-------------------------------------------------+ 270 271 .. rubric:: Returns 272 :name: returns_5 273 274 The function returns one of these values: 275 276 - If the slot is implemented in hardware, ``PR_TRUE``. 277 - If the slot is implemented in software, ``PR_FALSE``. 278 279 .. rubric:: PK11_IsPresent 280 :name: pk11_ispresent 281 282 Finds out whether the token for a slot is available. 283 284 .. rubric:: Syntax 285 :name: syntax_6 286 287 .. code:: 288 289 #include <pk11func.h> 290 #include <prtypes.h> 291 292 .. code:: 293 294 PRBool PK11_IsPresent(PK11SlotInfo *slot); 295 296 .. rubric:: Parameters 297 :name: parameters_6 298 299 This function has the following parameter: 300 301 +-------------------------------------------------+-------------------------------------------------+ 302 | .. code:: | A pointer to a slot info structure. | 303 | | | 304 | slot | | 305 +-------------------------------------------------+-------------------------------------------------+ 306 307 .. rubric:: Returns 308 :name: returns_6 309 310 The function returns one of these values: 311 312 - If token is available, ``PR_TRUE``. 313 - If token is disabled or missing, ``PR_FALSE``. 314 315 .. rubric:: PK11_IsReadOnly 316 :name: pk11_isreadonly 317 318 Finds out whether a slot is read-only. 319 320 .. rubric:: Syntax 321 :name: syntax_7 322 323 .. code:: 324 325 #include <pk11func.h> 326 #include <prtypes.h> 327 328 .. code:: 329 330 PRBool PK11_IsReadOnly(PK11SlotInfo *slot); 331 332 .. rubric:: Parameters 333 :name: parameters_7 334 335 This function has the following parameter: 336 337 +-------------------------------------------------+-------------------------------------------------+ 338 | .. code:: | A pointer to a slot info structure. | 339 | | | 340 | slot | | 341 +-------------------------------------------------+-------------------------------------------------+ 342 343 .. rubric:: Returns 344 :name: returns_7 345 346 The function returns one of these values: 347 348 - If slot is read-only, ``PR_TRUE``. 349 - Otherwise, ``PR_FALSE``. 350 351 .. rubric:: PK11_SetPasswordFunc 352 :name: pk11_setpasswordfunc 353 354 Defines a callback function used by the NSS libraries whenever information protected by a 355 password needs to be retrieved from the key or certificate databases. 356 357 .. rubric:: Syntax 358 :name: syntax_8 359 360 .. code:: 361 362 #include <pk11func.h> 363 #include <prtypes.h> 364 365 .. code:: 366 367 void PK11_SetPasswordFunc(PK11PasswordFunc func); 368 369 .. rubric:: Parameter 370 :name: parameter 371 372 This function has the following parameter: 373 374 +-------------------------------------------------+-------------------------------------------------+ 375 | .. code:: | A pointer to the callback function to set. | 376 | | | 377 | func | | 378 +-------------------------------------------------+-------------------------------------------------+ 379 380 .. rubric:: Description 381 :name: description_5 382 383 During the course of an SSL operation, it may be necessary for the user to log in to a PKCS #11 384 token (either a smart card or soft token) to access protected information, such as a private key. 385 Such information is protected with a password that can be retrieved by calling an 386 application-supplied callback function. The callback function is identified in a call to 387 ``PK11_SetPasswordFunc`` that takes place during NSS initialization. 388 389 The callback function set up by ``PK11_SetPasswordFunc`` has the following prototype: 390 391 .. code:: 392 393 typedef char *(*PK11PasswordFunc)( 394 PK11SlotInfo *slot, 395 PRBool retry, 396 void *arg); 397 398 This callback function has the following parameters: 399 400 +-------------------------------------------------+-------------------------------------------------+ 401 | .. code:: | A pointer to a slot info structure. | 402 | | | 403 | slot | | 404 +-------------------------------------------------+-------------------------------------------------+ 405 | .. code:: | Set to ``PR_TRUE`` if this is a retry. This | 406 | | implies that the callback has previously | 407 | retry | returned the wrong password. | 408 +-------------------------------------------------+-------------------------------------------------+ 409 | .. code:: | A pointer supplied by the application that can | 410 | | be used to pass state information. Can be | 411 | arg | ``NULL``. | 412 +-------------------------------------------------+-------------------------------------------------+ 413 414 This callback function returns one of these values: 415 416 - If successful, a pointer to the password. This memory must have been allocated with 417 ```PR_Malloc`` <../../../../../nspr/reference/html/prmem2.html#21428>`__ or 418 ```PL_strdup`` <../../../../../nspr/reference/html/plstr.html#21753>`__. 419 - If unsuccessful, returns ``NULL``. 420 421 Many tokens keep track of the number of attempts to enter a password and do not allow further 422 attempts after a certain point. Therefore, if the ``retry`` argument is ``PR_TRUE``, indicating 423 that the password was tried and is wrong, the callback function should return ``NULL`` to 424 indicate that it is unsuccessful, rather than attempting to return the same password again. 425 Failing to terminate when the ``retry`` argument is ``PR_TRUE`` can result in an endless loop. 426 427 Several functions in the NSS libraries use the password callback function to obtain the password 428 before performing operations that involve the protected information. The third parameter to the 429 password callback function is application-defined and can be used for any purpose. For example, 430 Communicator uses the parameter to pass information about which window is associated with the 431 modal dialog box requesting the password from the user. When NSS libraries call the password 432 callback function, the value they pass in the third parameter is determined by 433 :ref:`mozilla_projects_nss_ssl_functions_sslfnc#1088040`. 434 435 .. rubric:: See Also 436 :name: see_also 437 438 For examples of password callback functions, see the samples in the 439 :ref:`mozilla_projects_nss_nss_sample_code` directory.