# 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 `NSSItem`s.

String types -- even complicated `CHOICE`s 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 `PRTime`s; 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.