MozillaWiki

NSS Shared DB: Difference between revisions

Page Discussion

NSS Shared DB (view source)

Revision as of 21:16, 23 March 2018

43 bytes removed ,  23 March 2018
→‎Shared Database Proposal: Fix NSS version number for the SQLite change.
(Deleted a HUGE block of duplicated text, and do some wordsmithing)
(→‎Shared Database Proposal: Fix NSS version number for the SQLite change.)
 
(13 intermediate revisions by 6 users not shown)
Line 1: Line 1:
== Shared Database Proposal ==
== Shared Database Proposal ==


NSS has been using an old version of the Berkeley DataBase as its database engine since Netscape Navigator 2.0 in 1994. This database engine is commonly described in NSS documents as "DBM" and has a  
Prior to version 3.35, NSS had been using an old version of the Berkeley DataBase as its database engine since Netscape Navigator 2.0 in 1994. This database engine is commonly described in NSS documents as "DBM" and has a  
number of limitations.  One of the most severe limitations concerns the  
number of limitations.  One of the most severe limitations concerns the  
number of processes that may share a database file.  While any process has  
number of processes that may share a database file.  While any process has  
Line 7: Line 7:
Multiple processes may share a DBM database ONLY if they ALL access it  
Multiple processes may share a DBM database ONLY if they ALL access it  
READ-ONLY.  Processes cannot share a DBM database file if ANY of them wants
READ-ONLY.  Processes cannot share a DBM database file if ANY of them wants
to update it.
to update it.
 
NOTE: Since 3.35, NSS has moved to an [[NSS SQLite-based DB]].


This limitation has been cumbersome for applications that wish to use NSS.   
This limitation has been cumbersome for applications that wish to use NSS.   
Line 13: Line 15:


*Synchronized updates, with application down time: The applications share the database read-only.  If any update is desired, all the applications are shut down, and a database update program performs the update, then all the applications are restarted in read-only mode.  Some server products, for example, have an administration program that stops the servers, updates the database that they share, and then restarts the servers.  This results in undesirable downtime and desired database changes are delayed until the next interval in which such downtime is acceptable.
*Synchronized updates, with application down time: The applications share the database read-only.  If any update is desired, all the applications are shut down, and a database update program performs the update, then all the applications are restarted in read-only mode.  Some server products, for example, have an administration program that stops the servers, updates the database that they share, and then restarts the servers.  This results in undesirable downtime and desired database changes are delayed until the next interval in which such downtime is acceptable.
*Multiple copies with duplicated updates.  Each application keeps its own copy of its databases, and applications communicate their changes to each other, so that each application may apply received changes to its own DB. FireFox and Thunderbird are examples of this.  When one of those applications gets a new certificate and private key, the user may "export" that pair to a PKCS#12 file, and then import that file into the other application.  Most users never master these steps, and so have databases entirely out of sync.
*Multiple copies with duplicated updates.  Each application keeps its own copy of its databases, and applications communicate their changes to each other, so that each application may apply received changes to its own database. FireFox and Thunderbird are examples of this.  When one of those applications gets a new certificate and private key, the user may "export" that pair to a PKCS#12 file, and then import that file into the other application.  Most users never master these steps, and so have databases entirely out of sync.


These workarounds for the DBM engine's limitations are sufficiently onerous  
These workarounds for the DBM engine's limitations are sufficiently onerous  
Line 31: Line 33:
=== Where we are today ===
=== Where we are today ===


At initialization time, the application gives NSS a string that it uses as the pathname of a directory to store NSS's security and configuration data. NSS typically stores 3 dbm files in that directory:
At initialization time, the application gives NSS a string that it uses as the pathname of a directory to store NSS's security and configuration data. NSS typically stores 3 DBM files in that directory:


* cert8.db  - stores publicly accessible objects (certs, CRLs, S/MIME records).
* cert8.db  - stores publicly accessible objects (certs, CRLs, S/MIME records).
Line 38: Line 40:


Also in that directory:<br />
Also in that directory:<br />
* If it has very large security objects (such as large CRLs), NSS will store them in files in a subdirectory named cert8.dir.
* If it has very large security objects (such as large CRLs), NSS will store them in files in a subdirectory named cert8.dir. (Yes, really!)
* If the cert8.db and/or key3.db files are missing, NSS will read data from older versions of those databases (e.g., cert7.db, cert5.db, if they exist) and may build new cert8.db and/or key3.db files with that data (upgrade).
* If the cert8.db and/or key3.db files are missing, NSS will read data from older versions of those databases (e.g., cert7.db, cert5.db, if they exist) and may build new cert8.db and/or key3.db files with that data (upgrade).


