Mode 2 Applications can also continue to call traditional NSS_Initialize() functions. The should, however, prepend the string "sql:" to the directory path passed to NSS in the configdir parameter. If the sql databases do not exist, NSS will automatically update any old DBM databases in the config directory to shared databases. Like the upgrade from cert7 to cert8, if the update does not work, the app will open and use the old DBM database. Upgrade will not happen if
1) # NSS is opened readOnly. 2) # NSS_Initialization fails. 3) #The database is password protected and the user never logs into the token during the lifetime of the application.
Applications can avoid final case 3 of failure by forcing the user to authenticate to softoken using PK11_Authenticate(). Sample code fragment.
Mode 3 Applications are the most complicated. NSS provides some services to help applications get through and update and merge with the least interaction with the user of the application.
FirstStep 0: Preparation: collect the directory and prefix names of both thesource and target DBs. Prepare two strings for the operation: a) A string to uniquely identify the source DB, Mode three for the purpose ofavoiding a repeat of this merge (making the merge idempotent). Thisstring could be derived from the name of the application that used thesource DB, from any application "instance" names (such as profilenames), from the absolute path name of the source DB directory and theDB prefixes, and from the last modification time of the source DBs. The algorithm for deriving this string should always produce the sameresult for the same set of source files, so that the code can detect asecond or subsequent attempt to merge the same source file into thedestination file. 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 need to can safely call it each time they initialize. b) A string that will be the name of the removable PKCS#11 token thatwill represent the source DB. This string must follow the rules for avalid token name and must not contain any colon (:) characters. Step 1: Call NSS_InitWithMerge, passing as arguments the destinationdirectory name, destination file name prefix, source directory name,source file name prefix, unique source DB identifier string, and sourcetoken name string. If this function fails, stop. (Note: the present implementation has no way to pass the source DBprefix to the function. This needs to be corrected.) Step 2: Determine if it is necessary to authenticate for the source DB.This will not be necessary if the merge operation has already completed,or if the source DB had no password. To determine this, the applicationcalls a function to ask if the token in the DB slot is removable. Thefunction to be called for that purpose has not yet been made public, sothose details are TBD. That needs to be corrected. If the DB slot token is removable, then it is necessary to authenticateto the source token, at step 3 below. If the token is not removable,then it NOT necessary to authenticate to the source DB. Skip to step 4. Step 3. Authenticate to the source token. The substeps are: a) (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. b) Call PK11_Authenticate() to authenticate to the source token. This step is likely to call includes extra parameters needed the application-supplied PKCS11 password callbackfunction to retrieve the password. If this step fails: stop. A Failure at this point is described in thewiki document as "Exception A".Otherwise, continue with step 4. Step 4. Determine if it is necessary to authenticate to the target DB.This is done by NSS calling PK11_IsLoggedIn for the DB slot.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 help automatically determine step 8. Step 5. Call PK11_IsPresent(). You may think of this step as tellingyou if an update/the removable source token has been removed and the target tokenhas been inserted into the DB slot. In reality, this call makes thosethings happen. After this call succeeds the token name should be thatof the target token (see next step). If this fails, stop.If this call indicates that the token is NOT present, then something isamiss. (More details needed here).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. Step 7: Call PK11_Authenticate to authenticate to the target token.This step is likely to call the application-supplied PKCS11 passwordcallback function to retrieve the password. If this step fails: stop. A Failure at this point is described in thewiki document as "Exception B".Otherwise, continue with step 8. Step 8. SUCCESS! You have successfully performed the merge. Rejoice!The Source DB Unique identifier string will have been written into thetarget DB, so that future attempts to merge the same DB will be detectedand avoided. A tool wishing to perform only the merge may stop here. A product thatwishes to continue on to perform its normal function may do so.Be sure to do a clean shutdown before exiting. Notes:Note 1: The actual merger may take place during step 1, or step 3b, orstep 7; that is , during the call to NSS_InitWithMerge or during eitherof the calls to PK11_Authenticate. This will depend on the ability ofthe code to open the necessaryDBs, the presence or absence of passwordson the DBs, and if both have passwords, it will depend on whether theyhave the same password or different passwords, and when theauthentication attempts, if any, succeed. This API does not make itpossible to predict, accurately, which step will actually perform themerge. The code must try it and see. However, 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 8. Note: If the attempt to open thesource DB fails for any reason, the operation will behave as if thesource DB was empty. It will record the unique source DB identifierstring in the target DB and act as if the merger is complete. This is similiar to what happens in all previous versions of NSS during database update. See "Database Merge" below for how to accomplish itrecover from this.
==== Database Upgrade Underlying Implementation ====
