diff --git a/mozilla/security/nss/lib/pki/doc/standoc.html b/mozilla/security/nss/lib/pki/doc/standoc.html index ec72a36a9ec..ec72e8c45fe 100644 --- a/mozilla/security/nss/lib/pki/doc/standoc.html +++ b/mozilla/security/nss/lib/pki/doc/standoc.html @@ -1,7 +1,7 @@ - - + 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 + +
+ 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.
-
-
- +
+ Open issues appears as numbered indents.
+
+
+

- +

- - ASN.1 -

- ASN.1 encoder/decoder wrapping around the current ASN.1 + + ASN.1 + + ASN.1 encoder/decoder wrapping around the current ASN.1 implementation.
-
- NSSASN1EncodingType -
- nssASN1Item -
- nssASN1Template -
- - nssASN1ChooseTemplateFunction -
- nssASN1Encoder -
- nssASN1Decoder -
- nssASN1EncodingPart -
- - nssASN1NotifyFunction -
- - nssASN1EncoderWriteFunction -
- - nssASN1DecoderFilterFunction -
-
- -
+
+ 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.
- -
    + + 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. -
    2. Ignored for now.
      -
      3. -
    - nssStringType -
    -
    - Suggested additions:
    - + 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. - +
    2. nssList - A list that optionally uses a lock.  This list +would manage the currently loaded modules in a trust domain, etc.
      3. + - +
    -
    - -
    +
    + +

    - 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, + +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 + +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.
    -
    - 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.
    - +
    + 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.
    +
    + 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. - +
    2. 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:
      3. +
        - -
      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. - +
      4. Implement the API entirely as NSSToken.  If the token +is not present, some calls will simply fail.
        5. +
      5. 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.
        6. +
      6. Others?
        +
        7. +
      - +
    -
    - + 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 -
    - -
      + + 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. 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. -
    2. 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.
      3. -
    - 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 +
    + 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 +
    3. 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)
      4. +
    4. 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.
      5. +
    5. 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?
      6. +
    6. Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?
      +
      7. -
    7. 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?
      8. -
    8. Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?
      +
    +
    + NSSCryptoContext     +
    +Analgous to a Cryptoki session.
    +
      +
    1. Why do the TrustDomain and CryptoContext API's have the same calls +related to importing/finding certificates and other objects?  If a CryptoContext +manages a session, shouldn't it be sufficient for the handling of token objects? + Where does the TrustDomain obtain the session needed to fulfill its +Import and Find calls?
      2. -
    -
    - NSSCryptoContext     -
    - NSSTime -
    - NSSUsage -
    - -
      +
      + NSSTime +
      + NSSUsage +
      -
    1. See Fred's - comments - .
      2. - -
    - NSSPolicies -
    - - NSSAlgorithmAndParameters -
    -
      +
    1. See Fred's + comments + .
      2. -
    2. 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.
      3. -
    - NSSCallback -
    - NSSOperations -
    -
    - + 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 +
    +
    +

    - +

    - - PKI1 -

    -
    - NSSOID -
    - NSSATAV -
    - NSSRDN -
    - NSSRDNSeq -
    - NSSName -
    - NSSNameChoice
    - NSSGeneralName
    - NSSGeneralNameChoice
    - NSSOtherName
    - NSSRFC822Name
    - NSSDNSName
    - NSSX400Address
    - NSSEdiParityAddress
    - NSSURI
    - NSSIPAddress
    - NSSRegisteredID
    - NSSGeneralNameSeq
    - - nssAttributeTypeAliasTable -
    -
    -
    - + + 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.
    -
    - + + PKIX  + + There is a plethora of PKIX related types here.
    +
    +

    - +

    - Building Stan

    -
    - From nss/lib, run "make BUILD_STAN=1"
    -
    - + 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:
    - + 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. -
    3. cd nss/cmd/cmdlib; make
      4. - -
    4. cd ../pkiutil; make
      5. -
    - 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 + 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.
    -
    - +
    +