Line 57: Line 59:


In the presence of a multiaccess initialization string, during initialization
In the presence of a multiaccess initialization string, during initialization
NSS will try to find a shared library named librdb.so (rdb.dll on Windows) in its path and load it. This shared library is expected to implement a superset of the old dbm interface.  The main entry point is rdbopen, which will be passed the appName, database name, and open flags. The rdb shared library will pick a location or method to store the database (it may not necessarily be a file), then handle the raw db records from NSS.  The records passed to and from this library use exactly the same schema and record formats as the records in the DBM library.   
NSS will try to find a shared library named librdb.so (rdb.dll on Windows) in its path and load it. This shared library is expected to implement a superset of the old DBM interface.  The main entry point is rdbopen, which will be passed the appName, database name, and open flags. The rdb shared library will pick a location or method to store the database (it may not necessarily be a file), then handle the raw database records from NSS.  The records passed to and from this library use exactly the same schema and record formats as the records in the DBM library.   


=== The proposal ===
=== The proposal ===
Line 353: Line 355:
'''extern:'''''directory'' open a sql-like database by loading an external module, a. la. rdb and ''multiaccess:''. This option would not be implemented in the initial release, but the ''extern:'' keyword would be reserved for future use.
'''extern:'''''directory'' open a sql-like database by loading an external module, a. la. rdb and ''multiaccess:''. This option would not be implemented in the initial release, but the ''extern:'' keyword would be reserved for future use.


Plain directory spec. For binary compatibility, the plain directory spec as the same as '''dbm:'''''directory'' unless overridden with the NSS_DEFAULT_DATABASE environment variable. Applications will not need to change for this release of NSS. (particularly unfriendly applications that want to tweak with the actual database file). Users can force older applications to share the database with the environment variable. The environment variable only affects non-tagged directories.  
Plain directory spec. For binary compatibility, the plain directory spec as the same as '''dbm:'''''directory'' unless overridden with the NSS_DEFAULT_DB_TYPE environment variable. Applications will not need to change for this release of NSS. (particularly unfriendly applications that want to tweak with the actual database file). Users can force older applications to share the database with the environment variable. The environment variable only affects non-tagged directories.  


When accessing the '''dbm:''' and '''multiaccess:''' directories, external shared library will be loaded which knows how to handle these legacy databases. This allows us to move much of the current mapping code into this shared library.
When accessing the '''dbm:''' and '''multiaccess:''' directories, external shared library will be loaded which knows how to handle these legacy databases. This allows us to move much of the current mapping code into this shared library.
Line 402: Line 404:
     minor changes to Init,  
     minor changes to Init,  
     Changes to code that updates trust values or imports certificates with  
     Changes to code that updates trust values or imports certificates with  
         trust.
         trust. ###kaie please clarify what existing code must get changed


====== Mode 3 ======
====== Mode 3 ======
Line 416: Line 418:
     minor changes to Init,  
     minor changes to Init,  
     Changes to code that updates trust values or imports certificates with  
     Changes to code that updates trust values or imports certificates with  
         trust.
         trust. ###kaie please clarify what existing code must get changed
     Changes to aid in update
     Changes to aid in update


Line 444: Line 446:
#The database is password protected and the user never logs into the token during the lifetime of the application.
#The database is password protected and the user never logs into the token during the lifetime of the application.


Applications can avoid final case of failure by forcing the user to authenticate to softoken using PK11_Authenticate().
Applications can avoid that third failure case by forcing the user to authenticate to softoken using PK11_Authenticate().


<pre>
<pre>
Line 464: Line 466:


====== Mode 3A ======
====== Mode 3A ======
Mode 3A 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. Below is the steps a Mode 3A application should use whenever initializing NSS.
Mode 3A Applications are the most complicated. NSS provides some services to help applications get through an update and merge with the least interaction with the user of the application. The steps a Mode 3A application should use whenever initializing NSS are listed below.


