Changes

Step 0: Preparation: collect the directory and prefix names of both thesource and target DBs. Prepare two strings for the operation: a) # <nowiki>A string to uniquely identify the source DB, for the purpose of

DB prefixes, and from the last modification time of the source DBs.<br><br>

destination file. </nowiki><br><br><nowiki>Note: The purpose of this string is to prevent multiple updates from the same old Database. This merge sequence is meant to be light enough weight that applications can safely call it each time they initialize.</nowiki> b) # <nowiki>A string that will be the name of the removable PKCS#11 token that

valid token name and must not contain any colon (:) characters.</nowiki>

*If the DB slot token is removable, then an update/merge is necessary. *However,if there is no database password on either the source or the target database,then NSS has already completed the merge. You can test for this withPK11_NeedLogin(). If PK11_NeedLogin() is true then it is necessary to authenticate to the source token, at step 3 below.*If the token is not removable, then no merge is necessary and you can skipto step 87.

a) # <nowiki>(optional) Call PK11_GetTokenName to get the name of the token. Withthat name, you can be sure that you are authenticating to the source token. Skipping this step is not harmful, it is only necessary if the application absolutely needs to know which token the following PK11_Authenticate() will be called on (for instance pwArg contains the actual password for the token). For most NSS applications the underlying password prompt system will properly disambiguate the appropriate password to the user (or it's password cache).</nowiki>#* If the token name does not match the token name skip to step 5.#* Otherwise proced to step 3.2.b) # <nowiki>Call PK11_Authenticate() to authenticate to the source token. This

function to retrieve the password.</nowiki> #*If this step fails: stop. A Failure at this point is described below as "Exception A".#*Otherwise, continue with step 4.

*If the function indicates that the DB token is NOT logged in, then it isnecessary to authenticate to the target DB, with the next step below.*If the function indicates that the token is logged in, skip down to step 87.

If this fails, stop.If this call indicates that the token is NOT present, something fundamentally wrong in the NSS softoken engine. Applications should treat this the same asan NSS initialization failure.If this call indicates that the token name in the DB slot is now thetarget token name, continue to step 6. Step 6: (optional) Call PK11_GetTokenName to get the name of the tokenin the DB slot. If this is the name of the target token, then the nextstep will be to authenticate to the target DB token. This call allowsthe caller to ensure that he is about the authenticate to the targettoken, and to get the target token name string for prompts. NOTE: Again, this check is only necessary form applications which need to know exactly which password PK11_Authenticate() is prompting for. For most well written NSS applications this step is not needed. Step 7: Call PK11_Authenticate to authenticate to the target token.

* If this step fails: stop. A Failure at this point is described below as "Exception B".* Otherwise, continue with step 87. Step 7. SUCCESS! You have successfully performed the merge. Future calls using the same unique identifier will single that the merge is not necessary, skipping to here from step 2 above. At this point NSS is fully enabled and the application can start making NSS calls as normal.

ExeptionsExceptions:

exception Exception A. Application needs to decide what happens if the legacy password

# continue to use the legacy DB and try to update later. (Probably a future restart of the application).# force NSS to mark legacy DB to be updated without actually updating reset the legacy DB (database, throwing away everything any private or secret keys in the legacy DB)old database.# force shutdown NSS and initialize it only with the new shared database.: The exact strategy for recovering is application dependent and depends on factors like:# the sensitivity of the application to update those objects it can loosing key data.:# possible input from the legacy DB, throwinguser.away private keys and saved passwords:# the likelihood that the password will every be recovered.

exception Exception B. Applications needs to decide what happens if the new shared DB

# force NSS to reset the shared database password, throwing away private keys and saved passwords, and trust information rom from the shared DB.

Note Notes: 1: . The actual merger may take place during step 1, or step 3b, or

authentication attempts, if any, succeed. This The system tries to complete themerge as soon as it is able, to increase reliability of the merge update actually completing. Therefore API does not make it

merge. The code must try it and see. However, Since multiple calls to PK11_Authenticate() do not hurt (PK11_Authenticate will automatically return without prompting, so applications that just need to update (without necessarily caring which step the update completes) can simply follow the steps and know the update is done by step 87.

Note: 2. If the attempt to open the

*/