This is a working document for progress on Stan design/development.
 
        Current build
       and test
        instructions.
 
                      The current set of Stan libraries.
 asn1
 
 base
 
 ckfw
 
 dev
 
 pki
 
 pki1
 
 pkix
 
 
                     "Public" types below (those available to consumers of
 NSS)   begin    with   "NSS".   "Protected" types (those only available
 within   NSS)   begin   with  "nss".
 
        Open issues appears as numbered indents.
 
 
 
 
                          ASN.1 encoder/decoder wrapping around the current 
 ASN.1    implementation.
 
   NSSASN1EncodingType
 
 nssASN1Item
 
 nssASN1Template
 
 
                     nssASN1ChooseTemplateFunction
 
 nssASN1Encoder
 
 nssASN1Decoder
 
   nssASN1EncodingPart
 
 
       nssASN1NotifyFunction
 
 
                     nssASN1EncoderWriteFunction
 
 
                     nssASN1DecoderFilterFunction
 
 
 
 
                          Set of base utilities for Stan implementation.
 These       are   all   fairly straightforward, except for nssPointerTracker.
 
 NSSError
 
 NSSArena
 
 NSSItem
 
 NSSBER
 
 NSSDER
 
 NSSBitString
 
 NSSUTF8
 
 NSSASCII7
 
 nssArenaMark
 
 nssPointerTracker
 
          This is intended for debug builds only.
 
   - Ignored for now.
 
nssStringType
 
          Suggested additions:
 
   - nssList - A list that optionally uses a lock.  This list  would 
   manage the currently loaded modules in a trust domain, etc.
     - SECMODListLock kept track of the number of waiting threads.   Will 
  this be needed in the trust domain?
 
 
                     The cryptoki framework, used for building cryptoki tokens. 
    This      needs  to be described in a separate document showing how
   to set up a  token    using  CKFW.  This code only relates to tokens,
   so it is not  relevant    here.
 
 
 
 
                          Defines cryptoki devices used in NSS.  This
 is  not   part  of the exposed API.  It is a low-level API allowing
NSS to manage   cryptoki  devices.
 
         The relationship is like this:
 
         libpki --> libdev --> cryptoki
 
         As an example,
 
         NSSTrustDomain_FindCertificate --> NSSToken_FindCertificate -->
   C_FindObjects
 
 NSSModule
 
                     Replaces the SECMOD API.  The module manages a
PRLibrary       that   holds  a cryptoki implementation via a number of slots.
 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.
 
 NSSSlot
 
                     This and NSSToken combine to replace the PK11 API parts
  that   relate    to  slot  and token management.  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.
 
   - Should slots also maintain a default session?  This session would 
 be used for slot management calls (sections 9.5 and9.6 of PKCS#11).  Or 
 is the token session sufficient (this would not work if C_GetTokenInfo and 
 C_InitToken need to be wrapped in a threadsafe session).
 
 NSSToken
 
                     Fills in the gaps left by NSSSlot.  Much of the 
cryptoki     API   is  directed   towards slots.   However,   some  functionality
   clearly belongs with a token type.  For  example,   a certificate
 lives  on a token, not a slot, so one would expect  a function   NSSToken_FindCertificate.
     Thus functions that deal with  importing/exporting   an object
and    performing  actual cryptographic operations  belong here.
 
   - The   distinction  between a slot and a token is not clear.  Most 
   functions take  a slotID   as an argument,  even though it is obvious that
     the event   is intended to occur on a token.  That leaves various
   possibilities:
     - Implement the API entirely as NSSToken.  If the token  is not 
  present, some calls will simply fail.
- Divide the API between NSSToken and NSSSlot, as described  above. 
 NSSSlot  would handle cryptoki calls specified as "slot management",
  while NSSToken  handles actual token operations.
- Others?
- Session management.  Tokens needs a threadsafe session handle 
 to perform operations.  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).  For those functions, the token could 
 maintain a default session.  Thus all NSSToken API functions would take
 sessionOpt as an argument.  If the caller is going to provide a session,
 it sends an NSSSession there, otherwise it sends NULL and the default session
 is utilized.
 
