179 lines
7.6 KiB
HTML
179 lines
7.6 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<!--
|
|
- 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.
|
|
-->
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.6 [en] (X11; U; IRIX 6.3 IP32) [Netscape]">
|
|
</head>
|
|
<body>
|
|
|
|
<h1>
|
|
Notes on libpkix name rules</h1>
|
|
|
|
<h2>
|
|
Types</h2>
|
|
Every type mentioned in RFC 2459 is reflected in libpkix. The type
|
|
names, defined in <tt>nsspkix.h</tt>, are exactly the names used in the
|
|
RFC with the added prefix of ``<tt>NSSPKIX</tt>.'' The <tt>PKIX</tt>
|
|
part of the name is to distinguish between these specifically defined types
|
|
and more general reflections that are used in higher-level trust domains,
|
|
crypto contexts, etc. For example, <tt>NSSPKIXCertificate</tt> is
|
|
a type with specific properties defined in RFC 2459, while <tt>NSSCertificate</tt>
|
|
is a general type, not necessarily based on an X.509 certificate, that
|
|
has additional associated information.
|
|
<p>Additionally, libpkix defines some "helper" types, usually when
|
|
a type definition in the RFC was unusually complex. These types
|
|
are prefixed with <tt>NSSPKIX</tt> as above, but the next letter is lowercase.
|
|
Examples of these types include <tt>NSSPKIXrevokedCertificates</tt> and
|
|
<tt>NSSPKIXpolicyMapping</tt>.
|
|
<br>
|
|
<h2>
|
|
Simple types</h2>
|
|
Many types used in or defined by RFC 2459 have more-or-less equivalent
|
|
``natural'' types. These include <tt>BOOLEAN</tt>, <tt>INTEGER</tt>,
|
|
the string types, and the date types.
|
|
<p><tt>BOOLEAN</tt> values are always automatically converted to and from
|
|
<tt>PRBool</tt> types.
|
|
<p><tt>INTEGER</tt> types are used in two ways: as a ``small integer,''
|
|
typically a quantity, and as an identification value (e.g., the serial
|
|
number of a certificate). In the former situation, the RFC usually
|
|
states that the values may be limited by the application to some value.
|
|
We reflect these integers as <tt>PRInt32</tt> values, which is limited
|
|
to about two billion. (The reason an unsigned integer wasn't used
|
|
is that we use -1 as an error value; while admittedly reserving one half
|
|
of the number space merely to indicate an error is perhaps wasteful, reducing
|
|
the count limit from four billion to two isn't that unreasonable.)
|
|
``Large integer'' uses are reflected as <tt>NSSItem</tt>s.
|
|
<p>String types -- even complicated <tt>CHOICE</tt>s of strings -- are
|
|
always converted to and from <tt>NSSUTF8</tt> strings. Most of the
|
|
string types can handle any UTF-8 string; the few that don't will check
|
|
the <tt>NSSUTF8</tt> string for invalid characters and return an error
|
|
if any are found.
|
|
<p>Date types are always converted to and from <tt>PRTime</tt> values.
|
|
<font color="#FF0000">***FGMR*** or whatever.</font><font color="#000000">
|
|
The RFC-defined types may contain values that may not be represented as
|
|
<tt>PRTime</tt>s; when conversion of such a value is attempted, the error
|
|
<tt>NSS_ERROR_VALUE_OUT_OF_RANGE</tt> will be returned. However,
|
|
types that contain time values have comparator methods defined, so that
|
|
valid comparisons may be made, even if the time is out of the range of
|
|
<tt>PRTime</tt>.</font>
|
|
<br><font color="#000000"></font>
|
|
<h2>
|
|
<font color="#000000">Function names</font></h2>
|
|
<font color="#000000">All function names are created by catenating the
|
|
type name, an underscore, and the name of a method defined on that type.
|
|
In some situations, this does create rather long function names; however,
|
|
since these are usually assocated with the more obscure types, we felt
|
|
that sticking to a common naming system was preferable to inventing new
|
|
names. (The Principle of Least Surprise.)</font>
|
|
<br><font color="#000000"></font>
|
|
<h2>
|
|
<font color="#000000">Universal methods</font></h2>
|
|
<font color="#000000">Every type has a few standard methods:</font>
|
|
<ul>
|
|
<li>
|
|
<tt><font color="#000000"><typename>_CreateFromBER</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Create</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Destroy</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_GetDEREncoding</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Equal</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Duplicate</font></tt></li>
|
|
</ul>
|
|
<font color="#000000">For types for which a BER encoding can be created
|
|
which is not the DER encoding, there is a method <tt><typename>_GetBEREncoding</tt>.</font>
|
|
<br><font color="#000000"></font>
|
|
<h2>
|
|
<font color="#000000">Accessors</font></h2>
|
|
<font color="#000000">Simple accessor method names are constructed with
|
|
``<tt>Get</tt>'' and ``<tt>Set</tt>'' followed by the field name:</font>
|
|
<ul>
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Get<fieldname></font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Set<fieldname></font></tt></li>
|
|
</ul>
|
|
<font color="#000000">Optional fields also have ``<tt>Has</tt>'' and ``<tt>Remove</tt>''
|
|
methods, constructed in the same way.</font>
|
|
<br><font color="#000000"></font>
|
|
<h2>
|
|
<font color="#000000">Sequences</font></h2>
|
|
<font color="#000000">Sequences have the following accessors:</font>
|
|
<ul>
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Get<name>Count</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Get<name>s</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Set<name>s</font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Get<name></font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Set<name></font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Append<name></font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Insert<name></font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Remove<name></font></tt></li>
|
|
|
|
<li>
|
|
<tt><font color="#000000"><typename>_Find<name></font></tt></li>
|
|
</ul>
|
|
<font color="#000000">Sets (unordered sequences) replace the <tt>Append</tt>
|
|
and <tt>Insert</tt> methods with <tt>Add</tt>. The plural Get and
|
|
Set methods operate on arrays of the subtype.</font>
|
|
<br><font color="#000000"></font>
|
|
<br><font color="#000000"></font>
|
|
<br><font color="#000000"></font>
|
|
</body>
|
|
</html>
|