index.rst (26479B)
1 .. _mozilla_projects_nss_pkcs11_implement: 2 3 PKCS11 Implement 4 ================ 5 6 .. _implementing_pkcs_.2311_for_nss: 7 8 `Implementing PKCS #11 for NSS <#implementing_pkcs_.2311_for_nss>`__ 9 -------------------------------------------------------------------- 10 11 .. container:: 12 13 **NOTE:** This document was originally for the Netscape Security Library that came with Netscape 14 Communicator 4.0. This note will be removed once the document is updated for the current version 15 of NSS. 16 17 This document supplements the information in PKCS #11: Cryptographic Token Interface Standard, 18 version 2.0 with guidelines for implementors of cryptographic modules who want their products to 19 work with Mozilla client software: 20 21 - How NSS Calls PKCS #11 Functions. Function-specific information organized in the same 22 categories as the PKCS #11 specification. 23 - Functions for Different Kinds of Tokens. Summarizes the support NSS expects from different 24 kinds of tokens. 25 - Installation. Installing modules and informing the user of changes in the Cryptographic 26 Modules settings. 27 - Semantics Unique to NSS. Miscellaneous NSS semantics that affect module implementation. 28 29 Future versions of Netscape server products will also support of PKCS #11 version 2.0. 30 31 How NSS Calls PKCS #11 Functions This section is organized according to the categories used in 32 PKCS #11: Cryptographic Token Interface Standard, version 2.0. To understand this section, you 33 should be familiar with the standard specification. 34 35 .. _general-purpose_functions: 36 37 `General-Purpose Functions <#general-purpose_functions>`__ 38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39 40 .. container:: 41 42 .. rubric:: C_Initialize 43 :name: c_initialize 44 45 The NSS calls C_Initialize on startup or when it loads a new module. The NSS always passes NULL, 46 as required by the PKCS #11 specification, in the single C_Initialize parameter pReserved. 47 48 .. rubric:: C_Finalize 49 :name: c_finalize 50 51 The NSS calls C_Finalize on shutdown and whenever it unloads a module. 52 53 .. rubric:: C_GetFunctionList 54 :name: c_getfunctionlist 55 56 The NSS calls C_GetFunctionList on startup or when it loads a new module. The function list 57 returned should include all the PKCS 2.0 function calls. If you don't implement a function, you 58 should still provide a stub that returns CKR_FUNCTION_NOT_SUPPORTED. 59 60 .. rubric:: C_GetInfo 61 :name: c_getinfo 62 63 The NSS calls C_GetInfo on startup or when it loads a new module. The version numbers, 64 manufacturer IDs, and so on are displayed when the user views the information. The supplied 65 library names are used as the default library names; currently, these names should not include 66 any double quotation marks. (This is more restrictive than PKCS 2.0 and may change in future 67 versions of NSS.). 68 69 .. _slot_and_token_management: 70 71 `Slot and Token Management <#slot_and_token_management>`__ 72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 74 .. container:: 75 76 .. rubric:: C_GetSlotList 77 :name: c_getslotlist 78 79 The NSS calls C_GetSlotList on startup or when it loads a new module, requests all the module's 80 slots, and keeps track of the list from that point on. The slots are expected to remain static: 81 that is, the module never has more slots or fewer slots than the number on the original list. 82 83 .. rubric:: C_GetSlotInfo 84 :name: c_getslotinfo 85 86 The NSS calls C_GetSlotInfo on startup or when it loads a new module and reads in the information 87 that can be viewed on the slot information page. If the CKF_REMOVABLE_DEVICE flag is set, NSS 88 also calls C_GetSlotInfo whenever it looks up slots to make sure the token is present. If the 89 CKF_REMOVABLE_DEVICE flag is not set, NSS uses that token information without checking again. 90 91 If the CKF_REMOVABLE_DEVICE flag is not set, the CKF_TOKEN_PRESENT flag must be set, or else NSS 92 marks the slot as bad and will never use it. 93 94 The NSS doesn't currently use the CKF_HW_SLOT flag. 95 96 .. rubric:: C_GetTokenInfo 97 :name: c_gettokeninfo 98 99 If a token is a permanent device (that is, if the CKF_REMOVABLE_DEVICE flag is not set), NSS 100 calls C_GetTokenInfo only on startup or when it loads a new module. If the token is a removable 101 device, NSS may call C_GetTokenInfo anytime it's looking for a new token to check whether the 102 token is write protected, whether it can generate random numbers, and so on. 103 104 The NSS expects CK_TOKEN_INFO.label to contain the name of the token. 105 106 If the CKF_WRITE_PROTECTED flag is set, NSS won't use the token to generate keys. 107 108 The NSS interprets the combination of the CKF_LOGIN_REQUIRED and CKF_USER_PIN_INITIALIZED flags 109 as shown in Table 1.1. 110 111 +-----------------------------------+--------------------------+-----------------------------------+ 112 | NSS's interpretation of the | | | 113 | CKF_LOGIN_REQUIRED and | | | 114 | CKF_USER_PIN_INITIALIZED flags | | | 115 +-----------------------------------+--------------------------+-----------------------------------+ 116 | CFK_LOGIN_REQUIRED | CFK_USER_PIN_INITIALIZED | NSS assumes that: | 117 +-----------------------------------+--------------------------+-----------------------------------+ 118 | FALSE | FALSE | This is a general access device. | 119 | | | The NSS will use it without | 120 | | | prompting the user for a PIN. | 121 +-----------------------------------+--------------------------+-----------------------------------+ 122 | TRUE | FALSE | The device is uninitialized. The | 123 | | | NSS attempts to initialize the | 124 | | | device only if it needs to | 125 | | | generate a key or needs to set | 126 | | | the user PIN. The NSS calls | 127 | | | C_InitPIN to initialize the | 128 | | | device and set the user PIN; if | 129 | | | these calls are successful, the | 130 | | | key is generated and at that | 131 | | | point the | 132 | | | CFK_USER_PIN_INITIALIZED flag | 133 | | | should change from FALSE to TRUE. | 134 +-----------------------------------+--------------------------+-----------------------------------+ 135 | FALSE | TRUE | This is a general access device | 136 | | | that can have a PIN set on it. | 137 | | | Because it's a general access | 138 | | | device, NSS never prompts for the | 139 | | | PIN, even though it's possible to | 140 | | | set a PIN with C_SetPIN. If the | 141 | | | PIN is set successfully, the | 142 | | | CFK_LOGIN_REQUIRED flag should | 143 | | | change to TRUE. The NSS uses this | 144 | | | combination of flags for its | 145 | | | internal token when the key | 146 | | | database password is NULL. These | 147 | | | are not standard PKCS #11 | 148 | | | semantics; they are intended for | 149 | | | NSS's internal use only. | 150 +-----------------------------------+--------------------------+-----------------------------------+ 151 | TRUE | TRUE | The device has been initialized | 152 | | | and requires authentication. The | 153 | | | NSS checks whether the user is | 154 | | | logged on, and if not prompts the | 155 | | | user for a PIN. | 156 +-----------------------------------+--------------------------+-----------------------------------+ 157 158 .. rubric:: C_GetMechanismList 159 :name: c_getmechanismlist 160 161 The NSS calls C_GetMechanismList fairly frequently to identify the mechanisms supported by a 162 token. 163 164 .. rubric:: C_GetMechanismInfo 165 :name: c_getmechanisminfo 166 167 The NSS currently doesn't call C_GetMechanismInfo. This function may be called in the future, so 168 you should implement it anyway. 169 170 .. rubric:: C_InitToken 171 :name: c_inittoken 172 173 The NSS never calls C_InitToken. 174 175 .. rubric:: C_InitPIN 176 :name: c_initpin 177 178 The NSS calls C_InitPIN only in the key generation case, as noted in this document under 179 C_GetTokenInfo, when CFK_LOGIN_REQUIRED = TRUE and CFK_USER_PIN_INITIALIZED = FALSE. 180 181 .. rubric:: C_SetPIN 182 :name: c_setpin 183 184 Called only in the key generation case, as noted in this document under C_GetTokenInfo, when 185 CFK_LOGIN_REQUIRED = TRUE and CFK_USER_PIN_INITIALIZED = FALSE. 186 187 .. _session_management: 188 189 `Session Management <#session_management>`__ 190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 191 192 .. container:: 193 194 .. rubric:: C_OpenSession 195 :name: c_opensession 196 197 The NSS calls C_OpenSession whenever it initializes a token and keeps the session open as long as 198 possible. The NSS almost never closes a session after it finishes doing something with a token. 199 It uses a single session for all single-part RSA operations such as logging in, logging out, 200 signing, verifying, generating keys, wrapping keys, and so on. 201 202 The NSS opens a separate session for each part of a multipart encryption (bulk encryption). If it 203 runs out of sessions, it uses the initial session for saves and restores. 204 205 .. rubric:: C_CloseSession 206 :name: c_closesession 207 208 The NSS calls C_CloseSession to close sessions created for bulk encryption. 209 210 .. rubric:: C_CloseAllSessions 211 :name: c_closeallsessions 212 213 The NSS may call C_CloseAllSessions when it closes down a slot. 214 215 .. rubric:: C_GetSessionInfo 216 :name: c_getsessioninfo 217 218 The NSS calls C_GetSessionInfo frequently. 219 220 If a token has been removed during a session, C_GetSessionInfo should return either 221 CKR_SESSION_CLOSED or CKR_SESSION_HANDLE_INVALID. If a token has been removed and then the same 222 or another token is inserted, C_GetSessionInfo should return CKR_SESSION_HANDLE_INVALID. 223 224 .. rubric:: C_Login 225 :name: c_login 226 227 The NSS calls C_Login on a token's initial session whenever CKF_LOGIN_REQUIRED is TRUE and the 228 user state indicates that the user isn't logged in. 229 230 .. rubric:: C_Logout 231 :name: c_logout 232 233 The NSS calls C_Logout on a token's initial session 234 235 - when the password is timed out 236 - when performing any kind of private key operation if "ask always" is turned on 237 - when changing a password 238 - when the user logs out 239 240 .. _object_management: 241 242 `Object Management <#object_management>`__ 243 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 244 245 .. container:: 246 247 .. rubric:: C_CreateObject 248 :name: c_createobject 249 250 The NSS calls C_CreateObject when loading new private keys and new certificates into a token. 251 Typically, NSS uses C_CreateObject for creating a new private key if PKCS #12 is operating or if 252 your writable token doesn't support C_GenerateKeyPair. Currently PKCS #12 isn't allowed to import 253 onto a token. 254 255 The NSS also uses C_CreateObject to create new session keys. The NSS sometimes loads raw key data 256 and builds a key from that. 257 258 The NSS will be doing more and more session key generation on tokens in the future. It's also 259 possible for NSS to load a key if the private key that decrypted the key is located on a 260 different slot. For example, if a particular token can't do DES encryption, NSS decrypts the key, 261 then copies it over to the token that can do DES encryption. 262 263 The NSS creates certificates as token objects. It loads the token object only if the private key 264 for that certificate exists on the token and was generated by NSS. All the fields defined by PKCS 265 #11 for certificates are set. 266 267 The NSS also sets the CKA_ID and CKA_LABEL attributes for the token. Currently, the CKA_ID 268 attribute is set to the modulus for RSA or to the public value on DSA. The NSS may hash this 269 value in the future. In either case, NSS does set the CKA_ID attribute and expects it to remain 270 the same. If a certificate is loaded, the value of the certificate's CKA_ID attribute must match 271 the value of the CKA_ID attribute for the corresponding private key, and the value of the 272 certificate's CKA_LABEL attribute must also match the value of the CKA_LABEL attribute for the 273 private key. For private keys that don't include certificates, NSS doesn't set the CKA_LABEL 274 attribute, or sets it to NULL, until it receives the certificate. 275 276 .. rubric:: C_CopyObject 277 :name: c_copyobject 278 279 The NSS rarely calls C_CopyObject but may sometimes do so for non-token private keys. 280 281 .. rubric:: C_DestroyObject 282 :name: c_destroyobject 283 284 The NSS calls C_DestroyObject to destroy certificates and keys on tokens. 285 286 .. rubric:: C_GetObjectSize 287 :name: c_getobjectsize 288 289 The NSS never calls C_GetObjectSize. 290 291 .. rubric:: C_GetAttributeValue 292 :name: c_getattributevalue 293 294 The NSS calls C_GetAttributeValue to get the value of attributes for both single objects and 295 multiple objects. This is useful for extracting public keys, nonsecret bulk keys, and so on. 296 297 .. rubric:: C_SetAttributeValue 298 :name: c_setattributevalue 299 300 The NSS uses C_SetAttributeValue to change labels on private keys. 301 302 .. rubric:: C_FindObjectsInit, C_FindObjects, C_FindFinal 303 :name: c_findobjectsinit.2c_c_findobjects.2c_c_findfinal 304 305 The NSS calls these functions frequently to look up objects by CKA_ID or CKA_LABEL. These values 306 must match the equivalent values for related keys and certificates and must be unique among key 307 pairs on a given token. 308 309 The NSS also looks up certificates by CK_ISSUER and CK_SERIAL. If those fields aren't set on the 310 token, S/MIME won't work. 311 312 Functions for Different Kinds of Tokens The NSS expects different kinds of PKCS #11 support from 313 four different kinds of tokens: 314 315 - External key distribution tokens are used with corresponding plug-ins to distribute private 316 keys. 317 - Signing tokens include a signing certificate and are used to sign objects or messages or to 318 perform SSL authentication. They cannot be used for encrypted S/MIME, because they can't 319 decrypt messages. 320 - Signing and decryption tokens can be used for S/MIME and for encrypted transactions over 321 unsecured networks such as the Internet. 322 - Multipurpose tokens provide the full range of cryptographic services. They can be thought of 323 as cryptographic accelerator cards. Future releases of NSS will also support multipurpose 324 tokens that are FIPS-140 compliant. 325 326 Table 1.2 summarizes the PKCS #11 functions (in addition to the other functions described in this 327 document) that NSS expects each type of token to support. 328 329 +------------------------+------------------------+------------------------+------------------------+ 330 | PKCS #11 functions | | | | 331 | required for different | | | | 332 | kinds of tokens | | | | 333 +------------------------+------------------------+------------------------+------------------------+ 334 | External key | Signing tokens | Signing and decryption | Multipurpose tokens | 335 | distribution tokens | | tokens | | 336 +------------------------+------------------------+------------------------+------------------------+ 337 | | | | C_Encrypt | 338 +------------------------+------------------------+------------------------+------------------------+ 339 | C_Decrypt | | C_Decrypt | C_Decrypt | 340 | | | | | 341 | - CKM_RSA_PKCS | | - CKM_RSA_PKCS | | 342 | - CKM_RSA_X_509 (SSL | | - CKM_RSA_X_509 (SSL | | 343 | 2.0 server only) | | 2.0 server only) | | 344 +------------------------+------------------------+------------------------+------------------------+ 345 | C_Sign | C_Sign | C_Sign | C_Sign | 346 | | | | | 347 | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | 348 | - CKM_DSA | - CKM_DSA | - CKM_DSA | - CKM_DSA | 349 +------------------------+------------------------+------------------------+------------------------+ 350 | | | | C_Verify | 351 | | | | | 352 | | | | - CKM_RSA_PKCS | 353 | | | | - CKM_DSA | 354 +------------------------+------------------------+------------------------+------------------------+ 355 | | | | C_VerifyRecover | 356 | | | | | 357 | | | | - CKM_RSA_PKCS | 358 +------------------------+------------------------+------------------------+------------------------+ 359 | | | | C_GenerateKey | 360 +------------------------+------------------------+------------------------+------------------------+ 361 | C_GenerateKeyPair (if | C_GenerateKeyPair (if | C_GenerateKeyPair (if | C_GenerateKeyPair (if | 362 | token is read/write) | token is read/write) | token is read/write) | token is read/write) | 363 +------------------------+------------------------+------------------------+------------------------+ 364 | | | | C_WrapKey | 365 +------------------------+------------------------+------------------------+------------------------+ 366 | C_UnwrapKey | C_UnwrapKey | C_UnwrapKey | C_UnwrapKey | 367 | | | | | 368 | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | - CKM_RSA_PKCS | 369 +------------------------+------------------------+------------------------+------------------------+ 370 | | | | C_GenerateRandom | 371 +------------------------+------------------------+------------------------+------------------------+ 372 | | | | C_Save (when token | 373 | | | | runs out of sessions) | 374 +------------------------+------------------------+------------------------+------------------------+ 375 | | | | C_Restore (when token | 376 | | | | runs out of sessions) | 377 +------------------------+------------------------+------------------------+------------------------+ 378 379 External key tokens need to support C_Decrypt and C_Sign. If they have a read/write value and 380 can't generate a key pair, NSS uses its own C_GenerateKeyPair and loads the key with 381 C_CreateObject. 382 383 Signing tokens just need to support C_Sign and possibly C_GenerateKeyPair. 384 385 In addition to C_Sign and C_GenerateKeyPair, signing and decryption tokens should also support 386 C_Decrypt and, optionally, C_UnwrapKey. 387 388 Multipurpose tokens should support all the functions listed in Table 1.2, except that C_WrapKey 389 and C_UnwrapKey are optional. The NSS always attempts to use these two functions but uses 390 C_Encrypt and C_Decrypt instead if C_WrapKey and C_UnwrapKey aren't implemented. 391 392 `Installation <#installation>`__ 393 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 394 395 .. container:: 396 397 You can install your module in any convenient location on the user's hard disk, but you must tell 398 the user to type the module name and location in the Cryptographic Modules portion of the 399 Communicator Security Info window. To do so, the user should follow these steps: 400 401 #. Click the Security icon near the top of any Communicator window. 402 #. In the Security Info window, click Cryptographic Modules. 403 #. In the Cryptographic Modules frame, click Add. 404 #. In the Create a New Security Module dialog box, add the Security Module Name for your module 405 and the full pathname for the Security Module File. 406 407 To avoid requiring the user to type long pathnames, make sure your module is not buried too 408 deeply. 409 410 .. _semantics_unique_to_nss: 411 412 `Semantics Unique to NSS <#semantics_unique_to_nss>`__ 413 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 414 415 .. container:: 416 417 These sections describe semantics required by NSS but not specified by PKCS #11. 418 419 .. rubric:: Supporting Multiple Sessions 420 :name: supporting_multiple_sessions 421 422 If you support multiple sessions simultaneously and if you wish to support C_InitPIN, C_SetPIN, 423 or C_GenerateKeyPair, you must support simultaneous read-only and read/write sessions. 424 425 .. rubric:: Random-Number Generation and Simple Digesting 426 :name: random-number_generation_and_simple_digesting 427 428 The NSS requires that the following functions operate without authenticating to the token: 429 C_SeedRandom, C_GenerateRandom, and C_Digest (for SHA, MD5, and MD2). If your token requires 430 authentication before executing these functions, your token cannot provide the default 431 implementation for them. (You can still use your token for other default functions.) NSS does not 432 support replacement of default functions. Later versions will provide such support. 433 434 .. rubric:: Read/Write and Read-Only Requirements 435 :name: read.2fwrite_and_read-only_requirements 436 437 The NSS assumes that the following operations always require a read/write session: 438 439 - creating a token object, such as with C_CreateObject (token) or C_DestroyObject (token) 440 - changing a password 441 - initializing a token 442 443 Creating session objects must work with a read-only session. 444 445 .. rubric:: Creating an RSA Private Key 446 :name: creating_an_rsa_private_key 447 448 When NSS creates an RSA private key with C_CreateObject, it writes the entire set of RSA 449 components. It expects to be able to read back the modulus and the value of the CKA_ID attribute. 450 It also expects to be able to set the label and the subject on the key after creating it. 451 452 .. rubric:: Encrypting Email 453 :name: encrypting_email 454 455 If you wish to support encrypted email, your token must be able to look up a certificate by the 456 issuer and serial number attributes. When NSS loads a certificate, it sets these attributes 457 correctly. Token initialization software that you supply should also set these fields. 458 459 .. rubric:: Use of Key IDs 460 :name: use_of_key_ids 461 462 The NSS associates a key with its certificates by its key ID (CKA-ID). It doesn't matter how the 463 key ID is generated, as long as it is unique for the token and maps to a certificate to it 464 associated private key. More than one certificate can point to the same private key. 465 466 The only exception to this requirement involves key generation for a new certificate, during 467 which an orphan key waits for a brief time for a matching certificate. The NSS uses part of the 468 public key (modulus for RSA, value for DSA) as the key ID during this time. 469 470 NSS doesn't require token public keys, but if they exist, NSS expects the value of the CKA_ID 471 attribute to be associated with private key and any related certificates. 472 473 .. rubric:: Sessions and Session Objects 474 :name: sessions_and_session_objects 475 476 The NSS depends on a PKCS #11 v. 2.0 semantic requiring all session objects to be visible in all 477 of a token's sessions.