Source code
Revision control
Copy as Markdown
Other Tools
.. _mozilla_projects_nss_nss_api_guidelines:
NSS API Guidelines
==================
.. container::
`Introduction <#introduction>`__
--------------------------------
.. container::
This document describes how the NSS code is organized, the libraries that get built from the NSS
sources, and guidelines for writing NSS code. These guidelines will familiarize you with some of
the ways things can be done in the NSS code. This will help you understand existing NSS code. It
should also help you understand how to write new code, and where to place it.
Some of the guidelines in this document, are more forward-looking than documentary. These rules
are here to help us all immediately achieve more consistent and usable code, but some existing
code won't follow all these rules.
.. _nss_api_structure:
`NSS API Structure <#nss_api_structure>`__
------------------------------------------
.. container::
This section explains the structure and relationships of the NSS libraries. The
`Layering <#layering>`__ section explains how the NSS code is layered, and how higher-level
functions wrap low-level functions. The `Libraries <#libraries>`__ section describes the NSS
libraries, the functionality each provides, and the layer in which the library (mostly) operates.
`Layering <#layering>`__
~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
Each separate component of the API should live in its own layer. The functions in these APIs
should never call API layers above them. In addition, some low-level APIs may be completely
opaque to higher level layers. That is, access to these functions should only be provided by the
API directly above them. The NSS APIs are layered, as shown in this diagram:
.. image:: /en-US/docs/Mozilla/Projects/NSS/NSS_API_Guidelines/layer.gif
:alt: A diagram of the different layers that collectively make up "NSS". Dependencies are only
permitted between siblings and layers below them.
:width: 427px
:height: 507px
The boxes in the gray section, towards the center, are exported only through PKCS #11. PKCS #11
is only exported through the Wrappers. The areas which need the most work (both here and
throughout the code) is:
#. The relationship of the Certificate library with just about every other component (most
noticeably PKCS #12, PKCS #7, and PKCS #11)
#. Splitting Low Key and High Key components more clearly
#. The Crypto wrappers (PKCS #11 Wrappers) and High Key
#. PKCS #12 and PKCS #5
`Libraries <#libraries>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
NSS compiles into the libraries described below. The Layer indicates the main layer, seen in the
previous diagram, in which the library operates. The Directory is the location of the library
code in the NSS source tree. The Public Headers is a list of header files that contain types, and
functions, that are publicly available to higer-level APIs.
+----------+---------------------+---------------------+---------------+---------------------+
| Library | Description | Layer | Directory | Public Headers |
+----------+---------------------+---------------------+---------------+---------------------+
| certdb | Provides all | Low Cert | lib/certdb | cdbhdl.h, certdb.h, |
| | certificate | | | cert.h, certt.h |
| | handling functions | | | |
| | and types. The | | | |
| | certdb library | | | |
| | manipulates the | | | |
| | certificate | | | |
| | database (add, | | | |
| | create, delete | | | |
| | certificates and | | | |
| | CRLs). It also | | | |
| | provides general | | | |
| | c | | | |
| | ertificate-handling | | | |
| | routines (create a | | | |
| | certificate, | | | |
| | verify, add/check | | | |
| | certificate | | | |
| | extensions). | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| certhi | Provides high-level | High Cert | lib/certhigh | ocsp.h, ocspt.h |
| | certificate-related | | | |
| | functions, that do | | | |
| | not access the | | | |
| | certificate | | | |
| | database, nor | | | |
| | individual | | | |
| | certificate data | | | |
| | directly. | | | |
| | Currently, OCSP | | | |
| | checking settings | | | |
| | are exported | | | |
| | through certhi. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| crmf | Provides functions, | Same Level as SSL | lib/crmf | cmmf.h, crmf.h, |
| | and data types, to | | | crmft.h, cmmft.h, |
| | handle Certificate | | | crmffut.h |
| | Management Message | | | |
| | Format (CMMF) and | | | |
| | Certificate Request | | | |
| | Message Format | | | |
| | (CRMF, see `RFC | | | |
| | tracker.ietf.org/do | | | |
| | c/html/rfc2511>`__) | | | |
| | data. CMMF no | | | |
| | longer exists as a | | | |
| | proposed standard; | | | |
| | CMMF functions have | | | |
| | been incorporated | | | |
| | into the proposal | | | |
| | for `Certificate | | | |
| | Management | | | |
| | Protocols | | | |
| | tracker.ietf.org/do | | | |
| | c/html/rfc2510>`__. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| cryptohi | Provides high-level | Sign/Verify | lib/cryptohi | cryptohi.h, |
| | cryptographic | | | cryptoht.h, |
| | support operations: | | | hasht.h, keyhi.h, |
| | such as signing, | | | keythi.h, key.h, |
| | verifying | | | keyt.h, sechash.h |
| | signatures, key | | | |
| | generation, key | | | |
| | manipulation, | | | |
| | hashing; and data | | | |
| | types. This code is | | | |
| | above the PKCS #11 | | | |
| | layer. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| fort | Provides a PKCS #11 | PKCS #11 | lib/fortcrypt | cryptint.h, |
| | interface, to | | | fmutex.h, |
| | Fortezza crypto | | | fortsock.h, |
| | services. Fortezza | | | fpkcs11.h, |
| | is a set of | | | fpkcs11f.h, |
| | security | | | fpkcs11t.h, |
| | algorithms, used by | | | fpkmem.h, |
| | the U.S. | | | fpkstrs.h, genci.h, |
| | government. There | | | maci.h |
| | is also a SWFT | | | |
| | library that | | | |
| | provides a | | | |
| | software-only | | | |
| | implementation of a | | | |
| | PKCS #11 Fortezza | | | |
| | token. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| freebl | Provides the API to | Within PKCS #11, | lib/freebl | blapi.h, blapit.h |
| | actual | wraps Crypto | | |
| | cryptographic | | | |
| | operations. The | | | |
| | freebl is a wrapper | | | |
| | API. You must | | | |
| | supply a library | | | |
| | that implements the | | | |
| | cryptographic | | | |
| | operations, such as | | | |
| | BSAFE from RSA | | | |
| | Security. This is | | | |
| | also known as the | | | |
| | "bottom layer" API, | | | |
| | or BLAPI. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| jar | Provides support | Port | lib/jar | jar-ds.h, jar.h, |
| | for reading and | | | jarfile.h |
| | writing data in | | | |
| | Java Archive (jar) | | | |
| | format, including | | | |
| | zlib compression. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| nss | Provides high-level | Above High Cert, | lib/nss | nss.h |
| | initialiazation and | High Key | | |
| | shutdown of | | | |
| | security services. | | | |
| | Specifically, this | | | |
| | library provides | | | |
| | NSS_Init() for | | | |
| | establishing | | | |
| | default | | | |
| | certificate, key, | | | |
| | module databases, | | | |
| | and initializing a | | | |
| | default random | | | |
| | number generator. | | | |
| | NSS_Shutdown() | | | |
| | closes these | | | |
| | databases, to | | | |
| | prevent further | | | |
| | access by an | | | |
| | application. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| pk11wrap | Provides access to | Crypto Wrapper | lib/pk11wrap | pk11func.h, |
| | PKCS #11 modules, | | | secmod.h, secmodt.h |
| | through a unified | | | |
| | interface. The | | | |
| | pkcs11wrap library | | | |
| | provides functions | | | |
| | for | | | |
| | selecting/finding | | | |
| | PKCS #11 modules | | | |
| | and slots. It also | | | |
| | provides functions | | | |
| | that invoke | | | |
| | operations in | | | |
| | selected modules | | | |
| | and slots, such as | | | |
| | key selection and | | | |
| | generation, | | | |
| | signing, encryption | | | |
| | and decryption, | | | |
| | etc. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| pkcs12 | Provides functions | PKCS #12 | lib/pkcs12 | pkcs12t.h, |
| | and types for | | | pkcs12.h, |
| | encoding and | | | p12plcy.h, p12.h, |
| | decoding PKCS #12 | | | p12t.h |
| | data. PKCS #12 can | | | |
| | be used to encode | | | |
| | keys, and | | | |
| | certificates, for | | | |
| | export or import | | | |
| | into other | | | |
| | applications. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| pkcs7 | Provides functions | PKCS #7 | lib/pkcs7 | secmime.h, |
| | and types for | | | secpkcs7.h, |
| | encoding and | | | pkcs7t.h |
| | decoding encrypted | | | |
| | data in PKCS #7 | | | |
| | format. For | | | |
| | example, PKCS #7 is | | | |
| | used to encrypt | | | |
| | certificate data to | | | |
| | exchange between | | | |
| | applications, or to | | | |
| | encrypt S/MIME | | | |
| | message data. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| softoken | Provides a software | PKCS #11: | lib/softoken | keydbt.h, keylow.h, |
| | implementation of a | implementation | | keytboth.h, |
| | PKCS #11 module. | | | keytlow.h, |
| | | | | secpkcs5.h, |
| | | | | pkcs11.h, |
| | | | | pkcs11f.h, |
| | | | | pkcs11p.h, |
| | | | | pkcs11t.h, |
| | | | | pkcs11u.h |
+----------+---------------------+---------------------+---------------+---------------------+
| ssl | Provides an | SSL | lib/ssl | ssl.h, sslerr.h, |
| | implementation of | | | sslproto.h, |
| | the SSL protocol | | | preenc.h |
| | using NSS and NSPR. | | | |
+----------+---------------------+---------------------+---------------+---------------------+
| secutil | Provides utility | Utility for any | lib/util | base64.h, |
| | functions and data | Layer | | ciferfam.h, |
| | types used by other | | | nssb64.h, |
| | libraries. The | | | nssb64t.h, |
| | library supports | | | nsslocks.h, |
| | base-64 | | | nssrwlk.h, |
| | encoding/decoding, | | | nssrwlkt.h, |
| | reader-writer | | | portreg.h, |
| | locks, the SECItem | | | pqgutil.h, |
| | data type, DER | | | secasn1.h, |
| | encoding/decoding, | | | secasn1t.h, |
| | error types and | | | seccomon.h, |
| | numbers, OID | | | secder.h, |
| | handling, and | | | secdert.h, |
| | secure random | | | secdig.h, |
| | number generation. | | | secdigt.h, |
| | | | | secitem.h, |
| | | | | secoid.h, |
| | | | | secoidt.h, |
| | | | | secport.h, |
| | | | | secrng.h, |
| | | | | secrngt.h, |
| | | | | secerr.h, |
| | | | | watcomfx.h |
+----------+---------------------+---------------------+---------------+---------------------+
.. _naming_conventions:
`Naming Conventions <#naming_conventions>`__
--------------------------------------------
.. container::
This section describes the rules that (ideally) should be followed for naming and identifying new
files, functions, and data types.
.. _cvs_id:
`CVS ID <#cvs_id>`__
~~~~~~~~~~~~~~~~~~~~
.. container::
Each file should include a CVS ID string for identification. The preferred format is:
.. code::
"@(#) $RCSfile: nss-guidelines.html,
v $ $Revision: 48936 $ $Date: 2009-08-11 07:45:57 -0700 (Tue, 11 Aug 2009) $ $Name$"
You can put the string in a comment or in a static char array. Use #ifdef DEBUG to include the
array in debug builds only. The advantage of using an array is that you can use strings(1) to
pull the ID tags out of a (debug) compiled library. You can even put them in header files; the
header files are protected from double inclusion. The only catch is that you have to determine
the name of the array.
Here is an example from lib/base/baset.h:
.. code::
#ifdef DEBUG
static const char BASET_CVS_ID[] = "@(#) $RCSfile: nss-guidelines.html,
v $ $Revision: 48936 $ $Date: 2009-08-11 07:45:57 -0700 (Tue, 11 Aug 2009) $ $Name$";
#endif /* DEBUG */
The difference, between this and Id, is that Id has some useless information (*every* file is
"experimental"), and doesn't have Name. Name is the tag (if any) from which this file was pulled.
If you're good with tagging your releases, and then checking out (or exporting!) from the tag for
your build, this saves you from messing around with specific files revision numbers.
.. _header_files:
`Header Files <#header_files>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
| We have a preferred naming system for include files. We had been moving towards one, for some
time, but for the NSS 3.0 project we finally wrote it down.
|
========================= =========== ===================
\ Data Types Function Prototypes
Public nss____t.h nss____.h
Friend (only if required) nss____tf.h nss____f.h
NSS-private \____t.h \____.h
Module-private \____tm.h \____m.h
========================= =========== ===================
The files on the right include the files to their left; the files in a row include the files
directly above them. Header files always include what they need; the files are protected against
double inclusion (and even double opening by the compiler).
.. note::
Note: It's not necessary all eight files exist. Further, this is a simple ideal, and often
reality is more complex.
We would like to keep names to 8.3, even if we no longer support win16. This usually gives us
four characters to identify a module of NSS.
In short:
#. Header files for consumption outside NSS start with "nss."
#. Header files with types have a trailing "t", header files with prototypes don't.
"extern" declarations of data also go in the prototypes files.
#. "Friend" headers are for things that we really wish weren't used by non-NSS code, but which
are. Those files have a trailing "f," and their use should be deprecated.
#. "Module" headers are for things used only within a specific subset of NSS; things which would
have been "static" if we had combined separate C source files together. These header files
have a trailing "m."
.. _functions_and_types:
`Functions and Types <#functions_and_types>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
There are a number of ways of doing things in our API, as well as naming decisions for functions
that can affect the usefulness of our library. If our library is self-consistent with how we
accomplish these tasks, it makes it easier for the developer to learn how to use our functions.
This section of the document should grow as we develop our API.
First some general rules. These rules are derived from existing coding practices inside the
security library, since consistency is more important than debates about what might look nice.
#. **Public functions** should have the form LAYER_Body(), where LAYER is an all caps prefix for
what layer the function lives in, and Body is concatenated English words, where the beginning
letter of each word is capitalized (also known as
LAYER_CapitalizedEnglishWords() or CERT_DestroyCertificate().
#. **Data types** and typdefs should have the Form LAYERBody, with the same definitions for LAYER
as public functions, and Body in camel case English words. For example:
LAYERCapitalizedEnglishWords or SECKEYPrivateKey.
#. **Structures** should have the same name as their typedefs, with the string Str added to the
end. For example LAYERCapitalizedEnglishWordsStr or SECKEYPrivateKeyStr.
#. **Private functions** should have the form layer_Body(), where layer is the all lower case
prefix for what layer the function lives in, and Body is camel case English words. Private
functions include functions that may be "public" in a C sense, but are not exported out of the
layer. For example: layer_CapitalizedEnglishWords() or pk11_GenerateKeyID().
#. **Public macros** should have the form LAYER_BODY(), where LAYER is an all caps prefix for
what layer the macro lives in, and BODY is English words, all in upper case, separated by
underscores. For example: LAYER_UPPER_CASE_ENGLISH_WORDS() or DER_CONVERT_BIT_STRING().
#. **Structure members** for exposed data structures should have the form capitalizedEnglishWords
(the first letter uncapitalized). For example: PK11RSAGenParamsStr.\ **keySizeInBits**
#. For **members of enums**, our current API has no standard (typedefs for enums should follow
the Data types standard). There seem to be three reasonable options:
#. Enum members have the same standard as exposed data structure members.
#. Enum members have the same standard as data types.
#. Enum members have the same standard as public macros (minus the '()' of course).
Options 2 and 3 are the more preferred options. Option 1, currently the most common used for
enums, actually creates namespace pollution.
#. **Callback functions**, and functions used in function tables, should have a typedef used to
define the complete signature of the given function. Function typedefs should have the
following format: LAYERBody(), with the same definitions for LAYER as public functions, and
Body is camel case English words. For example: LAYERCapitalizedEnglishWords or
SECKEYPrivateKey.
.. _opaque_data_structures:
`Opaque Data Structures <#opaque_data_structures>`__
----------------------------------------------------
.. container::
There are many data structures in the security library whose definition is effectively private,
to the portion of the security library that defines and operates on those data structures.
External code does not have access to these definitions. The goal here is to increase the
opaqueness of these structures. This will allow us to modify the size, definition, and format of
these data structures in future releases, without interfering with the operation of existing
applications that use the security library.
The first task is to ensure the data structure definition lives in a private header file, while
its declaration lives in the public. The current standard in the security library is to typedef
the data structure name, the easiest way to accomplish this would be to add the typedef to the
public header file.
For example, for the structure SECMyOpaqueData you would add:
.. code::
typedef struct SECMyOpaqueDataStr SECMyOpaqueData;
and add the actual structure definition to the private header file. In this same example:
.. code::
struct SECMyOpaqueDataStr {
unsigned long myPrivateData1;
unsigned long myPrivateData2;
char *myName;
};
the second task is to determine if individual data fields, within the data structure, are part of
the API. One example may be the peerCert field, in an SSL data structure. Accessor functions, for
these data elements, should be added to the API.
There can be legitimate exceptions to this 'make everything opaque' rule. For example, in
container structures, such as SECItem, or maybe linked list data structures. These data
structures need to be examined on a case by case basis, to determine if
#. They are truly stable and will not change in future release
#. It is necessary for the callers of the API to know the size of these structures, as they may
allocate new ones and pass them down.
.. _memory_allocation_with_arenas:
`Memory Allocation with Arenas <#memory_allocation_with_arenas>`__
------------------------------------------------------------------
.. container::
This section discusses memory allocation using arenas. NSS code uses arenas, and this section
explains some of the improvements we are making.
NSS makes use of traditional memory allocation functions, wrapping NSPR's PR_Alloc in a util
function called PORT_Alloc. Though NSS makes further use of an NSPR memory-allocation facility
which uses 'Arenas' and 'ArenaPools'. This was added via javascript; a fast, lightweight,
non-thread-safe (though 'free-threaded') implementation.
Experience shows that users of the security library expect arenas to be threadsafe, so we added
locking, and other useful changes.
- There has always been confusion as to the difference between Arenas and ArenaPools. We will
simplify down to one logical 'memory bucket' type. Consensus called this type NSSArena.
- We have lots of code which takes an optional arena pointer, using the arena if there is one,
or alternatively the heap if there isn't. Therefore, we wrap that logic into the allocators.
Knowing what to then free does takes discipline not to leak memory, but it simplifies things a
lot. Also, the implementation of free works (doesn't crash), no matter if from an arena, or
the heap, as long as from our allocators. Combined with purify, this also helps us catch cases
where things being allocated by one allocator are freed by another, which is a common Windows
pitfall.
- The security code often wants to be sure to zero memory, when it's being freed; we'll add it
to the primitives to deal with.
The ARENA_THREADMARK preprocessor definition (default in debug builds), and code it encloses,
will add some checking for the following situation:
#. Thread A marks the arena, and allocates some memory from it.
#. Thread B allocates some memory from the arena.
#. Thread A releases the arena back to the mark.
#. Thread B now finds itself with a pointer to released data.
#. Some thread -- doesn't matter which -- allocates some data from the arena; this may overlap
the chunk thread B has.
#. Boom!
Threadmark code notes the thread ID, whenever an arena is marked, and disallows any allocations
or marks by any other thread. (Frees are allowed.)
The ARENA_DESTRUCTOR_LIST preprocessor definition, and the code it encloses, are an effort to
make the following work together:
#. Arenas, letting you allocate stuff and then removing them all at once
#. Lazy creation of pure-memory objects from ASN.1 blobs, for example use of NSSPKIXCertificate
doesn't drag all the code in for all constituent objects, unless they're actually being used
#. Our agressive pointer-tracking facility
All these are useful, but they don't combine well. Now some of the pointer-tracking pressure has
eased off, we can drop its use when it becomes too difficult.
Many routines are defined to take an NSSArena \*arenaOpt argument. This means if an arena is
specified (non-null), it is used, otherwise (null) the routine uses the heap. You can think of
the heap as a default arena you can't destroy.
.. _error_handling:
`Error Handling <#error_handling>`__
------------------------------------
.. container::
NSS 3.0 introduces the concept of an error stack. When something goes wrong, the call stack
unwinds, with routines returning an error indication. Each level which flags a problem, adds its
own error number to the stack. At the bottom of the stack is the fundamental error, for example:
file not found, and on top is an error precisely relating to what you are doing.
.. note::
Note: Error stacks are vertical, and never horizontal. If multiple things go wrong
simultaneously, and you want to report them all, use another mechanism.
Errors, though not integers, are done as external constants, instead of preprocessor definitions.
This is so any additional error doesn't trigger the entire tree to rebuild. Likewise, the
external references to errors are made in the prototypes files, with the functions which can
return them. Error stacks are thread-private.
The usual semantic is that public routines clear the stack first, private routines don't.
Usually, every public routine has a private counterpart, and the implementation of the public
routine looks like this:
.. code::
NSSImplement rv *
NSSType_Method
(
NSSType *t,
NSSFoo *arg1,
NSSBar *arg2
)
{
nss_ClearErrorStack();
#ifdef DEBUG
if( !nssFoo_verifyPointer(arg1) ) return (rv *)NULL;
if( !nssBar_verifyPointer(arg2) ) return (rv *)NULL;
#endif /* DEBUG */
return nssType_Method(t, arg1, arg2);
}
Aside from error cases, all documented entry points should check pointers in a debug, wherever
possible. Pointers to user-supplied buffers, and templates, should be checked against NULL.
Pointers to context-style functions should be checked using special debug macros. These macros
only define code when DEBUG is turned on, providing a way for systems to register, deregister,
and check valid pointers.
SECPORT_DECL_PTR_CLASS(*classname*, *size*) - declare a class of pointers (labelled *classname*)
this object file needs to check. This class is local only to this object file. *Size* is the
expected number of pointers of type *classname*.
SECPORT_DECL_GLOBAL_PTR_CLASS(*classname*, *size*) - same as above except *classname* can be used
in other object files.
SECPORT_ADD_POINTER(*classname*, *pointer*) - Add *pointer* as a valid pointer for
class\ *classname*. This is usually called by a Create function.
SECPORT_VERIFY_POINTER(*classname*, *pointer*, *secError*, *returnValue*)- Check if a given
*pointer* really belongs to the requested class. If it doesn't set the error *secError* and
return the value *returnValue*.
SECPORT_REMOVE_POINTER(*classname*, *pointer*) - Remove a pointer from the valid list. Usually
called by a destroy function.
Finally, error logging should be added an documented when debug is turned on. Interfaces for
these are in NSPR.
.. _thread_safety:
`Thread Safety <#thread_safety>`__
----------------------------------
.. container::
Code developed using the NSS APIs needs to make use of thread safety features. First to examine
is **object creation** and **deletion**.
Object creation is usually not a problem. No other threads have access to allocated memory just
created. Exceptions to this include objects which are created on the fly, or as global objects.
Deletion, on the other hand, may be trickier. Threads may be referencing the object at the same
time a another thread tries to delete it. The semantics depend on the way the application uses
the object, also how and when the application wants to destroy it. For some data structures, this
problem can be removed by protected reference counting. The object does not disappear until all
users have released it.
Next we examine **global data**, including function local static structures. Just initialized,
and never to be changed global data, does not need to protection from mutexes. We should also
determine if global data should be moved to a session context (see `session
context <#sessioncontext>`__ and `global effects <#globaleffects>`__ below).
.. note::
Note: Permanent objects, like data in files, databases, tokens, etc. should be treated as
global data. Global data which is changed rarely, should be protected by reader/writer locks.
Aside from global data, **allocated data** that gets modified needs to be examined. Data that's
just been allocated, within a function, is safe to modify. No other code has access to that data
pointer. Once that data pointer is made visible to the 'outside', either by returning the
pointer, or attaching the pointer to an existing visible data structure, access to the data
should be protected. Data structures that are read only, like SECKEYPublicKeys or PK11SymKeys,
need not be protected.
Many of the data structures in the security code contain some sort of **session state** or
**session context**. These data structures may be accessed without data protection as long as:
#. This semantic is documented in the functions which use these data structures.
#. These data structures are used for single streams, and not reused.
Examples of these data in structures may include things like the PKCS #7 ContentInfo structure.
Example code should be included in the documentation, to show how to safely use these data
objects.
A major type of global and allocated data that should be examined is various **data on lists**.
Queued, linked, and hash table stored objects should be examined with special care. Make sure
adding, removing, accessing, and destroying these objects are all safe operations.
There are a number of strategies, and entire books about how to safely access data on lists. Some
simple strategies and their issues:
- **Use hash tables:** Hash table lookups are usually quite fast, limiting the contention on the
lock. This is best for large lists of objects. Be sure to calculate the hash value first, then
only lock over the hash table value itself. Be sure to increment the reference count, on the
returned object, before unlocking. Examples of hash tables can be found in
security/nss/lib/certdb/pcertdb.c
- **Lock over the entire search:** For small linked listed, queues, or arrays, you can lock over
the entire search. This strategy is best when lists are short, or even better if lists are
relatively read only (they don't change very often) and using reader/writer locks.
- **Copy the linked list:** Instead of operating on the global list, you can copy the list. This
also requires small lists.
- **Lock over single element with retry:** For medium sized lists, you can secure the reference
to each element, complete a test, then detect if the given element has been removed from the
list. In the case of removal, the search can either be either restarted, or terminated. This
method is a more complicated than the other methods: requiring the calling of search code
tolerant to often repeated element inspection.
- Examples of the previous strategies can be found in
`security/nss/lib/pk11wrap/pk11slot.c. <https://searchfox.org/mozilla-central/source/security/nss/lib/pk11wrap/pk11slot.c>`__
Where possible use the NSPR list primitives. From these you can even set up SECUtil style
thread-safe lists that use some combination of the above strategies.
In order to be fully thread safe, your code must understand the semantics of the **service
functions** it calls, and whether they are thread safe. For now, we should internally document
which service functions we call, and how we expect them to behave in a threaded environment.
Finally, from an API point of view, we should examine functions which have **global effects**.
Functions like XXX_SetDefaultYYY(); should not operate on global data, particularly if they may
be called multiple times, to provide different semantics for different operations. For example,
the following should be avoided :
- SEC_SetKey(keyForOperation);
SEC_Encrypt(Data,Length);
Instead, a context handle should be created, and the SEC_SetKey() function, above, made on that
handle. Fortunately most of the existing API has the correct semantics.
The exception to this global effects rule may be functions which set global state for an
application at initialization time.
.. _methodsfunctions_design:
`Methods/Functions Design <#methodsfunctions_design>`__
-------------------------------------------------------
.. container::
.. _init_shutdown_functions:
`Init, Shutdown Functions <#init_shutdown_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
If a layer has some global initialization tasks, which need to be completed before the layer can
be used, that layer should supply an initialization function of the form LAYER_Init(). If an
initialization function is supplied, a corresponding LAYER_Shutdown() function should also be
supplied. LAYER_INIT() should increment a count of the number of times it is called, and
LAYER_Shutdown() should decrement that count, and shutdown when the count reaches '0'.
.. _open_close_functions:
`Open, Close Functions <#open_close_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
Open functions should have a corresponding close function. Open and close function are not
reference counted, like init and shutdown functions.
.. _creation_functions:
`Creation Functions <#creation_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
In general, data objects should all have functions which create them. These functions should have
the form LAYER_CreateDataType[FromDataType](). For instance generating a new key would change
from PK11_KeyGen() to PK11_CreateSymKey().
.. _destruction_functions:
`Destruction Functions <#destruction_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
In the security library we have 3 different ways of saying 'get rid of this data object': Free,
Delete, and Destroy.
It turns out there are several different semantics of getting rid of a data object too:
#. decrement the reference count, and when the object goes to '0' free/delete/destroy it
#. destroy it right now, this very instance, not matter what
#. make any permanent objects associated with this data object go away
#. a combination of 1 and 3, or 2 and 3
Unfortunately, within the security library Free, Delete, and Destroy are all used
interchangeably, for all sorts of object destruction. For instance, CERT_DestroyCertificate() is
type 1, PK11_DestroySlot() is type 2, and PK11_DestroyTokenObject() is type 3.
.. note::
Note: In non-reference counted functions, types 1 and 2 are the same.
We are standardizing on the following definitions:
Destroy - means #1 for reference counted objects, #2 for non reference counted objects.
Delete - means #3.
This has the advantage of *not* surfacing the reference countedness of a data object. If you own
a pointer to an object, you must always destroy it. There is no way to destroy an object by
bypassing it's reference count. Also, the signature of public destruction functions do not have
the 'freeit' PRBool, since the structures being freed are opaque.
.. _dup_copy_and_reference_functions:
`Dup, Copy, and Reference Functions <#dup_copy_and_reference_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
Functions that return a new reference or copy of a given object should have the form
LAYER_DupDataType(). For instance, CERT_DupCertifiate() will remain the same, but
PK11_ReferenceSlot() will become PK11_DupSlot(), and PK11_CloneContext() will become
PK11_DupContext().
.. _search_functions:
`Search Functions <#search_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
There are several different kinds of searches done via the security library. The first is a
search for exactly one object, meeting a given criteria. These types of searches include
CERT_FindCertByDERCert(), PK11_FindAnyCertFromDERCert(), PK11_FindKeyByCert(),
PK11_GetBestSlot(). These functions should all have the form LAYER_FindDataType[ByDataType]().
The second kind of search, looks for all the objects that match a given criteria. These functions
operate on a variety of levels. Some return allocated arrays of data, some return linked lists of
data, others use callbacks to return data elements one at a time. Unfortunately, there are good
reasons to maintain all these types. So here are some guidelines to make them more manageable:
All callback operating search functions should be in the low level of the API, if exposed at all.
Developers dealing with SSL and PKCS #7 layers should not have to see any of these functions.
These functions should have the form LAYER_TraverseStorageObjectOrList().
List and Array returning functions should be available at the higher layers of the API, most
wrapping LAYER_Traverse() functions. They should have the form
LAYER_LookupDataType{List|Array}[ByDataType]().
.. _accesssor_functions:
`Accesssor Functions <#accesssor_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
Accessor Functions should take the following formats:
| LAYER_DataTypeGetElement() -- Get a specific element of a data structure.
| LAYER_DataTypeSetElement() -- Set a specific element of a data structure.
| LAYER_DataTypeExtractDataType() -- Get a pointer to the second data type which was derived for
elements of the first data type.
Examples: PK11_SlotGetSeries(), PK11_SymKeyGetSeries(), CERT_CertificateExtractPublicKey()
.. _parameter_ordering:
`Parameter ordering <#parameter_ordering>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
Most functions will have a 'Natural' ordering for parameters. To keep consistency we should have
some minimal parameter consistency. For most functions, they can be seen as operating on a
particular object. This object, that the function is operating on, should come first. For
instance, in most SSL functions this is the NSPR Socket, or the SSL Socket structure: Update,
final, encrypt, decrypt type functions operating on their state contexts, etc.
All encrypt and decrypt functions, which return data inline, should have a consistent signature:
.. code::
SECStatus MY_FunctionName(MyContext *context,
unsigned char *outBuf,
SECBufferLen *outLen,
SECBufferLenmaxOutLength,
unsigned char *inBuf,
SECBufferLeninLen)
Encrypt and decrypt like functions which have different properties, additional parameters,
callbacks, etc., should insert their additional parameters between the context (first parameter)
and the output buffer.
All hashing update, MACing update, and encrypt/decrypt functions which act like filters should
have a consistent signature:
.. code::
SECStatus PK11_DigestOp(PK11Context *context,
unsigned char *inBuf,
SECBufferLeninLen)
Functions like these which have different properties, for example, additional parameters,
callbacks, etc., should insert their additional parameters between the context (first parameter)
and the input buffer.
Within your layer, multiple similar functions should have consistent parameter order.
.. _callback_functions:
`Callback Functions <#callback_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
Callback functions should all contain an opaque parameter (void \*) as their first argument,
passed by the original caller. Callbacks which are set, like SSL callbacks, should have defaults
which provide generally useful semantics.