diff --git a/mozilla/security/nss/lib/pki/doc/standoc.html b/mozilla/security/nss/lib/pki/doc/standoc.html index 7e6b3e676b4..43eb3a3cf89 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 NSS) begin with "nss".
-
- Open issues appears as numbered indents.
-
-
+
+ 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 + + 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 +
  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, so it is not relevant here.
-
-
-
+ + 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.
+ + 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 +
  2. 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).
    -
    3. + +
-
-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.
+
+ 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 +
    2. Implement the API entirely as NSSToken.  If the token is not present, some calls will simply fail.
      3. -
    3. 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.
      4. -
    4. Others?
      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. +
    -
  3. 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.
    -
    4. +
  4. 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.
    +
    5. +
- 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.
-
+ 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. +
  2. 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).
    3. +
-
-NSSUserCertificate -
+
+ NSSUserCertificate +
+
    -
  1. Should this be a typedef of NSSCertificate?  This implies that - any function that requires an NSSUserCertificate would fail when called +
  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 another way [is that a good example?].
-
+ 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 +
  2. 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)
    3. -
  3. 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 +
  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 +
  6. 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?
    7. -
  7. Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?
    -
    8. +
  8. Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?
    +
    9. +
-
- NSSCryptoContext -
- Analgous to a Cryptoki session.
+
+ NSSCryptoContext +
+ Analgous to a Cryptoki session.  Manages session objects only.
+
+ NSSTime +
+ NSSUsage +
+
    -
  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. +
  2. See Fred's + comments + .
    3. +
-
-NSSTime -
-NSSUsage -
+ 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. +
-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 -
-
-
+ NSSCallback +
+ NSSOperations +
+
+
+

-
-A diagram to suggest a possible TrustDomain architecture.
-
-Trust Domain Diagram -
+
+ 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 -
-
-
+ + 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 + 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 +
+ 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.
-
-
+
+
+