Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 825 insertions, 0 deletions

diff --git a/security/nss/doc/rst/legacy/pkcs11/faq/index.rst b/security/nss/doc/rst/legacy/pkcs11/faq/index.rst
new file mode 100644
index 0000000000..81fe124736
--- /dev/null
+++ b/security/nss/doc/rst/legacy/pkcs11/faq/index.rst
@@ -0,0 +1,390 @@
+.. _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.
\ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/pkcs11/index.rst b/security/nss/doc/rst/legacy/pkcs11/index.rst
new file mode 100644
index 0000000000..957080266d
--- /dev/null
+++ b/security/nss/doc/rst/legacy/pkcs11/index.rst
@@ -0,0 +1,14 @@
+.. _mozilla_projects_nss_pkcs11:
+
+PKCS11
+======
+
+.. container::
+
+   PKCS #11 information for implementors of cryptographic modules:
+
+   -  `Implementing PKCS11 for NSS <PKCS11_Implement>`__
+   -  :ref:`mozilla_projects_nss_pkcs11_faq`
+   -  `Using the JAR Installation Manager to Install a PKCS #11 Cryptographic
+      Module <PKCS11_Jar_Install>`__
+   -  `PKCS #11 Conformance Testing <PKCS11_Conformance>`__
\ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/pkcs11/module_installation/index.rst b/security/nss/doc/rst/legacy/pkcs11/module_installation/index.rst
new file mode 100644
index 0000000000..bd3502e4b6
--- /dev/null
+++ b/security/nss/doc/rst/legacy/pkcs11/module_installation/index.rst
@@ -0,0 +1,56 @@
+.. _mozilla_projects_nss_pkcs11_module_installation:
+
+PKCS11 module installation
+==========================
+
+.. container::
+
+   `PKCS #11 </en-US/PKCS11>`__ modules are external modules which add to Firefox support for
+   smartcard readers, biometric security devices, and external certificate stores. This article
+   covers the two methods for installing PKCS #11 modules into Firefox. Users can use the
+   preferences dialog to install or remove PKCS #11 module. Extensions can programmatically manage
+   PKCS #11 modules using the nsIPKCS11 programming interface.
+
+   .. note::
+
+      **Note:** The information in this article is specific to Firefox 3.5 and newer. Older versions
+      of Firefox may support the
+      `window.pkcs11 <https://developer.mozilla.org/en-US/docs/Web/API/Window/pkcs11>`__ property
+      for installing PKCS #11 modules.
+
+.. _using_the_firefox_preferences_to_install_pkcs_11_modules:
+
+`Using the Firefox preferences to install PKCS #11 modules <#using_the_firefox_preferences_to_install_pkcs_11_modules>`__
+-------------------------------------------------------------------------------------------------------------------------
+
+.. container::
+
+   #. Save the PKCS #11 module to a permanent location on your local computer
+   #. Open the Firefox preferences dialog. Choose "Advanced" > "Encryption" > "Security Devices"
+   #. Choose "Load"
+   #. Enter a name for the security module, such as "My Client Database". NOTE: there is currently a
+      bug in Firefox where international characters may cause problems.
+   #. Choose "Browse..." to find the location of the PKCS #11 module on your local computer, and
+      choose "OK" when done.
+
+.. _provisioning_pkcs_11_modules_using_the_pkcs11_api:
+
+`Provisioning PKCS #11 modules using the pkcs11 API <#provisioning_pkcs_11_modules_using_the_pkcs11_api>`__
+-----------------------------------------------------------------------------------------------------------
+
+.. container::
+
+   Starting with Firefox 58, extensions can use the ``pkcs11`` browser extension API to enumerate
+   PKCS #11 modules and make them accessible to the browser as sources of keys and certificates.
+
+.. _see_also:
+
+`See also <#see_also>`__
+------------------------
+
+.. container::
+
+   -  `Web security <https://developer.mozilla.org/en-US/docs/Web/Security>`__
+   -  :ref:`mozilla_projects_nss_pkcs11`
+   -  ``pkcs11.installModule()``
+   -  ``pkcs11.isModuleInstalled()``
\ No newline at end of file
diff --git a/security/nss/doc/rst/legacy/pkcs11/module_specs/index.rst b/security/nss/doc/rst/legacy/pkcs11/module_specs/index.rst
new file mode 100644
index 0000000000..cb8729161e
--- /dev/null
+++ b/security/nss/doc/rst/legacy/pkcs11/module_specs/index.rst
@@ -0,0 +1,365 @@
+.. _mozilla_projects_nss_pkcs11_module_specs:
+
+PKCS #11 Module Specs
+=====================
+
+.. _pkcs_.2311_module_specs:
+
+`PKCS #11 Module Specs <#pkcs_.2311_module_specs>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   The following is a proposal to the `PKCS <https://en.wikipedia.org/wiki/PKCS>`__ #11 working
+   group made in August 2001 for configuring PKCS #11 modules. NSS currently implements this
+   proposal internally.
+
+   The file format consists of name/value pairs of the form ``name=value``. Each name/value pair is
+   separated by a blank value. A single line, terminated by a '\n', '\r\n', or '\r' represents a
+   single pkcs #11 library.
+
+   Names can be any alpha/numeric combination, and are parsed case-insensitive.
+
+   Values can contain any printable ASCII value, including UTF8 characters. Values can contain
+   embedded blanks either through quoting the entire value, or by escaping the embedded blanks with
+   '\'. The value is considered quoted if the first character after the '=' is ', ", {, [, or <. If
+   the value is quoted, then the value is terminated with and ending quote of the form ', ", ), ],
+   }, or > matching the respective starting quote. Ending quotes can be escaped. Embedded '\'
+   characters are considered escape characters for the next character in the stream. Note that case
+   must be preserved in the values.
+
+   These modules specs can be passed by the application directly to NSS via the
+   ``SECMOD_LoadUserModule()`` call. To initialize a PKCS #11 module 'on-the-fly'.
+
+   .. rubric:: Recognized Names
+      :name: recognized_names
+
+   All applications/libraries must be able recognize the following name values:
+
+   library 
+      This specifies the path to the pkcs #11 library.
+   name 
+      This specifies the name of the pkcs #11 library.
+   parameter 
+      This specifies a pkcs #11 library parameter with the application must pass to the pkcs #11
+      library at ``C_Initialize()`` time (see below).
+
+   In additions applications/libraries should be able to ignore additional name value pairs which
+   are used to specify configuration for other applications. Of course these application/libraries
+   should be able to parse their own name/value pairs.
+
+   Each of these name/value pairs are optional.
+
+   If the library is not specified, the line represents some application specific meta configuration
+   data. Other applications and libraries can safely ignore this line.
+
+   If the name is not specified, the application can use the library path to describe the PKCS #11
+   library in any UI it may have.
+
+   If the parameter is not specified, no parameters are passed to the PKCS #11 module.
+
+   If the application/library does not find its application/library specific data, it should use
+   it's defaults for this pkcs #11 library.
+
+   .. rubric:: Parameter Passing
+      :name: parameter_passing
+
+   If the parameter is specified, the application/library will strip the value out, processing any
+   outter quotes and escapes appropriately, and pass the parameter to the pkcs #11 library when it
+   calls ``C_Initialize()``.
+
+   A new ``CK_C_INITIALIZE_ARGS`` structure is defined as
+
+   .. code::
+
+      typedef struct CK_C_INITIALIZE_ARGS {
+        CK_CREATEMUTEX CreateMutex;
+        CK_DESTROYMUTEX DestroyMutex;
+        CK_LOCKMUTEX LockMutex;
+        CK_UNLOCKMUTEX UnlockMutex;
+        CK_FLAGS flags;
+        CK_VOID_PTR LibraryParameters;
+        CK_VOID_PTR pReserved;
+      } CK_C_INITIALIZE_ARGS;
+
+   Applications/libraries must set LibraryParameters to ``NULL`` if no parameter value is specified.
+   PKCS #11 libraries which accept parameters must check if the 'new' ``pReserved`` field is
+   ``NULL`` if and only if ``LibraryParameters`` field is not ``NULL``.
+
+.. _nss_specific_parameters_in_module_specs:
+
+`NSS Specific Parameters in Module Specs <#nss_specific_parameters_in_module_specs>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   Here are the NSS Application specific parameters in use. This data is currently stored in
+   ``secmod.db`` or pkcs11.txt. This isn't part of the generic spec (that is other applications need
+   not parse it, nor pkcs #11 modules need supply them or use them).
+
+   .. code::
+
+      NSS="nss_params"
+
+   ``nss_params`` are themselves name/value pairs, parsed with the same rules described above. Valid
+   names inside ``nss_params`` are:
+
+   flags
+      comma separated list of flag values, parsed case-insensitive.
+      Valid flag values are:
+
+      internal
+         this library is actually the Netscape internal library
+      fips
+         this library is the Netscape internal fips library.
+      critical
+         if this library cannot be loaded, completely fail initialization.
+      moduleDB
+         this library includes NSS specific functions to supply additional module specs for loading.
+         **moduleDBOnly** - this library has no PKCS #11 functions and is only used for loading
+         additional modules.
+   trustOrder
+      integer value specifying the order in which the trust information for certificates specified
+      by tokens on this PKCS #11 library should be rolled up. A value of 0 means that tokens on this
+      library should not supply trust information. The default trust order value is 50. The relative
+      order of two pkcs#11 libraries which have the same trustOrder value is undefined.
+   cipherOrder
+      integer value specifiying the order in which tokens are searched when looking for a token to
+      do a generic operation (DES/Hashing, etc).
+   ciphers
+      comma separated list of ciphers this token will enable that isn't already enabled by the
+      library (currently only **FORTEZZA** is defined) (case-insensitive).
+   slotParams
+      space separated list of name/value pairs where the name is a slotID and the value is a space
+      separated list of parameters related to that slotID. Valid slotParams values are:
+
+      slotFlags
+         comma separated list of cipher groups which this slot is expected to be the default
+         implementation for (case-insensitive).
+         Valid flags are:
+
+         RSA
+            This token should be used for all RSA operations (other than Private key operations
+            where the key lives in another token).
+         DSA
+            This token should be used for all DSA operations (other than Private key operations
+            where the key lives in another token).
+         RC4
+            This token should be used for all RC4 operations which are not constrained by an
+            existing key in another token.
+         RC2
+            This token should be used for all RC2 operations which are not constrained by an
+            existing key in another token.
+         DES
+            This token should be used for all DES, DES2, and DES3 operations which are not
+            constrained by an existing key in another token.
+         DH
+            This token should be used for all DH operations (other than Private key operations where
+            the key lives in another token).
+         FORTEZZA
+            This token should be used for all KEA operations (other than Private key operations
+            where the key lives in another token), as well as SKIPJACK operations which are not
+            constrained by an existing key in another token.
+         RC5
+            This token should be used for all RC5 operations which are not constrained by an
+            existing key in another token.
+         SHA1
+            This token should be used for all basic SHA1 hashing.
+         MD5
+            This token should be used for all basic MD5 hashing.
+         MD2
+            This token should be used for all basic MD2 hashing.
+         SSL
+            This token should be used for SSL key derivation which are not constrained by an
+            existing key in another token.
+         TLS
+            This token should be used for TLS key derivation which are not constrained by an
+            existing key in another token.
+         AES
+            This token should be used for all AES operations which are not constrained by an
+            existing key in another token.
+         RANDOM
+            This token should be used to generate random numbers when the application call
+            'PK11_GenerateRandom'.
+         PublicCerts
+            The certificates on this token can be read without authenticating to this token, and any
+            user certs on this token have a matching public key which is also readable without
+            authenticating. Setting this flags means NSS will not try to authenticate to the token
+            when searching for Certificates. This removes spurious password prompts, but if
+            incorrectly set it can also cause NSS to miss certificates in a token until that token
+            is explicitly logged in.
+      rootFlags
+         comma separated of flags describing any root certs that may be stored (case-insensitive).
+         Valid flags are:
+
+         hasRootCerts
+            claims that this token has the default root certs and trust values. At init time NSS,
+            will try to look for a default root cert device if one has not already been loaded.
+         hasRootTrust
+            parsed but ignored.
+      timeout
+         time in minutes before the current authentication should be rechecked. This value is only
+         used if askpwd is set to 'timeout'. (default = 0).
+      askpwd
+         case-insensitive flag describing how password prompts should be manages. Only one of the
+         following can be specified.
+
+         every
+            prompt whenever the a private key on this token needs to be access (this is on the
+            entire token, not on a key-by-key basis.
+         timeout
+            whenever the last explicit login was longer than 'timeout' minutes ago.
+         only
+            authenticate to the token only when necessary (default).
+
+   Sample file:
+
+   .. code::
+
+      library= name="Netscape Internal Crypto Module"   parameters="configdir=/u/relyea/.netscape certprefix= secmod=secmod.db" NSS="Flags=internal,pkcs11module TrustOrder=1 CipherOrder=-1 ciphers= slotParams={0x1=[slotFlags='RSA,DSA,DH,RC4,RC2,DES,MD2,MD5,SHA1,SSL,TLS,PublicCerts,Random'] 0x2=[slotFlags='RSA' askpw=only]}"
+      library=dkck32.dll name="DataKey SignaSURE 3600" NSS="TrustOrder=50 ciphers= "
+      library=swft32.dll name="Netscape Software Fortezza" parameters="keyfile=/u/relyea/keyfile" NSS="TrustOrder=50 ciphers=FORTEZZA slotParams=0x1=[slotFlags='FORTEZZA']"
+      library=core32.dll name="Litronic Netsign"
+
+.. _softoken_specific_parameters:
+
+`Softoken Specific Parameters <#softoken_specific_parameters>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. container::
+
+   The internal NSS PKCS #11 implementation (softoken) requires Applications parameters. It will not
+   initialize if the **parameters**\ = is not specified. If another application wishes to load the
+   softoken, that application must supply a non-``NULL`` ``libraryParameters`` value in the
+   ``CK_C_INITIALIZE_ARGS`` structure passed at ``C_INITIALIZE`` time. The parameter passed to
+   softoken is a space separated list of name/value pairs exactly like those specified in the PKCS
+   #11 module spec.
+
+   Valid values are:
+
+   configDir 
+      Configuration Directory where NSS can store persistant state information (typically
+      databases).
+   secmod 
+      Name of the secmod database (default = secmod.db).
+   certPrefix 
+      Prefix for the cert database.
+   keyPrefix 
+      Prefix for the key database.
+   minPWLen 
+      Minimum password length in bytes.
+   manufacturerID 
+      Override the default ``manufactureID`` value for the module returned in the ``CK_INFO``,
+      ``CK_SLOT_INFO``, and ``CK_TOKEN_INFO`` structures with an internationalize string (UTF8).
+      This value will be truncated at 32 bytes (no NULL, partial UTF8 characters dropped).
+   libraryDescription 
+      Override the default ``libraryDescription`` value for the module returned in the ``CK_INFO``
+      structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no
+      ``NULL``, partial UTF8 characters dropped).
+   cryptoTokenDescription 
+      Override the default label value for the internal crypto token returned in the
+      ``CK_TOKEN_INFO`` structure with an internationalize string (UTF8). This value will be
+      truncated at 32 bytes (no NULL, partial UTF8 characters dropped).
+   dbTokenDescription 
+      Override the default label value for the internal DB token returned in the ``CK_TOKEN_INFO``
+      structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no
+      NULL, partial UTF8 characters dropped).
+   FIPSTokenDescription 
+      Override the default label value for the internal FIPS token returned in the ``CK_TOKEN_INFO``
+      structure with an internationalize string (UTF8). This value will be truncated at 32 bytes (no
+      NULL, partial UTF8 characters dropped).
+   cryptoSlotDescription 
+      Override the default ``slotDescription`` value for the internal crypto token returned in the
+      ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be
+      truncated at 64 bytes (no NULL, partial UTF8 characters dropped).
+   dbSlotDescription 
+      Override the default ``slotDescription`` value for the internal DB token returned in the
+      ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be
+      truncated at 64 bytes (no NULL, partial UTF8 characters dropped).
+   FIPSSlotDescription 
+      Override the default ``slotDescription`` value for the internal FIPS token returned in the
+      ``CK_SLOT_INFO`` structure with an internationalize string (UTF8). This value will be
+      truncated at 64 bytes (no NULL, partial UTF8 characters dropped).
+   flags 
+      comma separated list of flag values, parsed case-insensitive.
+
+   .. rubric:: Flags
+      :name: flags
+
+   Valid flags are:
+
+   noModDB 
+      Don't open ``secmod.db`` and try to supply the strings. The MOD DB function is not through
+      standard PKCS #11 interfaces.
+   readOnly 
+      Databases should be opened read only.
+   noCertDB 
+      Don't try to open a certificate database.
+   noKeyDB 
+      Don't try to open a key database.
+   forceOpen 
+      Don't fail to initialize the token if the databases could not be opened.
+   passwordRequired 
+      Zero length passwords are not acceptable (valid only if there is a keyDB).
+   optimizeSpace 
+      allocate smaller hash tables and lock tables. When this flag is not specified, Softoken will
+      allocate large tables to prevent lock contention.
+   tokens 
+      configure 'tokens' by hand. The tokens parameter specifies a space separated list of slotIDS,
+      each of which specify their own set of parameters affecting that token. Typically 'tokens'
+      would not be specified unless additional databases are to be opened as additional tokens. If
+      tokens is specified, then all tokens (including the default tokens) need to be specified. If
+      tokens is not specified, then softoken would default to the following specs:
+
+   In non-FIPS mode:
+
+   .. code::
+
+      tokens=<0x01=[configDir=configDir tokenDescription=cryptoTokenDescription slotDescription=cryptoSlotDescription flags=noCertDB,noKeyDB,optimizeSpace] 0x02=[configDir=configDir tokenDescription=dbTokenDescription slotDescription=dbSlotDescription certPrefix=certPrefix keyPrefix=keyPrefix flags=flags minPWLen=minPWLen]>
+
+   In FIPS mode:
+
+   .. code::
+
+      tokens=<0x03=[configDir=configDir tokenDescription=FIPSTokenDescription slotDescription=FIPSSlotDescription certPrefix=certPrefix keyPrefix=keyPrefix flags=flags minPWLen=minPWLen]>
+
+   where *configDir*, *cryptoTokenDescription*, *cryptoSlotDescription*, *dbTokenDescription*,
+   *dbSlotDescription*, *FIPSTokenDescription*, *FIPSSlotDescription*, *optimizeSpace*,
+   *certPrefix*, *keyPrefix*, *flags*, and *minPWLen* are copied from the parameters above.
+
+   Parameters:
+
+   configDir 
+      The location of the databases for this token. If ``configDir`` is not specified, the default
+      ``configDir`` specified earlier will be used.
+   certPrefix 
+      Cert prefix for this token.
+   keyPrefix 
+      Prefix for the key database for this token.
+   tokenDescription 
+      The label value for this token returned in the ``CK_TOKEN_INFO`` structure with an
+      internationalize string (UTF8). This value will be truncated at 32 bytes (no NULL, partial
+      UTF8 characters dropped).
+   slotDescription 
+      The ``slotDescription`` value for this token returned in the ``CK_SLOT_INFO`` structure with
+      an internationalize string (UTF8). This value will be truncated at 64 bytes (no NULL, partial
+      UTF8 characters dropped).
+   minPWLen 
+      minimum password length for this token.
+   flags 
+      comma separated list of flag values, parsed case-insensitive.
+      Valid flags are:
+
+      readOnly 
+         Databases should be opened read only.
+      noCertDB 
+         Don't try to open a certificate database.
+      noKeyDB 
+         Don't try to open a key database.
+      forceOpen 
+         Don't fail to initialize the token if the databases could not be opened.
+      passwordRequired 
+         Zero length passwords are not acceptable (valid only if there is a ``keyDB``).
+      optimizeSpace 
+         allocate smaller hash tables and lock tables. When this flag is not specified, Softoken
+         will allocate large tables to prevent lock contention.
\ No newline at end of file