DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Untracked file

Line Code
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 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
         <!-- 
   - The contents of this file are subject to the Mozilla Public
   - License Version 1.1 (the "License"); you may not use this file
   - except in compliance with the License. You may obtain a copy of
   - the License at http://www.mozilla.org/MPL/
   - 
   - Software distributed under the License is distributed on an "AS
   - IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
   - implied. See the License for the specific language governing
   - rights and limitations under the License.
   - 
   - The Original Code is the Netscape security libraries.
   - 
   - The Initial Developer of the Original Code is Netscape
   - Communications Corporation.  Portions created by Netscape are 
   - Copyright (C) 1994-2000 Netscape Communications Corporation.  All
   - Rights Reserved.
   - 
   - Contributor(s):
   - 
   - Alternatively, the contents of this file may be used under the
   - terms of the GNU General Public License Version 2 or later (the
   - "GPL"), in which case the provisions of the GPL are applicable 
   - instead of those above.  If you wish to allow use of your 
   - version of this file only under the terms of the GPL and not to
   - allow others to use your version of this file under the MPL,
   - indicate your decision by deleting the provisions above and
   - replace them with the notice and other provisions required by
   - the GPL.  If you do not delete the provisions above, a recipient
   - may use your version of this file under either the MPL or the
   - GPL.
  -->
                                                                        
                              
  <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".  &nbsp;"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.
&nbsp;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. &nbsp;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.  &nbsp;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. 
   &nbsp;This      needs  to be described in a separate document showing how
   to set up a  token    using  CKFW. &nbsp;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. &nbsp;This
 is  not   part  of the exposed API. &nbsp;It is a low-level API allowing
NSS to manage   cryptoki  devices.<br>
 <br>
         The relationship is like this:<br>
 <br>
         libpki --&gt; libdev --&gt; cryptoki<br>
 <br>
         As an example,<br>
 <br>
         NSSTrustDomain_FindCertificate --&gt; NSSToken_FindCertificate --&gt;
   C_FindObjects<br>
 <br>
 <a href="http://lxr.mozilla.org/mozilla/ident?i=NSSModule">NSSModule</a>
 <br>
                     Replaces the SECMOD API. &nbsp;The module manages a
PRLibrary       that   holds  a cryptoki implementation via a number of slots.
&nbsp;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. &nbsp;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? &nbsp;This session would 
 be used for slot management calls (sections 9.5 and9.6 of PKCS#11). &nbsp;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. &nbsp;Much of the 
cryptoki     API   is  directed   towards slots.  &nbsp;However,   some  functionality
   clearly belongs with a token type. &nbsp;For  example,   a certificate
 lives  on a token, not a slot, so one would expect  a function   NSSToken_FindCertificate.
    &nbsp;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. &nbsp;Most 
   functions take  a slotID   as an argument,  even though it is obvious that
     the event   is intended to occur on a token. &nbsp;That leaves various
   possibilities:</li>
   
  <ol>
     <li>Implement the API entirely as NSSToken. &nbsp;If the token  is not 
  present, some calls will simply fail.</li>
     <li>Divide the API between NSSToken and NSSSlot, as described  above. 
&nbsp;NSSSlot  would handle cryptoki calls specified as "slot management",
  while NSSToken  handles actual token operations.</li>
     <li>Others?</li>
   
  </ol>
   <li>Session management. &nbsp;Tokens needs a threadsafe session handle 
 to perform operations. &nbsp;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). &nbsp;For those functions, the token could 
 maintain a default session. &nbsp;Thus all NSSToken API functions would take
 sessionOpt as an argument. &nbsp;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. &nbsp;Created from a slot. &nbsp;Used to manage
  sessions for crypto contexts. &nbsp;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. &nbsp;The way to keep open this  possibility 
 is to keep only generally useful information in the NSSCertificate  type. 
&nbsp;Examples would be the certificate encoding, label, trust (obtained
 from cryptoki calls), an email address, etc. &nbsp;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?&nbsp; 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."       &nbsp;It  is a collection of modules capable of performing 
  cryptographic      operations  and storing certs and keys. &nbsp;This collection 
  is managed     by NSS in a manner opaque to the consumer. &nbsp;The slots 
  will have various      orderings determining which has preference for a 
given  operation. &nbsp;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? &nbsp;We already have the  suggestion 
      that  there be two kinds of ordering: storage and search.  &nbsp;How 
will     they be  constructed/managed? &nbsp;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? &nbsp;Nelson wonders what it means   to   Stan 
    when a cert does not live on a token yet. &nbsp;Bob, Terry, and    I discussed
    this. &nbsp;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). &nbsp;NSSCertificate   would
  keep  a handle to this type, so that it only needs to decode the  cert
once.   &nbsp;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). 
     &nbsp;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. &nbsp;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. &nbsp;Therefore, in a hash of certificates, the key is the certificate 
pointer itself. &nbsp;One possibility is to store the decoded cert (NSSX509DecodedParts 
above) as the value in the {key, value} pair. &nbsp;When a cert is decoded, 
the cert pointer and decoding pointer are added to the hash. &nbsp;Subsequent 
lookups have access to one or both of these pointers. &nbsp;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.  &nbsp;However, 
 it has already been realized that PSM and CMS may need special  access to 
tokens. &nbsp;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. &nbsp;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>
              . &nbsp;The old NSS code had various types related to  algorithms 
    running around in it. &nbsp;We had SECOidTag, SECAlgorithmID,   SECItem's
     for parameters, CK_MECHANISM for cryptoki, etc. &nbsp;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&nbsp;</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&nbsp;new command line tool, pkiutil, has been created to use only
 the   Stan API. &nbsp;It depends on a new library, cmdlib, meant to replace
 the   old secutil library. &nbsp;The old library had code used by products
 that   needed to be integrated into the main library codebase somehow. &nbsp;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. 
  &nbsp;Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil. &nbsp;Then 
  run "pkiutil -L" or "pkiutil --list". &nbsp;The list of certificate nicknames 
  should be displayed.<br>
 <br>
 <br>
 
</body>
</html>