Certificate Manager
Introduction
This document has been reviewed for maemo 3.X.
This is a detailed API reference for developers that have read themaemo Certificate Manager Tutorial and are developing applicationswith digital certificate support for maemo.
Since it is a reference, it is not meant to be read from top tobottom. Developers without any previous contact with this API shouldread the CertmanTutorial first.
Introduction and general conventions
The certificate manager main mission is to allow sharing of acertificate 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 encryptionfunctions, since these jobs are covered by OpenSSL library, alsoincluded in maemo.
This API uses some types from OpenSSL, like X509_* andASN1_* types. Also, release of pointers to these types mustuse OpenSSL-specific free functions. Refer to OpenSSL documentationfor 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.
Certificate database functions
These functions are in the top level of API, since they only manipulate database files as a whole. They hide the actual storage format details (e.g. in maemo SDK 1.2, file format is Berkeley DB 1).
CST* CST_open (const int readonly, unsigned char * password)Opens default storage. If find gconf key /apps/osso/certman/filename then open file use this value. Else open file storage.cst. If file not exist then created. Parameters* readonly If storage will be readonly (NOT USED)* password Password for storage or NULL if password is empty (NOT USED)Returns* Pointer to storage descriptor. User is responsible to release it using CST_free.* NULL if error, get the specific error with CST_lastError()Errors* CST_ERROR_NOT_FOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_NOSPC* CST_ERROR_LOCK
CST_open_file
CST* CST_open_file (const char * filename, const int readonly, unsigned char * password)Opens local storage from a specified file. If the file does not exist, it is created. Parameters* filename File name of local storage* readonly If storage will be read-only (NOT USED)* password Password for storage access, or NULL if password is empty (NOT USED)Returns* Pointer to storage descriptor. User is responsible to release it using CST_free.* NULL if some error occurred. Get the error code via CST_lastError().Errors* CST_ERROR_NOT_FOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_NOSPC* CST_ERROR_LOCK* CST_ERROR_PARAM_INCORRECTCST_create_file
int CST_create_file (const char * filename, unsigned char * password)Creates a database file. WARNING: This function is deprecated. Use CST_open_file or CST_open instead. Parameters* filename Filename of local storage* password Password for storage or NULL if password is empty (NOT USED)Returns* Error code.Errors* CST_ERROR_IO* CST_ERROR_NOSPC* CST_ERROR_LOCK* CST_ERROR_PARAM_INCORRECTCST_save
int CST_save (CST * st)Save storage. WARNING: This function is deprecated; use CST_free() instead. Parameters* st Pointer to storage structureReturns* Error codeErrors* CST_ERROR_NOT_FOUND* CST_ERROR_DBSTRUCTURE_CORRUPTCST_free
void CST_free (CST * st)Closes storage and frees its resources. Parameters* st Pointer to storage structureCST_last_error
int CST_last_error ()Last error code. If error then return last error code. Returns* Last error codeCST_backup
int CST_backup ( CST * st, const char * filename, unsigned char * password)Backup local (file) storage. Parameters* st Pointer to storage structure* filename Filename for backup* password Password (NOT USED)Returns* Error codeErrors* CST_ERROR_LOCKCertificate manipulation functions
CST_delete_cert
int CST_delete_cert (CST * st, const cst_t_seqnum certID)Delete certificate Parameters* st Pointer to storage structure* certID Certificate sequential number ID.Returns* Error codeErrors* CST_ERROR_CERT_NOTFOUNDCST_append_X509
int CST_append_X509 (CST * st, X509 * cert)Append X509 certificate to storage Parameters* st Pointer to storage structure* cert Pointer to X509 structureReturns* Error codeErrors* CST_ERROR_CERT_EXIST* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO, CST_ERROR_NOSPCCST_append_sk_X509
GSList* CST_append_sk_X509 (CST * st, CST_STACK_OF_X509 * list)Append STACK_OF(X509) to storage Parameters* st Pointer to storage structure* list Stack of X509 certificatesReturns* Pointer to GSList with error code for each element of stack. Use GPOINTER_TO_INT(i->data) to get result for each code. User is responsible to free this resource with g_slist_free().Errors (in GSList elements)* CST_ERROR_CERT_EXISTCST_get_chain
CST_STACK_OF_X509* CST_get_chain (CST * st, X509 * cert)Get cert chain for given certificate Parameters* st Pointer to storage structure* cert Certificate for which need chainReturns* Stack of certificates. The stack must be freed by user either by using cert_free_stack() or by releasing all individual certificates inside the stack before the stack itself.* NULL if chain not foundErrors* CST_ERROR_CERT_NOTFOUND (if certificate chain is incomplete)CST_get_chain_id_by_id
GSList* CST_get_chain_id_by_id (CST * st, const cst_t_seqnum certID)Get cert chain for given certificate ID Parameters* st Pointer to storage structure* certID Certificate IDReturns* GSList * list of certificate IDs. User is responsible to free the list by using g_slist_free().* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_get_chain_id
GSList* CST_get_chain_id (CST * st, X509 * x)Get certificate chain for a given certificate ID Parameters* st Pointer to storage structure* x X509 CertificateReturns* GSList * list of certificate IDs. User is responsible to free the list using g_slist_free().* NULL if certificate not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_get_issued_by_dn
X509_NAME* CST_get_issued_by_dn (X509 * cert)Get issuer distinguished name (issued by) Parameters* cert X.509 certificate to be queriedReturns* Issuer distinguished name. User is responsible to free this object using X509_NAME_free().CST_get_subject_dn
X509_NAME* CST_get_subject_dn (X509 * cert)Get subject distinguished name (issued to) Parameters* cert X.509 certificate to be queriedReturns* Distinguished name of certificate subject. User is responsible to free this object using X509_NAME_free().CST_is_expired
int CST_is_expired (X509 * cert)Returns expiration status of a certificate Parameters* cert X.509 certificate to be queriedReturns* TRUE if certificate is expired or not yet validCST_get_serial_number
ASN1_INTEGER* CST_get_serial_number (X509 * cert)Get serial number Parameters* cert X.509 certificate to be queriedReturns* Serial number as a ASN1_INTEGER object. User is responsible to free this object using ASN1_INTEGER_free().CST_get_serial_number_t
char* CST_get_serial_number_t (X509 * cert)Get serial number in string Parameters* cert X.509 certificate to be queriedReturns* Serial number in string form. User is responsible to free this object using g_free().CST_get_fingerprint
char* CST_get_fingerprint (X509 * cert)Get fingerprint. In maemo SDK 1.2, MD5 is the default fingerprint hash for this function. Parameters* cert X.509 certificate to be queriedReturns* Certificate fingerprint in ASCII/hexadecimal string form. User is responsible to free this object using g_free().CST_get_fingerprint_MD5
char* CST_get_fingerprint_MD5 (X509 * cert)Get fingerprint hashed by MD5 Parameters* cert X.509 certificate to be queriedReturns* MD5 hash fingerprint in ASCII/hexadecimal string form. User is responsible to free this object using g_free().CST_get_fingerprint_SHA1
char* CST_get_fingerprint_SHA1 (X509 * cert)Get fingerprint hashed by SHA1 Parameters* cert X.509 certificate to be queriedReturns* SHA1 hash fingerprint in ASCII/hexadecimal string form. User is responsible to free this object using g_free().CST_get_email
char* CST_get_email (X509 * cert)Get email if exist or NULL Parameters* cert X.509 certificate to be queriedReturns* Certificate contact e-mail in string form. User is responsible to free this object using g_free().CST_get_domain_name
char* CST_get_domain_name (X509 * cert)Get domain name if exist or NULL Parameters* cert X.509 certificate to be queriedReturns* Domain name in string form. User is responsible to free this object using g_free().CST_get_public_key_alg
char* CST_get_public_key_alg (X509 * cert)Get public key algorithm Parameters* cert X.509 certificate to be queriedReturns* Public key algorithm in human-readable string form. User is responsible to free this object using g_free().CST_check_purpose_x
int CST_check_purpose_x (X509 * x, const cst_t_cert_purpose purposes)Check purpose of X.509 certificate. Parameters* x X509 certificate* purposes Bitmap of purposes. See also Data structures, typedefs and constants section for purpose constants.Returns* TRUE if all purposes are ok for the certificateCST_check_purpose
int CST_check_purpose (CST * st, const cst_t_seqnum certID, const cst_t_cert_purpose purpose) Check purpose of certificate in storage by his storage ID. Parameters* st Pointer to certificate storage* certID Certificate ID* purpose Bitmap of needed purposesReturns* TRUE if certificate is suitable for the given purposes* FALSE if not suitable or if the certID does not exist. You need to query CST_last_error() to tell apart.Errors* CST_ERROR_PARAM_INCORRECT if a zero certID is passedCST_is_root
int CST_is_root (X509 * cert)Check that certificate is root Parameters* cert X509 certificateReturns* TRUE if is rootCST_is_root_id
int CST_is_root_id (CST * st, const cst_t_seqnum certID)Check that certificate (certID) is root Parameters* st Pointer to storage structure* certID Certificate IDReturns* TRUE if certificate is root* FALSE if it is not root, or if certID does not exist. You need to query CST_last_error() to tell apart.CST_is_CA
int CST_is_CA (X509 * cert)Check that certificate can be a Certificate Authority (CA) Parameters* cert X509 certificateReturns* TRUE if "Basic Constraint" not present or in "Basic Constraint" CA = TRUECST_is_revoked
int CST_is_revoked (CST * st, X509 * cert)Get revoked state Parameters* st Pointer to storage structure* cert X509 certificateReturns* TRUE if certificate is revoked* FALSE if it is not, or if the certificate does not exist. You need to query CST_last_error() to tell apart.Errors* CST_ERROR_PARAM_INCORRECT if passed storage is NULLCST_is_network
int CST_is_network (CST * st, X509 * cert)Get stored on network state. WARNING: still not implemented. Parameters* st Pointer to storage structure* cert X.509 certificate to be queriedReturns* TODOErrors* TODOCST_get_network_URL
char* CST_get_network_URL (CST * st, X509 * cert)Get stored on network URL. WARNING: not yet implemented.Parameters* st Pointer to storage structure* cert X509 certificateReturns* TODO Network URL. User is responsible to free this object using g_free().Errors* TODOCST_set_folder
int CST_set_folder (CST * st, const cst_t_seqnum certID, const cst_t_cert_folder f)Set the certificate folder Parameters* st Pointer to storage structure* certID Certificate ID* f Folder where to put the certificate in. See Data structures, typedefs and constants section for a list of available folders.Returns* Error code.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_NOSPC* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_get_folder
cst_t_cert_folder CST_get_folder (CST * st, const cst_t_seqnum certID)Get certificate folder Parameters* st Pointer to storage structure* certID Certificate IDReturns* Folder value (see Data structures, typedefs and constants section for a list of folder options)* -1 if errorErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_set_purpose
int CST_set_purpose (CST * st, const cst_t_seqnum certID, const cst_t_cert_purpose p, const int value)Set purpose (trust settings) for a certificate. Parameters* st Pointer to storage structure* certID Certificate number inside the storage* p Purposes of the certificate as a bitmap (see Data structures, typedefs and constants section)* value TRUE if the purposes specified in p should be enabled; FALSE if they should be disabled for the certificate.Returns* Error code.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_NOSPC* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_is_purpose
int CST_is_purpose (CST * st, const cst_t_seqnum certID, const cst_t_cert_purpose p)Check purpose (trust) of a given certificate. Parameters* st Pointer to storage structure* certID Certificate number inside the storage* p Purposes of the certificate as a bitmap (see Data structures, typedefs and constants section)Returns* TRUE if all purposes passed in p are fulfilled by the certificate.* FALSE otherwiseErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_is_valid
int CST_is_valid (CST * st, X509 * cert)Check certificate validity. WARNING: present implementation does NOT check trust chain, so any non-corrupt certificate will be considered valid. In next versions, this behavior may change: only trusted certificates may be considered valid, and a self-signed certificate that is not itself a trusted CA will be considered invalid. Parameters* st Pointer to storage structure* cert the X.509 certificate to be queriedReturns* TRUE if certificate is valid* FALSE if certificate is not valid, or if some parameter is invalid. You need to query CST_last_error() to tell apart.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_is_valid_f
int CST_is_valid_f (CST * st, FILE * file, GError ** error)Check certificate validity, reading the certificate from a PEM-format file. WARNING: present implementation does NOT check trust chain, so any non-corrupt certificate will be considered valid. In next versions, this behavior may change: only trusted certificates may be considered valid, and a self-signed certificate that is not itself a trusted CA will be considered invalid. Parameters* st Pointer to storage structure* file an open FILE* descriptor* error Pointer to GError*. NOT USEDReturns* TRUE if certificate is valid* FALSE if certificate is invalid/corrupt, or if some error occurred. You need to test CST_last_error() to tell apart.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_is_valid_f_DER
int CST_is_valid_f_DER (CST * st, FILE * file, GError ** error)Check certificate of a certificate inside a DER-format file. WARNING: present implementation does NOT check trust chain, so any non-corrupt certificate will be considered valid. In next versions, this behavior may change: only trusted certificates may be considered valid, and a self-signed certificate that is not itself a trusted CA will be considered invalid. Parameters* st Pointer to storage structure* file an open FILE* descriptor* error Pointer to GError*. NOT USEDReturns* TRUE if certificate is valid* FALSE if certificate is invalid, or if some error occurred. You need to test CST_last_error() to tell apart.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_is_valid_for
int CST_is_valid_for (CST * st, X509 * cert, const cst_t_cert_purpose purpose)Check certificate validity for a set of purposes. Parameters* st Pointer to storage structure* cert the X.509 certificate to be queried* p Purposes of the certificate as a bitmap (see Data structures, typedefs and constants section)Returns* TRUE if all purposes passed in p are fulfilled by the certificate* FALSE otherwise, or if some error occurred. You need to query CST_last_error() to tell apart.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_get_state
int CST_get_state (CST * st, X509 * cert)Get state of certificate (valid, invalid etc.). Parameters* st Pointer to storage structure* cert the X.509 certificate to be queriedReturns* Certificate state bitmap. See Data structures, typedefs and constants section for details.* -1 in case of error.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_get_cert
X509* CST_get_cert (CST * st, const cst_t_seqnum certID)Get X509 by certID Parameters* st Pointer to storage structure* certID Certificate number inside the storageReturns* X.509 certificate. User is responsible to free this object using X509_free().* NULL if not found or if some error ocurred.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_STRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_get_valid_from
time_t CST_get_valid_from(X509 * cert)Gets the date/time that certificate begins to be valid. Parameters* cert the X.509 certificate to be queriedReturns* Initial valid date, in UNIX timestamp format.CST_get_valid_to
time_t CST_get_valid_to(X509 * cert)Gets the certification expiration date/time. Parameters* cert the X.509 certificate to be queriedReturns* Expiration date, in UNIX timestamp format.Certificate search functions
These functions allow searching for a certificate in a storage. Certificates can be looked for by several arguments: ID, domain, distinguished name etc.
Functions that may return more than one certificate for a given query will return lists (pointers to GSList), so the API user must be aware of this. These lists contain storage IDs of certificates, which can be used to get the storage sequential number and/or the certificate itself. The lists must be released by the user with g_slist_free().
Revisit the Introduction section to learn about UIDs and storage IDs that are used in this section.
CST_search_by_subj_name
GSList* CST_search_by_subj_name (CST * st, X509_NAME * subject_name)Search certificate by subject name Parameters* st Pointer to storage structure* subject_name Subject Distinguished nameReturns* List of certificate storage IDs for a given name. User is responsible to free this object using g_slist_free().* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_email
GSList* CST_search_by_email (CST * st, const char * email)Search certificate by email Parameters* st Pointer to storage structure* email Email of subjectReturns* Array of certificate storage IDs for given e-mail. User is responsible to free this object using g_slist_free().* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_domain_name
GSList* CST_search_by_domain_name (CST * st, const char * domain_name)Search certificate by domain name Parameters* st Pointer to storage structure* domain_name Domain name of subjectReturns* Array of certificates for given domain name. User is responsible to free this object using g_slist_free().* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_serial
GSList* CST_search_by_serial (CST * st, const char * serial)Search certificate by serial number. Parameters* st Pointer to storage structure* serial Serial numberReturns* Array of certificates for a given serial number. User is responsible to free this object using g_slist_free().* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_fingerprint
GSList* CST_search_by_fingerprint (CST * st, const char * fingerprint)Search certificate by email Parameters* st Pointer to storage structure* fingerprint Fingerprint (see. CST_get_fingerprint())Returns* Array of certificates for given fingerprint. User is responsible to free this object using g_slist_free().* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_issuer
cst_t_seqnum CST_search_issuer (CST * st, X509 * cert)Search issuer of given certificate Parameters* st Pointer to storage structure* cert CertificateReturns* certID of issuer* NULLErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_folder_and_purpose
GSList* CST_search_by_folder_and_purpose (CST * st, const cst_t_cert_folder folder, const cst_t_cert_purpose purpose)Get all trusted certificates for given purpose in selected folder. For example, all CA certificates for WLAN. Parameters* st Pointer to storage structure* folder Folder* purpose Certificate purposeReturns* List of certificates. User is responsible to free this object using g_slist_free().* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_folder
GSList* CST_search_by_folder (CST * st, const cst_t_cert_folder folder)Get all certificates by folder e.g. if requested folder is CST_FOLDER_CA then return all CA certificates. Parameters* st Pointer to storage structure* folder Folder. Refer to Data structures, typedefs and constants section to get a list of folder constants.Returns* List of certificates. User is responsible to free this object using g_slist_free()..* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_all_expired
GSList* CST_all_expired (CST * st )Get all expired certificates. WARNING: still not implemented. Parameters* st Pointer to storage structureReturns* Array of certificates. User is responsible to free this object using g_slist_free()..* NULL if chain not foundErrors* CST_ERROR_CERT_NOTFOUND - if cert chain incompleteCST_all_revoked
GSList* CST_all_revoked (CST * st)Get all revoked certificates. WARNING: still not implemented. Parameters* st Pointer to storage structureReturns* List of certificates. User is responsible to free this object using g_slist_free()..* NULL if chain not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_purpose
GSList* CST_search_by_purpose (CST * st, const cst_t_cert_purpose purpose)Get all trusted certificates that fill the given purpose bitmap. Only the certificates that fit for all purposes required will be returned. If you want all certificates, pass CST_PURPOSE_NONE (zero). Parameters* st Pointer to storage structure* purpose Certificate purposeReturns* List of certificates. User is responsible to free this object using g_slist_free()..* NULL if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_UID
cst_t_seqnum CST_search_by_UID (CST * st, X509_NAME * issuer, ASN1_INTEGER * serial)Get certificate storage ID (int) by UID (issuer + serial) Parameters* st Pointer to storage structure* issuer Distinguished name of issuer* serial Serial numberReturns* Certificate or 0 if not foundErrors* CST_ERROR_CERT_NOTFOUNDCST_search_by_X509
cst_t_seqnum CST_search_by_X509 (CST * st, X509 * xcert)Get certificate ID (int) by openssl X509 certificate Parameters* st Pointer to storage structure* xcert X509 certificateReturns* Certificate ID* 0 in not foundErrors* CST_ERROR_CERT_NOTFOUNDCertificate and key import/export functions
Apart from two file checking functions in Certificate manipulation functions section, in this section you will find all functions that allow the maemo Certificate Manager API to communicate with the outside world.
Also, functions for importing/exporting bare keys are also included here.
CST_import_PKCS12
void CST_import_PKCS12 ( CST * st, FILE * file, cst_pkcs12_confirm_cb confirm_cb, cst_pkcs12_error_cb error_cb, unsigned char * password, void * user_data, GError ** error)Import certificate with private key (if any) from the PKCS12-format file. Parameters* st Pointer to storage structure* file Input file* confirm_cb Callback function to confirm import of certificate or key* error_cb Callback function to inform about errors* password Password of input file to disclose the private key* user_data User data, that need in both callback functions* error Error codeConfirm_cb callback function received parameters* is_pair TRUE if need confirm import of private key and corresponding certificate* xcert certificate to import* folder use to set folder, by default equal to CST_FOLDER_CA (is_pair == FALSE) or CST_FOLDER_PERSONAL (is_pair == TRUE)* purpose use to set purpose of certificate, by default equal to CST_PURPOSE_NONE* out_password - use to set private key password, need only if is_pair equal to TRUE* cancel - set TRUE to stop import, by default FALSE* data - user data.Error_cb callback function received parameters* xcert certificate on which error* error error code* data user data.Callback functions details* Callback function confirm_cb must return TRUE to import and FALSE to skip.* Callback function error_cb must return FALSE if need stop import and TRUE to skip and continue import.Confirm_cb callback function exampleint confirm_cb(X509 * xcert, cst_t_cert_folder * folder, cst_t_cert_purpose * purpose,unsigned char * out_pass, int is_pair, int *cancel, void * user_data){if (is_pair) {*out_pass = "secret";*purpose = CST_PURPOSE_SSL_CLIENT;*folder = CST_FOLDER_PERSONAL;*cancel = FALSE;return TRUE;} else {*purpose = CST_PURPOSE_CA;*folder = CST_FOLDER_CA;*cancel = FALSE;return TRUE;}}Returns* Error codeErrors* CST_ERROR_PASSWORD_WRONG* CST_ERROR_STRUCTURE_CORRUPT* CST_ERROR_CANCEL.* Errors received by error_cb: see error codes of CST_import_cert, CST_assign (8.5), CST_import_priv_key.CST_import_cert
int CST_import_cert (CST * st, FILE * file, unsigned char * password)Import certificate from the PEM-format file. TODO: does it set folder and purpose based on certificate data?Parameters* st Pointer to storage structure* file Input file* password Password for open file or NULL if password is emptyReturns* Error codeErrors* CST_ERROR_NOT_FOUND - certificate not found in file or format incorrect* CST_ERROR_DBSTRUCTURE_CORRUPT - db-file structure corrupt* CST_ERROR_IO - I/O error* CST_ERROR_NOSPC - no space left on device* CST_ERROR_CERT_EXISTCST_import_cert_DER
int CST_import_cert_DER (CST * st, FILE * file)Import certificate from the DER-format file. Parameters* st Pointer to storage structure* file Input fileReturnsError code Errors* Refer to CST_import_cert errors.CST_import_cert_f
int CST_import_cert_f (CST * st, FILE * file, unsigned char * password, const cst_t_cert_folder folder)Import certificate from the PEM-format file and set its folder. Parameters* st Pointer to storage structure* file Input file* password Password for open file or NULL if password is empty* folder Folder code to put the certificate into. If this is passed incorrectly, certificate is still imported but placed in default folder (CST_FOLDER_UNKNOWN) and an error is returned.Returns* Error codeErrors* Refer to CST_import_cert errors.CST_import_cert_f_DER
int CST_import_cert_f_DER (CST * st, FILE * file, const cst_t_cert_folder folder)Import certificate from the DER-format file to a folder. Parameters* st Pointer to storage structure* file Name of input file* folder Folder code to put the certification into. If this is passed incorrectly, certificate is still imported but placed in default folder (CST_FOLDER_UNKNOWN) and an error is returned.Returns* Error codeErrors* Refer to CST_import_cert errors.CST_import_cert_adv
cst_t_seqnum CST_import_cert_adv (CST * st, FILE * file, const cst_t_cert_folder folder, GError ** error)Import certificate from the file and set folder (PEM format). If folder incorrect cert placed in default folder (CST_FOLDER_UNKNOWN) and error returned. Parameters* st Pointer to storage structure* file Name of input file* folder Folder code* error Used to return error code (if NULL then ignored)Returns* ID imported certificate* 0 if errorErrors* Refer to CST_import_cert errors.CST_import_cert_adv_DER
cst_t_seqnum CST_import_cert_adv_DER (CST * st, FILE * file, const cst_t_cert_folder folder, GError ** error)Import all certificates from the file and set folder (DER format). If folder incorrect cert placed in default folder (CST_FOLDER_UNKNOWN) and error returned. Parameters* st Pointer to storage structure* file Name of input file* folder Folder code* error Used to return error code (if NULL then ignored)Returns* ID imported certificate* 0 if errorErrors* Refer to CST_import_cert errors.CST_export_all
int CST_export_all (CST * st, FILE * file, const cst_t_cert_folder folder)Export all certificates to the file (PEM format). Parameters* st Pointer to storage structure* file Output file* folder Folder which need exportReturns* Error codeErrors* CST_ERROR_CREATE_FILECST_export_all_DER
int CST_export_all_DER (CST * st, FILE * file, const cst_t_cert_folder folder)Export all certificates to the file (DER format). Parameters* st Pointer to storage structure* file Output file* folder Folder which need exportReturns* Error codeErrors* CST_ERROR_CREATE_FILECST_export_cert
int CST_export_cert (CST * st, X509 * cert, FILE * file)Export selected certificate to a PEM format file. Parameters* st Pointer to storage structure* cert The certificate to be exported* file Output fileReturns* Error codeErrors* CST_ERROR_CREATE_FILECST_export_cert_DER
int CST_export_cert_by_id (CST * st, const cst_t_seqnum certID, FILE * file)Export selected certificate (by certID) to the file (PEM format) Parameters* st Pointer to storage structure* certID Certificate ID* file Output fileReturns* Error codeErrors* CST_ERROR_CREATE_FILECST_export_cert_by_id
int CST_export_cert_by_id (CST * st, const cst_t_seqnum certID, FILE * file)Export selected certificate (by certID) to the file (PEM format) Parameters* st Pointer to storage structure* certID Certificate ID* file Output fileReturns* Error codeErrors* CST_ERROR_CREATE_FILECST_export_cert_by_id_DER
int CST_export_cert_by_id_DER (CST * st, const cst_t_seqnum certID, FILE * file)Export selected certificate (by certID) to the file (DER format) Parameters* st Pointer to storage structure* certID Certificate ID* file Output fileReturns* Error codeErrors* CST_ERROR_CREATE_FILECST_import_priv_key
int CST_import_priv_key ( CST * st, X509_NAME * account, FILE * file, unsigned char * inpass, unsigned char * outpass)Import private key from PEM encoded file. If a private key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input PEM encoded file* account Distinguished name for identify imported key* inpass Password for imported keys* outpass Password for key in storageReturns* Error codeErrors* Refer to CST_import_cert errors.CST_import_priv_key_DER
int CST_import_priv_key_DER ( CST * st, X509_NAME * account, FILE * file, unsigned char * outpass)mport private key from DER encoded file. If a private key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input DER encoded file* account Distinguished name for identify imported key* outpass Password for key in storageReturns* Error codeErrors* Refer to CST_import_cert errors.CST_import_priv_key_adv
cst_t_seqnum CST_import_priv_key_adv (CST * st, X509_NAME * account, FILE * file, unsigned char * inpass, unsigned char * outpass, GError ** error)Import private key from PEM encoded file. If a private key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input PEM encoded file* account Distinguished name for identify imported key* inpass Password for imported keys* outpass Password for key in storage* error Used to return error code (if NULL then ignored)Returns* Id of imported key* 0 on errorErrors* Refer to CST_import_cert errors.CST_import_priv_key_adv_DER
cst_t_seqnum CST_import_priv_key_adv_DER (CST * st, X509_NAME * account, FILE * file, unsigned char * outpass, GError ** error)Import private key from DER encoded file. If a private key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input DER encoded file* account Distinguished name for identify imported key* outpass Password for key in storage* error Used to return error code (if NULL then ignored)Returns* Id of imported key* 0 on errorErrors* Refer to CST_import_cert errors.CST_export_priv_key
int CST_export_priv_key (CST * st, EVP_PKEY * key, FILE * file, unsigned char * password)Export private key with given account to PEM format file. Parameters* st Pointer to storage structure* key Pointer to key* file Output file* password Password for exported keysReturns* Error codeErrors* CST_ERROR_NOT_FOUNDCST_export_priv_key_DER
int CST_export_priv_key_DER (CST * st, EVP_PKEY * key, FILE * file, unsigned char * password)Export private key with given account to file (DER format). Parameters* st Pointer to storage structure* key Pointer to key* file Output file* password Password for exported keysReturns* Error codeErrors* CST_ERROR_NOT_FOUNDCST_import_pub_key
int CST_import_pub_key (CST * st, X509_NAME * account, FILE * file)Import public key from file. If a public key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input file* account Distinguished name Key for identify imported keyReturns* Error codeErrors* Refer to CST_import_cert errors.CST_import_pub_key_DER
int CST_import_pub_key_DER (CST * st, X509_NAME * account, FILE * file)Import public key from file. If a public key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input file* account Distinguished name Key for identify imported keyReturns* Error codeErrors* Refer to CST_import_cert errors.CST_import_pub_key_adv
cst_t_seqnum CST_import_pub_key_adv (CST * st, X509_NAME * account, FILE * file, GError ** error)Import public key from file. If a public key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input file* account Distinguished name Key for identify imported key* error Used to return error code (if NULL then ignored)Returns* Id of imported key* 0 on errorErrors* Refer to CST_import_cert errors.CST_import_pub_key_adv_DER
cst_t_seqnum CST_import_pub_key_adv_DER (CST * st, X509_NAME * account, FILE * file, GError ** error)Import public key from file. If a public key for the same account exists in storage, key is appended. Parameters* st Pointer to storage structure* file Input file* account Distinguished name Key for identify imported key* error Used to return error code (if NULL then ignored)Returns* Id of imported key or 0 on errorErrors* Refer to CST_import_cert errors.CST_export_all_pub_key
int CST_export_all_pub_key (CST * st, X509_NAME * account, FILE * file)Export all public keys with given account to file (PEM format). Parameters* st Pointer to storage structure* account Key for identify key* file Output fileReturns* Error codeErrors* CST_ERROR_NOT_FOUND* CST_ERROR_KEY_NOTFOUNDCST_export_all_pub_key_DER
int CST_export_all_pub_key_DER (CST * st, X509_NAME * account, FILE * file)Export all public keys with given account to file (DER format). Parameters* st Pointer to storage structure* account Key for identify key* file Output fileReturns* Error codeErrors* CST_ERROR_NOT_FOUND* CST_ERROR_KEY_NOTFOUNDCST_export_pub_key
int CST_export_pub_key (CST * st, EVP_PKEY * key, FILE * file)Export public key with given account to file (PEM format). Parameters* st Pointer to storage structure* key Pointer to key* file Output file (FILE* descriptor)Returns* Error codeErrors* CST_ERROR_NOT_FOUND* CST_ERROR_KEY_NOTFOUNDCST_export_pub_key_DER
int CST_export_pub_key_DER (CST * st, EVP_PKEY * key, FILE * file)Export public key with given account to file (DER format) Parameters* st Pointer to storage structure* key Pointer to key* file Output file (FILE* descriptor)Returns* Error codeErrors* CST_ERROR_NOT_FOUND* CST_ERROR_KEY_NOTFOUNDS/MIME capabilities
These functions allow for S/MIME capability manipulation of certificates.
These capabilities are an extension to the X.509 standard to accomodate the S/MIME capabilities that a given message recipient has. They are included in the certificate so the message sender has a way to know about them (see RFC 4262 and its references for details).
Each capability is a tuple with an unique OID key plus a data binary string.
CST_set_capability
int CST_set_capability ( CST * st, const cst_t_seqnum certID, ASN1_OBJECT * oid, unsigned char * data, int data_length)Set S/MIME Capability for a given certificate Parameters* st Pointer to storage structure* certID the certificate ID inside the storage* oid Capability OID* data Capability binary data buffer* data_length Length of data bufferReturns* Error code.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_get_capability_data
unsigned char* CST_get_capability_data (CST * st, const cst_t_seqnum certID, ASN1_OBJECT * oid, int * data_length)Get S/MIME Capability for given cert Parameters* st Pointer to storage structure* certID the certificate ID inside the storage* oid Capability OID* data_length Pointer to integer that will receive the length of returned buffer.Returns* Binary string buffer. User is responsible to free this object using g_free().Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERROR* CST_ERROR_CAPABILITY_NOTFOUNDCST_get_capabilities
CST_STACK_OF_ASN1_OBJECT* CST_get_capabilities (CST * st, const cst_t_seqnum certID)Get S/MIME Capabilities list for given cert Parameters* st Pointer to storage structure* certID the certificate ID inside the storageReturns* Stack of ASN.1 objects with capability tuples. User is responsible to free this object. Do this by freeing each element in the list with ASN1_OBJECT_free() and then freeing the stack with sk_ASN1_OBJECT_free().Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_is_capability
int CST_is_capability (CST * st, const cst_t_seqnum certID, ASN1_OBJECT * oid)Returns TRUE if capability exists Parameters* st Pointer to storage structure* certID the certificate ID inside the storage* oid Capability OIDReturns* TRUE if capability exists* FALSE if it does not exist, of if some error ocurred. You need to test CST_last_error() to tell apart.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERRORCST_delete_capability
int CST_delete_capability (CST * st, const cst_t_seqnum certID, ASN1_OBJECT * oid)Delete capabilities Parameters* st Pointer to storage structure* certID the certificate ID inside the storage* oid Capability OIDReturns* Error code.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_UNDEF_FILE_ERROR* CST_ERROR_CAPABILITY_NOTFOUND- An OID key is an numeric structured code (e.g. 1.3.6.1.4.1) for a given capability. The number is assigned by ISO and/or ITU-T, which guarantee them to be unique. OID keys are also used in SNMP protocol.
Certificate Revocation Lists (CRL)
Certificate Revocation Lists (CRL) are lists of certifications that have been actively expired before their natural expiration date. This section describes the functions that deal with CRL files.
CST_import_CRL
int CST_import_CRL (CST * st, FILE * file)Import Certificate Revocation List from file (PEM). The related certificates stored inside the database are checked and revoked accordingly. Parameters* st Pointer to storage structure* file Input file (PEM encoded)Returns* Error codeErrors* CST_ERROR_CRL_NOT_VALID* Refer to CST_import_cert errors.CST_import_CRL_DER
int CST_import_CRL_DER (CST * st, FILE * file)Import Certificate Revocation List from file (DER). The related certificates stored inside the database are checked and revoked accordingly. Parameters* st Pointer to storage structure* file Input file (DER encoded)Returns* Error codeErrors* CST_ERROR_CRL_NOT_VALID* Refer to CST_import_cert errors.CST_get_all_crl
GSList* CST_get_all_crl (CST * st)Return all CRLs from storage Parameters* st Pointer to storage structureReturns* List of CRL storage IDs. User is responsible to free this object using g_slist_free().* NULL if some error ocurred.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)CST_delete_crl
int CST_delete_crl (CST * st, const cst_t_seqnum crlID)Remove CRL from storage. The related certificates stored inside the database are checked and unrevoked accordingly. Parameters* st Pointer to storage structure* crlID CRL IDReturns* Error code.Errors* CST_ERROR_PARAM_INCORRECT (if storage or crlID is NULL)* CST_ERROR_NOT_FOUNDCST_get_CRL
X509_CRL* CST_get_CRL (CST * st, const cst_t_seqnum crlID)Get CRL by crlID Parameters* st Pointer to storage structure* crlID CRL IDReturns* X509_CRL structure. User is responsible to free this object using X509_CRL_free().* NULL if not found.Errors* CST_ERROR_PARAM_INCORRECT (if storage or crlID is NULL)* CST_ERROR_NOT_FOUNDCertification keys manipulation functions
These functions allow to manipulate particular keys of a certificate.
CST_set_default
int CST_set_default (CST * st, const cst_t_seqnum certID)Set default certificate for the certificate's e-mail. Parameters* st Pointer to storage structure* certID Certificate IDReturns* Error codeErrors* CST_ERROR_PARAM_INCORRECT (if storage or crlID is NULL)* CST_ERROR_NOT_FOUNDCST_default_cert
X509* CST_default_cert (CST * st, const char * email)Get default certificate for an e-mail Parameters* st Pointer to storage structure* email Email to be searched forReturns* Default certificate for the supplied e-mail. User is responsible to free this object using X509_free().* NULL if no certificate is marked defaultErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUNDCST_default_cert_id
cst_t_seqnum CST_default_cert_id (CST * st, const char * email)Get default certificate ID by email Parameters* st Pointer to storage structure* email Email to be searched forReturns* certID of default certificate for the supplied e-mailErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUNDCST_is_default
int CST_is_default (CST * st, const cst_t_seqnum certID)Tests if a certificate is the default for its e-mail contact. Parameters* st Pointer to storage structure* certID Certificate idReturns* TRUE if defaultErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUNDCST_assign
int CST_assign (CST * st, const cst_t_seqnum certID, const cst_t_seqnum keyID, unsigned char * password)Assign private key with certificate. Useful to assign a private key previously imported by CST_import_priv_key() to a certificate. Parameters* st Storage structure* certID Certificate storage ID* keyID Private key storage ID* password Password, need for test correct assignReturns* Error codeErrors* CST_ERROR_ASSIGN_INCORRECTCST_get_priv_key_by_UID
EVP_PKEY* CST_get_priv_key_by_UID (CST * st, X509_NAME * issuer, ASN1_INTEGER * serial, unsigned char * password)Get private key by certificate UID Parameters* st Pointer to storage structure* issuer Distinguished name of issuer* serial Serial number* password PasswordReturns* Private key. User is responsible to free this object using EVP_PKEY_free().* NULL if not foundErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_KEY_NOTFOUND* CST_ERROR_PASSWORD_WRONGCST_get_priv_key
EVP_PKEY* CST_get_priv_key (CST * st, X509 * cert, unsigned char * password)Get private key by certificate Parameters* st Pointer to storage structure* cert Pointer to cert* password PasswordReturns* Private key. User is responsible to free this object using EVP_PKEY_free().* NULL if not foundErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_KEY_NOTFOUND* CST_ERROR_PASSWORD_WRONGCST_get_assigned_key
cst_t_seqnum CST_get_assigned_key (CST * st, const cst_t_seqnum certID)Get private key ID by its certificate ID Parameters* st Pointer to storage structure* certID certIDReturns* Private key storage ID* 0 if not foundErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUNDCST_get_priv_key_default
EVP_PKEY* CST_get_priv_key_default (CST * st, char * email, unsigned char * password)Get private key for default certificate Parameters* st Pointer to storage structure* email Email* password PasswordReturns* Private key. User is responsible to free this object using EVP_PKEY_free().* NULL if not foundErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_CERT_NOTFOUND* CST_ERROR_KEY_NOTFOUND* CST_ERROR_PASSWORD_WRONGKey manipulation functions
These functions allow to store and retrieve keys that are not related to any certificate. They manipulate in-memory keys; in order to import and export such keys, refer to Certificate and key import/export functions section.
CST_append_priv_key
int CST_append_priv_key (CST * st, X509_NAME * account, EVP_PKEY * key, unsigned char * password)Append private key to storage Parameters* st Pointer to storage structure* account Distinguished name for identify key* key Pointer to private key* password Password for key in storageReturns* Error codeErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_NOSPCCST_append_pub_key
int CST_append_pub_key (CST * st, X509_NAME * account, EVP_PKEY * key)Append public key to storage Parameters* st Pointer to storage structure* account Distinguished name for identify key* key Pointer to public keyReturns* Error codeErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_DBSTRUCTURE_CORRUPT* CST_ERROR_IO* CST_ERROR_NOSPCCST_get_key_account
X509_NAME* CST_get_key_account (CST * st, cst_t_seqnum keyID)Get account assigned with key Parameters* st Pointer to storage structure* keyID Key IDReturns* Account assigned with key on append or import . User is responsible to free this object using X509_NAME_free().Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUND - if account not foundCST_delete_all_pub_key
int CST_delete_all_pub_key (CST * st, X509_NAME * account)Delete all public key for account Parameters* st Pointer to storage structure* account Key for identify keyReturns* Error codeErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUND - if account not foundCST_delete_all_priv_key
int CST_delete_all_priv_key (CST * st, X509_NAME * account)Delete all private key for account Parameters* st Pointer to storage structure* account Key for identify keyReturns* Error codeErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUND - if account not foundCST_delete_pub_key
int CST_delete_pub_key (CST * st, const cst_t_seqnum keyID)Delete public key form storage Parameters`* st Pointer to storage structure* keyID Public key IDReturns* Error codeErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUNDCST_delete_priv_key
int CST_delete_priv_key (CST * st, const cst_t_seqnum keyID)Delete private key form storage Parameters* st Pointer to storage structure* keyID Private key IDReturns* Error codeErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUNDCST_priv_key_search_by_name
GSList* CST_priv_key_search_by_name (CST * st, X509_NAME * account)Get all private keys for a given account. Parameters* st Pointer to storage structure* account AccountReturns* Array of storage IDs of keys. User is responsible to free this object using g_slist_free().* NULL if chain not foundErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUND - if cert chain incompleteCST_pub_key_search_by_name
GSList* CST_pub_key_search_by_name (CST * st, X509_NAME * account)Get all public keys for a given account. Parameters* st Pointer to storage structure* account AccountReturns* Array of keys' storage IDs. User is responsible to free this object using g_slist_free().* NULL if chain not foundErrors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUND - if cert chain incompleteCST_EVP_PKEY_to_text
char* CST_EVP_PKEY_to_text (EVP_PKEY * key)Convert key to human-readable text format Parameters* key the key to be converted.Returns* Key in human-readable string. User is responsible to free this object using g_free().* NULL if some error occured (no error is set).CST_get_key
EVP_PKEY* CST_get_key (CST * st, const cst_t_seqnum keyID, unsigned char * password)Get private key by storage ID. Parameters* st Pointer to storage structure* keyID Private key ID* password the password to recover the keyReturns* Private key. User is responsible to free this object using EVP_PKEY_free().* NULL if error.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUND* CST_ERROR_PASSWORD_WRONGCST_get_pub_key
EVP_PKEY* CST_get_pub_key (CST * st, const cst_t_seqnum keyID)Get public key EVP_PKEY by keyID Parameters* st Pointer to storage structure* keyID Public key IDReturns* Public key. User is responsible to free this object using EVP_PKEY_free()* NULL if error.Errors* CST_ERROR_PARAM_INCORRECT (if storage is NULL)* CST_ERROR_KEY_NOTFOUNDMiscelaneous functions
cert_free_stack
void cert_free_stack (STACK_OF(X509) * certs)Releases a stack of X.509 certificates. It is a convenience function that frees the user from walking the stack, release all certificates and then release the stack itself. Parameters* certs stack of X.509 certificatesData structures, typedefs and constants
Important typedefs and structures
| Typedef | Type | Description |
|---|---|---|
| CST | struct CST_st | Descriptor of a certificate storage |
| cst_t_cert_folder | guint8 | Certificate folder inside a storage |
| cst_t_cert_purpose | guint32 | Bitmap of certificate purposes |
| cst_t_seqnum | guint | used for certificate and key IDs |
| CST_STACK_OF_X509 | STACKOF(X509) | A stack of X.509 certificates |
Folder constants
| CST_FOLDER_CA | Certificate Authority certificates |
| CST_FOLDER_OTHER | Other certificates |
| CST_FOLDER_PERSONAL | Unsorted certificates |
| CST_FOLDER_SITE | Site-wide certificates |
| CST_FOLDER_UNKNOWN | Certificates of unknown type |
Error codes
| CST_ERROR_OK = 0 | CST_ERROR_NOT_FOUND |
| ST_ERROR_STRUCTURE_CORRUPT | CST_ERROR_CREATE_FILE |
| CST_ERROR_CERT_EXIST | CST_ERROR_CRL_EXIST |
| CST_ERROR_STORAGE_IS_READONLY | CST_ERROR_KEY_NOTFOUND |
| CST_ERROR_CERT_NOTFOUND | CST_ERROR_NOT_IMPLEMENTED |
| CST_ERROR_NOT_INIT | CST_ERROR_UNDEF |
| CST_ERROR_PARAM_INCORRECT | CST_ERROR_NOT_OPEN |
| CST_ERROR_ASSIGN_INCORRECT | CST_ERROR_CRL_NOT_VALID |
| CST_ERROR_CHAIN_INCOMPLETE | CST_ERROR_CAPABILITY_NOTFOUND |
| CST_ERROR_INCORRECT_PURPOSE | CST_ERROR_IO |
| CST_ERROR_NOSPC | CST_ERROR_DBSTRUCTURE_CORRUPT |
| CST_ERROR_LOCK | CST_ERROR_PASSWORD_WRONG |
| CST_ERROR_BAD_INTERNAL_FORMAT | CST_ERROR_EXPORT |
| CST_ERROR_UNDEF_FILE_ERROR | CST_ERROR_CANCEL |
Certificate purposes
Certificate purposes are bitmaps. Every constant has only one bit on; a multipurpose certificate will have several of these constants OR-ed together.
| CST_PURPOSE_NONE = 0 | CST_PURPOSE_CA |
| CST_PURPOSE_SMIME_SGN | CST_PURPOSE_SMIME_ENC |
| CST_PURPOSE_SSL_SERVER | CST_PURPOSE_SSL_CLIENT |
| CST_PURPOSE_SSL_WLAN | CST_PURPOSE_CRL_SIGN |
| CST_PURPOSE_ALL = 0xFFFF |
Certificate states
Certificate states are also bits in a bitmap.
| CST_STATE_VALID | CST_STATE_NOTVALID |
| CST_STATE_EXPIRED | CST_STATE_REVOKED |
- Comes from OpenSSL
- Should be 0xFFFFFFFF (32 bits), it is a bug that will be corrected in next release
References
- maemo Certificate Manager API Doxygen documentation and source code
- OpenSSL include files
- Maemo SDK tutorial
- Certman API example programs
Improve this page