~ubuntu-branches/ubuntu/quantal/nss/quantal-updates

« back to all changes in this revision

Viewing changes to mozilla/security/nss/lib/pki/doc/standoc.html

  • Committer: Package Import Robot
  • Author(s): Marc Deslauriers
  • Date: 2013-11-14 14:58:07 UTC
  • mfrom: (1.1.19)
  • Revision ID: package-import@ubuntu.com-20131114145807-vj6v4erz8xj6kwz3
Tags: 3.15.3-0ubuntu0.12.10.1
* SECURITY UPDATE: New upstream release to fix multiple security issues
  and add TLSv1.2 support.
  - CVE-2013-1739
  - CVE-2013-1741
  - CVE-2013-5605
  - CVE-2013-5606
* Adjusted packaging for 3.15.3:
  - debian/patches/*: refreshed.
  - debian/patches/lower-dhe-priority.patch: removed, no longer needed,
    was a workaround for an old version of firefox.
  - debian/libnss3.symbols: added new symbols.
  - debian/rules: updated for new source layout.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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".  &nbsp;"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
 
&nbsp;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. &nbsp;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.  &nbsp;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
 
   &nbsp;This      needs  to be described in a separate document showing how
139
 
   to set up a  token    using  CKFW. &nbsp;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. &nbsp;This
150
 
 is  not   part  of the exposed API. &nbsp;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 --&gt; libdev --&gt; cryptoki<br>
156
 
 <br>
157
 
         As an example,<br>
158
 
 <br>
159
 
         NSSTrustDomain_FindCertificate --&gt; NSSToken_FindCertificate --&gt;
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. &nbsp;The module manages a
165
 
PRLibrary       that   holds  a cryptoki implementation via a number of slots.
166
 
&nbsp;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. &nbsp;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? &nbsp;This session would 
180
 
 be used for slot management calls (sections 9.5 and9.6 of PKCS#11). &nbsp;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. &nbsp;Much of the 
190
 
cryptoki     API   is  directed   towards slots.  &nbsp;However,   some  functionality
191
 
   clearly belongs with a token type. &nbsp;For  example,   a certificate
192
 
 lives  on a token, not a slot, so one would expect  a function   NSSToken_FindCertificate.
193
 
    &nbsp;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. &nbsp;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. &nbsp;That leaves various
200
 
   possibilities:</li>
201
 
   
202
 
  <ol>
203
 
     <li>Implement the API entirely as NSSToken. &nbsp;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
 
&nbsp;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. &nbsp;Tokens needs a threadsafe session handle 
212
 
 to perform operations. &nbsp;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). &nbsp;For those functions, the token could 
216
 
 maintain a default session. &nbsp;Thus all NSSToken API functions would take
217
 
 sessionOpt as an argument. &nbsp;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. &nbsp;Created from a slot. &nbsp;Used to manage
226
 
  sessions for crypto contexts. &nbsp;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. &nbsp;The way to keep open this  possibility 
245
 
 is to keep only generally useful information in the NSSCertificate  type. 
246
 
&nbsp;Examples would be the certificate encoding, label, trust (obtained
247
 
 from cryptoki calls), an email address, etc. &nbsp;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?&nbsp; 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."       &nbsp;It  is a collection of modules capable of performing 
272
 
  cryptographic      operations  and storing certs and keys. &nbsp;This collection 
273
 
  is managed     by NSS in a manner opaque to the consumer. &nbsp;The slots 
274
 
  will have various      orderings determining which has preference for a 
275
 
given  operation. &nbsp;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? &nbsp;We already have the  suggestion 
282
 
      that  there be two kinds of ordering: storage and search.  &nbsp;How 
283
 
will     they be  constructed/managed? &nbsp;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? &nbsp;Nelson wonders what it means   to   Stan 
287
 
    when a cert does not live on a token yet. &nbsp;Bob, Terry, and    I discussed
288
 
    this. &nbsp;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). &nbsp;NSSCertificate   would
291
 
  keep  a handle to this type, so that it only needs to decode the  cert
292
 
once.   &nbsp;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
 
     &nbsp;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. &nbsp;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. &nbsp;Therefore, in a hash of certificates, the key is the certificate 
301
 
pointer itself. &nbsp;One possibility is to store the decoded cert (NSSX509DecodedParts 
302
 
above) as the value in the {key, value} pair. &nbsp;When a cert is decoded, 
303
 
the cert pointer and decoding pointer are added to the hash. &nbsp;Subsequent 
304
 
lookups have access to one or both of these pointers. &nbsp;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.  &nbsp;However, 
309
 
 it has already been realized that PSM and CMS may need special  access to 
310
 
tokens. &nbsp;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. &nbsp;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
 
              . &nbsp;The old NSS code had various types related to  algorithms 
342
 
    running around in it. &nbsp;We had SECOidTag, SECAlgorithmID,   SECItem's
343
 
     for parameters, CK_MECHANISM for cryptoki, etc. &nbsp;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&nbsp;</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&nbsp;new command line tool, pkiutil, has been created to use only
418
 
 the   Stan API. &nbsp;It depends on a new library, cmdlib, meant to replace
419
 
 the   old secutil library. &nbsp;The old library had code used by products
420
 
 that   needed to be integrated into the main library codebase somehow. &nbsp;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
 
  &nbsp;Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil. &nbsp;Then 
436
 
  run "pkiutil -L" or "pkiutil --list". &nbsp;The list of certificate nicknames 
437
 
  should be displayed.<br>
438
 
 <br>
439
 
 <br>
440
 
 
441
 
</body>
442
 
</html>