Stan Design - Work In Progress

michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: Stan Design - Work In Progress michael@0: michael@0: michael@0:
michael@0: This is a working document for progress on Stan design/development.
michael@0:
michael@0: Current build michael@0: and test michael@0: instructions.
michael@0:
michael@0: The current set of Stan libraries.
michael@0: asn1 michael@0:
michael@0: base michael@0:
michael@0: ckfw michael@0:
michael@0: dev michael@0:
michael@0: pki michael@0:
michael@0: pki1 michael@0:
michael@0: pkix michael@0:
michael@0:
michael@0: "Public" types below (those available to consumers of michael@0: NSS) begin with "NSS". "Protected" types (those only available michael@0: within NSS) begin with "nss".
michael@0:
michael@0: Open issues appears as numbered indents.
michael@0:
michael@0:
michael@0: michael@0:

michael@0: michael@0:

michael@0: michael@0: ASN.1 michael@0:

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

michael@0:

michael@0: michael@0: Base michael@0:

michael@0: Set of base utilities for Stan implementation. michael@0: These are all fairly straightforward, except for nssPointerTracker.
michael@0:
michael@0: NSSError michael@0:
michael@0: NSSArena michael@0:
michael@0: NSSItem michael@0:
michael@0: NSSBER michael@0:
michael@0: NSSDER michael@0:
michael@0: NSSBitString michael@0:
michael@0: NSSUTF8 michael@0:
michael@0: NSSASCII7 michael@0:
michael@0: nssArenaMark michael@0:
michael@0: nssPointerTracker michael@0:
michael@0: This is intended for debug builds only.
michael@0: michael@0:

Ignored for now.
michael@0:

michael@0: nssStringType michael@0:
michael@0:
michael@0: Suggested additions:
michael@0: michael@0:

nssList - A list that optionally uses a lock. This list would michael@0: manage the currently loaded modules in a trust domain, etc.

SECMODListLock kept track of the number of waiting threads. Will michael@0: this be needed in the trust domain?

michael@0:
michael@0: michael@0:

michael@0:

michael@0: michael@0: CKFW michael@0:

michael@0: The cryptoki framework, used for building cryptoki tokens. michael@0: This needs to be described in a separate document showing how michael@0: to set up a token using CKFW. This code only relates to tokens, michael@0: so it is not relevant here.
michael@0:
michael@0:
michael@0: michael@0:

michael@0:

michael@0: michael@0: Device michael@0:

michael@0: Defines cryptoki devices used in NSS. This michael@0: is not part of the exposed API. It is a low-level API allowing michael@0: NSS to manage cryptoki devices.
michael@0:
michael@0: The relationship is like this:
michael@0:
michael@0: libpki --> libdev --> cryptoki
michael@0:
michael@0: As an example,
michael@0:
michael@0: NSSTrustDomain_FindCertificate --> NSSToken_FindCertificate --> michael@0: C_FindObjects
michael@0:
michael@0: NSSModule michael@0:
michael@0: Replaces the SECMOD API. The module manages a michael@0: PRLibrary that holds a cryptoki implementation via a number of slots. michael@0: The API should provide the ability to Load and Unload a module, michael@0: Login and Logout to the module (through its slots), and to locate a michael@0: particular slot/token.
michael@0:
michael@0: NSSSlot michael@0:
michael@0: This and NSSToken combine to replace the PK11 API parts michael@0: that relate to slot and token management. The slot API should michael@0: provide the ability to Login/Logout to a slot, check the login status, michael@0: determine basic configuration information about the slot, and modify michael@0: the password settings.
michael@0: michael@0:

