1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<!-- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>Stan Design - Work In Progress</title>
</head>
<body>
<br>
This is a working document for progress on Stan design/development.<br>
<br>
Current <a href="#build">build</a>
and <a href="#test">test</a>
instructions.<br>
<br>
The current set of Stan libraries.<br>
<a href="#asn1">asn1</a>
<br>
<a href="#base">base</a>
<br>
<a href="#ckfw">ckfw</a>
<br>
<a href="#dev">dev</a>
<br>
<a href="#pki">pki</a>
<br>
<a href="#pki1">pki1</a>
<br>
<a href="#pkix">pkix</a>
<br>
<br>
"Public" types below (those available to consumers of
NSS) begin with "NSS". "Protected" types (those only available
within NSS) begin with "nss".<br>
<br>
Open issues appears as numbered indents.<br>
<br>
<br>
<hr width="100%" size="2" align="Left"><br>
<h3><a name="asn1"></a>
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/asn1/">
ASN.1</a>
</h3>
ASN.1 encoder/decoder wrapping around the current
ASN.1 implementation.<br>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASN1EncodingType"> NSSASN1EncodingType</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Item">nssASN1Item</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Template">nssASN1Template</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1ChooseTemplateFunction">
nssASN1ChooseTemplateFunction</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Encoder">nssASN1Encoder</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Decoder">nssASN1Decoder</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncodingPart"> nssASN1EncodingPart</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1NotifyFunction">
nssASN1NotifyFunction</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncoderWriteFunction">
nssASN1EncoderWriteFunction</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1DecoderFilterFunction">
nssASN1DecoderFilterFunction</a>
<br>
<br>
<hr width="100%" size="2" align="Left">
<h3><a name="base"></a>
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/base/">
Base</a>
</h3>
Set of base utilities for Stan implementation.
These are all fairly straightforward, except for nssPointerTracker.<br>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSError">NSSError</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSArena">NSSArena</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSItem">NSSItem</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBER">NSSBER</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSDER">NSSDER</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBitString">NSSBitString</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUTF8">NSSUTF8</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASCII7">NSSASCII7</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssArenaMark">nssArenaMark</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssPointerTracker">nssPointerTracker</a>
<br>
This is intended for debug builds only.<br>
<ol>
<li>Ignored for now.<br>
</li>
</ol>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssStringType">nssStringType</a>
<br>
<br>
Suggested additions:<br>
<ol>
<li>nssList - A list that optionally uses a lock. This list would
manage the currently loaded modules in a trust domain, etc.</li>
<ul>
<li>SECMODListLock kept track of the number of waiting threads. Will
this be needed in the trust domain?</li>
</ul>
</ol>
<br>
<hr width="100%" size="2" align="Left">
<h3><a name="ckfw"></a>
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/">
CKFW</a>
</h3>
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.<br>
<br>
<br>
<hr width="100%" size="2" align="Left">
<h3><a name="dev"></a>
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/dev/">
Device</a>
</h3>
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.<br>
<br>
The relationship is like this:<br>
<br>
libpki --> libdev --> cryptoki<br>
<br>
As an example,<br>
<br>
NSSTrustDomain_FindCertificate --> NSSToken_FindCertificate -->
C_FindObjects<br>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSModule">NSSModule</a>
<br>
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.<br>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSlot">NSSSlot</a>
<br>
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.<br>
<ol>
<li>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).<br>
</li>
</ol>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSToken">NSSToken</a>
<br>
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.<br>
<ol>
<li>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:</li>
<ol>
<li>Implement the API entirely as NSSToken. If the token is not
present, some calls will simply fail.</li>
<li>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.</li>
<li>Others?</li>
</ol>
<li>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.<br>
</li>
</ol>
Proposed:<br>
NSSSession<br>
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.<br>
<br>
<hr width="100%" size="2" align="Left"><br>
<h3><a name="pki"></a>
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/">
PKI</a>
</h3>
The NSS PKI library.<br>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">NSS</a>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">Certificate</a>
<br>
<ol>
<li>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).</li>
</ol>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUserCertificate">NSSUserCertificate</a>
<br>
<ol>
<li>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. </li>
</ol>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPrivateKey">NSSPrivateKey</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPublicKey">NSSPublicKey</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSymmetricKey">NSSSymmetricKey</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTrustDomain">NSSTrustDomain</a>
<br>
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?].<br>
<br>
<ol>
<li> 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)</li>
<li>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.</li>
<ul>
<li>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.</li>
</ul>
<li>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?</li>
<li>Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?<br>
</li>
</ol>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCryptoContext"><br>
NSSCryptoContext</a>
<br>
Analgous to a Cryptoki session. Manages session objects only.<br>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTime">NSSTime</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUsage">NSSUsage</a>
<br>
<ol>
<li> See Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#187">
comments</a>
.</li>
</ol>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPolicies">NSSPolicies</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSAlgorithmAndParameters">
NSSAlgorithmAndParameters</a>
<br>
<ol>
<li> Again, Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#215">
comments</a>
. 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.</li>
</ol>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCallback">NSSCallback</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOperations">NSSOperations</a>
<br>
<br>
<br>
<hr width="100%" size="2"><br>
<br>
A diagram to suggest a possible TrustDomain architecture.<br>
<br>
<img src="./standiag.png" alt="Trust Domain Diagram" width="748" height="367">
<br>
<hr width="100%" size="2" align="Left"><br>
<h3><a name="pki1"></a>
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki1/">
PKI1</a>
</h3>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOID">NSSOID</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSATAV">NSSATAV</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDN">NSSRDN</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDNSeq">NSSRDNSeq</a>
<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSName">NSSName</a>
<br>
NSSNameChoice<br>
NSSGeneralName<br>
NSSGeneralNameChoice<br>
NSSOtherName<br>
NSSRFC822Name<br>
NSSDNSName<br>
NSSX400Address<br>
NSSEdiParityAddress<br>
NSSURI<br>
NSSIPAddress<br>
NSSRegisteredID<br>
NSSGeneralNameSeq<br>
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssAttributeTypeAliasTable">
nssAttributeTypeAliasTable</a>
<br>
<br>
<br>
<hr width="100%" size="2" align="Left"><br>
<h3><a name="pkix"></a>
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pkix/">
PKIX </a>
</h3>
There is a plethora of PKIX related types here.<br>
<br>
<hr width="100%" size="2" align="Left"><br>
<h3><a name="build"></a>
Building Stan</h3>
<br>
From nss/lib, run "make BUILD_STAN=1"<br>
<br>
<hr width="100%" size="2" align="Left"><br>
<h3><a name="test"></a>
Testing Stan</h3>
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.<br>
<br>
How to build:<br>
<ol>
<li>cd nss/cmd/cmdlib; make</li>
<li>cd ../pkiutil; make</li>
</ol>
pkiutil will give detailed help with either "pkiutil -?" or "pkiutil
--help".<br>
<br>
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.<br>
<br>
<br>
</body>
</html>
|
