Source code
Revision control
Copy as Markdown
Other Tools
.. _mozilla_projects_nss_pkcs11_faq:
PKCS11 FAQ
==========
.. _pkcs11_faq:
`PKCS11 FAQ <#pkcs11_faq>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
.. rubric:: QUESTIONS AND ANSWERS
:name: questions_and_answers
.. rubric:: GENERAL QUESTIONS
:name: general_questions
.. rubric:: 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?
:name: after_plugging_in_an_external_pkcs_.2311_module.2c_how_do_you_use_the_certificate_available_on_the_token.3f_does_the_certificate_need_to_be_imported_into_nss.27s_internal_certificate_database.3f_if_so.2c_is_there_a_way_to_get_the_certificate_from_an_external_token_into_nss.27s_internal_certificate_database.3f
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.
.. rubric:: What version of PKCS #11 does NSS support?
:name: what_version_of_pkcs_.2311_does_nss_support.3f
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.
.. rubric:: 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?
:name: what_are_the_expectations_in_terms_of_session_manipulation.3f_will_nss_potentially_open_more_than_one_session_at_a_time.3f_read-only_sessions.2c_read.2fwrite_sessions.2c_serial.2c_parallel.3f
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.
.. rubric:: 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.
:name: what_permanent_pkcs_.2311_objects_are_used_by_nss_or_read_from_the_token.3f_example:_rsa_private_key.2c_ca_certificate.2c_user.27s_own_certificate.2c_user.27s_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.
.. rubric:: 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?
:name: how_are_permanent_pkcs_.2311_objects_found_by_nss.3f_that_is.2c_which_pkcs_.2311_attributes_are_used_in_the_object_searches.3f_labels.3f_key_ids.3f_key_types.3f
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.
.. rubric:: What labels does NSS use to identify certificates?
:name: what_labels_does_nss_use_to_identify_certificates.3f
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 each\ *token label* should be unique and
meaningful to the user, and that each\ *certificate 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.
.. rubric:: Will NSS use the random number generation features of PKCS #11?
:name: will_nss_use_the_random_number_generation_features_of__pkcs_.2311.3f
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.
.. rubric:: Can Mozilla provide a list of all PKCS #11 functions that NSS will use?
:name: can_mozilla_provide_a_list_of_all_pkcs_.2311_functions_that_nss_will_use.3f
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.
.. rubric:: 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?
:name: will_nss_get_the_user.27s_ca_certificate_via_pkcs_.2311_and_push_it_into_the_ca_certificate_database_or_is_the_ca_certificate_database_expected_to_obtain_the_ca_certificate_by_some_other_means.3f
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.
.. rubric:: Which function does NSS use to get login state information?
:name: which_function_does_nss_use_to_get_login_state_information.3f
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.
.. rubric:: I have noticed that NSS sometimes use a session handle value of 0. Is this an invalid
session handle?
:name: i_have_noticed_that_nss_sometimes_use__a_session_handle_value_of_0._is_this_an_invalid_session_handle.3f
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.
.. rubric:: 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)?
:name: what_are_.22generic_crypto_svcs.22_.28the_first_item_listed_when_you_click_the_view.2fedit_button_for_the_nss_internal_pkcs_.2311_module__under_security_devices_under_options.2fsecurity_in_firefox.29.3f
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.
.. rubric:: 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?
:name: our_plugin_provides_several_slots_with_different_capabilities._for_example.2c_one_does_all_the_hashing.2fsymmetric_operations.2c_while_another_does_only_asymmetric_rsa_operations._can_this_kind_of_division_lead_to_problems.3f
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.
.. rubric:: Is the PKCS #11 module supplied with NSS accessible through a shared library?
:name: is_the_pkcs_.2311_module_supplied_with_nss_accessible_through_a_shared_library.3f
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.
.. rubric:: If multiple PKCS #11 modules are loaded, how does NSS determine which ones to use for
the mechanisms required by SSL?
:name: if_multiple_pkcs_.2311_modules_are_loaded.2c_how_does_nss_determine_which_ones_to_use_for_the_mechanisms_required_by_ssl.3f
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.
.. rubric:: Does NSS support the use of PKCS #11 callbacks specified in the pNotify and
pApplication parameters for C_OpenSession?
:name: does_nss_support_the_use_of_pkcs_.2311_callbacks_specified_in_the_pnotify_and_papplication_parameters_for_c_opensession.3f
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.
.. rubric:: What must an X.509 certificate include to allow it to be recognized as an email
certificate for use with S/MIME?
:name: what_must_an_x.509_certificate_include_to_allow_it_to_be_recognized_as_an_email_certificate_for_use_with_s.2fmime.3f
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.
.. rubric:: 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?
:name: if_i_have_a_multipurpose_token_that_supports_all_required_pkcs_.2311_functions_and_provides_rsa_pkcs_and_dsa_mechanisms_but_but_not_aes.2c_des_or_rc4.2c_will_nss_use_the_token_for_the_rsa_pkcs_mechanisms_and_the_nss_internal_pkcs_.2311_module_for_aes.2c_des_or_rc4_when_making_an_ssl_connection.3f
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.
.. rubric:: When do NSS Applications spawn threads off the main thread, which in turn opens up a
new PKCS #11 session?
:name: when_do_nss_applications_spawn_threads_off_the_main_thread.2c_which_in_turn_opens_up_a_new_pkcs_.2311_session.3f
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.
.. rubric:: QUESTIONS ABOUT KEYS AND TOKENS
:name: questions_about_keys_and_tokens
.. rubric:: 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.?
:name: is_the_pkcs_.2311_token_treated_in_a_read-only_manner.3f_that_is.2c_no_token_init.2c_no_key_gens.2c_no_data_puts.2c_no_cert_puts.2c_etc..3f
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.
.. rubric:: 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?
:name: how_is_private_key_handled_when_an_external_pkcs_.2311_module_is_loaded.3f_is_it_picked_up_from_the_token_when_securing.2c_or_does_nss_expect_it_to_be_added_in_its_private_key_database_to_use_it.3f
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.
.. rubric:: 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?
:name: if_a_pkcs_.2311_library_reports_that.2c_for_example.2c_it_does_not_support_rsa_signing_operations.2c_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.3f
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).
.. rubric:: 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?
:name: if_so.2c_by_what_means_does_nss_attempt_to_retrieve_the_data.3f_by_searching_for_some_fixed_label_attribute.3f_must_the_token_store_any_temporary_.28session.29_objects.3f
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.)
.. rubric:: 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.
:name: if_a_session_key_is_unwrapped_and_stays_on_a_hardware_token.2c_is_it_sufficient_to_support_just_the_usual_decryption_mechanisms_for_it.2c_or_is_it_assumed_that_such_a_symmetric_key_will_always_be_extractable_from_the_token_into_the_browser.3f_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.
.. rubric:: If the smartcard can't do key generation, will NSS do the key generation
automatically?
:name: if_the_smartcard_can.27t_do_key_generation.2c_will_nss_do_the_key_generation_automatically.3f
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.
.. rubric:: 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?).
:name: what_is_the_c_generatekeypair_process.3f_for_example.2c_what_happens_when_an_application_in_the_a_server_asks_an_nss_based_client_to_do_a_keypair_generation_while_a_smartcard_is_attached.3f_how_is_the_private_key_stored_to_the_smartcard.2c_and_how_is_the_public_key_sent_to_the_server_.28with_wrapping.3f.29.
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.
.. rubric:: 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?
:name: are_persistent_objects_that_are_stored_on_the_token.2c_such_as_private_keys_and_certificates.2c_created_by_the_pkcs_.2311_module.3f_is_it_safe_to_assume_that_nss_never_calls_c_createobject_for_those_persistent_objects.3f
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.
.. rubric:: When and how does NSS generate private keys on the token?
:name: when_and_how_does_nss_generate_private_keys_on_the_token.3f
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.
.. rubric:: Does NSS ever use C_CopyObject to copy symmetric keys if it needs to reference the
same key for different sessions?
:name: does_nss_ever_use_c_copyobject_to_copy_symmetric_keys_if_it_needs_to_reference_the_same_key_for_different_sessions.3f
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.
.. rubric:: QUESTIONS ABOUT PINS
:name: questions_about_pins
.. rubric:: Will a password change ever be done on the token?
:name: will_a_password_change_ever_be_done_on_the_token.3f
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.
.. rubric:: 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)?
:name: if_i_have_my_smart_card_which_has_initial_pin_set_at__.279999.27.2c_i_insert_it_into_my_reader_and_download_with_my_certificate_.28keygen_completed.29.2c_can_i_issue_.27change_password.27_from_the_firefox_to_set_a_new_pin_to_the_smart_card.3f_any_scenario_that_you_can_give_me_similar_to_this_process_.28a_way_to_issue_a_certificate_on_an_initialized_new_card.29.3f
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.
.. rubric:: 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?
:name: why_does_firefox_require_users_to_authenticate_themselves_by_entering_a_pin_at_the_keyboard.3f_why_not_use_a_pin_pad_or_a_fingerprint_reader_located_on_the_token_or_reader.3f
PKCS #11 defines how these kinds of devices work. There is an outstanding bug in Firefox to
implement this support.