Step 0: Preparation: collect the directory and prefix names of both the source and target DBs.  Prepare two strings for the operation:
Step 0: Preparation: collect the directory and prefix names of both the source and target databases.  Prepare two strings for the operation:
# <nowiki>A string to uniquely identify the source DB, for the purpose of
# <nowiki>A string to uniquely identify the source database, for the purpose of
avoiding a repeat of this merge (making the merge idempotent).  This
avoiding a repeat of this merge (making the merge idempotent).  This
string could be derived from the name of the application that used the
string could be derived from the name of the application that used the
source DB, from any application "instance" names (such as profile
source database, from any application "instance" names (such as profile
names), from the absolute path name of the source DB directory and the
names), from the absolute path name of the source database directory and the
DB prefixes, and from the last modification time of the source DBs.</nowiki><br><br><nowiki>
database prefixes, and from the last modification time of the source databases.</nowiki><br><br><nowiki>
The algorithm for deriving this string should always produce the same
The algorithm for deriving this string should always produce the same
result for the same set of source files, so that the code can detect a
result for the same set of source files, so that the code can detect a
second or subsequent attempt to merge the same source file into the
second or subsequent attempt to merge the same source file into the
destination file.</nowiki><br><br><nowiki>
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><br>
Note: The purpose of this string is to prevent multiple updates from the same old database. This merge sequence is meant to be sufficiently light weight that applications can safely call it each time they initialize.</nowiki><br>
# <nowiki>A string that will be the name of the removable PKCS#11 token that
# <nowiki>A string that will be the name of the removable PKCS#11 token that
will represent the source DB.  This string must follow the rules for a
will represent the source database.  This string must follow the rules for a
valid token name and must not contain any colon (:) characters.</nowiki>
valid token name and must not contain any colon (:) characters.</nowiki>


Step 1: Call NSS_InitWithMerge, passing as arguments the destination
Step 1: Call NSS_InitWithMerge, passing as arguments the destination
directory name, destination file name prefix, source directory name,
directory name, destination file name prefix, source directory name,
source file name prefix, unique source DB identifier string, and source
source file name prefix, unique source database identifier string, and source
token name string.
token name string.


Line 490: Line 492:
* Otherwise proceed to step 2.
* Otherwise proceed to step 2.


Step 2: Determine if a merge is even necessary. If a merge is necessary,
Step 2: Determine if a merge is necessary. If a merge is necessary,
NSS will set the slot to a 'removable slot'. You can use PK11_IsPerm to
NSS will set the slot to a 'removable slot'. You can use PK11_IsRemovable to
test for this.
test for this.


* If the DB slot token is not removable, then no update/merge is necessary, goto step 7.
* If the database slot token is not removable, then no update/merge is necessary, goto step 7.
* (optional) If PK11_NeedLogin() is not true then NSS has already completed the merge for you (no passwords were needed), skip to step 7.
* (optional) If PK11_NeedLogin() is not true then NSS has already completed the merge for you (no passwords were needed), skip to step 7.
* Otherwise it is necessary to authenticate to the source token, at step 3 below.
* Otherwise it is necessary to authenticate to the source token, at step 3 below.
Line 502: Line 504:


# <nowiki>(optional) Call PK11_GetTokenName to get the name of the token.  With
# <nowiki>(optional) Call PK11_GetTokenName to get the name of the token.  With
that 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>
that 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 or user 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 some 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.
#* If the token name does not match the token name skip to step 5.
#* Otherwise proced to step 3.2.
#* Otherwise proced to the next substep.
# <nowiki>Call PK11_Authenticate() to authenticate to the source token.  This
# <nowiki>Call PK11_Authenticate() to authenticate to the source token.  This
step is likely to call the application-supplied PKCS11 password callback
step is likely to call the application-supplied PKCS11 password callback
Line 511: Line 513:
#*Otherwise, continue with step 4.
#*Otherwise, continue with step 4.


Step 4.  Determine if it is necessary to authenticate to the target DB.
Step 4.  Determine if it is necessary to authenticate to the target database.
This is done by calling PK11_IsLoggedIn for the DB slot.
This is done by calling PK11_IsLoggedIn for the database slot.
*If the function indicates that the DB token is NOT logged in, then it is necessary to authenticate to the target DB, with the step 5 below.
*If the function indicates that the database token is NOT logged in, then it is necessary to authenticate to the target database, with the step 5 below.
*(optional) Otherwise skip down to step 7.
*(optional) Otherwise skip down to step 7.


Step 5. Call PK11_IsPresent().  You may think of this step as telling
Step 5. Call PK11_IsPresent().  You may think of this step as telling
you if the removable source token has been removed and the target token
you if the removable source token has been removed and the target token
has been inserted into the DB slot.  In reality, this call makes those
has been inserted into the database slot.  In reality, this call makes those
things happen.  After this call succeeds the token name should be that
things happen.  After this call succeeds the token name should be that
of the target token (see next step).
of the target token (see next step).
Line 528: Line 530:
callback function to retrieve the password.
callback function to retrieve the password.