Proposed:
    NSSSession
    Wraps a Cryptoki session.  Created from a slot.  Used to manage
  sessions for crypto contexts.  Has a lock field, which locks the session
  if the slot is not threadsafe.
 
 
 
                          The NSS PKI library.
 
 NSS
 Certificate
 
 
   - The API leaves open the possibility of NSSCertificate meaning  various 
 certificate types, not just X.509.  The way to keep open this  possibility 
 is to keep only generally useful information in the NSSCertificate  type. 
 Examples would be the certificate encoding, label, trust (obtained
 from cryptoki calls), an email address, etc.  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).
 NSSUserCertificate
 
 
   - Should this be a typedef of NSSCertificate?  This implies  that 
 any function that requires an   NSSUserCertificate   would fail when  called 
 with a certificate lacking a private key. 
NSSPrivateKey
 NSSPublicKey
 
 NSSSymmetricKey
 
 NSSTrustDomain
 
                    A trust domain is "the field in which certificates may
 be  validated."        It  is a collection of modules capable of performing 
  cryptographic      operations  and storing certs and keys.  This collection 
  is managed     by NSS in a manner opaque to the consumer.  The slots 
  will have various      orderings determining which has preference for a 
given  operation.  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?].
 
 
   -            How will ordering work?  We already have the  suggestion 
      that  there be two kinds of ordering: storage and search.   How 
will     they be  constructed/managed?  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)
- How are certs cached?  Nelson wonders what it means   to   Stan 
    when a cert does not live on a token yet.  Bob, Terry, and    I discussed
    this.  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).  NSSCertificate   would
  keep  a handle to this type, so that it only needs to decode the  cert
once.    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). 
      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.  Note    that this is essentially the same as CERT_TempCertToPerm.
     - The hashtable in lib/base (copied from ckfw/hash.c) uses the identity 
hash.  Therefore, in a hash of certificates, the key is the certificate 
pointer itself.  One possibility is to store the decoded cert (NSSX509DecodedParts 
above) as the value in the {key, value} pair.  When a cert is decoded, 
the cert pointer and decoding pointer are added to the hash.  Subsequent 
lookups have access to one or both of these pointers.  This keeps NSSCertificate 
separate from its decoding, while providing a way to locate it.
- The API is designed to keep token details hidden from the user.   However, 
 it has already been realized that PSM and CMS may need special  access to 
tokens.  Is this part of the TrustDomain API, or should PSM  and CMS 
be allowed to use "friend" headers from the Token API?
- Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?
 
                   NSSCryptoContext
 
    Analgous to a Cryptoki session.  Manages session objects only.
  
 NSSTime
 
 NSSUsage
 
 
   -        See Fred's 
               comments
              .
NSSPolicies
 
                      NSSAlgorithmAndParameters
 
 
   -        Again, Fred's 
               comments
              .  The old NSS code had various types related to  algorithms 
    running around in it.  We had SECOidTag, SECAlgorithmID,   SECItem's
     for parameters, CK_MECHANISM for cryptoki, etc.  This type   should
    be  able to encapsulate all of those.
NSSCallback
 NSSOperations
 
 
 
 
 
 A diagram to suggest a possible TrustDomain architecture.
 
  
 
 
 
 
 NSSOID
 
 NSSATAV
 
 NSSRDN
 
 NSSRDNSeq
 
 NSSName
 
            NSSNameChoice
            NSSGeneralName
            NSSGeneralNameChoice
            NSSOtherName
            NSSRFC822Name
            NSSDNSName
            NSSX400Address
            NSSEdiParityAddress
            NSSURI
            NSSIPAddress
            NSSRegisteredID
            NSSGeneralNameSeq
 
            nssAttributeTypeAliasTable
 
 
 
 
 
           There is a plethora of PKIX related types here.
 
 
 
        Building Stan
 
       From nss/lib, run "make BUILD_STAN=1"
 
 
 
       Testing Stan
       A new command line tool, pkiutil, has been created to use only
 the   Stan API.  It depends on a new library, cmdlib, meant to replace
 the   old secutil library.  The old library had code used by products
 that   needed to be integrated into the main library codebase somehow.  The
   goal of the new cmdlib is to have functionality needed strictly for NSS
 tools.
 
       How to build:
 
   - cd nss/cmd/cmdlib; make
- cd ../pkiutil; make
pkiutil will give detailed help with either "pkiutil -?" or "pkiutil 
 --help".
 
      So far, the only available test is to list certs on the builtins token. 
   Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil.  Then 
  run "pkiutil -L" or "pkiutil --list".  The list of certificate nicknames 
  should be displayed.