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: 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: Optional fields also have ``Has'' and ``Remove'' methods, constructed in the same way.
 

Sequences

Sequences have the following accessors: Sets (unordered sequences) replace the Append and Insert methods with Add.  The plural Get and Set methods operate on arrays of the subtype.