NSS Developer Tutorial

NSS Coding Style

Formatting

Line length should not exceed 80 characters.

Indentation level is 4.

Tabs are used heavily in many NSS source files. Try to stay consistent when you modify existing code. The proper use of tabs has been confusing to new NSS developers. In nss/lib/ssl, I’ve decided to gradually remove the use of tabs.

Curly braces: both of the following styles are allowed:

if (condition) { 
    action1();
} else {
    action2();
}

Or:

if (condition)
{
    action1();
}
else
{
    action2();
}

The former style is more common. When modifying existing code, try to stay consistent. In new code, prefer the former style because it conserves vertical space.

When a block of code consists of a single statement, NSS doesn’t require curly braces, so both of these are fine:

if (condition) { 
    action();
}

Or:

if (condition)
    action();

although the use of curly braces seems more common.

Multiple-line comments should be formatted as follows:

/*
 * Line1
 * Line2
 */ 

or

/*
** Line 1
** Line 2
*/

The following styles are also common because they conserve vertical space:

/* Line1
 * Line2
 */

or

/* Line1
** Line2
*/

or

/* Line1
 * Line2 */

Naming

Public functions are named FOO_DoOneAction.

Global but unexported functions are usually named foo_DoOneAction.

Variable and function parameter names always start with a lowercase letter. The most common style is fooBarBaz, although foobarbaz and foo_bar_baz are also used.

Miscellaneous

goto can be used to simplify resource deallocation before returning from a function.

A data buffer is usually represented as:

unsigned char *data;
unsigned int len;

The buffer pointer is unsigned char * as opposed to void * so that we can perform pointer arithmetic without casting. Use char * only if the data is interpreted as text characters.

For historical reasons, the buffer length is unsigned int as opposed to size_t. Unfortunately this can be a source of integer overflow bugs on 64-bit systems.

C Features

NSS requires C99.  However, not all features from C99 are equally available.

• Variables can be declared at the point they are first used.
• The inline keyword can be used.
• Variadic macro arguments are permitted, but their use should be limited to using __VA_ARGS__.
• The exact-width integer types in NSPR should be used in preference to those declared in <stdint.h> (which will be used by NSPR in the future).
• Universal character names are not permitted as are wide character types (char16_t and char32_t).  NSS source should only include ASCII text.  Escape non-printing characters (with \x if there is no special escape such as \r, \n, and \t) and avoid defining string literals that use non-ASCII characters.
• One line comments starting with // are permitted.

Check with nss-dev@ before using a language feature that is not already used if you are uncertain.  Please update this list if you do.

These restrictions are different for C++ unit tests, which can use most C++11 features.  The Mozilla C++ language features guide and the Chromium C++ usage guide list C++ features that are known to be widely available and compatible.  You should limit features to those that appear in both guides.  Ask on nss-dev@ if you think that this is too restrictive, or if you want to prohibit a specific feature.

NSS C ABI backward compatibility

Functions

Exported functions cannot be removed.

The function prototype of an exported function cannot be changed, with these exceptions:

• A Foo * parameter can be changed to const Foo *. This change is always safe.

• Sometimes an int parameter can be changed to unsigned int, or an int * parameter can be changed to unsigned int *. Whether such a change is safe needs to be reviewed on a case-by-case basis.

Types

Structs

Members of an exported struct cannot be reordered or removed.

Under certain circumstances it is safe to add new members to an exported struct at the end.

Opaque structs give us complete freedom to change them, but require applications to call NSS functions to allocate and free them.

Enums

The numeric values of public enumerators cannot be changed. To stress this fact, we often explicitly assign numeric values to enumerators rather than relying on the values assigned by the compiler.

Symbol export lists

The manifest.mn file in a directory in the NSS source tree specifies which headers are public and which headers are private.

Public headers are in the EXPORTS variable.

Private headers that may be included by files in other directories are in the PRIVATE_EXPORTS variable.

Private headers that are only included by files in the same directory are not listed in either variable.

Only functions listed in the symbol export lists (nss.def, ssl.def, smime.def, etc.) are truly public functions. Unfortunately public headers may declare private functions for historical reasons. The symbol export lists are the authoritative source of public functions.

Behavioral changes

Bug/quirk compatible: Occasionally we cannot fix a bug because applications may depend on the buggy behavior; we need to add a new function to provide the proper behavior.

Similarly, new options often need to be disabled by default.

NSS review/feature approval process

NSS doesn’t have super reviewers. We should increase the number of NSS developers who have broad understanding of NSS.

One review is usually enough. For critical code reviews, such as a patch release of a stable branch, two reviews may be prudent.

For new features, especially those that appear controversial, try to find a reviewer from a different company/organization to avoid the appearance that a single company/organization unilaterally adds that new feature.

Update NSS in mozilla-inbound and mozilla-central

The procedure is documented at https://developer.mozilla.org/en-US/docs/Updating_NSPR_or_NSS_in_mozilla-central.

If it is necessary to apply private patches, please document them in <tree>/security/patches/README.