<!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>
