NSS searches all the installed PKCS #11 modules when looking for certificates. Once you've installed the module, the module's certificates simply appear in the list of certificates displayed in the Certificate window.
NSS requires at least PKCS #11 version 2.0, but can support some features of later versions of NSS, including NSS 2.20. NSS does not use all the features of later versions of PKCS #11.
NSS typically holds one session read-only session per slot, in which some of the non-multipart functions are handled. Multipart functions, such as bulk encryption, hashing, and mac functions (for example, C_Digest and C_Sign) and those that require overlapped operation (C_Unwrap, C_Decrypt) are handled by creating new sessions. If no new sessions are available, the one read-only session is used, and the state is saved and restored after each multipart operation.
NSS never uses Parallel mode.
NSS opens new read/write sessions for key generation, some password management, and storage of new certificates.
If your token is read/write and has only one session, NSS will open that one initial session read/write.
Private keys (RSA and DSA) and the corresponding certificates are read from the token. Other certificates on the token are also loaded (to allow building certificate chains), but it's not necessary to include the full chain, as long as the full chain is available in the regular certificate database. For the sake of completeness, it's also a good idea to expose public key objects. NSS falls back to looking for the existance of public keys to determine if the token may have the corresponding private key while the token is not logged in.
These are the general guidelines:
NSS can use the CKA_LABEL attribute to identify user certificates (see previous question) and presents this label to the user. Therefore, each user certificate must have some label associated with it. The label for a token certificate is presented to the user as follows:token label :certificate label . This implies that eachtoken label should be unique and meaningful to the user, and that eachcertificate label should be unique to the token.
NSS gets the value of the CKA_LABEL attribute from the token. Labels should not have any trailing blank characters.
Only if you identify your token as the default random number generator. If you do, your token must be able to generate random numbers even when it is not logged in. NSS uses installed random number generators if PKCS11_MECH_RANDOM_FLAG is set in the installer script. For information on how to do this, see Using the JAR Installation Manager to Install a PKCS #11 Cryptographic Module.
Your token should expect to implement all the PKCS #11 functions that make sense for your token. NSS continues to evolve, and periodically enhances it's functionality by using a more complete list of PKCS #11 functions. You should have implementations for all the functions specified in the version of the PKCS #11 spec your token implements. If you do not actually do the operation specified by that function, you can return CKR_FUNCTION_NOT_SUPPORTED.
PKCS #11 certificates that have private keys associated with them are loaded into the temporary database (in memory) and marked as user certificates. All other certificates in the module are loaded into the temporary database with no special trust bits associated with them. NSS is perfectly capable of using token certificates in place.
NSS calls C_GetSessionInfo to get the login/logout state. NSS never attempts to cache this information, because login state can change instantly without NSS knowing about it (for example, when the user removes the card). You must update all sessions correctly when the state changes. Not doing so is a common source of problems.
A session handle of 0 is indeed invalid. In the past, NSS uses the invalid session handle to mark problems with acquiring or using a session. There have been cases where NSS would then use this handle to try to do some operation. PKCS #11 modules should fail with CKR_INVALID_SESSION. We are working to remove these cases as we find them.
Generic Crypto Svcs are the services that NSS uses to do its basic cryptography (RSA encryption with public keys, hashing, AES, DES, RC4, RC2, and so on).Other PKCS #11 modules can supply implementations of these functions, and NSS uses those versions under certain conditions. However, these are not the services NSS calls to get to other PKCS #11 modules, which show up separately under Cryptographic Modules.
The only issue is dealing with keys. For example, if the RSA slot unwraps a key, NSS needs to move that key to a slot that can do the symmetric operations. NSS itself uses two tokens internally--one that provides generic cryptographic services without authentication, and one that provides operations based on the keys stored in the user's database and do need authentication. NSS does this to avoid having to prompt for a password when performing an RSA verify operation, DES encryption, and so on. Therefore, NSS can move keys around when necessary and possible. When operating in FIPS mode, moving keys is significantly harder. In this case NSS uses a single token to handle both key and cert storage and crypto operations.
In general, you not should use different slots unless you have a good reason. Much of NSS's token selection is based on where the key involved is currently stored. If the token that has your private keys doesn't also do symmetric operations, for example, it's likely that the internal token will end up doing the symmetric operations.
Yes, the token is call softokn3 (softokn3.dll on windows, libsoftokn3.so on most unix platforms). The NSS softokn3 is not a complete PKCS #11 module, it was implemented only to support NSS, though other products have managed to get it to work in their environment. There are a number of bugs against softoken's non-compliance, but these bugs have lower priority than fixing NSS's non-complient uses of PKCS #11 or adding new features to NSS.
NSS uses the first slot it finds that can perform all the required operations. On servers, it's almost always the slot that contains the server's private key.
NSS does not currently use any of the callbacks.
NSS applications detect card insertion and deletion by means of polling to determine whether the card is still in the slot and whether the open session associated with that card is still valid, or by waiting on the C_WaitForSlotEvent call.
An email address must be included in the attribute of the subject DN or the mail attribute of the subject DN. If the subject DN does not include an email address, the certificate extension subjectAltName must include an email address. The subjectAltName extension is part of the X.509 v3 and PKIX specifications.
Once NSS starts using a token for a given operation (like S/MIME or SSL), it works hard to keep using that same token (so keys don't get moved around). Symmetric operations supported by NSS include the following: CKM_AES_XXX, CKM_DES3_XXX, CKM_DES_XXX, CKM_RC2_XXX, and CKM_RC4_XXX. NSS knows about all the mechanisms defined in PKCS #11 version 2.01, but will not perform those that aren't defined by NSS's policy mechanism.
This depends on the application. PKCS #11 sessions are cryptographic session states, independent of threads. In NSS based servers, multiple threads may call the same session, but two threads will not call the same session at the same time.
If the token is marked read-only, then it will be treated as such. If the token is marked read/write and advertises that it can generate keys, NSS uses the token (through PKCS #11) to generate the key and loads the user's certificate into the token. If the token is marked read/write and does not advertise that it can generate keys, NSS generates the keys and loads them into the token.
While certificates may be read into the temporary database, private keys are never extracted from the PKCS #11 module unless the user is trying to back up the key. NSS represents each private key and a pointer to its PKCS #11 slot as a CK_OBJECT_HANDLE. When NSS needs to do anything with a private key, it calls the PCKS #11 module that holds the key.
No. NSS will never try to pull private keys out of tokens (except as wrapped objects for PKCS #12). Operations the token does not support are considered impossible for the key to support.
NSS may try to pull and load symmetric keys, usually if the key exchange happens in a token that does not support the symmetric algorithm. NSS works very hard not to have to pull any key out of a token (since that operation does not always work on all tokens).
In general, yes, the token should store temporary session objects. This may not be necessary for "private key op only" tokens, but this is not guaranteed. You should be prepared to handle temporary objects. (Many NSS based server products will use temporary session objects, even for "private key op only" tokens.)
NSS attempts to extract an unwrapped key from a token only if the token cannot provide the necessary service with that key. For instance if you are decrypting an S/MIME message and you have unwrapped the DES key with the private key provided by a given token, NSS attempts to use that token to provide the DES encryption. Only if that token cannot do DES will NSS try to extract the key.
Yes. If your token can do CKM_RSA_PKCS, and is writable, NSS displays it as one of the options to do key generation with. If the token cannot do CKM_RSA_PKCS_GEN_KEYPAIR, NSS uses its software key generation code and writes the private and public keys into the token using C_CreateObject. The RSA private key will contain all the attributes specified by PKCS #11 version 2.0. This is also true for CKM_DSA and CKM_DSA_GEN_KEYPAIR.
The private key is created using C_GenerateKeyPair or stored using C_CreateObject (depending on who generates the key). NSS does not keep a copy of the generated key if it generates the key itself. Key generation in Mozilla clients is triggered either by the standard <KEYGEN> tag, or by the keygen functions off the window.crypto object. This is the same method used for generating software keys and certificates and is used by certificate authorities like VeriSign and Thawte. (Red Hat Certificate Server also uses this method). The public key is sent to the server base-64-DER-encoded with an (optional) signed challenge.
No. As stated in the answer to the preceding question, when NSS does a keygen it uses C_GenerateKeyPair if the token supports the keygen method. If the token does not support keygen, NSS generates the key internally and uses C_CreateObject to load the private key into the token. When the certificate is received after the keygen, NSS loads it into the token with C_CreateObject. NSS also does a similar operation for importing private keys and certificates through pkcs12.
The above statement is true for read-write tokens only.
As stated above, NSS uses C_GenerateKeyPair if the token supports the keygen method. If an RSA key is being generated, the NSS application will present a list of all writable RSA devices asks the user to select which one to use, if a DSA key is being generated, it will present a list of all the writable DSA devices, if an EC key is being generated, it will present a list of all writable EC devices.
No. This is never necessary. The PKCS #11 specification explicitly requires that symmetric keys must be visible to all sessions of the same application. NSS explicitly depends on this semantic without the use of C_CopyObject. If your module does not support this semantic, it will not work with NSS.
Yes, NSS attempts to change the password in user mode only. (It goes to SSO mode only if your token identifies itself as CKF_LOGIN_REQUIRED, but not CKF_USER_INITIALIZED).
It's perfectly valid to reject the password change request with a return value such as CKR_FUNCTION_NOT_SUPPORTED. If you do this, NSS applications display an appropriate error message for the user.
Yes. First open the Tools/Options/Advanced/Security window in Mozilla and click Security Devices. Then select your PKCS #11 module, click View/Edit, select the token, and click Change Password. For this to work, you must supply a C_SetPIN function that operates as CKU_USER. Mozilla, Thunderbird, and Netscape products that use NSS have different UI to get the Security Devices dialog.
To get a key into an initialized token, go to your local Certificate Authority and initiate a certificate request. Somewhere along the way you will be prompted with a keygen dialog. Normally this dialog does not have any options and just provides information; however, if you have more than one token that can be used in this key generation process (for example, your smartcard and the NSS internal PKCS#11 module), you will see a selection of "cards and databases" that can be used to generate your new key info.
In the key generation process, NSS arranges for the key to have it's CKA_ID set to some value derived from the public key, and the public key will be extracted using C_GetAttributes. This key will be sent to the CA.
At some later point, the CA presents the certificate to you (as part of this keygen, or in an e-mail, or you go back and fetch it from a web page once the CA notifies you of the arrival of the new certificate). NSS uses the public key to search all its tokens for the private key that matches that certificate. The certificate is then written to the token where that private key resides, and the certificate's CKA_ID is set to match the private key.
PKCS #11 defines how these kinds of devices work. There is an outstanding bug in Firefox to implement this support.