diff -r 000000000000 -r 6474c204b198 security/nss/lib/pki/doc/standoc.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/security/nss/lib/pki/doc/standoc.html Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,442 @@ + + + + + + + + Stan Design - Work In Progress + + +
+ 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 +

+ ASN.1 encoder/decoder wrapping around the current + ASN.1 implementation.
+
+ NSSASN1EncodingType +
+ nssASN1Item +
+ nssASN1Template +
+ + nssASN1ChooseTemplateFunction +
+ nssASN1Encoder +
+ nssASN1Decoder +
+ nssASN1EncodingPart +
+ + nssASN1NotifyFunction +
+ + nssASN1EncoderWriteFunction +
+ + nssASN1DecoderFilterFunction +
+
+ +
+

+ + Base +

+ 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.
+ +
    +
  1. Ignored for now.
    +
    2. + +
+ nssStringType +
+
+ Suggested additions:
+ +
    +
  1. nssList - A list that optionally uses a lock.  This list would + manage the currently loaded modules in a trust domain, etc.
    2. + + + +
+
+ +
+

+ + CKFW +

+ 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.
+
+
+ +
+

+ + Device +

+ 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.
+ +
    +
  1. 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).
    +
    2. + +
+
+ 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.
+ +
    +
  1. 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:
    2. + +
      +
    1. Implement the API entirely as NSSToken.  If the token is not + present, some calls will simply fail.
      2. +
    2. 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.
      3. +
    3. Others?
      4. + +
    +
  2. 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.
    +
    3. + +
+ 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.
+
+ +

+ +

+ + PKI +

+ The NSS PKI library.
+
+ NSS + Certificate +
+ +
    +
  1. 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).
    2. + +
+
+ NSSUserCertificate +
+ +
    +
  1. 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.
    2. + +
+ 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?].
+
+ +
    +
  1. 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)
    2. +
  2. 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.
    3. + + +
  3. 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?
    4. +
  4. Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?
    +
    5. + +
+
+ NSSCryptoContext +
+ Analgous to a Cryptoki session.  Manages session objects only.
+
+ NSSTime +
+ NSSUsage +
+ +
    +
  1. See Fred's + comments + .
    2. + +
+ NSSPolicies +
+ + NSSAlgorithmAndParameters +
+ +
    +
  1. 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.
    2. + +
+ NSSCallback +
+ NSSOperations +
+
+
+ +

+
+ A diagram to suggest a possible TrustDomain architecture.
+
+ Trust Domain Diagram +
+ +

+ +

+ + PKI1 +

+
+ NSSOID +
+ NSSATAV +
+ NSSRDN +
+ NSSRDNSeq +
+ NSSName +
+ NSSNameChoice
+ NSSGeneralName
+ NSSGeneralNameChoice
+ NSSOtherName
+ NSSRFC822Name
+ NSSDNSName
+ NSSX400Address
+ NSSEdiParityAddress
+ NSSURI
+ NSSIPAddress
+ NSSRegisteredID
+ NSSGeneralNameSeq
+ + nssAttributeTypeAliasTable +
+
+
+ +

+ +

+ + PKIX  +

+ 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:
+ +
    +
  1. cd nss/cmd/cmdlib; make
    2. +
  2. cd ../pkiutil; make
    3. + +
+ 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.
+
+
+ + +