protected_storage

Protected Storage API 提供安全存储服务，支持根据唯一标识符（uid）对敏感数据进行创建、读取、删除及元数据查询等操作，并可通过标志位控制数据的写保护和机密性属性。

头文件清单

#include "middleware/utils/psa/protected_storage.h"

接口清单

接口名称	功能简述
psa_ps_set	根据指定uid存储数据
psa_ps_get	根据指定uid获取存储数据
psa_ps_get_info	根据指定uid获取元数据信息
psa_ps_remove	根据指定uid删除存储数据
psa_ps_create	根据指定uid预留存储空间
psa_ps_set_extended	根据指定uid在指定偏移处写入数据
psa_ps_get_support	获取实现支持的可选功能标志位掩码

Functions

psa_ps_set

函数声明

psa_status_t psa_ps_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags)

头文件清单

#include "middleware/utils/psa/protected_storage.h"

功能说明

根据指定的uid存储数据到安全存储区
若该uid已存在数据，则覆盖原有数据
通过create_flags参数指定数据的属性标志

前置条件

安全存储服务已初始化就绪
uid取值有效且未被写保护标志锁定（若已设置PSA_STORAGE_FLAG_WRITE_ONCE则不可覆盖）

入参

名称	参数类型	详细说明	约束取值范围
uid	psa_storage_uid_t	数据标识符	`0` ~ `0xFFFFFFFFFFFFFFFF`
data_length	size_t	数据长度，单位字节	`0` ~ 存储最大容量
p_data	const void *	数据缓存区指针	非NULL
create_flags	psa_storage_create_flags_t	数据标志属性	- PSA_STORAGE_FLAG_NONE - PSA_STORAGE_FLAG_WRITE_ONCE - PSA_STORAGE_FLAG_NO_CONFIDENTIALITY - PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION

返回值

返回类型：psa_status_t

返回值	文字含义	触发场景
PSA_SUCCESS(0)	执行成功	数据存储成功
Other	其他错误码，参考psa_status_t	执行失败

psa_ps_get

函数声明

psa_status_t psa_ps_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length)

头文件清单

#include "middleware/utils/psa/protected_storage.h"

功能说明

根据指定uid从安全存储区获取数据
支持从指定偏移位置读取指定大小的数据
通过p_data_length返回实际读取的数据长度

前置条件

安全存储服务已初始化就绪
指定uid对应的存储数据已存在

入参

名称	参数类型	详细说明	约束取值范围
uid	psa_storage_uid_t	数据标识符	`0` ~ `0xFFFFFFFFFFFFFFFF`
data_offset	size_t	数据偏移量，单位字节	`0` ~ 存储数据总大小
data_size	size_t	请求读取的数据大小，单位字节	`0` ~ 存储数据总大小

出参

名称	数据类型	输出说明
p_data	void *	实际读取的存储数据
p_data_length	size_t *	实际读取的数据长度，单位字节

返回值

返回类型：psa_status_t

返回值	文字含义	触发场景
PSA_SUCCESS(0)	执行成功	数据读取成功
Other	其他错误码，参考psa_status_t	执行失败

psa_ps_get_info

函数声明

psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info)

头文件清单

#include "middleware/utils/psa/protected_storage.h"

功能说明

根据指定uid获取存储数据的元数据信息
元数据包括存储容量、数据大小和创建标志属性
通过p_info结构体返回完整的元数据

前置条件

安全存储服务已初始化就绪
指定uid对应的存储数据已存在

入参

名称	参数类型	详细说明	约束取值范围
uid	psa_storage_uid_t	数据标识符	`0` ~ `0xFFFFFFFFFFFFFFFF`

出参

名称	数据类型	输出说明
p_info	struct psa_storage_info_t *	存储数据的元数据信息，包含容量、大小和标志

返回值

返回类型：psa_status_t

返回值	文字含义	触发场景
PSA_SUCCESS(0)	执行成功	元数据获取成功
Other	其他错误码，参考psa_status_t	执行失败

psa_ps_remove

函数声明

psa_status_t psa_ps_remove(psa_storage_uid_t uid)

头文件清单

#include "middleware/utils/psa/protected_storage.h"

功能说明

根据指定uid删除安全存储区中的数据
删除后该uid及其关联数据将从存储中移除
设置了写保护标志的数据不可删除

前置条件

安全存储服务已初始化就绪
指定uid对应的存储数据已存在
uid未被PSA_STORAGE_FLAG_WRITE_ONCE标志锁定

入参

名称	参数类型	详细说明	约束取值范围
uid	psa_storage_uid_t	数据标识符	`0` ~ `0xFFFFFFFFFFFFFFFF`

返回值

返回类型：psa_status_t

返回值	文字含义	触发场景
PSA_SUCCESS(0)	执行成功	数据删除成功
Other	其他错误码，参考psa_status_t	执行失败

psa_ps_create

