standoc.html (17138B)
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>