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.

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.

- SECMODListLock kept track of the number of waiting threads. Will this be needed in the trust domain?

### 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).

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:

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

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.

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

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.

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

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. Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?

NSSCryptoContext
Analgous to a Cryptoki session. Manages session objects only.
NSSTime
NSSUsage

1. See Fred's comments .

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.

NSSCallback
NSSOperations

A diagram to suggest a possible TrustDomain architecture.

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