security.h File Reference

#include <anjay/dm.h>
#include <avsystem/commons/avs_stream.h>

Go to the source code of this file.

Data Structures
struct	anjay_security_instance_t
struct	anjay_security_hsm_configuration_t

Typedefs
typedef const char *	anjay_security_hsm_query_cb_t(anjay_iid_t iid, anjay_ssid_t ssid, const void *data, size_t data_size, void *arg)

Functions
int	anjay_security_object_add_instance (anjay_t *anjay, const anjay_security_instance_t *instance, anjay_iid_t *inout_iid)
void	anjay_security_object_purge (anjay_t *anjay)
avs_error_t	anjay_security_object_persist (anjay_t *anjay, avs_stream_t *out_stream)
avs_error_t	anjay_security_object_restore (anjay_t *anjay, avs_stream_t *in_stream)
bool	anjay_security_object_is_modified (anjay_t *anjay)
int	anjay_security_object_install (anjay_t *anjay)
int	anjay_security_object_install_with_hsm (anjay_t *anjay, const anjay_security_hsm_configuration_t *hsm_config)
void	anjay_security_mark_hsm_permanent (anjay_t *anjay, anjay_ssid_t ssid)

Typedef Documentation

anjay_security_hsm_query_cb_t

typedef const char * anjay_security_hsm_query_cb_t(anjay_iid_t iid, anjay_ssid_t ssid, const void *data, size_t data_size, void *arg)

Type for a callback function that will be called by the Security object implementation whenever a query string for storing a new security credential (provisioned by means other than EST) in external security engine is necessary. See also the fields of the anjay_security_hsm_configuration_t structure.

Parameters

iid	ID of the Security object Instance for which the credential is to be stored.
ssid	Short Server ID of the server account for which the credential is to be stored (ANJAY_SSID_BOOTSTRAP in case of the Bootstrap Server).
data	Pointer to a buffer containing the credential that will be stored.
data_size	Size in bytes of the data located at data.
arg	Opaque argument configured through a corresponding *_arg field of anjay_security_hsm_configuration_t.

Returns

String that will be used as a query string for the provisioned security credential. The string will be copied shortly after this function returns, so it is safe to deallocate or overwrite it when control is returned to user code, or during the next call to this function, whichever happens first. Anjay will never attempt to modify or deallocate the returned value.

Attention

The data and data_size are provided only as a hint for users who want the query strings to depend on the credential contents in any way. This callback shall not attempt to store the certificate itself. This will be performed by Anjay afterwards.

Function Documentation

anjay_security_mark_hsm_permanent()

void anjay_security_mark_hsm_permanent	(	anjay_t *	anjay,
		anjay_ssid_t	ssid
	)

Marks security credential for a given Server Account as "permanent", preventing them from being removed from the hardware security module.

The credentials that are moved into hardware security module according to the logic described for anjay_security_object_install_with_hsm are, by default, automatically removed whenever they are deleted from the data model (e.g. by the Bootstrap Server or using anjay_security_object_purge).

This function causes such credentials to be marked as "permanent", equivalent to credentials provisioned using the avs_crypto_*_from_engine APIs passed into the fields of the anjay_security_instance_t structure. This will prevent them from being automatically erased from the hardware even if they are removed from the data model, or if the object is cleaned up without up-to-date persistence status.

Parameters

anjay	Anjay instance with Security Object installed to operate on.
ssid	Short Server ID of the Server Account whose credentials to mark as permanent. ANJAY_SSID_BOOTSTRAP may be used to refer to the Bootstrap Server (if present), and ANJAY_SSID_ANY may be used to mark all the Server Account credentials as permanent.

anjay_security_object_add_instance()

int anjay_security_object_add_instance	(	anjay_t *	anjay,
		const anjay_security_instance_t *	instance,
		anjay_iid_t *	inout_iid
	)

Adds new Instance of Security Object and returns newly created Instance id via inout_iid .

Note: if *inout_iid is set to ANJAY_ID_INVALID then the Instance id is generated automatically, otherwise value of *inout_iid is used as a new Security Instance Id.

Note: instance may be safely freed by the user code after this function finishes (internally a deep copy of anjay_security_instance_t is performed).

Warning: calling this function during active communication with Bootstrap Server may yield undefined behavior and unexpected failures may occur.

Parameters

anjay	Anjay instance with Security Object installed to operate on.
instance	Security Instance to insert.
inout_iid	Security Instance id to use or ANJAY_ID_INVALID .

Returns

0 on success, negative value in case of an error or if the instance of specified id already exists.

anjay_security_object_install()

int anjay_security_object_install

(

anjay_t *

anjay

)

Installs the Security Object in an Anjay instance.

The Security module does not require explicit cleanup; all resources will be automatically freed up during the call to anjay_delete.

Parameters

anjay

Anjay instance for which the Security Object is installed.

Returns

0 on success, or a negative value in case of error.

anjay_security_object_install_with_hsm()

int anjay_security_object_install_with_hsm	(	anjay_t *	anjay,
		const anjay_security_hsm_configuration_t *	hsm_config
	)

Installs the Security Object in an Anjay instance, with support for moving security credentials to a hardware security module.

For each of the security credential type for which the query string generation callback is provided, any credentials provisioned either using anjay_security_object_add_instance or by the Bootstrap Server, will be stored in the hardware security module and wiped from the main system memory. These credentials will be managed by Anjay and automatically deleted when removed from the data model (either by the Bootstrap Server or anjay_security_object_purge) or when the object is cleaned up without having been properly persisted (see the next paragraph for details).

The Security module does not require explicit cleanup; all resources will be automatically freed up during the call to anjay_delete - in this case this will also cause the removal of all the keys moved into the hardware security module, unless unchanged since the last call to anjay_security_object_persist or anjay_security_object_restore, or marked permanent using anjay_security_mark_hsm_permanent.

Parameters

anjay	Anjay instance for which the Security Object is installed.
hsm_config	Configuration of the mechanism that moves security credentials to the hardware security module. When the pointer is NULL or all of the callback fields are NULL, this functions is equivalent to anjay_security_object_install.

Returns

0 on success, or a negative value in case of error.

anjay_security_object_is_modified()

bool anjay_security_object_is_modified

(

anjay_t *

anjay

)

Checks whether the Security Object in Anjay instance has been modified since last successful call to anjay_security_object_persist or anjay_security_object_restore.

anjay_security_object_persist()

avs_error_t anjay_security_object_persist	(	anjay_t *	anjay,
		avs_stream_t *	out_stream
	)

Dumps Security Object Instances to the out_stream.

Parameters

anjay	Anjay instance with Security Object installed.
out_stream	Stream to write to.

Returns

AVS_OK in case of success, or an error code.

anjay_security_object_purge()

void anjay_security_object_purge

(

anjay_t *

anjay

)

Purges instances of Security Object leaving it in an empty state.

Parameters

anjay

Anjay instance with Security Object installed to purge.

anjay_security_object_restore()

avs_error_t anjay_security_object_restore	(	anjay_t *	anjay,
		avs_stream_t *	in_stream
	)

Attempts to restore Security Object Instances from specified in_stream.

Note: if restore fails, then Security Object will be left untouched, on success though all Instances stored within the Object will be purged.

Parameters

anjay	Anjay instance with Security Object installed.
in_stream	Stream to read from.

Returns

AVS_OK in case of success, or an error code.