The Tor Browser: security/nss/lib/pki/doc/standoc.html@7e26c7da4463 (annotated)

security/nss/lib/pki/doc/standoc.html@7e26c7da4463 (annotated)

security/nss/lib/pki/doc/standoc.html

Wed, 31 Dec 2014 06:55:50 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:55:50 +0100
changeset 2: 7e26c7da4463
permissions: -rw-r--r--

Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 <!-- This Source Code Form is subject to the terms of the Mozilla Public
    - License, v. 2.0. If a copy of the MPL was not distributed with this
    - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
   <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
   <title>Stan Design - Work In Progress</title>
 </head>
   <body>
  <br>
                This is a working document for progress on Stan design/development.<br>
  <br>
         Current <a href="#build">build</a>
        and <a href="#test">test</a>
         instructions.<br>
  <br>
                       The current set of Stan libraries.<br>
  <a href="#asn1">asn1</a>
  <br>
  <a href="#base">base</a>
  <br>
  <a href="#ckfw">ckfw</a>
  <br>
  <a href="#dev">dev</a>
  <br>
  <a href="#pki">pki</a>
  <br>
  <a href="#pki1">pki1</a>
  <br>
  <a href="#pkix">pkix</a>
  <br>
  <br>
                      "Public" types below (those available to consumers of
  NSS)   begin    with   "NSS".  &nbsp;"Protected" types (those only available
  within   NSS)   begin   with  "nss".<br>
  <br>
         Open issues appears as numbered indents.<br>
  <br>
  <br>
 <hr width="100%" size="2" align="Left"><br>
 <h3><a name="asn1"></a>
  <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/asn1/">
            ASN.1</a>
  </h3>
                           ASN.1 encoder/decoder wrapping around the current
  ASN.1    implementation.<br>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASN1EncodingType">  NSSASN1EncodingType</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Item">nssASN1Item</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Template">nssASN1Template</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1ChooseTemplateFunction">
                      nssASN1ChooseTemplateFunction</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Encoder">nssASN1Encoder</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Decoder">nssASN1Decoder</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncodingPart">  nssASN1EncodingPart</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1NotifyFunction">
        nssASN1NotifyFunction</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncoderWriteFunction">
                      nssASN1EncoderWriteFunction</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1DecoderFilterFunction">
                      nssASN1DecoderFilterFunction</a>
  <br>
  <br>
 <hr width="100%" size="2" align="Left">
 <h3><a name="base"></a>
  <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/base/">
        Base</a>
  </h3>
                           Set of base utilities for Stan implementation.
 &nbsp;These       are   all   fairly straightforward, except for nssPointerTracker.<br>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSError">NSSError</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSArena">NSSArena</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSItem">NSSItem</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBER">NSSBER</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSDER">NSSDER</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBitString">NSSBitString</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUTF8">NSSUTF8</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASCII7">NSSASCII7</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssArenaMark">nssArenaMark</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssPointerTracker">nssPointerTracker</a>
  <br>
           This is intended for debug builds only.<br>
 <ol>
    <li>Ignored for now.<br>
    </li>
 </ol>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssStringType">nssStringType</a>
  <br>
  <br>
           Suggested additions:<br>
 <ol>
    <li>nssList - A list that optionally uses a lock. &nbsp;This list  would
    manage the currently loaded modules in a trust domain, etc.</li>
   <ul>
      <li>SECMODListLock kept track of the number of waiting threads.  &nbsp;Will
   this be needed in the trust domain?</li>
   </ul>
 </ol>
  <br>
 <hr width="100%" size="2" align="Left">
 <h3><a name="ckfw"></a>
  <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/">
   CKFW</a>
  </h3>
                      The cryptoki framework, used for building cryptoki tokens.
    &nbsp;This      needs  to be described in a separate document showing how
    to set up a  token    using  CKFW. &nbsp;This code only relates to tokens,
    so it is not  relevant    here.<br>
  <br>
  <br>
 <hr width="100%" size="2" align="Left">
 <h3><a name="dev"></a>
  <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/dev/">
  Device</a>
  </h3>
                           Defines cryptoki devices used in NSS. &nbsp;This
  is  not   part  of the exposed API. &nbsp;It is a low-level API allowing
 NSS to manage   cryptoki  devices.<br>
  <br>
          The relationship is like this:<br>
  <br>
          libpki --&gt; libdev --&gt; cryptoki<br>
  <br>
          As an example,<br>
  <br>
          NSSTrustDomain_FindCertificate --&gt; NSSToken_FindCertificate --&gt;
    C_FindObjects<br>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSModule">NSSModule</a>
  <br>
                      Replaces the SECMOD API. &nbsp;The module manages a
 PRLibrary       that   holds  a cryptoki implementation via a number of slots.
 &nbsp;The      API should   provide  the ability  to Load and Unload a module,
 Login  and    Logout to the   module (through its slots), and to locate a
 particular   slot/token.<br>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSlot">NSSSlot</a>
  <br>
                      This and NSSToken combine to replace the PK11 API parts
   that   relate    to  slot  and token management. &nbsp;The slot API should
   provide   the ability   to Login/Logout   to a slot, check the login status,
   determine    basic configuration    information   about the slot, and modify
   the password    settings.<br>
 <ol>
    <li>Should slots also maintain a default session? &nbsp;This session would
  be used for slot management calls (sections 9.5 and9.6 of PKCS#11). &nbsp;Or
  is the token session sufficient (this would not work if C_GetTokenInfo and
  C_InitToken need to be wrapped in a threadsafe session).<br>
    </li>
 </ol>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSToken">NSSToken</a>
  <br>
                      Fills in the gaps left by NSSSlot. &nbsp;Much of the
 cryptoki     API   is  directed   towards slots.  &nbsp;However,   some  functionality
    clearly belongs with a token type. &nbsp;For  example,   a certificate
  lives  on a token, not a slot, so one would expect  a function   NSSToken_FindCertificate.
     &nbsp;Thus functions that deal with  importing/exporting   an object
 and    performing  actual cryptographic operations  belong here.<br>
 <ol>
    <li>The   distinction  between a slot and a token is not clear. &nbsp;Most
    functions take  a slotID   as an argument,  even though it is obvious that
      the event   is intended to occur on a token. &nbsp;That leaves various
    possibilities:</li>
   <ol>
      <li>Implement the API entirely as NSSToken. &nbsp;If the token  is not
   present, some calls will simply fail.</li>
      <li>Divide the API between NSSToken and NSSSlot, as described  above.
 &nbsp;NSSSlot  would handle cryptoki calls specified as "slot management",
   while NSSToken  handles actual token operations.</li>
      <li>Others?</li>
   </ol>
    <li>Session management. &nbsp;Tokens needs a threadsafe session handle
  to perform operations. &nbsp;CryptoContexts are meant to provide such sessions,
  but other objects will need access to token functions as well (examples:
 the TrustDomain_Find functions, _Login, _Logout, and others that do not exist
  such as NSSToken_ChangePassword). &nbsp;For those functions, the token could
  maintain a default session. &nbsp;Thus all NSSToken API functions would take
  sessionOpt as an argument. &nbsp;If the caller is going to provide a session,
  it sends an NSSSession there, otherwise it sends NULL and the default session
  is utilized.<br>
    </li>
 </ol>
       Proposed:<br>
     NSSSession<br>
     Wraps a Cryptoki session. &nbsp;Created from a slot. &nbsp;Used to manage
   sessions for crypto contexts. &nbsp;Has a lock field, which locks the session
   if the slot is not threadsafe.<br>
  <br>
 <hr width="100%" size="2" align="Left"><br>
 <h3><a name="pki"></a>
  <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/">
    PKI</a>
  </h3>
                           The NSS PKI library.<br>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">NSS</a>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">Certificate</a>
  <br>
 <ol>
    <li>The API leaves open the possibility of NSSCertificate meaning  various
  certificate types, not just X.509. &nbsp;The way to keep open this  possibility
  is to keep only generally useful information in the NSSCertificate  type.
 &nbsp;Examples would be the certificate encoding, label, trust (obtained
  from cryptoki calls), an email address, etc. &nbsp;Some type of generic
 reference  should be kept to the decoded certificate, which would then be
 accessed by  a type-specific API (e.g., NSSX509_GetSubjectName).</li>
 </ol>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUserCertificate">NSSUserCertificate</a>
  <br>
 <ol>
    <li>Should this be a typedef of NSSCertificate?&nbsp; This implies  that
  any function that requires an   NSSUserCertificate   would fail when  called
  with a certificate lacking a private key. </li>
 </ol>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPrivateKey">NSSPrivateKey</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPublicKey">NSSPublicKey</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSymmetricKey">NSSSymmetricKey</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTrustDomain">NSSTrustDomain</a>
  <br>
                     A trust domain is "the field in which certificates may
  be  validated."       &nbsp;It  is a collection of modules capable of performing
   cryptographic      operations  and storing certs and keys. &nbsp;This collection
   is managed     by NSS in a manner opaque to the consumer. &nbsp;The slots
   will have various      orderings determining which has preference for a
 given  operation. &nbsp;For      example, the trust domain may order the storage
  of user certificates one    way, and the storage of email certificates in
  another way [is that a good    example?].<br>
  <br>
 <ol>
    <li>           How will ordering work? &nbsp;We already have the  suggestion
       that  there be two kinds of ordering: storage and search.  &nbsp;How
 will     they be  constructed/managed? &nbsp;Do we want to expose  access
 to a token     that overrides  this ordering (i.e., the download of  updated
 root certs   may  need to override  storage order)</li>
    <li>How are certs cached? &nbsp;Nelson wonders what it means   to   Stan
     when a cert does not live on a token yet. &nbsp;Bob, Terry, and    I discussed
     this. &nbsp;My conclusion is that there should be a type,  separate
 from   NSSCertificate,  that holds the decoded cert parts (e.g.,   NSSX509Certificate,
     or to avoid confusion, NSSX509DecodedParts). &nbsp;NSSCertificate   would
   keep  a handle to this type, so that it only needs to decode the  cert
 once.   &nbsp;The  NSSTrustDomain would keep a hash table of cached certs,
 some of  which may  not live on a token yet (i.e., they are only NSSX509DecodedParts).
      &nbsp;This  cache could be accessed in the same way the temp db was,
 and    when the cert  is ready to be moved onto a token a call to NSSTrustDomain_ImportCertificate
        is made. &nbsp;Note    that this is essentially the same as CERT_TempCertToPerm.</li>
   <ul>
      <li>The hashtable in lib/base (copied from ckfw/hash.c) uses the identity
 hash. &nbsp;Therefore, in a hash of certificates, the key is the certificate
 pointer itself. &nbsp;One possibility is to store the decoded cert (NSSX509DecodedParts
 above) as the value in the {key, value} pair. &nbsp;When a cert is decoded,
 the cert pointer and decoding pointer are added to the hash. &nbsp;Subsequent
 lookups have access to one or both of these pointers. &nbsp;This keeps NSSCertificate
 separate from its decoding, while providing a way to locate it.</li>
   </ul>
    <li>The API is designed to keep token details hidden from the user.  &nbsp;However,
  it has already been realized that PSM and CMS may need special  access to
 tokens. &nbsp;Is this part of the TrustDomain API, or should PSM  and CMS
 be allowed to use "friend" headers from the Token API?</li>
    <li>Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?<br>
    </li>
 </ol>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCryptoContext"><br>
                    NSSCryptoContext</a>
  <br>
     Analgous to a Cryptoki session. &nbsp;Manages session objects only.<br>
   <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTime">NSSTime</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUsage">NSSUsage</a>
  <br>
 <ol>
    <li>       See Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#187">
                comments</a>
               .</li>
 </ol>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPolicies">NSSPolicies</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSAlgorithmAndParameters">
                       NSSAlgorithmAndParameters</a>
  <br>
 <ol>
    <li>       Again, Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#215">
                comments</a>
               . &nbsp;The old NSS code had various types related to  algorithms
     running around in it. &nbsp;We had SECOidTag, SECAlgorithmID,   SECItem's
      for parameters, CK_MECHANISM for cryptoki, etc. &nbsp;This type   should
     be  able to encapsulate all of those.</li>
 </ol>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCallback">NSSCallback</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOperations">NSSOperations</a>
  <br>
  <br>
  <br>
 <hr width="100%" size="2"><br>
  <br>
  A diagram to suggest a possible TrustDomain architecture.<br>
  <br>
  <img src="./standiag.png" alt="Trust Domain Diagram" width="748" height="367">
  <br>
 <hr width="100%" size="2" align="Left"><br>
 <h3><a name="pki1"></a>
  <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki1/">
     PKI1</a>
  </h3>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOID">NSSOID</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSATAV">NSSATAV</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDN">NSSRDN</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDNSeq">NSSRDNSeq</a>
  <br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSName">NSSName</a>
  <br>
             NSSNameChoice<br>
             NSSGeneralName<br>
             NSSGeneralNameChoice<br>
             NSSOtherName<br>
             NSSRFC822Name<br>
             NSSDNSName<br>
             NSSX400Address<br>
             NSSEdiParityAddress<br>
             NSSURI<br>
             NSSIPAddress<br>
             NSSRegisteredID<br>
             NSSGeneralNameSeq<br>
  <a href="http://lxr.mozilla.org/mozilla/ident?i=nssAttributeTypeAliasTable">
             nssAttributeTypeAliasTable</a>
  <br>
  <br>
  <br>
 <hr width="100%" size="2" align="Left"><br>
 <h3><a name="pkix"></a>
  <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pkix/">
        PKIX&nbsp;</a>
  </h3>
            There is a plethora of PKIX related types here.<br>
  <br>
 <hr width="100%" size="2" align="Left"><br>
 <h3><a name="build"></a>
         Building Stan</h3>
  <br>
        From nss/lib, run "make BUILD_STAN=1"<br>
  <br>
 <hr width="100%" size="2" align="Left"><br>
 <h3><a name="test"></a>
        Testing Stan</h3>
        A&nbsp;new command line tool, pkiutil, has been created to use only
  the   Stan API. &nbsp;It depends on a new library, cmdlib, meant to replace
  the   old secutil library. &nbsp;The old library had code used by products
  that   needed to be integrated into the main library codebase somehow. &nbsp;The
    goal of the new cmdlib is to have functionality needed strictly for NSS
  tools.<br>
  <br>
        How to build:<br>
 <ol>
    <li>cd nss/cmd/cmdlib; make</li>
    <li>cd ../pkiutil; make</li>
 </ol>
        pkiutil will give detailed help with either "pkiutil -?" or "pkiutil
  --help".<br>
  <br>
       So far, the only available test is to list certs on the builtins token.
   &nbsp;Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil. &nbsp;Then
   run "pkiutil -L" or "pkiutil --list". &nbsp;The list of certificate nicknames
   should be displayed.<br>
  <br>
  <br>
 </body>
 </html>

The Tor Browser / annotate

security/nss/lib/pki/doc/standoc.html@7e26c7da4463 (annotated)

security/nss/lib/pki/doc/standoc.html