* If this step fails: stop.  A Failure at this point is described below as "Exception B".
* If this step fails: stop.  A failure at this point is described below as "Exception B".
* Otherwise, continue with step 7.
* Otherwise, continue with step 7.


Line 535: Line 537:
====== Failures and recovery ======
====== Failures and recovery ======


Exception A. Application needs to decide what happens if the legacy password
Exception A. Failure to authenticate to the source database
 
Application needs to decide what happens if the legacy password
is not supplied. Application can choose to:  
is not supplied. Application can choose to:  
# continue to use the legacy DB and try to update later. (Probably a future restart of the application).
# continue to use the legacy database and try to update later. (Probably a future restart of the application).
# reset the legacy database, throwing away any private or secret keys in the old database.
# reset the legacy database password, discarding any private or secret keys in the old database.
# shutdown NSS and initialize it only with the new shareable database.
# shutdown NSS and initialize it only with the new shareable database.
: The exact strategy for recovering is application dependent and depends on factors like
:# the sensitivity of the application to loosing key data.
:# possible input from the user.
:# the likelihood that the password will every be recovered.


Exception B. Applications needs to decide what happens if the new shareable DB
: The exact strategy for recovering is application dependent and depends on factors such as:
:* the sensitivity of the application to losing key data.
:* possible input from the user.
:* the likelihood that the password will every be recovered.
 
Exception B. Failure to authenticate to the target database
 
Applications needs to decide what happens if the new shareable database
password is not supplied. Application can choose to:
password is not supplied. Application can choose to:
# continue to use the legacy DB and try to update later.
# continue to use the legacy database and try to update later.
# force NSS to update those objects it can from the legacy DB,throwing away private keys and saved passwords, and trust information from the legacy DB.
# force NSS to update those objects it can from the legacy database, throwing away private keys and saved passwords, and trust information from the legacy database.
# force NSS to reset the shareable database password, throwing away private keys and saved passwords, and trust information from the shareable DB.
# force NSS to reset the shareable database password, throwing away private keys and saved passwords, and trust information from the shareable database.


Notes:
Notes:
Line 556: Line 563:
step 7; that is, during the call to NSS_InitWithMerge or during either
step 7; that is, during the call to NSS_InitWithMerge or during either
of the calls to PK11_Authenticate.  This will depend on the ability of
of the calls to PK11_Authenticate.  This will depend on the ability of
the code to open the necessary DBs, the presence or absence of passwords
the code to open the necessary databases, the presence or absence of passwords
on the DBs, and if both have passwords, it will depend on whether they
on the databases, and if both have passwords, it will depend on whether they
have the same password or different passwords, and when the
have the same password or different passwords, and when the
authentication attempts, if any, succeed. The system tries to complete the
authentication attempts, if any, succeed. The system tries to complete the
merge as soon as it is able, to increase reliability of the merge update actually completing. Therefore API does not make it
merge as soon as it is able, to increase reliability of the merge update actually completing. The API does not make it
possible to predict, accurately, which step will actually perform the
possible to predict, accurately, which step will actually perform the
merge.  The application must try it and see if it cares. Since multiple calls to PK11_Authenticate() do not hurt, the application can simply follow each step in order, and failing only on bad returns from PK11_Authenticate. (PK11_Authenticate will automatically return without prompting, so applications that just need to update (without necessarily caring which step the update completes)).
merge.  The application can only follow the steps. Since multiple calls to PK11_Authenticate() do not hurt, the application can simply follow each step in order, and fail only on bad returns from PK11_Authenticate. (PK11_Authenticate will automatically return without prompting, so applications that just need to merge, without caring which step does the merge, may do so.)


