security/nss/lib/pki/doc/standoc.html@b8a032363ba2
security/nss/lib/pki/doc/standoc.html
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
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>
11 </head>
12 <body>
13 <br>
14 This is a working document for progress on Stan design/development.<br>
15 <br>
16 Current <a href="#build">build</a>
17 and <a href="#test">test</a>
18 instructions.<br>
19 <br>
20 The current set of Stan libraries.<br>
21 <a href="#asn1">asn1</a>
22 <br>
23 <a href="#base">base</a>
24 <br>
25 <a href="#ckfw">ckfw</a>
26 <br>
27 <a href="#dev">dev</a>
28 <br>
29 <a href="#pki">pki</a>
30 <br>
31 <a href="#pki1">pki1</a>
32 <br>
33 <a href="#pkix">pkix</a>
34 <br>
35 <br>
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>
39 <br>
40 Open issues appears as numbered indents.<br>
41 <br>
42 <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/">
48 ASN.1</a>
49 </h3>
50 ASN.1 encoder/decoder wrapping around the current
51 ASN.1 implementation.<br>
52 <br>
53 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASN1EncodingType"> NSSASN1EncodingType</a>
54 <br>
55 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Item">nssASN1Item</a>
56 <br>
57 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Template">nssASN1Template</a>
58 <br>
59 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1ChooseTemplateFunction">
60 nssASN1ChooseTemplateFunction</a>
61 <br>
62 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Encoder">nssASN1Encoder</a>
63 <br>
64 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1Decoder">nssASN1Decoder</a>
65 <br>
66 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncodingPart"> nssASN1EncodingPart</a>
67 <br>
68 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1NotifyFunction">
69 nssASN1NotifyFunction</a>
70 <br>
71 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1EncoderWriteFunction">
72 nssASN1EncoderWriteFunction</a>
73 <br>
74 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssASN1DecoderFilterFunction">
75 nssASN1DecoderFilterFunction</a>
76 <br>
77 <br>
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/">
82 Base</a>
83 </h3>
84 Set of base utilities for Stan implementation.
85 These are all fairly straightforward, except for nssPointerTracker.<br>
86 <br>
87 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSError">NSSError</a>
88 <br>
89 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSArena">NSSArena</a>
90 <br>
91 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSItem">NSSItem</a>
92 <br>
93 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBER">NSSBER</a>
94 <br>
95 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSDER">NSSDER</a>
96 <br>
97 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSBitString">NSSBitString</a>
98 <br>
99 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUTF8">NSSUTF8</a>
100 <br>
101 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSASCII7">NSSASCII7</a>
102 <br>
103 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssArenaMark">nssArenaMark</a>
104 <br>
105 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssPointerTracker">nssPointerTracker</a>
106 <br>
107 This is intended for debug builds only.<br>
109 <ol>
110 <li>Ignored for now.<br>
111 </li>
113 </ol>
114 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssStringType">nssStringType</a>
115 <br>
116 <br>
117 Suggested additions:<br>
119 <ol>
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>
123 <ul>
124 <li>SECMODListLock kept track of the number of waiting threads. Will
125 this be needed in the trust domain?</li>
127 </ul>
129 </ol>
130 <br>
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/">
135 CKFW</a>
136 </h3>
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>
141 <br>
142 <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/">
147 Device</a>
148 </h3>
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>
152 <br>
153 The relationship is like this:<br>
154 <br>
155 libpki --> libdev --> cryptoki<br>
156 <br>
157 As an example,<br>
158 <br>
159 NSSTrustDomain_FindCertificate --> NSSToken_FindCertificate -->
160 C_FindObjects<br>
161 <br>
162 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSModule">NSSModule</a>
163 <br>
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>
169 <br>
170 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSlot">NSSSlot</a>
171 <br>
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>
178 <ol>
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>
183 </li>
185 </ol>
186 <br>
187 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSToken">NSSToken</a>
188 <br>
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>
196 <ol>
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
200 possibilities:</li>
202 <ol>
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>
208 <li>Others?</li>
210 </ol>
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
219 is utilized.<br>
220 </li>
222 </ol>
223 Proposed:<br>
224 NSSSession<br>
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>
228 <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/">
234 PKI</a>
235 </h3>
236 The NSS PKI library.<br>
237 <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>
240 <br>
242 <ol>
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>
251 </ol>
252 <br>
253 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUserCertificate">NSSUserCertificate</a>
254 <br>
256 <ol>
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>
261 </ol>
262 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPrivateKey">NSSPrivateKey</a>
263 <br>
264 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPublicKey">NSSPublicKey</a>
265 <br>
266 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSSymmetricKey">NSSSymmetricKey</a>
267 <br>
268 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTrustDomain">NSSTrustDomain</a>
269 <br>
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>
278 <br>
280 <ol>
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>
298 <ul>
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>
307 </ul>
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>
313 </li>
315 </ol>
316 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCryptoContext"><br>
317 NSSCryptoContext</a>
318 <br>
319 Analgous to a Cryptoki session. Manages session objects only.<br>
320 <br>
321 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSTime">NSSTime</a>
322 <br>
323 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUsage">NSSUsage</a>
324 <br>
326 <ol>
327 <li> See Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#187">
328 comments</a>
329 .</li>
331 </ol>
332 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSPolicies">NSSPolicies</a>
333 <br>
334 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSAlgorithmAndParameters">
335 NSSAlgorithmAndParameters</a>
336 <br>
338 <ol>
339 <li> Again, Fred's <a href="http://lxr.mozilla.org/mozilla/source/security/nss/lib/pki/nsspkit.h#215">
340 comments</a>
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>
346 </ol>
347 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSCallback">NSSCallback</a>
348 <br>
349 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOperations">NSSOperations</a>
350 <br>
351 <br>
352 <br>
354 <hr width="100%" size="2"><br>
355 <br>
356 A diagram to suggest a possible TrustDomain architecture.<br>
357 <br>
358 <img src="./standiag.png" alt="Trust Domain Diagram" width="748" height="367">
359 <br>
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/">
365 PKI1</a>
366 </h3>
367 <br>
368 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSOID">NSSOID</a>
369 <br>
370 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSATAV">NSSATAV</a>
371 <br>
372 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDN">NSSRDN</a>
373 <br>
374 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSRDNSeq">NSSRDNSeq</a>
375 <br>
376 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSName">NSSName</a>
377 <br>
378 NSSNameChoice<br>
379 NSSGeneralName<br>
380 NSSGeneralNameChoice<br>
381 NSSOtherName<br>
382 NSSRFC822Name<br>
383 NSSDNSName<br>
384 NSSX400Address<br>
385 NSSEdiParityAddress<br>
386 NSSURI<br>
387 NSSIPAddress<br>
388 NSSRegisteredID<br>
389 NSSGeneralNameSeq<br>
390 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssAttributeTypeAliasTable">
391 nssAttributeTypeAliasTable</a>
392 <br>
393 <br>
394 <br>
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/">
400 PKIX </a>
401 </h3>
402 There is a plethora of PKIX related types here.<br>
403 <br>
405 <hr width="100%" size="2" align="Left"><br>
407 <h3><a name="build"></a>
408 Building Stan</h3>
409 <br>
410 From nss/lib, run "make BUILD_STAN=1"<br>
411 <br>
413 <hr width="100%" size="2" align="Left"><br>
415 <h3><a name="test"></a>
416 Testing Stan</h3>
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
422 tools.<br>
423 <br>
424 How to build:<br>
426 <ol>
427 <li>cd nss/cmd/cmdlib; make</li>
428 <li>cd ../pkiutil; make</li>
430 </ol>
431 pkiutil will give detailed help with either "pkiutil -?" or "pkiutil
432 --help".<br>
433 <br>
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>
438 <br>
439 <br>
441 </body>
442 </html>
