PKCS11 FAQ¶
PKCS11 FAQ¶
QUESTIONS AND ANSWERS
GENERAL QUESTIONS
After plugging in an external PKCS #11 module, how do you use the certificate available on the token? Does the certificate need to be imported into NSS’s internal certificate database? If so, is there a way to get the certificate from an external token into NSS’s internal certificate database?
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.
What version of PKCS #11 does NSS support?
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.
What are the expectations in terms of session manipulation? Will NSS potentially open more than one session at a time? Read-only sessions, read/write sessions, serial, parallel?
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.
What permanent PKCS #11 objects are used by NSS or read from the token? Example: RSA private key, CA certificate, user’s own certificate, user’s name.
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.
How are permanent PKCS #11 objects found by NSS? That is, which PKCS #11 attributes are used in the object searches? Labels? Key IDs? Key types?
These are the general guidelines:
User certificates are identified by their labels.
Certificates and keys are often looked up by the following methods:
By looking up all private keys.
By looking up all certificates.
Certificates may be looked up by label. By convention, all certificates making up a single personality should have the same label (that is, a pair of certificates, one for signing and one for key exchange, should have the same label).
S/MIME-capable certificates are also looked up by issuer/serial number.
Certificates may be looked up by their DER value.
Certificates may also be looked up by subject. More than one certificate can match, but each certificate with the same subject should be part of the same personality.
NSS may enumerate all the permanment certificates in a token (CKA_TOKEN set to true).
Private keys must have the same CKA_ID value as their corresponding certificate, and this value must be unique on the token.
Orphaned keys have a CKA_ID generated from some part of the public key. This value is set when the key is generated, so that NSS will be able to find the key when the certificate for that key is loaded. This case is interesting only for read/write tokens.
What labels does NSS use to identify certificates?
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.
Will NSS use the random number generation features of PKCS #11?
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.
Can Mozilla provide a list of all PKCS #11 functions that NSS will use?
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.
Will NSS get the user’s CA certificate via PKCS #11 and push it into the CA certificate database or is the CA certificate database expected to obtain the CA certificate by some other means?
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.
Which function does NSS use to get login state information?
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.
I have noticed that NSS sometimes use a session handle value of 0. Is this an invalid session handle?
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.
What are “Generic Crypto Svcs” (the first item listed when you click the View/Edit button for the NSS Internal PKCS #11 Module under Security Devices under Options/Security in Firefox)?
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.
Our plugin provides several slots with different capabilities. For example, one does all the hashing/symmetric operations, while another does only asymmetric RSA operations. Can this kind of division lead to problems?
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.
If multiple PKCS #11 modules are loaded, how does NSS determine which ones to use for the mechanisms required by SSL?
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.
Does NSS support the use of PKCS #11 callbacks specified in the pNotify and pApplication parameters for C_OpenSession?
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.
What must an X.509 certificate include to allow it to be recognized as an email certificate for use with S/MIME?
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.
If I have a multipurpose token that supports all required PKCS #11 functions and provides RSA_PKCS and DSA mechanisms but not AES, DES or RC4, will NSS use the token for the RSA_PKCS mechanisms and the NSS Internal PKCS #11 module for AES, DES or RC4 when making an SSL connection?
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.
When do NSS Applications spawn threads off the main thread, which in turn opens up a new PKCS #11 session?
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.
QUESTIONS ABOUT KEYS AND TOKENS
Is the PKCS #11 token treated in a read-only manner? That is, no token init, no key gens, no data puts, no cert puts, etc.?
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.
How is private key handled when an external PKCS #11 module is loaded? Is it picked up from the token when securing, or does NSS expect it to be added in its private key database to use it?
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.
If a PKCS #11 library reports that, for example, it does not support RSA signing operations, does NSS expect to be able to pull an RSA private key off the token using the C_GetAttributeValue call and then do the operation in software?
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).
If so, by what means does NSS attempt to retrieve the data? By searching for some fixed label attribute? Must the token store any temporary (session) objects?
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.)
If a session key is unwrapped and stays on a hardware token, is it sufficient to support just the usual decryption mechanisms for it, or is it assumed that such a symmetric key will always be extractable from the token into the browser? The motivation for this is that some hardware tokens will prevent extraction of symmetric keys by design.
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.
If the smartcard can’t do key generation, will NSS do the key generation automatically?
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.
What is the C_GenerateKeyPair process? For example, what happens when an application in the a server asks an NSS based client to do a keypair generation while a smartCard is attached? How is the private key stored to the smartCard, and how is the public key sent to the server (with wrapping?).
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.
Are persistent objects that are stored on the token, such as private keys and certificates, created by the PKCS #11 module? Is it safe to assume that NSS never calls C_CreateObject for those persistent objects?
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.
When and how does NSS generate private keys on the token?
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.
Does NSS ever use C_CopyObject to copy symmetric keys if it needs to reference the same key for different sessions?
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.
QUESTIONS ABOUT PINS
Will a password change ever be done on the token?
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.
If I have my smart card which has initial PIN set at ‘9999’, I insert it into my reader and download with my certificate (keygen completed), can I issue ‘Change Password’ from the Firefox to set a new PIN to the smart card? Any scenario that you can give me similar to this process (a way to issue a certificate on an initialized new card)?
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.
Why does Firefox require users to authenticate themselves by entering a PIN at the keyboard? Why not use a PIN pad or a fingerprint reader located on the token or reader?
PKCS #11 defines how these kinds of devices work. There is an outstanding bug in Firefox to implement this support.