1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<!-- This Source Code Form is subject to the terms of the Mozilla Public
5
- License, v. 2.0. If a copy of the MPL was not distributed with this
6
- file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
9
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
10
<title>Stan Design - Work In Progress</title>
14
This is a working document for progress on Stan design/development.<br>
16
Current <a href="#build">build</a>
17
and <a href="#test">test</a>
20
The current set of Stan libraries.<br>
21
<a href="#asn1">asn1</a>
23
<a href="#base">base</a>
25
<a href="#ckfw">ckfw</a>
27
<a href="#dev">dev</a>
29
<a href="#pki">pki</a>
31
<a href="#pki1">pki1</a>
33
<a href="#pkix">pkix</a>
36
"Public" types below (those available to consumers of
37
NSS) begin with "NSS". "Protected" types (those only available
38
within NSS) begin with "nss".<br>
40
Open issues appears as numbered indents.<br>
44
<hr width="100%" size="2" align="Left"><br>
46
<h3><a name="asn1"></a>
47
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/asn1/">
50
ASN.1 encoder/decoder wrapping around the current
51
ASN.1 implementation.<br>
53
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASN1EncodingType"> NSSASN1EncodingType</a>
55
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Item">nssASN1Item</a>
57
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Template">nssASN1Template</a>
59
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1ChooseTemplateFunction">
60
nssASN1ChooseTemplateFunction</a>
62
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Encoder">nssASN1Encoder</a>
64
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Decoder">nssASN1Decoder</a>
66
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncodingPart"> nssASN1EncodingPart</a>
68
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1NotifyFunction">
69
nssASN1NotifyFunction</a>
71
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncoderWriteFunction">
72
nssASN1EncoderWriteFunction</a>
74
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1DecoderFilterFunction">
75
nssASN1DecoderFilterFunction</a>
79
<hr width="100%" size="2" align="Left">
80
<h3><a name="base"></a>
81
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/base/">
84
Set of base utilities for Stan implementation.
85
These are all fairly straightforward, except for nssPointerTracker.<br>
87
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSError">NSSError</a>
89
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSArena">NSSArena</a>
91
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSItem">NSSItem</a>
93
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBER">NSSBER</a>
95
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSDER">NSSDER</a>
97
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBitString">NSSBitString</a>
99
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUTF8">NSSUTF8</a>
101
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASCII7">NSSASCII7</a>
103
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssArenaMark">nssArenaMark</a>
105
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssPointerTracker">nssPointerTracker</a>
107
This is intended for debug builds only.<br>
110
<li>Ignored for now.<br>
114
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssStringType">nssStringType</a>
117
Suggested additions:<br>
120
<li>nssList - A list that optionally uses a lock. This list would
121
manage the currently loaded modules in a trust domain, etc.</li>
124
<li>SECMODListLock kept track of the number of waiting threads. Will
125
this be needed in the trust domain?</li>
132
<hr width="100%" size="2" align="Left">
133
<h3><a name="ckfw"></a>
134
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/">
137
The cryptoki framework, used for building cryptoki tokens.
138
This needs to be described in a separate document showing how
139
to set up a token using CKFW. This code only relates to tokens,
140
so it is not relevant here.<br>
144
<hr width="100%" size="2" align="Left">
145
<h3><a name="dev"></a>
146
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/dev/">
149
Defines cryptoki devices used in NSS. This
150
is not part of the exposed API. It is a low-level API allowing
151
NSS to manage cryptoki devices.<br>
153
The relationship is like this:<br>
155
libpki --> libdev --> cryptoki<br>
159
NSSTrustDomain_FindCertificate --> NSSToken_FindCertificate -->
162
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSModule">NSSModule</a>
164
Replaces the SECMOD API. The module manages a
165
PRLibrary that holds a cryptoki implementation via a number of slots.
166
The API should provide the ability to Load and Unload a module,
167
Login and Logout to the module (through its slots), and to locate a
168
particular slot/token.<br>
170
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSlot">NSSSlot</a>
172
This and NSSToken combine to replace the PK11 API parts
173
that relate to slot and token management. The slot API should
174
provide the ability to Login/Logout to a slot, check the login status,
175
determine basic configuration information about the slot, and modify
176
the password settings.<br>
179
<li>Should slots also maintain a default session? This session would
180
be used for slot management calls (sections 9.5 and9.6 of PKCS#11). Or
181
is the token session sufficient (this would not work if C_GetTokenInfo and
182
C_InitToken need to be wrapped in a threadsafe session).<br>
187
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSToken">NSSToken</a>
189
Fills in the gaps left by NSSSlot. Much of the
190
cryptoki API is directed towards slots. However, some functionality
191
clearly belongs with a token type. For example, a certificate
192
lives on a token, not a slot, so one would expect a function NSSToken_FindCertificate.
193
Thus functions that deal with importing/exporting an object
194
and performing actual cryptographic operations belong here.<br>
197
<li>The distinction between a slot and a token is not clear. Most
198
functions take a slotID as an argument, even though it is obvious that
199
the event is intended to occur on a token. That leaves various
203
<li>Implement the API entirely as NSSToken. If the token is not
204
present, some calls will simply fail.</li>
205
<li>Divide the API between NSSToken and NSSSlot, as described above.
206
NSSSlot would handle cryptoki calls specified as "slot management",
207
while NSSToken handles actual token operations.</li>
211
<li>Session management. Tokens needs a threadsafe session handle
212
to perform operations. CryptoContexts are meant to provide such sessions,
213
but other objects will need access to token functions as well (examples:
214
the TrustDomain_Find functions, _Login, _Logout, and others that do not exist
215
such as NSSToken_ChangePassword). For those functions, the token could
216
maintain a default session. Thus all NSSToken API functions would take
217
sessionOpt as an argument. If the caller is going to provide a session,
218
it sends an NSSSession there, otherwise it sends NULL and the default session
225
Wraps a Cryptoki session. Created from a slot. Used to manage
226
sessions for crypto contexts. Has a lock field, which locks the session
227
if the slot is not threadsafe.<br>
230
<hr width="100%" size="2" align="Left"><br>
232
<h3><a name="pki"></a>
233
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/">
236
The NSS PKI library.<br>
238
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">NSS</a>
239
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">Certificate</a>
243
<li>The API leaves open the possibility of NSSCertificate meaning various
244
certificate types, not just X.509. The way to keep open this possibility
245
is to keep only generally useful information in the NSSCertificate type.
246
Examples would be the certificate encoding, label, trust (obtained
247
from cryptoki calls), an email address, etc. Some type of generic
248
reference should be kept to the decoded certificate, which would then be
249
accessed by a type-specific API (e.g., NSSX509_GetSubjectName).</li>
253
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUserCertificate">NSSUserCertificate</a>
257
<li>Should this be a typedef of NSSCertificate? This implies that
258
any function that requires an NSSUserCertificate would fail when called
259
with a certificate lacking a private key. </li>
262
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPrivateKey">NSSPrivateKey</a>
264
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPublicKey">NSSPublicKey</a>
266
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSymmetricKey">NSSSymmetricKey</a>
268
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTrustDomain">NSSTrustDomain</a>
270
A trust domain is "the field in which certificates may
271
be validated." It is a collection of modules capable of performing
272
cryptographic operations and storing certs and keys. This collection
273
is managed by NSS in a manner opaque to the consumer. The slots
274
will have various orderings determining which has preference for a
275
given operation. For example, the trust domain may order the storage
276
of user certificates one way, and the storage of email certificates in
277
another way [is that a good example?].<br>
281
<li> How will ordering work? We already have the suggestion
282
that there be two kinds of ordering: storage and search. How
283
will they be constructed/managed? Do we want to expose access
284
to a token that overrides this ordering (i.e., the download of updated
285
root certs may need to override storage order)</li>
286
<li>How are certs cached? Nelson wonders what it means to Stan
287
when a cert does not live on a token yet. Bob, Terry, and I discussed
288
this. My conclusion is that there should be a type, separate
289
from NSSCertificate, that holds the decoded cert parts (e.g., NSSX509Certificate,
290
or to avoid confusion, NSSX509DecodedParts). NSSCertificate would
291
keep a handle to this type, so that it only needs to decode the cert
292
once. The NSSTrustDomain would keep a hash table of cached certs,
293
some of which may not live on a token yet (i.e., they are only NSSX509DecodedParts).
294
This cache could be accessed in the same way the temp db was,
295
and when the cert is ready to be moved onto a token a call to NSSTrustDomain_ImportCertificate
296
is made. Note that this is essentially the same as CERT_TempCertToPerm.</li>
299
<li>The hashtable in lib/base (copied from ckfw/hash.c) uses the identity
300
hash. Therefore, in a hash of certificates, the key is the certificate
301
pointer itself. One possibility is to store the decoded cert (NSSX509DecodedParts
302
above) as the value in the {key, value} pair. When a cert is decoded,
303
the cert pointer and decoding pointer are added to the hash. Subsequent
304
lookups have access to one or both of these pointers. This keeps NSSCertificate
305
separate from its decoding, while providing a way to locate it.</li>
308
<li>The API is designed to keep token details hidden from the user. However,
309
it has already been realized that PSM and CMS may need special access to
310
tokens. Is this part of the TrustDomain API, or should PSM and CMS
311
be allowed to use "friend" headers from the Token API?</li>
312
<li>Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?<br>
316
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCryptoContext"><br>
319
Analgous to a Cryptoki session. Manages session objects only.<br>
321
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTime">NSSTime</a>
323
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUsage">NSSUsage</a>
327
<li> See Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#187">
332
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPolicies">NSSPolicies</a>
334
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSAlgorithmAndParameters">
335
NSSAlgorithmAndParameters</a>
339
<li> Again, Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#215">
341
. The old NSS code had various types related to algorithms
342
running around in it. We had SECOidTag, SECAlgorithmID, SECItem's
343
for parameters, CK_MECHANISM for cryptoki, etc. This type should
344
be able to encapsulate all of those.</li>
347
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCallback">NSSCallback</a>
349
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOperations">NSSOperations</a>
354
<hr width="100%" size="2"><br>
356
A diagram to suggest a possible TrustDomain architecture.<br>
358
<img src="./standiag.png" alt="Trust Domain Diagram" width="748" height="367">
361
<hr width="100%" size="2" align="Left"><br>
363
<h3><a name="pki1"></a>
364
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki1/">
368
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOID">NSSOID</a>
370
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSATAV">NSSATAV</a>
372
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDN">NSSRDN</a>
374
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDNSeq">NSSRDNSeq</a>
376
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSName">NSSName</a>
380
NSSGeneralNameChoice<br>
385
NSSEdiParityAddress<br>
389
NSSGeneralNameSeq<br>
390
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssAttributeTypeAliasTable">
391
nssAttributeTypeAliasTable</a>
396
<hr width="100%" size="2" align="Left"><br>
398
<h3><a name="pkix"></a>
399
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pkix/">
402
There is a plethora of PKIX related types here.<br>
405
<hr width="100%" size="2" align="Left"><br>
407
<h3><a name="build"></a>
410
From nss/lib, run "make BUILD_STAN=1"<br>
413
<hr width="100%" size="2" align="Left"><br>
415
<h3><a name="test"></a>
417
A new command line tool, pkiutil, has been created to use only
418
the Stan API. It depends on a new library, cmdlib, meant to replace
419
the old secutil library. The old library had code used by products
420
that needed to be integrated into the main library codebase somehow. The
421
goal of the new cmdlib is to have functionality needed strictly for NSS
427
<li>cd nss/cmd/cmdlib; make</li>
428
<li>cd ../pkiutil; make</li>
431
pkiutil will give detailed help with either "pkiutil -?" or "pkiutil
434
So far, the only available test is to list certs on the builtins token.
435
Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil. Then
436
run "pkiutil -L" or "pkiutil --list". The list of certificate nicknames
437
should be displayed.<br>