storage.h File Reference

Platform hooks for external cryptographic storage. More...

#include <anj/init.h>
#include <anj/crypto.h>
#include <anj/defs.h>

Go to the source code of this file.

Macros
#define	ANJ_CRYPTO_STORAGE_PERSISTENCE_INFO_MAX_SIZE   64

Functions
int	anj_crypto_storage_init (void **out_crypto_ctx)
int	anj_crypto_storage_create_new_record (void *crypto_ctx, anj_crypto_security_info_t *out_info)
int	anj_crypto_storage_store_data (void *crypto_ctx, const anj_crypto_security_info_t *info, const void *data, size_t data_size, bool last_chunk)
int	anj_crypto_storage_delete_record (void *crypto_ctx, const anj_crypto_security_info_t *info)
int	anj_crypto_storage_resolve_security_info (void *crypto_ctx, anj_crypto_security_info_external_t *info, char *out_buffer, size_t out_buffer_size, size_t *out_record_size)
void	anj_crypto_storage_deinit (void *out_crypto_ctx)
int	anj_crypto_storage_get_persistence_info (void *crypto_ctx, const anj_crypto_security_info_external_t *info, void *out_data, size_t *out_data_size)
int	anj_crypto_storage_resolve_persistence_info (void *crypto_ctx, const void *data, size_t data_size, anj_crypto_security_info_external_t *out_info)

Detailed Description

Platform hooks for external cryptographic storage.

This header declares the API that platform integrators can implement to back Anjay Lite's credential handling with a secure store or HSM.

Typical responsibilities include:

• initializing and deinitializing a storage context
• creating and deleting key/certificate records
• writing data in chunks and finalizing records
• resolving identifiers into actual key/certificate bytes
• (optionally) serializing/deserializing persistence identifiers

Which functions are required depends on build-time options such as ANJ_WITH_EXTERNAL_CRYPTO_STORAGE and ANJ_WITH_PERSISTENCE.

Macro Definition Documentation

ANJ_CRYPTO_STORAGE_PERSISTENCE_INFO_MAX_SIZE

#define ANJ_CRYPTO_STORAGE_PERSISTENCE_INFO_MAX_SIZE   64

Maximum size of the persistence information used for storing cryptographic data.

Function Documentation

anj_crypto_storage_create_new_record()

int anj_crypto_storage_create_new_record	(	void *	crypto_ctx,
		anj_crypto_security_info_t *	out_info
	)

Creates a new security information record.

This function is called to create a new security information record. The implementation should allocate and initialize a new record on the underlying storage side, which will then be populated with data in subsequent calls to anj_crypto_storage_store_data.

The out_info->tag and out_info->source are set by the caller to identify the type and source of the security information being stored.

Parameters

	crypto_ctx	Cryptographic context.
[in,out]	out_info	Pointer to a structure that will receive the newly created security information record.

Returns

0 on success, or a negative value on failure.

anj_crypto_storage_deinit()

void anj_crypto_storage_deinit

(

void *

out_crypto_ctx

)

Deinitializes the Cryptographic storage context.

This function is called once in anj_core_shutdown to clean up the resources associated with the Cryptographic storage context.

Parameters

out_crypto_ctx

Cryptographic context.

anj_crypto_storage_delete_record()

int anj_crypto_storage_delete_record	(	void *	crypto_ctx,
		const anj_crypto_security_info_t *	info
	)

Deletes a security record.

This function removes the certificate, key, or other security information identified by info. After successful deletion, the record should no longer be retrievable through this API.

Parameters

crypto_ctx	Cryptographic context.
info	Identifier of the security record to delete.

Returns

0 on success, or a negative value on failure.

anj_crypto_storage_get_persistence_info()

int anj_crypto_storage_get_persistence_info	(	void *	crypto_ctx,
		const anj_crypto_security_info_external_t *	info,
		void *	out_data,
		size_t *	out_data_size
	)

Serializes key or certificate identification data from anj_crypto_security_info_external_t into the ANJ_DATA_TYPE_BYTES format for persistence.

This function is called by the Security Object to convert the given info into a byte array. The resulting data can be deserialized back into an anj_crypto_security_info_external_t using anj_crypto_storage_resolve_persistence_info.

Note

out_data_size can't exceed ANJ_CRYPTO_STORAGE_PERSISTENCE_INFO_MAX_SIZE.

Parameters

	crypto_ctx	Cryptographic context.
	info	Key or certificate identifier used to retrieve the data.
[out]	out_data	Pointer to the data buffer.
[out]	out_data_size	Size of the retrieved data.

Returns

0 on success, or a negative value on failure.

anj_crypto_storage_init()

int anj_crypto_storage_init

(

void **

out_crypto_ctx

)

Called once in anj_core_init to initialize the Cryptographic storage module.

Parameters

[out]

out_crypto_ctx

Pointer to a pointer that will receive the Cryptographic context. This can be NULL if the Cryptographic module does not require a context.

Returns

0 on success, or non-zero error code on failure.

anj_crypto_storage_resolve_persistence_info()

int anj_crypto_storage_resolve_persistence_info	(	void *	crypto_ctx,
		const void *	data,
		size_t	data_size,
		anj_crypto_security_info_external_t *	out_info
	)

This function is called by the Security Object to interpret the provided data buffer and populate out_info with the corresponding key or certificate identifier. It is the reverse operation of anj_crypto_storage_get_persistence_info.

Note

All data must be provided in single chunk.

Parameters

	crypto_ctx	Cryptographic context.
	data	Pointer to the data buffer containing the certificate or key identifier in ANJ_DATA_TYPE_BYTES format.
	data_size	Size of the data buffer in bytes.
[out]	out_info	Pointer to a structure that will be filled with the resolved persistence information.

Returns

0 on success, or a negative value on failure.

anj_crypto_storage_resolve_security_info()

int anj_crypto_storage_resolve_security_info	(	void *	crypto_ctx,
		anj_crypto_security_info_external_t *	info,
		char *	out_buffer,
		size_t	out_buffer_size,
		size_t *	out_record_size
	)

Retrieves the security information from the storage.

This function is called to load the security information from the storage into a buffer. The implementation should read the data associated with the provided info and copy it into the out_buffer. The size of the buffer is specified by out_buffer_size, and the actual size of the loaded data should be returned in out_record_size.

Parameters

	crypto_ctx	Cryptographic context.
	info	Security record identifier.
[out]	out_buffer	Buffer to store the loaded data.
	out_buffer_size	Size of the output buffer.
[out]	out_record_size	Size of the loaded data.

Returns

0 on success, negative value on failure.

anj_crypto_storage_store_data()

int anj_crypto_storage_store_data	(	void *	crypto_ctx,
		const anj_crypto_security_info_t *	info,
		const void *	data,
		size_t	data_size,
		bool	last_chunk
	)

Stores certificate or key data in the specified security record.

This function is always called after a successful call to anj_crypto_storage_create_new_record for the same security record.

This function is called to store a portion (or the entirety) of the certificate or key data in the record identified by info. Data may be provided in multiple calls, in which case the implementation should append each chunk to the existing record until the final chunk is received.

When last_chunk is true, the implementation should finalize the storage process and make the record ready for use.

Note

In case of any error during the storage process, Anjay will always call anj_crypto_storage_delete_record.

Only one security record can be created at a time.

Parameters

crypto_ctx	Cryptographic context.
info	Identifier of the target security record.
data	Pointer to the data to store.
data_size	Size of the provided data chunk in bytes.
last_chunk	True if this is the final data chunk.

Returns

0 on success, or a negative value on failure.