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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.