diff options
Diffstat (limited to 'security/nss/lib/pkix/doc/name_rules.html')
| -rw-r--r-- | security/nss/lib/pkix/doc/name_rules.html | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/security/nss/lib/pkix/doc/name_rules.html b/security/nss/lib/pkix/doc/name_rules.html new file mode 100644 index 000000000..70f9dd72e --- /dev/null +++ b/security/nss/lib/pkix/doc/name_rules.html @@ -0,0 +1,178 @@ +<!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> |