2. If the attempt to open the
2. If the attempt to open the
source DB fails for any reason, the operation will behave as if the
source database fails for any reason, the operation will behave as if the
source DB was empty.  It will record the unique source DB identifier
source database was empty.  It will record the unique source database identifier
string 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 recover from this.
string in the target database and act as if the merger is complete. This is similar to what happens in all previous versions of NSS during database update. See "Database Merge" below for how to recover from this.
<pre>
<pre>
     /*
     /*
Line 584: Line 591:
       * Step 2: Determine if update/merge is needed.
       * Step 2: Determine if update/merge is needed.
       */  
       */  
     if (!PK11_IsPerm(slot) && !PK11_NeedLogin(slot)) {
     if (PK11_IsRemovable(slot) && PK11_NeedLogin(slot)) {
         /* need to update/Merge the database */
         /* need to update/Merge the database */
         /*
         /*
Line 641: Line 648:
       * Step 2: Determine if update/merge is needed.
       * Step 2: Determine if update/merge is needed.
       */  
       */  
     if (!PK11_IsPerm(slot)) {
     if (PK11_IsRemovable(slot)) {
/* need to update/Merge the database */
/* need to update/Merge the database */
/*
/*
Line 675: Line 682:
In Mode 1, NSS never needs to do an update or a merge.  
In Mode 1, NSS never needs to do an update or a merge.  


<pre>
  State machine of NSS update actions for Mode 1:
  State machine of NSS update actions for Mode 1:


Line 684: Line 692:
                   V
                   V
                 done
                 done
</pre>


In Mode 2, the new database is uninitialized, so NSS only needs the
In Mode 2, the new database is uninitialized, so NSS only needs the
Line 699: Line 708:
the old database on future opens until the update succeeds.
the old database on future opens until the update succeeds.


<pre>
   State machine of NSS update actions for Mode 2:
   State machine of NSS update actions for Mode 2:
          
          
Line 739: Line 749:
                   V
                   V
                 done
                 done
------------------------------------------
</pre>
 
<pre>
             PK11_Authenticate
             PK11_Authenticate
                   |
                   |
Line 758: Line 770:
                   V
                   V
                 done
                 done
 
</pre>         
               
 


In Mode 3, the new database may or may not be initialized. For the first mode 3
In Mode 3, the new database may or may not be initialized. For the first mode 3
Line 776: Line 786:
database. The application must be able to tell us where the old database lives,
database. The application must be able to tell us where the old database lives,
since it's an application private directory compared the the multiple  
since it's an application private directory compared the the multiple  
application shared directory that the shared DB lives in.
application shared directory that the shared database lives in.


<pre>
   Flow chart of NSS update actions for Mode 3:
   Flow chart of NSS update actions for Mode 3:


Line 827: Line 838:
                   V
                   V
                 done
                 done
</pre>


---------------------------------------------------------------
<pre>
 
               PK11_Authenticate
               PK11_Authenticate
                       |
                       |
Line 864: Line 875:
                   V
                   V
                 done
                 done
</pre>


===== Merge Conflicts (Mode 3A only) =====
===== Merge Conflicts (Mode 3A only) =====


When merging databases in, it's possible (even likely), that the shared  
When merging databases in, it's possible (even likely), that the shared  
database and legacy DB's have the same objects. In the case of certs and keys,
database and legacy databases have the same objects. In the case of certs and keys,
the merge is a simple matter of identifying duplicates and not updating them.
the merge is a simple matter of identifying duplicates and not updating them.
In the case of trust attributes, however, there are a number of choices:
# don't update duplicate trust (shared database copy wins).
# overwrite trust from the legacy DB (legacy db copy wins).
# calculate the least common denominator trust between them (take the least trusted values). (turning off trust wins).
# calculate the most common demonimnator trust between the two (turning on trust wins).
From the user perspective, each of these choices means:
# after the update the application that just updated may trust certs that it had previously marked untrusted, or certs that it has marked trusted are no longer trusted.
# after the update other applications that share the database may trust certs they had previously marked untrusted, or certs that they had marked as trusted are no longer trusted.
# after the update all apps may find the certs that they marked trust are no longer trusted.
# after the update all apps may find that they trust certs that have  previously been marked untrusted.
Option 3 is the most secure, Option 4 will break have less breakage. Trust
merge conflicts that are real conflicts (application 'A' turned off trust and
application 'B' turned on trust) are expected to be rare. The common case would
be application 'A' turned on SSL trust and application 'B' turned on email
trust. In this case Option 4 is clearly the correct choice.


From a programming point of view, NSS should pick a default and implement it.
Trust records are made up of several entries, such as one for SSL Server Auth, SSL Client Auth, S/MIME, etc. Each entry could have several values, including CKT_NSS_MUST_VERIFY, CKT_NSS_TRUSTED_DELEGATOR, CKT_NSS_TRUSTED, CKT_NSS_VALID, etc).
Ideally no user interaction will occur.


Finally password entries are merge issues. If the two databases have different
Merge updates the trust records by the entries in that trust record separately:
passwords, the merged database will have to have a
# if the trust record entries are identical, no update is done.
# if either trust record entry has an explicit unknown (CKT_NSS_TRUST_UNKNOWN) or invalid trust record entry (entry does not exist), then the one that is valid and known is used.
# if one of the trust record entries has hard trust attributes (Trust flags with NSS_TRUSTED or NSS_UNTRUSTED in the name) and the other has soft attributes (NSS_VALID or NSS_MUST_VERIFY) the entry with hard attributes is used. Hard trust attributes are attributes that will terminate a certificate validation.
# if non of these cases apply, then the value in the target database is preserved.


===== Mozilla Applications =====
===== Mozilla Applications =====
Line 929: Line 925:
to do user interaction below.
to do user interaction below.


If the legacy db for the mozilla app has a master password set, we prompt for  
If the legacy database for the mozilla app has a master password set, we prompt for  
it. This prompt must be clear we are asking for the master password for  
it. This prompt must be clear we are asking for the master password for  
the running Mozilla app (Thunderbird, Firefox, Seamonkey, etc).
the running Mozilla app (Thunderbird, Firefox, Seamonkey, etc).




  Exception case A
:Exception case A


  If we fail to get this password, we need to handle the exception A case.
:If we fail to get this password, we need to handle the exception A case. If the user has a master password set, but does not know what the master password is, then the following data is lost for sure:
  If the user has a master password set, but does not know what the master
  password is, then the following data is lost for sure:


    The user's private keys.
:* The user's private keys.
    The user's secret keys.
:* The user's secret keys.
    Any data encrypted to the private keys.
:* Any data encrypted to the private keys.
    Any data encrpted with the secret keys.
:* Any data encrpted with the secret keys.


  I believe we can identify if the private keys are associated with a  
:I believe we can identify if the private keys are associated with a certificate. If so, then we can tell the user what certificate would no longer work. Data encrypted with the private keys in Mozilla products are currently only email messages. Secret keys encrypt saved passwords. The Mozilla app knows which saved passwords are encrypted with that key.
  certificate. If so, then we can tell the user what certificate would no  
  longer work. Data encrypted with the private keys in Mozilla products are  
  currently only email messages. Secret keys encrypt saved passwords. The  
  Mozilla app knows which saved passwords are encrypted with that key.


If we hit Exception case A we can do one of the following:
:If we hit Exception case A we can do one of the following:


1) attempt to just update the certs, trust, crl and s/mime records, skipping
:# attempt to just update the certs, trust, crl and s/mime records, skipping the all the keys. We would loose all the data described above.
the all the keys. We would loose all the data described above.
:# decide not to update. In this case we would loose all the data in the paragraph above as well as all the certs, trust crl and s/mime records.
2) decide not to update. In this case we would loose all the data in the  
:# run with the legacy database and allow the user to update later.
paragraph above as well as all the certs, trust crl and s/mime records.
:# run with the new shared database and allow the user to update later.
3) run with the legacy database and allow the user to update later.
4) run with the new shared database and allow the user to update later.


I would suggest we only offer the user the choice of 1 or 4. Note: if the user
:I would suggest we only offer the user the choice of 1 or 4. Note: if the user selects 1, the update  could fail again in exception case B. From a UI perspective, we may want to handle exception case B as we handle case A so the user is only asked once about forcing an update while losing data.
selects 1, the update  could fail again in exception case B. From a UI  
perspective, we may want to handle exception case B as we handle case A so
the user is only asked once about forcing an update while losing data.


 
Once we have a legacy database password, or if we determine we don't need the legacy
Once we have a legacy db password, or if we determine we don't need the legacy
database password (either because there isn't one, or because we are willing to loose
db password (either because there isn't one, or because we are willing to loose
the data that was protected by it). We need to acquire the shareable database's  
the data that was protected by it). We need to acquire the shareable db's  
password so we can encrypt and MAC the data properly. If the shareable database doesn't
password so we can encrypt and MAC the data properly. If the shareable db doesn't
have a password we can proceed with the update without further prompting the
have a password we can proceed with the update without further prompting the
user. If the shareable db has the same password as the legacy db, then we can  
user. If the shareable database has the same password as the legacy database, then we can  
detect that and again proceed with the update without further prompting.
detect that and again proceed with the update without further prompting.


Line 985: Line 969:




Exception case B  
:Exception case B  


If we fail to get this password, we need to handle the exception B case.
:If we fail to get this password, we need to handle the exception B case. If the user has a master password set on his shareable database, but does not know what that master password is, we now have the following choices:
If the user has a master password set on his shareable database, but does not  
know what that master password is, we now have the following choices:


1) eshew any private keys, secret keys and trust updates from the  
:# eshew any private keys, secret keys and trust updates from the legacy database.
legacy database.
:# reset the password on the shareable database (losing all private and secret keys, possibly losing some trust).
2) reset the password on the shareable database (losing all private and secret
:# run with the legacy database and allow the user to update later.
keys, possibly losing some trust).
:# run with the new shareable database and allow the user to update later.
3) run with the legacy database and allow the user to update later.
4) run with the new shareable database and allow the user to update later.


It seems pretty unlikely that the user truly does not know the shareable database
:It seems pretty unlikely that the user truly does not know the shareable database password, since he had to create or set it recently. However as the deployment time increases, this becomes more likely.
password, since he had to create or set it recently. However as the deployment
time increases, this becomes more likely.


Again, I think giving the user a choice between options 1) and 4) are the
:Again, I think giving the user a choice between options 1) and 4) are the best alternatives. If the user had already tripped over Exception case A, we can presume the user intends to make a similiar choice here. Case 2 can be handled later under the same way the user handles a forgotten master password today (only now resetting the master password affects all mozilla apps).
best alternatives. If the user had already tripped over Exception case A, we
can presume the user intends to make a similiar choice here. Case 2 can be
handled later under the same way the user handles a forgotten master password
today (only now resetting the master password affects all mozilla apps).




Line 1,012: Line 986:


Mozilla apps can create more than one profile. Developers use this capability  
Mozilla apps can create more than one profile. Developers use this capability  
to test bugs that new users are likely to run into without loosing their own  
to test bugs that new users are likely to run into without losing their own  
production environment.
production environment.


Line 1,021: Line 995:
couple of options.
couple of options.


# Allow profiles to be marked with 'private key/cert DB's. This will change The Mozilla app from a Mode 3A app to a Mode 2A app. This will return developers to their previous semantic if they want, while allowing them to also test the interaction of different profiles and the same database. It would require UI changes to the profile manager, and it will require action on the part of the developer to get back to the old semantic.
# Allow profiles to be marked with 'private key/cert databases. This will change The Mozilla app from a Mode 3A app to a Mode 2A app. This will return developers to their previous semantic if they want, while allowing them to also test the interaction of different profiles and the same database. It would require UI changes to the profile manager, and it will require action on the part of the developer to get back to the old semantic.
# Treat only the default profile as Mode 3A and all other profiles as Mode 2A. This will allow profile separation to operate as is today with no changes. It does mean, however, that only default profiles will share keys with application.
# Treat only the default profile as Mode 3A and all other profiles as Mode 2A. This will allow profile separation to operate as is today with no changes. It does mean, however, that only default profiles will share keys with application.
# Provide the checkbox in option 1, but make it default as in option 2.
# Provide the checkbox in option 1, but make it default as in option 2.
Line 1,037: Line 1,011:
# Because merge does not require the complicated state machine to manage password acquisition, it can (and is) implemented outside the softoken itself.
# Because merge does not require the complicated state machine to manage password acquisition, it can (and is) implemented outside the softoken itself.


Characteristic 3 allows database merge to work on arbitrary database types. You can merge a shareable db into a shareable db as well as an old database into a shareable db (in fact, to a point, on arbitrary tokens - you can merge a hardware token into a shareable db as long as the keys are extractable).
Characteristic 3 allows database merge to work on arbitrary database types. You can merge a shareable database into a shareable database as well as an old database into a shareable database (in fact, to a point, on arbitrary tokens - you can merge a hardware token into a shareable database as long as the keys are extractable).


To merge 2 databases, the application simply opens the both databases and calls the new PK11_MergeTokens() call. PK11_MergeTokens() has the following signature:
To merge 2 databases, the application simply opens both databases (using SECMOD_OpenUserDB) and then calls the new PK11_MergeTokens() function. PK11_MergeTokens() has the following signature:


  #include <pk11pub.h>
<pre>
  #include "pk11pub.h"


  SECStatus PK11_MergeTokens(
  SECStatus PK11_MergeTokens(
Line 1,048: Line 1,023:
     PK11MergeLog *log,
     PK11MergeLog *log,
     void *pwdata);
     void *pwdata);
</pre>


Parameters:
Parameters:
Line 1,059: Line 1,035:
''pwdata'' password arg
''pwdata'' password arg


The ''targetSlot'' and ''sourceSlot'' parameters could be slots that are simply looked up, or additional databases opened with SECMOD_OpenUserDB(). In order for the merge to be successful, ''targetSlot'' must support all the intersection of the following object list and the token objects in the ''sourceSlot'' (CKO_CERTIFICATE, CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, CKO_SECRET_KEY, CKO_NSS_TRUST, CKO_NSS_CRL, CKO_NSS_SMIME). The source Slot must also have extractable keys or the merge will fail (sensitive keys are OK, as long as the source slot supports PBE's if it contains private keys). All softoken slots (including those opened with SECMOD_OpenUserDB()) support these charateristics.
The ''targetSlot'' and ''sourceSlot'' parameters could be slots that are simply looked up, or additional databases opened with SECMOD_OpenUserDB(). In order for the merge to be successful, ''targetSlot'' must support all the object types in the following list for which token objects exist in the ''sourceSlot'':
* CKO_CERTIFICATE,  
* CKO_PUBLIC_KEY,  
* CKO_PRIVATE_KEY,  
* CKO_SECRET_KEY,  
* CKO_NSS_TRUST,  
* CKO_NSS_CRL,  
* CKO_NSS_SMIME.  
The source Slot must also have extractable keys or the merge will fail (sensitive keys are OK, as long as the source slot supports PBE's if it contains private keys). All softoken slots (including those opened with SECMOD_OpenUserDB()) support these charateristics.


Multiple calls to merge will only attempt to merge those objects which were created since the last merge, or failed to merge in the last call to merge.
Multiple calls to merge will only attempt to merge those objects which were created since the last merge, or failed to merge in the last call to merge.
Line 1,118: Line 1,102:


* directory full path to where the database lives.
* directory full path to where the database lives.
* certPrefix a prefix string to add in front of the key and cert db (if keyPrefix is null), null means add no prefix.
* certPrefix a prefix string to add in front of the key and cert database names (if keyPrefix is null), null means add no prefix.
* keyPrefix a prefix string to add in front of the key db. Null means use the same prefix as the cert db.
* keyPrefix a prefix string to add in front of the key database name. Null means use the same prefix as the cert database name uses.
* cert_version current version is the current database version
* cert_version current version is the current database version
* key_version is the current key database version
* key_version is the current key database version
Line 1,132: Line 1,116:
The returned SDB structure has the following format:
The returned SDB structure has the following format:


<pre>
  typedef struct SDBStr SDB;
  typedef struct SDBStr SDB;


Line 1,160: Line 1,145:
     CK_RV (*sdb_Close)(SDB *sdb);
     CK_RV (*sdb_Close)(SDB *sdb);
  };
  };
</pre>


where:
where:


* private is a pointer to opaque private data specific to the Shareable DB implementation.
* private is a pointer to opaque private data specific to the Shareable database implementation.
* sdb_type is the type of database (key [aka private] or cert [aka public]).
* sdb_type is the type of database (key [aka private] or cert [aka public]).
* sdb_flags specifies how the database was opened (ReadOnly, Create, etc).
* sdb_flags specifies how the database was opened (ReadOnly, Create, etc).
Line 1,276: Line 1,262:
==== legacy DB support ====
==== legacy DB support ====


The old dbm code can be supported with the above SDB structure with the following exceptions:
The old DBM code can be supported with the above SDB structure with the following exceptions:


# The old db code cannot be extensible (can't dynamically handle new types).
# The old database code cannot be extensible (can't dynamically handle new types).
# A private interface may be needed to unwrap the private keys, or provide a handle to the password so the keys can be presented in the attribute format.
# A private interface may be needed to unwrap the private keys, or provide a handle to the password so the keys can be presented in the attribute format.


Line 1,285: Line 1,271:
* legacy_ReadSecmodDB, legacy_ReleaseSecmodDBData, legacy_DeleteSecmodDB, legacy_AddSecmodDB - These functions provide access to the old secmod databases.
* legacy_ReadSecmodDB, legacy_ReleaseSecmodDBData, legacy_DeleteSecmodDB, legacy_AddSecmodDB - These functions provide access to the old secmod databases.
* legacy_Shutdown - This is called when NSS is through with all database support (that is when softoken shuts down).
* legacy_Shutdown - This is called when NSS is through with all database support (that is when softoken shuts down).
* legacy_SetCryptFunctions - This is used to set some callbacks that the legacy db can call to decrypt and encrypt password protected records (pkcs8 formatted keys, etc.). This allows the legacy database to translate it's database records to the new format without getting direct access to the keys.
* legacy_SetCryptFunctions - This is used to set some callbacks that the legacy database can call to decrypt and encrypt password protected records (pkcs8 formatted keys, etc.). This allows the legacy database to translate it's database records to the new format without getting direct access to the keys.


NSS will automatically load the legacy database support under the following conditions:
NSS will automatically load the legacy database support under the following conditions:
Jcjones
122

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/84354...1191032"