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 1) 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 name

Returns

• List of certificate storage IDs for a given name. User is responsible to free this object using g_slist_free().
• NULL if not found

Errors

• CST_ERROR_CERT_NOTFOUND

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

Returns

• Array of certificate storage IDs for given e-mail. User is responsible to free this object using g_slist_free().
• NULL if not found

Errors

• CST_ERROR_CERT_NOTFOUND

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

Returns

• Array of certificates for given domain name. User is responsible to free this object using g_slist_free().
• NULL if not found

Errors

• CST_ERROR_CERT_NOTFOUND

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

Returns

• Array of certificates for a given serial number. User is responsible to free this object using g_slist_free().
• NULL if not found

Errors

• CST_ERROR_CERT_NOTFOUND

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

Errors

• CST_ERROR_CERT_NOTFOUND

CST_search_issuer

cst_t_seqnum CST_search_issuer (CST * st, X509 * cert)

Search issuer of given certificate

Parameters

• st Pointer to storage structure
• cert Certificate

Returns

• certID of issuer
• NULL

Errors

• CST_ERROR_CERT_NOTFOUND

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

Returns

• List of certificates. User is responsible to free this object using g_slist_free().
• NULL if not found

Errors

• CST_ERROR_CERT_NOTFOUND

CST_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 Section 11 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 found

Errors

• CST_ERROR_CERT_NOTFOUND

CST_all_expired

GSList* CST_all_expired (CST * st )

Get all expired certificates. WARNING: still not implemented.

Parameters

• st Pointer to storage structure

Returns

• Array of certificates. User is responsible to free this object using g_slist_free()..
• NULL if chain not found

Errors

• CST_ERROR_CERT_NOTFOUND - if cert chain incomplete

CST_all_revoked

GSList* CST_all_revoked (CST * st)

Get all revoked certificates. WARNING: still not implemented.

Parameters

• st Pointer to storage structure

Returns

• List of certificates. User is responsible to free this object using g_slist_free()..
• NULL if chain not found

Errors

• CST_ERROR_CERT_NOTFOUND

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

Returns

• List of certificates. User is responsible to free this object using g_slist_free()..
• NULL if not found

Errors

• CST_ERROR_CERT_NOTFOUND

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

Returns

• Certificate or 0 if not found

Errors

• CST_ERROR_CERT_NOTFOUND

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

Returns

• Certificate ID
• 0 in not found

Errors

• CST_ERROR_CERT_NOTFOUND