forked from nrfconnect/sdk-nrf
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathprotected_storage.h
281 lines (261 loc) · 13.3 KB
/
protected_storage.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
/*
* Copyright (c) 2023 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
*/
/* This file describes the PSA Protected Storage API */
#ifndef PSA_PROTECTED_STORAGE_H
#define PSA_PROTECTED_STORAGE_H
#include <stddef.h>
#include <stdint.h>
#include "psa/error.h"
#include "psa/storage_common.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup protected_storage PSA Protected Storage
* @{
*/
/**
* \brief PSA_PS_API_VERSION version
*
* Major and minor PSA_PS_API_VERSION numbers
*/
#define PSA_PS_API_VERSION_MAJOR 1
#define PSA_PS_API_VERSION_MINOR 0
/* This version of the header file is associated with 1.0 final release */
/**
* \brief Create a new, or modify an existing, uid/value pair
*
* Stores data in the protected storage.
*
* \param[in] uid The identifier for the data
* \param[in] data_length The size in bytes of the data in `p_data`
* \param[in] p_data A buffer containing the data
* \param[in] create_flags The flags that the data will be stored with
*
* \return A status indicating the success/failure of the operation
*
* \retval PSA_SUCCESS The operation completed successfully
* \retval PSA_ERROR_NOT_PERMITTED The operation failed because the
* provided `uid` value was already
* created with
* PSA_STORAGE_FLAG_WRITE_ONCE
* \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one
* of the provided pointers(`p_data`)
* is invalid, for example is `NULL` or
* references memory the caller cannot
* access
* \retval PSA_ERROR_NOT_SUPPORTED The operation failed because one or
* more of the flags provided in
* `create_flags` is not supported or is
* not valid
* \retval PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there
* was insufficient space on the
* storage medium
* \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the
* physical storage has failed (Fatal
* error)
* \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an
* unspecified internal failure
*/
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);
/**
* \brief Retrieve data associated with a provided uid
*
* Retrieves up to `data_size` bytes of the data associated with `uid`, starting
* at `data_offset` bytes from the beginning of the data. Upon successful
* completion, the data will be placed in the `p_data` buffer, which must be at
* least `data_size` bytes in size. The length of the data returned will be in
* `p_data_length`. If `data_size` is 0, the contents of `p_data_length` will
* be set to zero.
*
* \param[in] uid The uid value
* \param[in] data_offset The starting offset of the data requested
* \param[in] data_size The amount of data requested
* \param[out] p_data On success, the buffer where the data will
* be placed
* \param[out] p_data_length On success, this will contain size of the data
* placed in `p_data`
*
* \return A status indicating the success/failure of the operation
*
* \retval PSA_SUCCESS The operation completed successfully
* \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the
* provided arguments (`p_data`,
* `p_data_length`) is invalid, for example
* is `NULL` or references memory the
* caller cannot access. In addition, this
* can also happen if `data_offset` is
* larger than the size of the data
* associated with `uid`
* \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the
* provided `uid` value was not found in
* the storage
* \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the
* physical storage has failed (Fatal
* error)
* \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an
* unspecified internal failure
* \retval PSA_ERROR_DATA_CORRUPT The operation failed because the data
* associated with the UID was corrupt
* \retval PSA_ERROR_INVALID_SIGNATURE The operation failed because the data
* associated with the UID failed
* authentication
*/
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);
/**
* \brief Retrieve the metadata about the provided uid
*
* Retrieves the metadata stored for a given `uid`
*
* \param[in] uid The `uid` value
* \param[out] p_info A pointer to the `psa_storage_info_t` struct that will
* be populated with the metadata
*
* \return A status indicating the success/failure of the operation
*
* \retval PSA_SUCCESS The operation completed successfully
* \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the
* provided pointers(`p_info`)
* is invalid, for example is `NULL` or
* references memory the caller cannot
* access
* \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided
* uid value was not found in the storage
* \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical
* storage has failed (Fatal error)
* \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an
* unspecified internal failure
* \retval PSA_ERROR_DATA_CORRUPT The operation failed because the data
* associated with the UID was corrupt
*/
psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
/**
* \brief Remove the provided uid and its associated data from the storage
*
* Removes previously stored data and any associated metadata,
* including rollback protection data.
*
* \param[in] uid The `uid` value
*
* \return A status indicating the success/failure of the operation
*
* \retval PSA_SUCCESS The operation completed successfully
* \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more
* of the given arguments were invalid (null
* pointer, wrong flags and so on)
* \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided
* uid value was not found in the storage
* \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided
* uid value was created with
* PSA_STORAGE_FLAG_WRITE_ONCE
* \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical
* storage has failed (Fatal error)
* \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an
* unspecified internal failure
*/
psa_status_t psa_ps_remove(psa_storage_uid_t uid);
/**
* \brief Reserves storage for the specified uid
*
* Upon success, the capacity of the storage will be capacity, and the size
* will be 0. It is only necessary to call this function for assets that will
* be written with the psa_ps_set_extended function. If only the psa_ps_set
* function is needed, calls to this function are redundant.
*
* \param[in] uid The `uid` value
* \param[in] capacity The capacity to be allocated in bytes
* \param[in] create_flags Flags indicating properties of storage
*
* \return A status indicating the success/failure of the operation
*
* \retval PSA_SUCCESS The operation completed successfully
* \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the
* physical storage has failed
* (Fatal error)
* \retval PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because the
* capacity is bigger than the current
* available space
* \retval PSA_ERROR_NOT_SUPPORTED The operation failed because the
* function is not implemented or one
* or more create_flags are not
* supported.
* \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because uid was
* 0 or create_flags specified flags
* that are not defined in the API.
* \retval PSA_ERROR_GENERIC_ERROR The operation failed due to an
* unspecified error
* \retval PSA_ERROR_ALREADY_EXISTS Storage for the specified uid
* already exists
*/
psa_status_t psa_ps_create(psa_storage_uid_t uid, size_t capacity,
psa_storage_create_flags_t create_flags);
/**
* \brief Sets partial data into an asset
*
* Before calling this function, the storage must have been reserved with a call
* to psa_ps_create. It can also be used to overwrite data in an asset that was
* created with a call to psa_ps_set. Calling this function with data_length = 0
* is permitted, which will make no change to the stored data.This function can
* overwrite existing data and/or extend it up to the capacity for the uid
* specified in psa_ps_create, but cannot create gaps.
*
* That is, it has preconditions:
* - data_offset <= size
* - data_offset + data_length <= capacity
* and postconditions:
* - size = max(size, data_offset + data_length)
* - capacity unchanged.
*
* \param[in] uid The `uid` value
* \param[in] data_offset Offset within the asset to start the write
* \param[in] data_length The size in bytes of the data in p_data to write
* \param[in] p_data Pointer to a buffer which contains the data to write
*
* \return A status indicating the success/failure of the operation
*
* \retval PSA_SUCCESS The asset exists, the input parameters
* are correct and the data is correctly
* written in the physical storage.
* \retval PSA_ERROR_STORAGE_FAILURE The data was not written correctly in
* the physical storage
* \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more
* of the preconditions listed above
* regarding data_offset, size, or
* data_length was violated.
* \retval PSA_ERROR_DOES_NOT_EXIST The specified uid was not found
* \retval PSA_ERROR_NOT_SUPPORTED The implementation of the API does not
* support this function
* \retval PSA_ERROR_GENERIC_ERROR The operation failed due to an
* unspecified error
* \retval PSA_ERROR_DATA_CORRUPT The operation failed because the
* existing data has been corrupted.
* \retval PSA_ERROR_INVALID_SIGNATURE The operation failed because the
* existing data failed authentication
* (MAC check failed).
* \retval PSA_ERROR_NOT_PERMITTED The operation failed because it was
* attempted on an asset which was written
* with the flag
* PSA_STORAGE_FLAG_WRITE_ONCE
*/
psa_status_t psa_ps_set_extended(psa_storage_uid_t uid, size_t data_offset, size_t data_length,
const void *p_data);
/**
* \brief Lists optional features.
*
* \return A bitmask with flags set for all of
* the optional features supported by the
* implementation. Currently defined flags
* are limited to
* PSA_STORAGE_SUPPORT_SET_EXTENDED
*/
uint32_t psa_ps_get_support(void);
/** @} */
#ifdef __cplusplus
}
#endif
#endif /* PSA_PROTECTED_STORAGE_H */