wms_secure_storage.h File Reference

Detailed Description

This library implements encrypted and authenticated record storage on top of the memory area library. Records can vary in length and are identified by 32-bit tags. Records can be read, written, or deleted.

Tags are similar to filenames. A tool called name_to_uint32.py is provided to convert up to six-character names to uint32 values and back. It is recommended to use this tool to generate tag values instead of choosing arbitrary numbers.

Applications have a predefined secure storage area for storing parameters. Additional areas may be created for special purposes.

Library services are accessed through the lib_secure_storage handle.

Definition in file wms_secure_storage.h.

Go to the source code of this file.

Typedefs
typedef uint32_t	app_lib_secure_storage_record_tag_t
	Secure storage record tag definition. More...
typedef app_lib_mem_area_res_e(*	app_lib_secure_storage_init_area_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_command_e cmd, uint32_t flags)
	Initialize secure storage area or check if already initialized. More...
typedef app_lib_mem_area_res_e(*	app_lib_secure_storage_read_record_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_record_tag_t tag, void *to, size_t *max_amount)
	Read a record from the secure storage area. More...
typedef app_lib_mem_area_res_e(*	app_lib_secure_storage_write_record_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_record_tag_t tag, const void *from, size_t amount, uint32_t flags)
	Write a record to the secure storage area, overwriting any previous version with the same record tag. More...
typedef app_lib_mem_area_res_e(*	app_lib_secure_storage_delete_record_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_record_tag_t tag)
	Delete a record in the secure storage area. More...

Data Structures
struct	app_lib_secure_storage_t
	List of library functions. More...

Enumerations
enum	app_lib_secure_storage_command_e { APP_LIB_SECURE_STORAGE_CMD_INIT = 0, APP_LIB_SECURE_STORAGE_CMD_NO_INIT = 1, APP_LIB_SECURE_STORAGE_CMD_ERASE = 2 }
	Secure storage initialization command. More...
enum	app_lib_secure_storage_record_flags_e { APP_LIB_SECURE_STORAGE_RECORD_FLAG_NO_ENCRYPT = (1 << 0), APP_LIB_SECURE_STORAGE_RECORD_FLAG_NO_AUTH = (1 << 1) }
	Secure storage record option flags. More...

Macros
#define	APP_LIB_SECURE_STORAGE_NAME   0x74be4415
	Library symbolic name. More...
#define	APP_LIB_SECURE_STORAGE_VERSION   0x200
	Maximum supported library version. More...

Typedef Documentation

app_lib_secure_storage_delete_record_f

typedef app_lib_mem_area_res_e(* app_lib_secure_storage_delete_record_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_record_tag_t tag)

Delete a record in the secure storage area.

Parameters

id	ID of the memory area to write
tag	Tag of record to delete

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful, APP_LIB_MEM_AREA_RES_INVALID_TAG if record doesn't exist. See app_lib_mem_area_res_e for memory area related result codes.

Definition at line 151 of file wms_secure_storage.h.

app_lib_secure_storage_init_area_f

typedef app_lib_mem_area_res_e(* app_lib_secure_storage_init_area_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_command_e cmd, uint32_t flags)

Initialize secure storage area or check if already initialized.

Parameters

id	ID of the memory area to initialize
cmd	Command to initialize or check secure storage area
flags	For future use, must be 0

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful, APP_LIB_MEM_AREA_RES_INVALID_TAG if area is not initialized when command is APP_LIB_SECURE_STORAGE_CMD_NO_INIT, APP_LIB_MEM_AREA_RES_NODRIVER if encryption or key management could not be initialized, APP_LIB_MEM_AREA_RES_PARAM for an error in parameters. See app_lib_mem_area_res_e for memory area related result codes.

Note

This function must be called before calling any other secure storage functions. It is safe to call this function multiple times, e.g., to erase an already initialized secure storage memory area.

Only areas of type APP_LIB_MEM_AREA_TYPE_USER are valid.

Accessing the memory area directly with memory area functions after it has been initialized as secure storage is undefined.

Definition at line 88 of file wms_secure_storage.h.

app_lib_secure_storage_read_record_f

typedef app_lib_mem_area_res_e(* app_lib_secure_storage_read_record_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_record_tag_t tag, void *to, size_t *max_amount)

