The Tor Browser / file comparison
comparison: security/nss/lib/pki/doc/standoc.html
security/nss/lib/pki/doc/standoc.html
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:b157b42a6b76 |
|---|---|
| 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/. --> | |
| 7 | |
| 8 | |
| 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> | |
| 43 | |
| 44 <hr width="100%" size="2" align="Left"><br> | |
| 45 | |
| 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> | |
| 78 | |
| 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> | |
| 108 | |
| 109 <ol> | |
| 110 <li>Ignored for now.<br> | |
| 111 </li> | |
| 112 | |
| 113 </ol> | |
| 114 <a href="http://lxr.mozilla.org/mozilla/ident?i=nssStringType">nssStringType</a> | |
| 115 <br> | |
| 116 <br> | |
| 117 Suggested additions:<br> | |
| 118 | |
| 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> | |
| 122 | |
| 123 <ul> | |
| 124 <li>SECMODListLock kept track of the number of waiting threads. Will | |
| 125 this be needed in the trust domain?</li> | |
| 126 | |
| 127 </ul> | |
| 128 | |
| 129 </ol> | |
| 130 <br> | |
| 131 | |
| 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> | |
| 143 | |
| 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> | |
| 177 | |
| 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> | |
| 184 | |
| 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> | |
| 195 | |
| 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> | |
| 201 | |
| 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> | |
| 209 | |
| 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> | |
| 221 | |
| 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> | |
| 229 | |
| 230 <hr width="100%" size="2" align="Left"><br> | |
| 231 | |
| 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> | |
| 241 | |
| 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> | |
| 250 | |
| 251 </ol> | |
| 252 <br> | |
| 253 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSUserCertificate">NSSUserCertificate</a> | |
| 254 <br> | |
| 255 | |
| 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> | |
| 260 | |
| 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> | |
| 279 | |
| 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> | |
| 297 | |
| 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> | |
| 306 | |
| 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> | |
| 314 | |
| 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> | |
| 325 | |
| 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> | |
| 330 | |
| 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> | |
| 337 | |
| 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> | |
| 345 | |
| 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> | |
| 353 | |
| 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> | |
| 360 | |
| 361 <hr width="100%" size="2" align="Left"><br> | |
| 362 | |
| 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> | |
| 395 | |
| 396 <hr width="100%" size="2" align="Left"><br> | |
| 397 | |
| 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> | |
| 404 | |
| 405 <hr width="100%" size="2" align="Left"><br> | |
| 406 | |
| 407 <h3><a name="build"></a> | |
| 408 Building Stan</h3> | |
| 409 <br> | |
| 410 From nss/lib, run "make BUILD_STAN=1"<br> | |
| 411 <br> | |
| 412 | |
| 413 <hr width="100%" size="2" align="Left"><br> | |
| 414 | |
| 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> | |
| 425 | |
| 426 <ol> | |
| 427 <li>cd nss/cmd/cmdlib; make</li> | |
| 428 <li>cd ../pkiutil; make</li> | |
| 429 | |
| 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> | |
| 440 | |
| 441 </body> | |
| 442 </html> |
