tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

index.rst (27360B)


      1 .. _mozilla_projects_nss_pkcs11_faq:
      2 
      3 PKCS11 FAQ
      4 ==========
      5 
      6 .. _pkcs11_faq:
      7 
      8 `PKCS11 FAQ <#pkcs11_faq>`__
      9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     10 
     11 .. container::
     12 
     13   .. rubric:: QUESTIONS AND ANSWERS
     14      :name: questions_and_answers
     15 
     16   .. rubric:: GENERAL QUESTIONS
     17      :name: general_questions
     18 
     19   .. rubric:: After plugging in an external PKCS #11 module, how do you use the certificate
     20      available on the token? Does the certificate need to be imported into NSS's internal
     21      certificate database? If so, is there a way to get the certificate from an external token into
     22      NSS's internal certificate database?
     23      :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
     24 
     25   NSS searches all the installed PKCS #11 modules when looking for certificates. Once you've
     26   installed the module, the module's certificates simply appear in the list of certificates
     27   displayed in the Certificate window.
     28 
     29   .. rubric:: What version of PKCS #11 does NSS support?
     30      :name: what_version_of_pkcs_.2311_does_nss_support.3f
     31 
     32   NSS requires at least PKCS #11 version 2.0, but can support some features of later versions of
     33   NSS, including NSS 2.20. NSS does not use all the features of later versions of PKCS #11.
     34 
     35   .. rubric:: What are the expectations in terms of session manipulation? Will NSS potentially open
     36      more than one session at a time? Read-only sessions, read/write sessions, serial, parallel?
     37      :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
     38 
     39   NSS typically holds one session read-only session per slot, in which some of the non-multipart
     40   functions are handled. Multipart functions, such as bulk encryption, hashing, and mac functions
     41   (for example, C_Digest and C_Sign) and those that require overlapped operation (C_Unwrap,
     42   C_Decrypt) are handled by creating new sessions. If no new sessions are available, the one
     43   read-only session is used, and the state is saved and restored after each multipart operation.
     44 
     45   NSS never uses Parallel mode.
     46 
     47   NSS opens new read/write sessions for key generation, some password management, and storage of
     48   new certificates.
     49 
     50   If your token is read/write and has only one session, NSS will open that one initial session
     51   read/write.
     52 
     53   .. rubric:: What permanent PKCS #11 objects are used by NSS or read from the token? Example: RSA
     54      private key, CA certificate, user's own certificate, user's name.
     55      :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.
     56 
     57   Private keys (RSA and DSA) and the corresponding certificates are read from the token. Other
     58   certificates on the token are also loaded (to allow building certificate chains), but it's not
     59   necessary to include the full chain, as long as the full chain is available in the regular
     60   certificate database. For the sake of completeness, it's also a good idea to expose public key
     61   objects. NSS falls back to looking for the existance of public keys to determine if the token may
     62   have the corresponding private key while the token is not logged in.
     63 
     64   .. rubric:: How are permanent PKCS #11 objects found by NSS? That is, which PKCS #11 attributes
     65      are used in the object searches? Labels? Key IDs? Key types?
     66      :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
     67 
     68   These are the general guidelines:
     69 
     70   -  User certificates are identified by their labels.
     71   -  Certificates and keys are often looked up by the following methods:
     72 
     73      -  By looking up all private keys.
     74      -  By looking up all certificates.
     75      -  Certificates may be looked up by label. By convention, all certificates making up a single
     76         personality should have the same label (that is, a pair of certificates, one for signing
     77         and one for key exchange, should have the same label).
     78      -  S/MIME-capable certificates are also looked up by issuer/serial number.
     79      -  Certificates may be looked up by their DER value.
     80      -  Certificates may also be looked up by subject. More than one certificate can match, but
     81         each certificate with the same subject should be part of the same personality.
     82      -  NSS may enumerate all the permanment certificates in a token (CKA_TOKEN set to true).
     83      -  Private keys must have the same CKA_ID value as their corresponding certificate, and this
     84         value must be unique on the token.
     85      -  Orphaned keys have a CKA_ID generated from some part of the public key. This value is set
     86         when the key is generated, so that NSS will be able to find the key when the certificate
     87         for that key is loaded. This case is interesting only for read/write tokens.
     88 
     89   .. rubric:: What labels does NSS use to identify certificates?
     90      :name: what_labels_does_nss_use_to_identify_certificates.3f
     91 
     92   NSS can use the CKA_LABEL attribute to identify user certificates (see previous question) and
     93   presents this label to the user. Therefore, each user certificate must have some label associated
     94   with it. The label for a token certificate is presented to the user as follows:*token label*
     95   **:**\ *certificate label* . This implies that each\ *token label* should be unique and
     96   meaningful to the user, and that each\ *certificate label* should be unique to the token.
     97 
     98   NSS gets the value of the CKA_LABEL attribute from the token. Labels should not have any trailing
     99   blank characters.
    100 
    101   .. rubric:: Will NSS use the random number generation features of PKCS #11?
    102      :name: will_nss_use_the_random_number_generation_features_of__pkcs_.2311.3f
    103 
    104   Only if you identify your token as the default random number generator. If you do, your token
    105   must be able to generate random numbers even when it is not logged in. NSS uses installed random
    106   number generators if PKCS11_MECH_RANDOM_FLAG is set in the installer script. For information on
    107   how to do this, see Using the JAR Installation Manager to Install a PKCS #11 Cryptographic
    108   Module.
    109 
    110   .. rubric:: Can Mozilla provide a list of all PKCS #11 functions that NSS will use?
    111      :name: can_mozilla_provide_a_list_of_all_pkcs_.2311_functions_that_nss_will_use.3f
    112 
    113   Your token should expect to implement all the PKCS #11 functions that make sense for your token.
    114   NSS continues to evolve, and periodically enhances it's functionality by using a more complete
    115   list of PKCS #11 functions. You should have implementations for all the functions specified in
    116   the version of the PKCS #11 spec your token implements. If you do not actually do the operation
    117   specified by that function, you can return CKR_FUNCTION_NOT_SUPPORTED.
    118 
    119   .. rubric:: Will NSS get the user's CA certificate via PKCS #11 and push it into the CA
    120      certificate database or is the CA certificate database expected to obtain the CA certificate
    121      by some other means?
    122      :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
    123 
    124   PKCS #11 certificates that have private keys associated with them are loaded into the temporary
    125   database (in memory) and marked as user certificates. All other certificates in the module are
    126   loaded into the temporary database with no special trust bits associated with them. NSS is
    127   perfectly capable of using token certificates in place.
    128 
    129   .. rubric:: Which function does NSS use to get login state information?
    130      :name: which_function_does_nss_use_to_get_login_state_information.3f
    131 
    132   NSS calls C_GetSessionInfo to get the login/logout state. NSS never attempts to cache this
    133   information, because login state can change instantly without NSS knowing about it (for example,
    134   when the user removes the card). You must update all sessions correctly when the state changes.
    135   Not doing so is a common source of problems.
    136 
    137   .. rubric:: I have noticed that NSS sometimes use a session handle value of 0. Is this an invalid
    138      session handle?
    139      :name: i_have_noticed_that_nss_sometimes_use__a_session_handle_value_of_0._is_this_an_invalid_session_handle.3f
    140 
    141   A session handle of 0 is indeed invalid. In the past, NSS uses the invalid session handle to mark
    142   problems with acquiring or using a session. There have been cases where NSS would then use this
    143   handle to try to do some operation. PKCS #11 modules should fail with CKR_INVALID_SESSION. We are
    144   working to remove these cases as we find them.
    145 
    146   .. rubric:: What are "Generic Crypto Svcs" (the first item listed when you click the View/Edit
    147      button for the NSS Internal PKCS #11 Module under Security Devices under Options/Security in
    148      Firefox)?
    149      :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
    150 
    151   Generic Crypto Svcs are the services that NSS uses to do its basic cryptography (RSA encryption
    152   with public keys, hashing, AES, DES, RC4, RC2, and so on).Other PKCS #11 modules can supply
    153   implementations of these functions, and NSS uses those versions under certain conditions.
    154   However, these are not the services NSS calls to get to other PKCS #11 modules, which show up
    155   separately under Cryptographic Modules.
    156 
    157   .. rubric:: Our plugin provides several slots with different capabilities. For example, one does
    158      all the hashing/symmetric operations, while another does only asymmetric RSA operations. Can
    159      this kind of division lead to problems?
    160      :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
    161 
    162   The only issue is dealing with keys. For example, if the RSA slot unwraps a key, NSS needs to
    163   move that key to a slot that can do the symmetric operations. NSS itself uses two tokens
    164   internally--one that provides generic cryptographic services without authentication, and one that
    165   provides operations based on the keys stored in the user's database and do need authentication.
    166   NSS does this to avoid having to prompt for a password when performing an RSA verify operation,
    167   DES encryption, and so on. Therefore, NSS can move keys around when necessary and possible. When
    168   operating in FIPS mode, moving keys is significantly harder. In this case NSS uses a single token
    169   to handle both key and cert storage and crypto operations.
    170 
    171   In general, you not should use different slots unless you have a good reason. Much of NSS's token
    172   selection is based on where the key involved is currently stored. If the token that has your
    173   private keys doesn't also do symmetric operations, for example, it's likely that the internal
    174   token will end up doing the symmetric operations.
    175 
    176   .. rubric:: Is the PKCS #11 module supplied with NSS accessible through a shared library?
    177      :name: is_the_pkcs_.2311_module_supplied_with_nss_accessible_through_a_shared_library.3f
    178 
    179   Yes, the token is call softokn3 (softokn3.dll on windows, libsoftokn3.so on most unix platforms).
    180   The NSS softokn3 is not a complete PKCS #11 module, it was implemented only to support NSS,
    181   though other products have managed to get it to work in their environment. There are a number of
    182   bugs against softoken's non-compliance, but these bugs have lower priority than fixing NSS's
    183   non-complient uses of PKCS #11 or adding new features to NSS.
    184 
    185   .. rubric:: If multiple PKCS #11 modules are loaded, how does NSS determine which ones to use for
    186      the mechanisms required by SSL?
    187      :name: if_multiple_pkcs_.2311_modules_are_loaded.2c_how_does_nss_determine_which_ones_to_use_for_the_mechanisms_required_by_ssl.3f
    188 
    189   NSS uses the first slot it finds that can perform all the required operations. On servers, it's
    190   almost always the slot that contains the server's private key.
    191 
    192   .. rubric:: Does NSS support the use of PKCS #11 callbacks specified in the pNotify and
    193      pApplication parameters for C_OpenSession?
    194      :name: does_nss_support_the_use_of_pkcs_.2311_callbacks_specified_in_the_pnotify_and_papplication_parameters_for_c_opensession.3f
    195 
    196   NSS does not currently use any of the callbacks.
    197 
    198   NSS applications detect card insertion and deletion by means of polling to determine whether the
    199   card is still in the slot and whether the open session associated with that card is still valid,
    200   or by waiting on the C_WaitForSlotEvent call.
    201 
    202   .. rubric:: What must an X.509 certificate include to allow it to be recognized as an email
    203      certificate for use with S/MIME?
    204      :name: what_must_an_x.509_certificate_include_to_allow_it_to_be_recognized_as_an_email_certificate_for_use_with_s.2fmime.3f
    205 
    206   An email address must be included in the attribute of the subject DN or the mail attribute of the
    207   subject DN. If the subject DN does not include an email address, the certificate extension
    208   subjectAltName must include an email address. The subjectAltName extension is part of the X.509
    209   v3 and PKIX specifications.
    210 
    211   .. rubric:: If I have a multipurpose token that supports all required PKCS #11 functions and
    212      provides RSA_PKCS and DSA mechanisms but not AES, DES or RC4, will NSS use the token for the
    213      RSA_PKCS mechanisms and the NSS Internal PKCS #11 module for AES, DES or RC4 when making an
    214      SSL connection?
    215      :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
    216 
    217   Once NSS starts using a token for a given operation (like S/MIME or SSL), it works hard to keep
    218   using that same token (so keys don't get moved around). Symmetric operations supported by NSS
    219   include the following: CKM_AES_XXX, CKM_DES3_XXX, CKM_DES_XXX, CKM_RC2_XXX, and CKM_RC4_XXX. NSS
    220   knows about all the mechanisms defined in PKCS #11 version 2.01, but will not perform those that
    221   aren't defined by NSS's policy mechanism.
    222 
    223   .. rubric:: When do NSS Applications spawn threads off the main thread, which in turn opens up a
    224      new PKCS #11 session?
    225      :name: when_do_nss_applications_spawn_threads_off_the_main_thread.2c_which_in_turn_opens_up_a_new_pkcs_.2311_session.3f
    226 
    227   This depends on the application. PKCS #11 sessions are cryptographic session states, independent
    228   of threads. In NSS based servers, multiple threads may call the same session, but two threads
    229   will not call the same session at the same time.
    230 
    231   .. rubric:: QUESTIONS ABOUT KEYS AND TOKENS
    232      :name: questions_about_keys_and_tokens
    233 
    234   .. rubric:: Is the PKCS #11 token treated in a read-only manner? That is, no token init, no key
    235      gens, no data puts, no cert puts, etc.?
    236      :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
    237 
    238   If the token is marked read-only, then it will be treated as such. If the token is marked
    239   read/write and advertises that it can generate keys, NSS uses the token (through PKCS #11) to
    240   generate the key and loads the user's certificate into the token. If the token is marked
    241   read/write and does not advertise that it can generate keys, NSS generates the keys and loads
    242   them into the token.
    243 
    244   .. rubric:: How is private key handled when an external PKCS #11 module is loaded? Is it picked
    245      up from the token when securing, or does NSS expect it to be added in its private key database
    246      to use it?
    247      :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
    248 
    249   While certificates may be read into the temporary database, private keys are never extracted from
    250   the PKCS #11 module unless the user is trying to back up the key. NSS represents each private key
    251   and a pointer to its PKCS #11 slot as a CK_OBJECT_HANDLE. When NSS needs to do anything with a
    252   private key, it calls the PCKS #11 module that holds the key.
    253 
    254   .. rubric:: If a PKCS #11 library reports that, for example, it does not support RSA signing
    255      operations, does NSS expect to be able to pull an RSA private key off the token using the
    256      C_GetAttributeValue call and then do the operation in software?
    257      :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
    258 
    259   No. NSS will never try to pull private keys out of tokens (except as wrapped objects for PKCS
    260   #12). Operations the token does not support are considered impossible for the key to support.
    261 
    262   NSS may try to pull and load symmetric keys, usually if the key exchange happens in a token that
    263   does not support the symmetric algorithm. NSS works very hard not to have to pull any key out of
    264   a token (since that operation does not always work on all tokens).
    265 
    266   .. rubric:: If so, by what means does NSS attempt to retrieve the data? By searching for some
    267      fixed label attribute? Must the token store any temporary (session) objects?
    268      :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
    269 
    270   In general, yes, the token should store temporary session objects. This may not be necessary for
    271   "private key op only" tokens, but this is not guaranteed. You should be prepared to handle
    272   temporary objects. (Many NSS based server products will use temporary session objects, even for
    273   "private key op only" tokens.)
    274 
    275   .. rubric:: If a session key is unwrapped and stays on a hardware token, is it sufficient to
    276      support just the usual decryption mechanisms for it, or is it assumed that such a symmetric
    277      key will always be extractable from the token into the browser? The motivation for this is
    278      that some hardware tokens will prevent extraction of symmetric keys by design.
    279      :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.
    280 
    281   NSS attempts to extract an unwrapped key from a token only if the token cannot provide the
    282   necessary service with that key. For instance if you are decrypting an S/MIME message and you
    283   have unwrapped the DES key with the private key provided by a given token, NSS attempts to use
    284   that token to provide the DES encryption. Only if that token cannot do DES will NSS try to
    285   extract the key.
    286 
    287   .. rubric:: If the smartcard can't do key generation, will NSS do the key generation
    288      automatically?
    289      :name: if_the_smartcard_can.27t_do_key_generation.2c_will_nss_do_the_key_generation_automatically.3f
    290 
    291   Yes. If your token can do CKM_RSA_PKCS, and is writable, NSS displays it as one of the options to
    292   do key generation with. If the token cannot do CKM_RSA_PKCS_GEN_KEYPAIR, NSS uses its software
    293   key generation code and writes the private and public keys into the token using C_CreateObject.
    294   The RSA private key will contain all the attributes specified by PKCS #11 version 2.0. This is
    295   also true for CKM_DSA and CKM_DSA_GEN_KEYPAIR.
    296 
    297   .. rubric:: What is the C_GenerateKeyPair process? For example, what happens when an application
    298      in the a server asks an NSS based client to do a keypair generation while a smartCard is
    299      attached? How is the private key stored to the smartCard, and how is the public key sent to
    300      the server (with wrapping?).
    301      :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.
    302 
    303   The private key is created using C_GenerateKeyPair or stored using C_CreateObject (depending on
    304   who generates the key). NSS does not keep a copy of the generated key if it generates the key
    305   itself. Key generation in Mozilla clients is triggered either by the standard <KEYGEN> tag, or by
    306   the keygen functions off the window.crypto object. This is the same method used for generating
    307   software keys and certificates and is used by certificate authorities like VeriSign and Thawte.
    308   (Red Hat Certificate Server also uses this method). The public key is sent to the server
    309   base-64-DER-encoded with an (optional) signed challenge.
    310 
    311   .. rubric:: Are persistent objects that are stored on the token, such as private keys and
    312      certificates, created by the PKCS #11 module? Is it safe to assume that NSS never calls
    313      C_CreateObject for those persistent objects?
    314      :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
    315 
    316   No. As stated in the answer to the preceding question, when NSS does a keygen it uses
    317   C_GenerateKeyPair if the token supports the keygen method. If the token does not support keygen,
    318   NSS generates the key internally and uses C_CreateObject to load the private key into the token.
    319   When the certificate is received after the keygen, NSS loads it into the token with
    320   C_CreateObject. NSS also does a similar operation for importing private keys and certificates
    321   through pkcs12.
    322 
    323   The above statement is true for read-write tokens only.
    324 
    325   .. rubric:: When and how does NSS generate private keys on the token?
    326      :name: when_and_how_does_nss_generate_private_keys_on_the_token.3f
    327 
    328   As stated above, NSS uses C_GenerateKeyPair if the token supports the keygen method. If an RSA
    329   key is being generated, the NSS application will present a list of all writable RSA devices asks
    330   the user to select which one to use, if a DSA key is being generated, it will present a list of
    331   all the writable DSA devices, if an EC key is being generated, it will present a list of all
    332   writable EC devices.
    333 
    334   .. rubric:: Does NSS ever use C_CopyObject to copy symmetric keys if it needs to reference the
    335      same key for different sessions?
    336      :name: does_nss_ever_use_c_copyobject_to_copy_symmetric_keys_if_it_needs_to_reference_the_same_key_for_different_sessions.3f
    337 
    338   No. This is never necessary. The PKCS #11 specification explicitly requires that symmetric keys
    339   must be visible to all sessions of the same application. NSS explicitly depends on this semantic
    340   without the use of C_CopyObject. If your module does not support this semantic, it will not work
    341   with NSS.
    342 
    343   .. rubric:: QUESTIONS ABOUT PINS
    344      :name: questions_about_pins
    345 
    346   .. rubric:: Will a password change ever be done on the token?
    347      :name: will_a_password_change_ever_be_done_on_the_token.3f
    348 
    349   Yes, NSS attempts to change the password in user mode only. (It goes to SSO mode only if your
    350   token identifies itself as CKF_LOGIN_REQUIRED, but not CKF_USER_INITIALIZED).
    351 
    352   It's perfectly valid to reject the password change request with a return value such as
    353   CKR_FUNCTION_NOT_SUPPORTED. If you do this, NSS applications display an appropriate error message
    354   for the user.
    355 
    356   .. rubric:: If I have my smart card which has initial PIN set at '9999', I insert it into my
    357      reader and download with my certificate (keygen completed), can I issue 'Change Password' from
    358      the Firefox to set a new PIN to the smart card? Any scenario that you can give me similar to
    359      this process (a way to issue a certificate on an initialized new card)?
    360      :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
    361 
    362   Yes. First open the Tools/Options/Advanced/Security window in Mozilla and click Security Devices.
    363   Then select your PKCS #11 module, click View/Edit, select the token, and click Change Password.
    364   For this to work, you must supply a C_SetPIN function that operates as CKU_USER. Mozilla,
    365   Thunderbird, and Netscape products that use NSS have different UI to get the Security Devices
    366   dialog.
    367 
    368   To get a key into an initialized token, go to your local Certificate Authority and initiate a
    369   certificate request. Somewhere along the way you will be prompted with a keygen dialog. Normally
    370   this dialog does not have any options and just provides information; however, if you have more
    371   than one token that can be used in this key generation process (for example, your smartcard and
    372   the NSS internal PKCS#11 module), you will see a selection of "cards and databases" that can be
    373   used to generate your new key info.
    374 
    375   In the key generation process, NSS arranges for the key to have it's CKA_ID set to some value
    376   derived from the public key, and the public key will be extracted using C_GetAttributes. This key
    377   will be sent to the CA.
    378 
    379   At some later point, the CA presents the certificate to you (as part of this keygen, or in an
    380   e-mail, or you go back and fetch it from a web page once the CA notifies you of the arrival of
    381   the new certificate). NSS uses the public key to search all its tokens for the private key that
    382   matches that certificate. The certificate is then written to the token where that private key
    383   resides, and the certificate's CKA_ID is set to match the private key.
    384 
    385   .. rubric:: Why does Firefox require users to authenticate themselves by entering a PIN at the
    386      keyboard? Why not use a PIN pad or a fingerprint reader located on the token or reader?
    387      :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
    388 
    389   PKCS #11 defines how these kinds of devices work. There is an outstanding bug in Firefox to
    390   implement this support.