Read a record from the secure storage area.

Parameters

id	ID of the memory area to read
tag	Tag of record to read
to	Pointer in RAM to read the record contents
max_amount	Number of bytes of space available for reading, actual number of bytes read returned

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful, APP_LIB_MEM_AREA_RES_INVALID_TAG if record doesn't exist, APP_LIB_MEM_AREA_RES_PARAM if max_amount is too small for the record contents, or other parameter error. See app_lib_mem_area_res_e for memory area related result codes.

Definition at line 109 of file wms_secure_storage.h.

app_lib_secure_storage_record_tag_t

typedef uint32_t app_lib_secure_storage_record_tag_t

Secure storage record tag definition.

Note

Use tools/genlibname.py to generate meaningful tag values

Definition at line 55 of file wms_secure_storage.h.

app_lib_secure_storage_write_record_f

typedef app_lib_mem_area_res_e(* app_lib_secure_storage_write_record_f) (app_lib_mem_area_id_t id, app_lib_secure_storage_record_tag_t tag, const void *from, size_t amount, uint32_t flags)

Write a record to the secure storage area, overwriting any previous version with the same record tag.

Parameters

id	ID of the memory area to write
tag	Tag of record to write. Previous record of the same tag will be overwritten
from	Pointer in RAM to the data to be written
amount	Number of bytes to write
flags	Record option flags, see app_lib_secure_storage_record_flags_e

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful, APP_LIB_MEM_AREA_RES_INVALID_TAG if not enough space available for the new record, APP_LIB_MEM_AREA_RES_PARAM for an error in parameters, APP_LIB_MEM_AREA_RES_NODRIVER for a write verify error. See app_lib_mem_area_res_e for memory area related result codes.

Definition at line 134 of file wms_secure_storage.h.

---

Data Structure Documentation

app_lib_secure_storage_t

struct app_lib_secure_storage_t

List of library functions.

Definition at line 157 of file wms_secure_storage.h.

Data Fields
app_lib_secure_storage_delete_record_f	deleteRecord
app_lib_secure_storage_init_area_f	initArea
app_lib_secure_storage_read_record_f	readRecord
app_lib_secure_storage_write_record_f	writeRecord

Enumeration Type Documentation

app_lib_secure_storage_command_e

enum app_lib_secure_storage_command_e

Secure storage initialization command.

Enumerator
APP_LIB_SECURE_STORAGE_CMD_INIT	Initialize if not already initialized
APP_LIB_SECURE_STORAGE_CMD_NO_INIT	Use as-is, return error if not initialized
APP_LIB_SECURE_STORAGE_CMD_ERASE	Unconditional initialization (erase)

Definition at line 42 of file wms_secure_storage.h.

{
    APP_LIB_SECURE_STORAGE_CMD_INIT = 0,
    APP_LIB_SECURE_STORAGE_CMD_NO_INIT = 1,
    APP_LIB_SECURE_STORAGE_CMD_ERASE = 2,
} app_lib_secure_storage_command_e;

app_lib_secure_storage_record_flags_e

enum app_lib_secure_storage_record_flags_e

Secure storage record option flags.

Enumerator
APP_LIB_SECURE_STORAGE_RECORD_FLAG_NO_ENCRYPT	Do not encrypt record contents
APP_LIB_SECURE_STORAGE_RECORD_FLAG_NO_AUTH	Do not authenticate record contents

Definition at line 58 of file wms_secure_storage.h.

{
    APP_LIB_SECURE_STORAGE_RECORD_FLAG_NO_ENCRYPT = (1 << 0),
    APP_LIB_SECURE_STORAGE_RECORD_FLAG_NO_AUTH = (1 << 1),
} app_lib_secure_storage_record_flags_e;

Macro Definition Documentation

APP_LIB_SECURE_STORAGE_NAME

#define APP_LIB_SECURE_STORAGE_NAME   0x74be4415

Library symbolic name.

"SECURE"

Definition at line 36 of file wms_secure_storage.h.

APP_LIB_SECURE_STORAGE_VERSION

#define APP_LIB_SECURE_STORAGE_VERSION   0x200

Maximum supported library version.

Definition at line 39 of file wms_secure_storage.h.