Defines | Typedefs | Functions

aegis_certman.h File Reference

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.

Detailed Description

The certman library low-level API.

The functions for accessing certificate stores as openSSL's X509 data structures.


Function Documentation

int aegis_certman_add_cert ( domain_handle  to_domain,
X509 *  cert 
)

Add a certificate into a domain.

Parameters:
to_domain (in) a handle to the domain
cert (in) the certificate to be added
Returns:
0 on success, otherwise an error code. EACCES if the application does not have the power to modify the domain. * The resource token of the domain is required to make changes in the domain for instance (aegis-certman-common-caCertCASSLAdd)
int aegis_certman_add_certs ( domain_handle  to_domain,
char *  cert_files[],
unsigned  count 
)

Add one or more certificates into a domain.

Parameters:
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
Returns:
The number of certificates successfully added or -1. * The resource token of the domain is required to make changes in the domain for instance (aegis-certman-common-caCertCASSLAdd)
int aegis_certman_close ( X509_STORE *  my_cert_store  ) 

Close the certificate store and release reserved resources.

Parameters:
my_cert_store (in) the certificate store to be released
Returns:
0 on success, otherwise an error code
int aegis_certman_close_domain ( domain_handle  handle  ) 

Close a domain.

Parameters:
handle (in) a handle to the domain
Returns:
0 on success, otherwise and error code

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.

Parameters:
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
Returns:
0 on success, otherwise an error code
int aegis_certman_domain_changed ( domain_handle  the_domain  ) 

Check if the domain has changed.

Parameters:
handle (in) a handle to the domain
Returns:
1 if the domain was modified by another process otherwise return 0
int aegis_certman_get_key_id ( X509 *  of_cert,
aegis_key_id  to_this 
)

Get the public key fingerprint out of a certificate.

Parameters:
of_cert (in) The certificate
to_this (out) The fingerprint of the public key
Returns:
0 on success. EINVAL if the given certificate is NULL or otherwise invalid.
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.

Parameters:
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.
Returns:
0 on success, otherwise an error code.
int aegis_certman_gui_check_certificate ( X509 *  cert,
long  timeout 
)

Verify a certificate using the certman GUI.

Parameters:
cert (in) X509 certificate, usually a server certificate
timeout (in) Wait for the answer this many seconds
Returns:
0 if the certificate is approved, an error code otherwise
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.

Parameters:
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
Returns:
0 if requested, and error code otherwise

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.

Note:
If you use this function, you need to call aegis_certman_gui_poll() periodically to look at the bus for certificate approval.
See also:
aegis_certman_gui_poll()
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.

Parameters:
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
Returns:
0 if the key could be retrieved, and error code otherwise * The resource token of the related user-domain is required for reading the key (for instance aegis-certman-common-caCertUserSSLUse)
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.

Parameters:
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
Returns:
0 if the key has been requested, and error code otherwise

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.

Note:
If you use this function, you need to call aegis_certman_gui_poll() periodically to look at the bus for requested private key.
See also:
aegis_certman_gui_poll()
void aegis_certman_gui_poll ( long  wait  ) 

Look for a reply from system bus.

Parameters:
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().

Note:
If your application uses only one thread, you don't have to worry about this note. This function delivers results of requests in the calling thread. If results are to be delivered in some other thread it must be implemented by the caller. That is, notification functions for pending calls are called in the same thread that has called this function. A notification function may then post reported results to some other thread using the framework API (Qt, GObject).

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.

Parameters:
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
Returns:
if >= 0, the index where iteration terminated, if < 0, an error code
Warning:
If you modify the domain inside the callback function with "add cert" or "rm cert", the results may be quite unpredictable. So don't.
int aegis_certman_iterate_domains ( int  flags,
aegis_callback *  cb_func,
void *  ctx 
)

Get a list of existing domains.

Parameters:
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
Returns:
if >= 0, the index where iteration terminated, if < 0, an error code
Warning:
If you modify the domain inside the callback function with "add cert" or "rm cert", the results may be quite unpredictable. So don't.
int aegis_certman_iterate_keys ( aegis_callback *  cb_func,
void *  ctx 
)

Iterate through all of the private keys in the global store.

Parameters:
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
Returns:
if >= 0, the index where iteration terminated, if < 0, an error code
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.

Parameters:
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
Returns:
0 on success, otherwise an error code
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.

Parameters:
the_domain (in) a handle to the domain
with_id (in) the fingerprint of the public key
cert (out) the certificate, if found
Returns:
0 on success, otherwise an error code. ENOENT if there is no certificate in the store with the given key fingerprint.
int aegis_certman_nbrof_certs ( domain_handle  in_domain  ) 

Return the number of certificates in a domain.

Parameters:
in_domain (in) a handle to the domain
Returns:
>= 0 on success, otherwise -1
int aegis_certman_open ( X509_STORE **  my_cert_store  ) 

Open a secure certificate store.

Parameters:
my_cert_store (out) the initial certificate store, contains the root X509 certificate from BB5. Should be NULL when the function is called.
Returns:
0 on success, otherwise an error code
int aegis_certman_open_domain ( const char *  domain_name,
int  flags,
domain_handle handle 
)

Open an existing domain or create a new one.

Parameters:
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)
Returns:
0 on success, otherwise an error code
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.

Parameters:
with_id (in) the fingerprint of the corresponding public key
the_key (out) the private key
with_passwd (in) the password for the container.
Returns:
0 on success, an error code otherwise. * The resource token of the related user-domain is required for reading the key (for instance aegis-certman-common-caCertUserSSLUse)
int aegis_certman_rm_cert ( domain_handle  from_domain,
aegis_key_id  key_id 
)

Remove a certificate from the domain.

Parameters:
from_domain (in)
key_id (in) The public key id of the certificate
Returns:
0 on success, otherwise an error code. EACCESS if the application does not have the power to modify the domain. * The resource token of the domain is required to make changes in the domain for instance (aegis-certman-common-caCertCASSLAdd)
int aegis_certman_set_credentials ( const char *  token_name  ) 

Set the credentials with which domains are created or opened for modification.

Parameters:
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
Returns:
0 on success, otherwise an error code
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.

Parameters:
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.
Returns:
0 on success, an error code otherwise.
int aegis_certman_str_to_key_id ( char *  from_str,
aegis_key_id  key_id 
)

Convert a string into a key id.

Parameters:
from_str The string presentation
key_id Key id as a byte array
Returns:
0 on success, otherwise an error code