Certificate and key import/export functions

Apart from two file checking functions in section 3, 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 code

Confirm_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 example

int 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 code

Errors

• CST_ERROR_PASSWORD_WRONG
• CST_ERROR_STRUCTURE_CORRUPT
• CST_ERROR_CANCEL.
• Errors received by error_cb: see error codes of CST_import_cert (5.2), CST_assign (8.5), CST_import_priv_key (5.14).

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 empty

Returns

• Error code

Errors

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

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

Returns

Error code

Errors

• Refer to CST_import_cert (5) 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 code

Errors

• Refer to CST_import_cert (5.2) 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 code

Errors

• Refer to CST_import_cert (5.2) 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 error

Errors

• Refer to CST_import_cert (5.2) 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 error

Errors

• Refer to CST_import_cert (5.2) 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 export

Returns

• Error code

Errors

• CST_ERROR_CREATE_FILE

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

Returns

• Error code

Errors

• CST_ERROR_CREATE_FILE

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

Returns

• Error code

Errors

• CST_ERROR_CREATE_FILE

CST_export_cert_DER

int CST_export_cert_DER (CST * st, X509 * cert, FILE * file)

Export selected certificate to the file (DER format)

Parameters

• st Pointer to storage structure
• cert Same cert (X509 structure)
• file Output file

Returns

• Error code

Errors

• CST_ERROR_CREATE_FILE

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

Returns

• Error code

Errors

• CST_ERROR_CREATE_FILE

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

Returns

• Error code

Errors

• CST_ERROR_CREATE_FILE

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

Returns

• Error code

Errors

• Refer to CST_import_cert (5.2) errors.

CST_import_priv_key_DER

int CST_import_priv_key_DER ( CST * st, X509_NAME * account, FILE * file, unsigned char * outpass)

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

Returns

• Error code

Errors

• Refer to CST_import_cert (5.2) 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 error

Errors

• Refer to CST_import_cert (5.2) 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 error

Errors

• Refer to CST_import_cert (5.2) 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 keys

Returns

• Error code

Errors

• CST_ERROR_NOT_FOUND

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

Returns

• Error code

Errors

• CST_ERROR_NOT_FOUND

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

Returns

• Error code

Errors

• Refer to CST_import_cert (5.2) 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 key

Returns

• Error code

Errors

• Refer to CST_import_cert (5.2) 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 error

Errors

• Refer to CST_import_cert (5.2) 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 error

Errors

• Refer to CST_import_cert (5.2) 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 file

Returns

• Error code

Errors

• CST_ERROR_NOT_FOUND
• CST_ERROR_KEY_NOTFOUND

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

Returns

• Error code

Errors

• CST_ERROR_NOT_FOUND
• CST_ERROR_KEY_NOTFOUND

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

Errors

• CST_ERROR_NOT_FOUND
• CST_ERROR_KEY_NOTFOUND

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

Errors

• CST_ERROR_NOT_FOUND
• CST_ERROR_KEY_NOTFOUND