The certman library low-level API. More...
Go to the source code of this file.
Defines | |
#define | AEGIS_CERTMAN_DOMAIN_PRIVATE 0 |
Private certificate domains can only be accessed by one application, the one that has created them and owns them. | |
#define | AEGIS_CERTMAN_DOMAIN_SHARED 1 |
Common certificate domain, accessible by all applications. | |
#define | AEGIS_CERTMAN_DOMAIN_NONE (void*)(0) |
The value a domain handle cannot have if its properly opened. | |
#define | AEGIS_KEY_ID_LEN SHA_DIGEST_LENGTH |
The length of a key identifier. | |
#define | AEGIS_KEY_ID_STR_LEN 2*SHA_DIGEST_LENGTH + 1 |
The lenght of a string representing a aegis_key_id in the printable form, with the terminating NUL included. | |
Typedefs | |
typedef void * | domain_handle |
A magic cookie reference to a domain opened by aegis_certman_open_domain and to be used in the domain management functions. | |
typedef unsigned char | aegis_key_id [AEGIS_KEY_ID_LEN] |
A type for a unique key identifier. In practice this is the SHA1 fingerprint of a (public) key, which is considered unique enough. | |
Functions | |
int | aegis_certman_key_id_to_str (aegis_key_id key_id, char *to_buf, unsigned max_len) |
Convert a key id value to string. | |
int | aegis_certman_str_to_key_id (char *from_str, aegis_key_id key_id) |
Convert a string into a key id. | |
General certificate management functions | |
int | aegis_certman_open (X509_STORE **my_cert_store) |
Open a secure certificate store. | |
int | aegis_certman_collect (const char *domain, int shared, X509_STORE *my_cert_store) |
Load and verify the certificates of the given domain. This function can be called multiple times. | |
int | aegis_certman_close (X509_STORE *my_cert_store) |
Close the certificate store and release reserved resources. | |
Certificate domain management functions | |
int | aegis_certman_iterate_domains (int flags, aegis_callback *cb_func, void *ctx) |
Get a list of existing domains. | |
int | aegis_certman_set_credentials (const char *token_name) |
Set the credentials with which domains are created or opened for modification. | |
int | aegis_certman_open_domain (const char *domain_name, int flags, domain_handle *handle) |
Open an existing domain or create a new one. | |
int | aegis_certman_iterate_certs (domain_handle the_domain, int cb_func(int, X509 *, void *), void *ctx) |
Iterate through all certificates in a domain. | |
int | aegis_certman_load_cert (domain_handle the_domain, aegis_key_id with_id, X509 **cert) |
Load a single certificate identifier by its key fingerprint. | |
int | aegis_certman_add_cert (domain_handle to_domain, X509 *cert) |
Add a certificate into a domain. | |
int | aegis_certman_add_certs (domain_handle to_domain, char *cert_files[], unsigned count) |
Add one or more certificates into a domain. | |
int | aegis_certman_rm_cert (domain_handle from_domain, aegis_key_id key_id) |
Remove a certificate from the domain. | |
int | aegis_certman_nbrof_certs (domain_handle in_domain) |
Return the number of certificates in a domain. | |
int | aegis_certman_close_domain (domain_handle handle) |
Close a domain. | |
int | aegis_certman_domain_changed (domain_handle the_domain) |
Check if the domain has changed. | |
int | aegis_certman_get_key_id (X509 *of_cert, aegis_key_id to_this) |
Get the public key fingerprint out of a certificate. | |
int | aegis_certman_store_key (aegis_key_id with_id, EVP_PKEY *the_key, char *with_passwd) |
Store a private key into the global private key store. | |
int | aegis_certman_retrieve_key (aegis_key_id with_id, EVP_PKEY **the_key, char *with_passwd) |
Retrieve a private key from the global private key store. | |
int | aegis_certman_iterate_keys (aegis_callback *cb_func, void *ctx) |
Iterate through all of the private keys in the global store. | |
int | aegis_certman_get_nickname (X509 *of_cert, char *to_buf, unsigned buf_len) |
Get a short name composed of the Subject DN name suitable for display. | |
int | aegis_certman_has_private_key (X509 *cert) |
int | aegis_certman_has_private_key_by_id (aegis_key_id key_id) |
int | aegis_certman_gui_check_certificate (X509 *cert, long timeout) |
Verify a certificate using the certman GUI. | |
int | aegis_certman_gui_get_private_key (aegis_key_id with_id, const char *with_credentials, long timeout, EVP_PKEY **the_key) |
Get a private key. | |
int | aegis_certman_gui_get_private_key_async (aegis_key_id with_id, const char *with_credentials, long timeout, void(*notify)(void *, int, EVP_PKEY *), void *state) |
Request a private key and report when it is ready. | |
int | aegis_certman_gui_check_certificate_async (X509 *cert, long timeout, void(*notify)(void *, int), void *state) |
Verify a certificate using certman GUI and report when checked. | |
void | aegis_certman_gui_poll (long wait) |
Look for a reply from system bus. |
The certman library low-level API.
The functions for accessing certificate stores as openSSL's X509 data structures.
int aegis_certman_add_cert | ( | domain_handle | to_domain, | |
X509 * | cert | |||
) |
Add a certificate into a domain.
to_domain | (in) a handle to the domain | |
cert | (in) the certificate to be added |
int aegis_certman_add_certs | ( | domain_handle | to_domain, | |
char * | cert_files[], | |||
unsigned | count | |||
) |
Add one or more certificates into a domain.
to_domain | (in) a handle to the domain | |
cert_files | (in) names of files from which the certificate are to be added | |
count | (in) how many file names there are in the list. A NULL also terminates the list |
int aegis_certman_close | ( | X509_STORE * | my_cert_store | ) |
Close the certificate store and release reserved resources.
my_cert_store | (in) the certificate store to be released |
int aegis_certman_close_domain | ( | domain_handle | handle | ) |
Close a domain.
handle | (in) a handle to the domain |
Upon closing the changes are updated on the disk, if the application has permissions to do that.
int aegis_certman_collect | ( | const char * | domain, | |
int | shared, | |||
X509_STORE * | my_cert_store | |||
) |
Load and verify the certificates of the given domain. This function can be called multiple times.
domain | (in) logical name of the domain | |
shared | (in) if true, a shared domain is expected, otherwise a private one | |
my_cert_store | (in,out) the store where to add the certificates |
int aegis_certman_domain_changed | ( | domain_handle | the_domain | ) |
Check if the domain has changed.
handle | (in) a handle to the domain |
int aegis_certman_get_key_id | ( | X509 * | of_cert, | |
aegis_key_id | to_this | |||
) |
Get the public key fingerprint out of a certificate.
of_cert | (in) The certificate | |
to_this | (out) The fingerprint of the public key |
int aegis_certman_get_nickname | ( | X509 * | of_cert, | |
char * | to_buf, | |||
unsigned | buf_len | |||
) |
Get a short name composed of the Subject DN name suitable for display.
of_cert | (in) a certificate | |
to_buf | (out) the buffer where the nickname is copied to | |
buf_len | (in) the maximum length of the name. If the nickname would exceed the length, it's truncated. |
int aegis_certman_gui_check_certificate | ( | X509 * | cert, | |
long | timeout | |||
) |
Verify a certificate using the certman GUI.
cert | (in) X509 certificate, usually a server certificate | |
timeout | (in) Wait for the answer this many seconds |
int aegis_certman_gui_check_certificate_async | ( | X509 * | cert, | |
long | timeout, | |||
void(*)(void *, int) | notify, | |||
void * | state | |||
) |
Verify a certificate using certman GUI and report when checked.
cert | (in) X509 certificate, usually a server certificate | |
timeout | (in) Wait for the answer this many seconds | |
notify | (in) Notification function | |
state | (in) A state object to be passed to the notify function |
This function acts just like aegis_certman_gui_check_certificate(), but returns immediately. The result will be reported to the caller when the certificate is checked, which may take some time. However, if it is not retrieved for timeout seconds, the error is reported to the caller.
When the certificate is checked (or when a timeout expires), the notification function supplied via notify parameter will be called. This function takes 2 arguments: state argument of this function and error code. The state argument is passed unchanged as supplied by caller and is ignored by this function. It may be any value, including NULL. The error code is 0 if the certificate was approved successfully. It is errno-based.
int aegis_certman_gui_get_private_key | ( | aegis_key_id | with_id, | |
const char * | with_credentials, | |||
long | timeout, | |||
EVP_PKEY ** | the_key | |||
) |
Get a private key.
with_id | (in) The certman_key_id of the related user certificate | |
with_credentials | (in) The resource token needed to read the key | |
timeout | (in) Wait for the answer this many seconds | |
the_key | (out) The private key |
int aegis_certman_gui_get_private_key_async | ( | aegis_key_id | with_id, | |
const char * | with_credentials, | |||
long | timeout, | |||
void(*)(void *, int, EVP_PKEY *) | notify, | |||
void * | state | |||
) |
Request a private key and report when it is ready.
with_id | (in) The certman_key_id of the related user certificate | |
with_credentials | (in) The resource token needed to read the key | |
timeout | (in) Wait for the answer this many seconds | |
notify | (in) Notification function | |
state | (in) A state object to be passed to the notify function |
This function acts just like aegis_certman_gui_get_private_key(), but returns immediately. The requested key will be reported to the caller when it is retrieved, which may take some time. However, if it is not retrieved for timeout seconds, the error is reported to the caller.
When the key is retrieved (or when a timeout expires), the notification function supplied via notify parameter will be called. This function takes 3 arguments: state argument of this function, error code, and the retrieved key. The state argument is passed unchanged as supplied by caller and is ignored by this function. It may be any value, including NULL. The error code is 0 if the key was retrieved successfully. It is errno-based.
void aegis_certman_gui_poll | ( | long | wait | ) |
Look for a reply from system bus.
wait | (in) Maximum time to wait for incoming reply, milliseconds. If <=0, the function returns immediately |
You need to call this function only if a private key was requested with aegis_certman_gui_get_private_key_async() and before the requested key is retrieved (or a timeout expires). This function blocks for at least wait milliseconds looking for an incoming key on session bus. If the key is found, it is decrypted and reported via the notification function passed to aegis_certman_gui_get_private_key_async().
If no operation was started with aegis_certman_gui_get_private_key_async() and this function is called, it will NOT block and will return immediately.
int aegis_certman_iterate_certs | ( | domain_handle | the_domain, | |
int | cb_funcint, X509 *, void *, | |||
void * | ctx | |||
) |
Iterate through all certificates in a domain.
the_domain | (in) a handle to the domain returned by aegis_certman_open_domain | |
cb_func | (in) a callback function called once for each certificate in the domain. The first parameter is the order number of the certificate in the domain (starting from 0), the second a pointer to a X509 certificate struct and the third is the given ctx pointer. If the callback returns other than 0 or -1, the iteration is terminated. If the callback returns 0, the certificate is released right after the callback. | |
ctx | (in) a void pointer passed to the callback function |
int aegis_certman_iterate_domains | ( | int | flags, | |
aegis_callback * | cb_func, | |||
void * | ctx | |||
) |
Get a list of existing domains.
flags | (in) the type of domains to iterate (shared, private) | |
cb_func | (in) a callback function called once for each domain. Parameters: order number, domain name, domain type and userdata pointer. | |
ctx | (in) a void pointer passed to the callback function |
int aegis_certman_iterate_keys | ( | aegis_callback * | cb_func, | |
void * | ctx | |||
) |
Iterate through all of the private keys in the global store.
cb_func | (in) a callback function. The first parameter is the order number of the key (starting from 0), the second a pointer to a aegis_key_id struct and the third is the given ctx pointer. | |
ctx | (in) a void pointer passed to the callback function |
int aegis_certman_key_id_to_str | ( | aegis_key_id | key_id, | |
char * | to_buf, | |||
unsigned | max_len | |||
) |
Convert a key id value to string.
key_id | Key id as a byte array | |
to_buf | A buffer to hold the default string | |
max_len | Size of the buffer, must be >= AEGIS_KEY_ID_STR_LEN |
int aegis_certman_load_cert | ( | domain_handle | the_domain, | |
aegis_key_id | with_id, | |||
X509 ** | cert | |||
) |
Load a single certificate identifier by its key fingerprint.
the_domain | (in) a handle to the domain | |
with_id | (in) the fingerprint of the public key | |
cert | (out) the certificate, if found |
int aegis_certman_nbrof_certs | ( | domain_handle | in_domain | ) |
Return the number of certificates in a domain.
in_domain | (in) a handle to the domain |
int aegis_certman_open | ( | X509_STORE ** | my_cert_store | ) |
Open a secure certificate store.
my_cert_store | (out) the initial certificate store, contains the root X509 certificate from BB5. Should be NULL when the function is called. |
int aegis_certman_open_domain | ( | const char * | domain_name, | |
int | flags, | |||
domain_handle * | handle | |||
) |
Open an existing domain or create a new one.
domain_name | (in) logical name of the domain | |
flags | (in) type of domain to open/create (see AEGIS_CD_* flags) | |
handle | (out) a handle to the domain to be used in subsequent calls * The resource token of the domain is required to make changes in the domain, for instance (aegis-certman-common-caCertCASSLAdd) |
int aegis_certman_retrieve_key | ( | aegis_key_id | with_id, | |
EVP_PKEY ** | the_key, | |||
char * | with_passwd | |||
) |
Retrieve a private key from the global private key store.
with_id | (in) the fingerprint of the corresponding public key | |
the_key | (out) the private key | |
with_passwd | (in) the password for the container. |
int aegis_certman_rm_cert | ( | domain_handle | from_domain, | |
aegis_key_id | key_id | |||
) |
Remove a certificate from the domain.
from_domain | (in) | |
key_id | (in) The public key id of the certificate |
int aegis_certman_set_credentials | ( | const char * | token_name | ) |
Set the credentials with which domains are created or opened for modification.
token_name | (in) typically a resource token name * If the domain does not exist already, it is created with this resource token in the aegis_certman_open_domain |
int aegis_certman_store_key | ( | aegis_key_id | with_id, | |
EVP_PKEY * | the_key, | |||
char * | with_passwd | |||
) |
Store a private key into the global private key store.
with_id | (in) the fingerprint of the corresponding public key | |
the_key | (in) the key to be stored | |
with_passwd | (in) the password for the container. The private key is stored in an encrypted PKCS#8 container. |
int aegis_certman_str_to_key_id | ( | char * | from_str, | |
aegis_key_id | key_id | |||
) |
Convert a string into a key id.
from_str | The string presentation | |
key_id | Key id as a byte array |