Introduction and general conventions (read this first!)

The certificate manager main mission is to allow sharing of a certificate and password database by many client applications, offering an uniform API and hiding the storage details from them.

This API has no actual certificate generation and/or encryption functions, since these jobs are covered by OpenSSL library, also included in Maemo.

This API uses some types from OpenSSL, like X509_* and ASN1_* types. Also, release of pointers to these types must use OpenSSL-specific free functions. Refer to OpenSSL documentation for further information about these types.

Several functions return only a generic error warning, by returning NULL or zero. The actual error code may be queried via CST_last_error() immediately after return, in the same fashion as C library's errno.

In the other hand, some functions do return the actual error code. For these, you must test for errors based on the return; CST_last_error() may not have this very last error.

Keep also in mind that, in all API functions that return pointers to objects, the user is responsible to free such objects. Do NOT use C library's free() for them; for every object type, there is a specific free function! Check the function API description to learn which function must be used for its returned pointer.

Certificates can be uniquely recovered from the database in two ways. the first is the UID, meaning``Unique ID'': a concatenation of certificate issuer plus serial number. Each CA maintains an independent monotonic serial number counter. Most search functions return a list of UIDs. UID is unique worldwide for every valid, trustable certificate.

The second way if the sequential number ID (seqnum or certID in function prototypes), that is unique within every database but not across two or more databases.