函数声明

psa_status_t psa_ps_create(psa_storage_uid_t uid, size_t capacity, psa_storage_create_flags_t create_flags)

头文件清单

#include "middleware/utils/psa/protected_storage.h"

功能说明

根据指定uid预留指定容量的存储空间
通过create_flags参数指定数据的属性标志
预留空间后可通过psa_ps_set_extended接口写入数据

前置条件

安全存储服务已初始化就绪
指定uid尚未被创建或占用

入参

名称	参数类型	详细说明	约束取值范围
uid	psa_storage_uid_t	数据标识符	`0` ~ `0xFFFFFFFFFFFFFFFF`
capacity	size_t	预留存储容量，单位字节	`0` ~ 存储最大容量
create_flags	psa_storage_create_flags_t	数据标志属性	- PSA_STORAGE_FLAG_NONE - PSA_STORAGE_FLAG_WRITE_ONCE - PSA_STORAGE_FLAG_NO_CONFIDENTIALITY - PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION

返回值

返回类型：psa_status_t

返回值	文字含义	触发场景
PSA_SUCCESS(0)	执行成功	存储空间预留成功
Other	其他错误码，参考psa_status_t	执行失败

psa_ps_set_extended

函数声明

psa_status_t psa_ps_set_extended(psa_storage_uid_t uid, size_t data_offset, size_t data_length, const void *p_data)

头文件清单

#include "middleware/utils/psa/protected_storage.h"

功能说明

根据指定uid在指定偏移处写入数据
支持向已预留的存储空间中部分写入数据
适用于先通过psa_ps_create预留空间后再分次写入数据的场景

前置条件

安全存储服务已初始化就绪
指定uid已通过psa_ps_create预留了足够的存储空间
data_offset + data_length不超过预留容量

入参

名称	参数类型	详细说明	约束取值范围
uid	psa_storage_uid_t	数据标识符	`0` ~ `0xFFFFFFFFFFFFFFFF`
data_offset	size_t	数据写入偏移量，单位字节	`0` ~ 预留容量
data_length	size_t	写入数据长度，单位字节	`0` ~ 预留容量
p_data	const void *	数据缓存区指针	非NULL

返回值

返回类型：psa_status_t

返回值	文字含义	触发场景
PSA_SUCCESS(0)	执行成功	数据写入成功
Other	其他错误码，参考psa_status_t	执行失败

psa_ps_get_support

函数声明

uint32_t psa_ps_get_support(void)

头文件清单

#include "middleware/utils/psa/protected_storage.h"

功能说明

获取实现所支持的可选功能标志位掩码
返回值中的各个标志位表示对应可选功能的支持状态
可用于判断是否支持psa_ps_set_extended等扩展功能

返回值

返回类型：uint32_t

返回值	文字含义	触发场景
PSA_STORAGE_SUPPORT_SET_EXTENDED(1)	支持set_extended扩展功能	实现支持psa_ps_set_extended接口
0	不支持任何扩展功能	实现不支持可选扩展功能

Type definitions

psa_status_t

typedef int32_t psa_status_t;

使用说明 作为psa_ps_set、psa_ps_get、psa_ps_get_info、psa_ps_remove、psa_ps_create、psa_ps_set_extended接口的返回值类型 [SDK公共基础类型]

psa_storage_uid_t

typedef uint64_t psa_storage_uid_t;

使用说明 作为psa_ps_set、psa_ps_get、psa_ps_get_info、psa_ps_remove、psa_ps_create、psa_ps_set_extended接口的uid参数类型

psa_storage_create_flags_t

typedef uint32_t psa_storage_create_flags_t;

使用说明 作为psa_ps_set、psa_ps_create接口的create_flags参数类型

Structures

psa_storage_info_t

struct psa_storage_info_t {
    /// @brief The allocated capacity of the storage associated with a uid.
    size_t capacity;
    /// @brief The size of the data associated with a uid.
    size_t size;
    /// @brief The flags set when the uid was create
    psa_storage_create_flags_t flags;
};

成员说明

成员名称	数据类型	描述
capacity	size_t	uid关联的存储分配容量，单位字节
size	size_t	uid关联的实际数据大小，单位字节
flags	psa_storage_create_flags_t	创建uid时设置的标志属性

Macros

PSA_STORAGE_FLAG_NONE

#define PSA_STORAGE_FLAG_NONE 0u

PSA_STORAGE_FLAG_WRITE_ONCE

#define PSA_STORAGE_FLAG_WRITE_ONCE (1u << 0)

PSA_STORAGE_FLAG_NO_CONFIDENTIALITY

#define PSA_STORAGE_FLAG_NO_CONFIDENTIALITY (1u << 1)

PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION

#define PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION (1u << 2)

PSA_STORAGE_SUPPORT_SET_EXTENDED

#define PSA_STORAGE_SUPPORT_SET_EXTENDED (1u << 0)