1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<!-- ***** BEGIN LICENSE BLOCK *****
5
- Version: MPL 1.1/GPL 2.0/LGPL 2.1
7
- The contents of this file are subject to the Mozilla Public License Version
8
- 1.1 (the "License"); you may not use this file except in compliance with
9
- the License. You may obtain a copy of the License at
10
- http://www.mozilla.org/MPL/
12
- Software distributed under the License is distributed on an "AS IS" basis,
13
- WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
14
- for the specific language governing rights and limitations under the
17
- The Original Code is the Netscape security libraries.
19
- The Initial Developer of the Original Code is
20
- Netscape Communications Corporation.
21
- Portions created by the Initial Developer are Copyright (C) 1994-2000
22
- the Initial Developer. All Rights Reserved.
26
- Alternatively, the contents of this file may be used under the terms of
27
- either the GNU General Public License Version 2 or later (the "GPL"), or
28
- the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
29
- in which case the provisions of the GPL or the LGPL are applicable instead
30
- of those above. If you wish to allow use of your version of this file only
31
- under the terms of either the GPL or the LGPL, and not to allow others to
32
- use your version of this file under the terms of the MPL, indicate your
33
- decision by deleting the provisions above and replace them with the notice
34
- and other provisions required by the GPL or the LGPL. If you do not delete
35
- the provisions above, a recipient may use your version of this file under
36
- the terms of any one of the MPL, the GPL or the LGPL.
38
- ***** END LICENSE BLOCK ***** -->
41
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
42
<title>Stan Design - Work In Progress</title>
46
This is a working document for progress on Stan design/development.<br>
48
Current <a href="#build">build</a>
49
and <a href="#test">test</a>
52
The current set of Stan libraries.<br>
53
<a href="#asn1">asn1</a>
55
<a href="#base">base</a>
57
<a href="#ckfw">ckfw</a>
59
<a href="#dev">dev</a>
61
<a href="#pki">pki</a>
63
<a href="#pki1">pki1</a>
65
<a href="#pkix">pkix</a>
68
"Public" types below (those available to consumers of
69
NSS) begin with "NSS". "Protected" types (those only available
70
within NSS) begin with "nss".<br>
72
Open issues appears as numbered indents.<br>
76
<hr width="100%" size="2" align="Left"><br>
78
<h3><a name="asn1"></a>
79
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/asn1/">
82
ASN.1 encoder/decoder wrapping around the current
83
ASN.1 implementation.<br>
85
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASN1EncodingType"> NSSASN1EncodingType</a>
87
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Item">nssASN1Item</a>
89
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Template">nssASN1Template</a>
91
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1ChooseTemplateFunction">
92
nssASN1ChooseTemplateFunction</a>
94
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Encoder">nssASN1Encoder</a>
96
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Decoder">nssASN1Decoder</a>
98
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncodingPart"> nssASN1EncodingPart</a>
100
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1NotifyFunction">
101
nssASN1NotifyFunction</a>
103
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncoderWriteFunction">
104
nssASN1EncoderWriteFunction</a>
106
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1DecoderFilterFunction">
107
nssASN1DecoderFilterFunction</a>
111
<hr width="100%" size="2" align="Left">
112
<h3><a name="base"></a>
113
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/base/">
116
Set of base utilities for Stan implementation.
117
These are all fairly straightforward, except for nssPointerTracker.<br>
119
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSError">NSSError</a>
121
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSArena">NSSArena</a>
123
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSItem">NSSItem</a>
125
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBER">NSSBER</a>
127
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSDER">NSSDER</a>
129
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBitString">NSSBitString</a>
131
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUTF8">NSSUTF8</a>
133
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASCII7">NSSASCII7</a>
135
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssArenaMark">nssArenaMark</a>
137
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssPointerTracker">nssPointerTracker</a>
139
This is intended for debug builds only.<br>
142
<li>Ignored for now.<br>
146
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssStringType">nssStringType</a>
149
Suggested additions:<br>
152
<li>nssList - A list that optionally uses a lock. This list would
153
manage the currently loaded modules in a trust domain, etc.</li>
156
<li>SECMODListLock kept track of the number of waiting threads. Will
157
this be needed in the trust domain?</li>
164
<hr width="100%" size="2" align="Left">
165
<h3><a name="ckfw"></a>
166
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/">
169
The cryptoki framework, used for building cryptoki tokens.
170
This needs to be described in a separate document showing how
171
to set up a token using CKFW. This code only relates to tokens,
172
so it is not relevant here.<br>
176
<hr width="100%" size="2" align="Left">
177
<h3><a name="dev"></a>
178
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/dev/">
181
Defines cryptoki devices used in NSS. This
182
is not part of the exposed API. It is a low-level API allowing
183
NSS to manage cryptoki devices.<br>
185
The relationship is like this:<br>
187
libpki --> libdev --> cryptoki<br>
191
NSSTrustDomain_FindCertificate --> NSSToken_FindCertificate -->
194
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSModule">NSSModule</a>
196
Replaces the SECMOD API. The module manages a
197
PRLibrary that holds a cryptoki implementation via a number of slots.
198
The API should provide the ability to Load and Unload a module,
199
Login and Logout to the module (through its slots), and to locate a
200
particular slot/token.<br>
202
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSlot">NSSSlot</a>
204
This and NSSToken combine to replace the PK11 API parts
205
that relate to slot and token management. The slot API should
206
provide the ability to Login/Logout to a slot, check the login status,
207
determine basic configuration information about the slot, and modify
208
the password settings.<br>
211
<li>Should slots also maintain a default session? This session would
212
be used for slot management calls (sections 9.5 and9.6 of PKCS#11). Or
213
is the token session sufficient (this would not work if C_GetTokenInfo and
214
C_InitToken need to be wrapped in a threadsafe session).<br>
219
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSToken">NSSToken</a>
221
Fills in the gaps left by NSSSlot. Much of the
222
cryptoki API is directed towards slots. However, some functionality
223
clearly belongs with a token type. For example, a certificate
224
lives on a token, not a slot, so one would expect a function NSSToken_FindCertificate.
225
Thus functions that deal with importing/exporting an object
226
and performing actual cryptographic operations belong here.<br>
229
<li>The distinction between a slot and a token is not clear. Most
230
functions take a slotID as an argument, even though it is obvious that
231
the event is intended to occur on a token. That leaves various
235
<li>Implement the API entirely as NSSToken. If the token is not
236
present, some calls will simply fail.</li>
237
<li>Divide the API between NSSToken and NSSSlot, as described above.
238
NSSSlot would handle cryptoki calls specified as "slot management",
239
while NSSToken handles actual token operations.</li>
243
<li>Session management. Tokens needs a threadsafe session handle
244
to perform operations. CryptoContexts are meant to provide such sessions,
245
but other objects will need access to token functions as well (examples:
246
the TrustDomain_Find functions, _Login, _Logout, and others that do not exist
247
such as NSSToken_ChangePassword). For those functions, the token could
248
maintain a default session. Thus all NSSToken API functions would take
249
sessionOpt as an argument. If the caller is going to provide a session,
250
it sends an NSSSession there, otherwise it sends NULL and the default session
257
Wraps a Cryptoki session. Created from a slot. Used to manage
258
sessions for crypto contexts. Has a lock field, which locks the session
259
if the slot is not threadsafe.<br>
262
<hr width="100%" size="2" align="Left"><br>
264
<h3><a name="pki"></a>
265
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/">
268
The NSS PKI library.<br>
270
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">NSS</a>
271
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCertificate">Certificate</a>
275
<li>The API leaves open the possibility of NSSCertificate meaning various
276
certificate types, not just X.509. The way to keep open this possibility
277
is to keep only generally useful information in the NSSCertificate type.
278
Examples would be the certificate encoding, label, trust (obtained
279
from cryptoki calls), an email address, etc. Some type of generic
280
reference should be kept to the decoded certificate, which would then be
281
accessed by a type-specific API (e.g., NSSX509_GetSubjectName).</li>
285
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUserCertificate">NSSUserCertificate</a>
289
<li>Should this be a typedef of NSSCertificate? This implies that
290
any function that requires an NSSUserCertificate would fail when called
291
with a certificate lacking a private key. </li>
294
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPrivateKey">NSSPrivateKey</a>
296
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPublicKey">NSSPublicKey</a>
298
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSymmetricKey">NSSSymmetricKey</a>
300
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTrustDomain">NSSTrustDomain</a>
302
A trust domain is "the field in which certificates may
303
be validated." It is a collection of modules capable of performing
304
cryptographic operations and storing certs and keys. This collection
305
is managed by NSS in a manner opaque to the consumer. The slots
306
will have various orderings determining which has preference for a
307
given operation. For example, the trust domain may order the storage
308
of user certificates one way, and the storage of email certificates in
309
another way [is that a good example?].<br>
313
<li> How will ordering work? We already have the suggestion
314
that there be two kinds of ordering: storage and search. How
315
will they be constructed/managed? Do we want to expose access
316
to a token that overrides this ordering (i.e., the download of updated
317
root certs may need to override storage order)</li>
318
<li>How are certs cached? Nelson wonders what it means to Stan
319
when a cert does not live on a token yet. Bob, Terry, and I discussed
320
this. My conclusion is that there should be a type, separate
321
from NSSCertificate, that holds the decoded cert parts (e.g., NSSX509Certificate,
322
or to avoid confusion, NSSX509DecodedParts). NSSCertificate would
323
keep a handle to this type, so that it only needs to decode the cert
324
once. The NSSTrustDomain would keep a hash table of cached certs,
325
some of which may not live on a token yet (i.e., they are only NSSX509DecodedParts).
326
This cache could be accessed in the same way the temp db was,
327
and when the cert is ready to be moved onto a token a call to NSSTrustDomain_ImportCertificate
328
is made. Note that this is essentially the same as CERT_TempCertToPerm.</li>
331
<li>The hashtable in lib/base (copied from ckfw/hash.c) uses the identity
332
hash. Therefore, in a hash of certificates, the key is the certificate
333
pointer itself. One possibility is to store the decoded cert (NSSX509DecodedParts
334
above) as the value in the {key, value} pair. When a cert is decoded,
335
the cert pointer and decoding pointer are added to the hash. Subsequent
336
lookups have access to one or both of these pointers. This keeps NSSCertificate
337
separate from its decoding, while providing a way to locate it.</li>
340
<li>The API is designed to keep token details hidden from the user. However,
341
it has already been realized that PSM and CMS may need special access to
342
tokens. Is this part of the TrustDomain API, or should PSM and CMS
343
be allowed to use "friend" headers from the Token API?</li>
344
<li>Do we want to allow traversal via NSSTrustDomain_TraverseXXXX?<br>
348
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCryptoContext"><br>
351
Analgous to a Cryptoki session. Manages session objects only.<br>
353
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTime">NSSTime</a>
355
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUsage">NSSUsage</a>
359
<li> See Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#187">
364
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPolicies">NSSPolicies</a>
366
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSAlgorithmAndParameters">
367
NSSAlgorithmAndParameters</a>
371
<li> Again, Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#215">
373
. The old NSS code had various types related to algorithms
374
running around in it. We had SECOidTag, SECAlgorithmID, SECItem's
375
for parameters, CK_MECHANISM for cryptoki, etc. This type should
376
be able to encapsulate all of those.</li>
379
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCallback">NSSCallback</a>
381
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOperations">NSSOperations</a>
386
<hr width="100%" size="2"><br>
388
A diagram to suggest a possible TrustDomain architecture.<br>
390
<img src="./standiag.png" alt="Trust Domain Diagram" width="748" height="367">
393
<hr width="100%" size="2" align="Left"><br>
395
<h3><a name="pki1"></a>
396
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki1/">
400
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOID">NSSOID</a>
402
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSATAV">NSSATAV</a>
404
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDN">NSSRDN</a>
406
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDNSeq">NSSRDNSeq</a>
408
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSName">NSSName</a>
412
NSSGeneralNameChoice<br>
417
NSSEdiParityAddress<br>
421
NSSGeneralNameSeq<br>
422
<a href="http://lxr.mozilla.org/mozilla/ident?i=nssAttributeTypeAliasTable">
423
nssAttributeTypeAliasTable</a>
428
<hr width="100%" size="2" align="Left"><br>
430
<h3><a name="pkix"></a>
431
<a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pkix/">
434
There is a plethora of PKIX related types here.<br>
437
<hr width="100%" size="2" align="Left"><br>
439
<h3><a name="build"></a>
442
From nss/lib, run "make BUILD_STAN=1"<br>
445
<hr width="100%" size="2" align="Left"><br>
447
<h3><a name="test"></a>
449
A new command line tool, pkiutil, has been created to use only
450
the Stan API. It depends on a new library, cmdlib, meant to replace
451
the old secutil library. The old library had code used by products
452
that needed to be integrated into the main library codebase somehow. The
453
goal of the new cmdlib is to have functionality needed strictly for NSS
459
<li>cd nss/cmd/cmdlib; make</li>
460
<li>cd ../pkiutil; make</li>
463
pkiutil will give detailed help with either "pkiutil -?" or "pkiutil
466
So far, the only available test is to list certs on the builtins token.
467
Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil. Then
468
run "pkiutil -L" or "pkiutil --list". The list of certificate nicknames
469
should be displayed.<br>
added
removed
security/nss-fips/lib/pki/doc/standoc.html
