Certificate manipulation functions

The following function allows querying and manipulation of certificates, provided that a storage is already open and the certificate to be manipulated is already known, either by its ID or by a X.509 structure.

If you need to search for a certificate inside the storage, go for Section 4. If you want to exchange certificates with the outside world (import/export), go for Section 5.

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 code

Errors

• CST_ERROR_CERT_NOTFOUND

CST_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 structure

Returns

• Error code

Errors

• CST_ERROR_CERT_EXIST
• CST_ERROR_DBSTRUCTURE_CORRUPT
• CST_ERROR_IO, CST_ERROR_NOSPC

CST_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 certificates

Returns

• 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_EXIST

CST_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 chain

Returns

• 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 found

Errors

• 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 ID

Returns

• GSList * list of certificate IDs. User is responsible to free the list by using g_slist_free().
• NULL if not found

Errors

• CST_ERROR_CERT_NOTFOUND

CST_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 Certificate

Returns

• GSList * list of certificate IDs. User is responsible to free the list using g_slist_free().
• NULL if certificate not found

Errors

• CST_ERROR_CERT_NOTFOUND

CST_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 queried

Returns

• 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 queried

Returns

• 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 queried

Returns

• TRUE if certificate is expired or not yet valid

CST_get_serial_number

ASN1_INTEGER* CST_get_serial_number (X509 * cert)

Get serial number

Parameters

• cert X.509 certificate to be queried

Returns

• 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 queried

Returns

• 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 queried

Returns

• 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 queried

Returns

• 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 queried

Returns

• 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 queried

Returns

• 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 queried

Returns

• 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 queried

Returns

• 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 Section 11 for purpose constants.

Returns

• TRUE if all purposes are ok for the certificate

CST_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 purposes

Returns

• 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 passed

CST_is_root

int CST_is_root (X509 * cert)

Check that certificate is root

Parameters

• cert X509 certificate

Returns

• TRUE if is root

CST_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 ID

Returns

• 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 certificate

Returns

• TRUE if "Basic Constraint" not present or in "Basic Constraint" CA = TRUE

CST_is_revoked

int CST_is_revoked (CST * st, X509 * cert)

Get revoked state

Parameters

• st Pointer to storage structure
• cert X509 certificate

Returns

• 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 NULL

CST_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 queried

Returns

• TODO

Errors

• TODO

CST_get_network_URL

char* CST_get_network_URL (CST * st, X509 * cert)

Get stored on network URL. WARNING: still not implemented.

Parameters

• st Pointer to storage structure
• cert X509 certificate

Returns

• (TODO) Network URL. User is responsible to free this object using g_free().

Errors

• TODO

CST_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 section 11 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_ERROR

CST_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 ID

Returns

• Folder value (see section 11 for a list of folder options)
• -1 if 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_ERROR

CST_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 section 11)
• 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_ERROR

CST_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 section 11)

Returns

• TRUE if all purposes passed in p are fulfilled by the certificate.
• FALSE otherwise

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_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 queried

Returns

• 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_ERROR

CST_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 USED

Returns

• 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_ERROR

CST_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 USED

Returns

• 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_ERROR

CST_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 section 11)

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_ERROR

CST_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 queried

Returns

• Certificate state bitmap. See section 11 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_ERROR

CST_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 storage

Returns

• 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_ERROR

CST_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 queried

Returns

• 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 queried

Returns

• Expiration date, in UNIX timestamp format.