mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-14 22:05:44 +00:00
work-in-progress document for stan development
This commit is contained in:
mcgreer%netscape.com
parent
a0dfc55f94
commit
bc2abb1968
438
security/nss/lib/pki/doc/standoc.html
Normal file
438
security/nss/lib/pki/doc/standoc.html
Normal file
@ -0,0 +1,438 @@
|
||||
<!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". "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. 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. 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. 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.
|
||||
This needs to be described in a separate document showing how
|
||||
to set up a token using CKFW. 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. This is
|
||||
not part of the exposed API. It is a low-level API allowing NSS
|
||||
to manage cryptoki devices.<br>
|
||||
<br>
|
||||
The relationship is like this:<br>
|
||||
<br>
|
||||
libpki --> libdev --> cryptoki<br>
|
||||
<br>
|
||||
As an example,<br>
|
||||
<br>
|
||||
NSSTrustDomain_FindCertificate --> NSSToken_FindCertificate -->
|
||||
C_FindObjects<br>
|
||||
<br>
|
||||
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSModule">NSSModule</a>
|
||||
<br>
|
||||
Replaces the SECMOD API. The module manages a PRLibrary
|
||||
that holds a cryptoki implementation via a number of slots. 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. 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>
|
||||
<br>
|
||||
<a href="http://lxr.mozilla.org/mozilla/ident?i=NSSToken">NSSToken</a>
|
||||
<br>
|
||||
Fills in the gaps left by NSSSlot. Much of the cryptoki
|
||||
API is directed towards slots. However, some functionality
|
||||
clearly belongs with a token type. For example, a certificate lives
|
||||
on a token, not a slot, so one would expect a function NSSToken_FindCertificate.
|
||||
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. Most
|
||||
functions take a slotID as an argument, even though it is obvious that
|
||||
the event is intended to occur on a token. That leaves various
|
||||
possibilities:</li>
|
||||
|
||||
<ol>
|
||||
|
||||
<li>Implement the API entirely as NSSToken. If the token is not
|
||||
present, some calls will simply fail.</li>
|
||||
|
||||
<li>Divide the API between NSSToken and NSSSlot, as described above. NSSSlot
|
||||
would handle cryptoki calls specified as "slot management", while NSSToken
|
||||
handles actual token operations.</li>
|
||||
|
||||
<li>Others?<br>
|
||||
</li>
|
||||
|
||||
</ol>
|
||||
|
||||
</ol>
|
||||
<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. The way to keep open this possibility
|
||||
is to keep only generally useful information in the NSSCertificate type. Examples
|
||||
would be the certificate encoding, label, trust (obtained from cryptoki calls),
|
||||
an email address, etc. 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? 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." It is a collection of modules capable of performing
|
||||
cryptographic operations and storing certs and keys. This collection
|
||||
is managed by NSS in a manner opaque to the consumer. The slots
|
||||
will have various orderings determining which has preference for a given
|
||||
operation. 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? We already have the suggestion
|
||||
that there be two kinds of ordering: storage and search. How will
|
||||
they be constructed/managed? 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? Nelson wonders what it means to Stan
|
||||
when a cert does not live on a token yet. Bob, Terry, and I discussed
|
||||
this. 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). NSSCertificate would
|
||||
keep a handle to this type, so that it only needs to decode the cert once.
|
||||
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).
|
||||
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. Note that this is essentially the same as CERT_TempCertToPerm.</li>
|
||||
|
||||
<li>The API is designed to keep token details hidden from the user. However,
|
||||
it has already been realized that PSM and CMS may need special access to tokens.
|
||||
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>
|
||||
<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>
|
||||
. The old NSS code had various types related to algorithms
|
||||
running around in it. We had SECOidTag, SECAlgorithmID, SECItem's
|
||||
for parameters, CK_MECHANISM for cryptoki, etc. 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>
|
||||
|
||||
<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 </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 new command line tool, pkiutil, has been created to use only the
|
||||
Stan API. It depends on a new library, cmdlib, meant to replace the
|
||||
old secutil library. The old library had code used by products that
|
||||
needed to be integrated into the main library codebase somehow. 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.
|
||||
Copy "libnssckbi.so" (or whatever it is) to cmd/pkiutil. Then
|
||||
run "pkiutil -L" or "pkiutil --list". The list of certificate nicknames
|
||||
should be displayed.<br>
|
||||
<br>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue
Block a user