Should slots also maintain a default session? This session would michael@0: be used for slot management calls (sections 9.5 and9.6 of PKCS#11). Or michael@0: is the token session sufficient (this would not work if C_GetTokenInfo and michael@0: C_InitToken need to be wrapped in a threadsafe session).
michael@0:

michael@0:
michael@0: NSSToken michael@0:
michael@0: Fills in the gaps left by NSSSlot. Much of the michael@0: cryptoki API is directed towards slots. However, some functionality michael@0: clearly belongs with a token type. For example, a certificate michael@0: lives on a token, not a slot, so one would expect a function NSSToken_FindCertificate. michael@0: Thus functions that deal with importing/exporting an object michael@0: and performing actual cryptographic operations belong here.
michael@0: michael@0:

The distinction between a slot and a token is not clear. Most michael@0: functions take a slotID as an argument, even though it is obvious that michael@0: the event is intended to occur on a token. That leaves various michael@0: possibilities:

Implement the API entirely as NSSToken. If the token is not michael@0: present, some calls will simply fail.
Divide the API between NSSToken and NSSSlot, as described above. michael@0: NSSSlot would handle cryptoki calls specified as "slot management", michael@0: while NSSToken handles actual token operations.
Others?

Session management. Tokens needs a threadsafe session handle michael@0: to perform operations. CryptoContexts are meant to provide such sessions, michael@0: but other objects will need access to token functions as well (examples: michael@0: the TrustDomain_Find functions, _Login, _Logout, and others that do not exist michael@0: such as NSSToken_ChangePassword). For those functions, the token could michael@0: maintain a default session. Thus all NSSToken API functions would take michael@0: sessionOpt as an argument. If the caller is going to provide a session, michael@0: it sends an NSSSession there, otherwise it sends NULL and the default session michael@0: is utilized.
michael@0:

michael@0: Proposed:
michael@0: NSSSession
michael@0: Wraps a Cryptoki session. Created from a slot. Used to manage michael@0: sessions for crypto contexts. Has a lock field, which locks the session michael@0: if the slot is not threadsafe.
michael@0:
michael@0: michael@0:

michael@0: michael@0:

michael@0: michael@0: PKI michael@0:

michael@0: The NSS PKI library.
michael@0:
michael@0: NSS michael@0: Certificate michael@0:
michael@0: michael@0:

The API leaves open the possibility of NSSCertificate meaning various michael@0: certificate types, not just X.509. The way to keep open this possibility michael@0: is to keep only generally useful information in the NSSCertificate type. michael@0: Examples would be the certificate encoding, label, trust (obtained michael@0: from cryptoki calls), an email address, etc. Some type of generic michael@0: reference should be kept to the decoded certificate, which would then be michael@0: accessed by a type-specific API (e.g., NSSX509_GetSubjectName).

michael@0:
michael@0: NSSUserCertificate michael@0:
michael@0: michael@0:

Should this be a typedef of NSSCertificate? This implies that michael@0: any function that requires an NSSUserCertificate would fail when called michael@0: with a certificate lacking a private key.

michael@0: NSSPrivateKey michael@0:
michael@0: NSSPublicKey michael@0:
michael@0: NSSSymmetricKey michael@0:
michael@0: NSSTrustDomain michael@0:
michael@0: A trust domain is "the field in which certificates may michael@0: be validated." It is a collection of modules capable of performing michael@0: cryptographic operations and storing certs and keys. This collection michael@0: is managed by NSS in a manner opaque to the consumer. The slots michael@0: will have various orderings determining which has preference for a michael@0: given operation. For example, the trust domain may order the storage michael@0: of user certificates one way, and the storage of email certificates in michael@0: another way [is that a good example?].
michael@0:
michael@0: michael@0:

How will ordering work? We already have the suggestion michael@0: that there be two kinds of ordering: storage and search. How michael@0: will they be constructed/managed? Do we want to expose access michael@0: to a token that overrides this ordering (i.e., the download of updated michael@0: root certs may need to override storage order)
How are certs cached? Nelson wonders what it means to Stan michael@0: when a cert does not live on a token yet. Bob, Terry, and I discussed michael@0: this. My conclusion is that there should be a type, separate michael@0: from NSSCertificate, that holds the decoded cert parts (e.g., NSSX509Certificate, michael@0: or to avoid confusion, NSSX509DecodedParts). NSSCertificate would michael@0: keep a handle to this type, so that it only needs to decode the cert michael@0: once. The NSSTrustDomain would keep a hash table of cached certs, michael@0: some of which may not live on a token yet (i.e., they are only NSSX509DecodedParts). michael@0: This cache could be accessed in the same way the temp db was, michael@0: and when the cert is ready to be moved onto a token a call to NSSTrustDomain_ImportCertificate michael@0: 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 michael@0: hash. Therefore, in a hash of certificates, the key is the certificate michael@0: pointer itself. One possibility is to store the decoded cert (NSSX509DecodedParts michael@0: above) as the value in the {key, value} pair. When a cert is decoded, michael@0: the cert pointer and decoding pointer are added to the hash. Subsequent michael@0: lookups have access to one or both of these pointers. This keeps NSSCertificate michael@0: separate from its decoding, while providing a way to locate it.

The API is designed to keep token details hidden from the user. However, michael@0: it has already been realized that PSM and CMS may need special access to michael@0: tokens. Is this part of the TrustDomain API, or should PSM and CMS michael@0: be allowed to use "friend" headers from the Token API?
Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?
michael@0:

michael@0:
michael@0: NSSCryptoContext michael@0:
michael@0: Analgous to a Cryptoki session. Manages session objects only.
michael@0:
michael@0: NSSTime michael@0:
michael@0: NSSUsage michael@0:
michael@0: michael@0:

See Fred's michael@0: comments michael@0: .

michael@0: NSSPolicies michael@0:
michael@0: michael@0: NSSAlgorithmAndParameters michael@0:
michael@0: michael@0:

Again, Fred's michael@0: comments michael@0: . The old NSS code had various types related to algorithms michael@0: running around in it. We had SECOidTag, SECAlgorithmID, SECItem's michael@0: for parameters, CK_MECHANISM for cryptoki, etc. This type should michael@0: be able to encapsulate all of those.

michael@0: NSSCallback michael@0:
michael@0: NSSOperations michael@0:
michael@0:
michael@0:
michael@0: michael@0:

michael@0:
michael@0: A diagram to suggest a possible TrustDomain architecture.
michael@0:
michael@0: Trust Domain Diagram

michael@0:
michael@0: michael@0:

michael@0: michael@0:

michael@0: michael@0: PKI1 michael@0:

michael@0:
michael@0: NSSOID michael@0:
michael@0: NSSATAV michael@0:
michael@0: NSSRDN michael@0:
michael@0: NSSRDNSeq michael@0:
michael@0: NSSName michael@0:
michael@0: NSSNameChoice
michael@0: NSSGeneralName
michael@0: NSSGeneralNameChoice
michael@0: NSSOtherName
michael@0: NSSRFC822Name
michael@0: NSSDNSName
michael@0: NSSX400Address
michael@0: NSSEdiParityAddress
michael@0: NSSURI
michael@0: NSSIPAddress
michael@0: NSSRegisteredID
michael@0: NSSGeneralNameSeq
michael@0: michael@0: nssAttributeTypeAliasTable michael@0:
michael@0:
michael@0:
michael@0: michael@0:

michael@0: michael@0:

michael@0: michael@0: PKIX michael@0:

michael@0: There is a plethora of PKIX related types here.
michael@0:
michael@0: michael@0:

michael@0: michael@0:

michael@0: Building Stan

michael@0:
michael@0: From nss/lib, run "make BUILD_STAN=1"
michael@0:
michael@0: michael@0:

michael@0: michael@0:

michael@0: Testing Stan

michael@0: A new command line tool, pkiutil, has been created to use only michael@0: the Stan API. It depends on a new library, cmdlib, meant to replace michael@0: the old secutil library. The old library had code used by products michael@0: that needed to be integrated into the main library codebase somehow. The michael@0: goal of the new cmdlib is to have functionality needed strictly for NSS michael@0: tools.
michael@0:
michael@0: How to build:
michael@0: michael@0:

cd nss/cmd/cmdlib; make
cd ../pkiutil; make

michael@0: pkiutil will give detailed help with either "pkiutil -?" or "pkiutil michael@0: --help".
michael@0:
michael@0: So far, the only available test is to list certs on the builtins token. michael@0: Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil. Then michael@0: run "pkiutil -L" or "pkiutil --list". The list of certificate nicknames michael@0: should be displayed.
michael@0:
michael@0:
michael@0: michael@0: michael@0: