Notes on libpkix name rules
Types
Every type mentioned in RFC 2459 is reflected in libpkix. The type
names, defined in nsspkix.h, are exactly the names used in the
RFC with the added prefix of ``NSSPKIX.'' The PKIX
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, NSSPKIXCertificate is
a type with specific properties defined in RFC 2459, while NSSCertificate
is a general type, not necessarily based on an X.509 certificate, that
has additional associated information.
Additionally, libpkix defines some "helper" types, usually when
a type definition in the RFC was unusually complex. These types
are prefixed with NSSPKIX as above, but the next letter is lowercase.
Examples of these types include NSSPKIXrevokedCertificates and
NSSPKIXpolicyMapping.
Simple types
Many types used in or defined by RFC 2459 have more-or-less equivalent
``natural'' types. These include BOOLEAN, INTEGER,
the string types, and the date types.
BOOLEAN values are always automatically converted to and from
PRBool types.
INTEGER 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 PRInt32 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 NSSItems.
String types -- even complicated CHOICEs of strings -- are
always converted to and from NSSUTF8 strings. Most of the
string types can handle any UTF-8 string; the few that don't will check
the NSSUTF8 string for invalid characters and return an error
if any are found.
Date types are always converted to and from PRTime values.
***FGMR*** or whatever.
The RFC-defined types may contain values that may not be represented as
PRTimes; when conversion of such a value is attempted, the error
NSS_ERROR_VALUE_OUT_OF_RANGE 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
PRTime.
Function names
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.)
Universal methods
Every type has a few standard methods:
-
<typename>_CreateFromBER
-
<typename>_Create
-
<typename>_Destroy
-
<typename>_GetDEREncoding
-
<typename>_Equal
-
<typename>_Duplicate
For types for which a BER encoding can be created
which is not the DER encoding, there is a method <typename>_GetBEREncoding.
Accessors
Simple accessor method names are constructed with
``Get'' and ``Set'' followed by the field name:
-
<typename>_Get<fieldname>
-
<typename>_Set<fieldname>
Optional fields also have ``Has'' and ``Remove''
methods, constructed in the same way.
Sequences
Sequences have the following accessors:
-
<typename>_Get<name>Count
-
<typename>_Get<name>s
-
<typename>_Set<name>s
-
<typename>_Get<name>
-
<typename>_Set<name>
-
<typename>_Append<name>
-
<typename>_Insert<name>
-
<typename>_Remove<name>
-
<typename>_Find<name>
Sets (unordered sequences) replace the Append
and Insert methods with Add. The plural Get and
Set methods operate on arrays of the subtype.