Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM/TARGET_TFM_LATEST/include/psa/internal_trusted_storage.h
1 /*
2  * Copyright (c) 2019, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 /** This file describes the PSA Internal Trusted Storage API
9 */
10 
11 #ifndef PSA_INTERNAL_TRUSTED_STORAGE_H
12 #define PSA_INTERNAL_TRUSTED_STORAGE_H
13 
14 #include <stddef.h>
15 #include <stdint.h>
16 
17 #include "psa/error.h"
18 #include "psa/storage_common.h"
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 #define PSA_ITS_API_VERSION_MAJOR 1 /**< The major version number of the
24  * PSA ITS API
25  */
26 #define PSA_ITS_API_VERSION_MINOR 0 /**< The minor version number of the
27  * PSA ITS API
28  */
29 // This version of the header file is associated with 1.0 final release.
30 
31 /**
32  * \brief Create a new, or modify an existing, uid/value pair
33  *
34  * Stores data in the internal storage.
35  *
36  * \param[in] uid The identifier for the data
37  * \param[in] data_length The size in bytes of the data in `p_data`
38  * \param[in] p_data A buffer containing the data
39  * \param[in] create_flags The flags that the data will be stored with
40  *
41  * \return A status indicating the success/failure of the operation
42  *
43  * \retval PSA_SUCCESS The operation completed successfully
44  * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the
45  * provided `uid` value was already
46  * created with
47  * PSA_STORAGE_FLAG_WRITE_ONCE
48  * \retval PSA_ERROR_NOT_SUPPORTED The operation failed because one or
49  * more of the flags provided in
50  * `create_flags` is not supported or is
51  * not valid
52  * \retval PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there
53  * was insufficient space on the
54  * storage medium
55  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the
56  * physical storage has failed (Fatal
57  * error)
58  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one
59  * of the provided pointers(`p_data`)
60  * is invalid, for example is `NULL` or
61  * references memory the caller cannot
62  * access
63  */
65  size_t data_length,
66  const void *p_data,
67  psa_storage_create_flags_t create_flags);
68 
69 /**
70  * \brief Retrieve data associated with a provided UID
71  *
72  * Retrieves up to `data_size` bytes of the data associated with `uid`, starting
73  * at `data_offset` bytes from the beginning of the data. Upon successful
74  * completion, the data will be placed in the `p_data` buffer, which must be at
75  * least `data_size` bytes in size. The length of the data returned will be in
76  * `p_data_length`. If `data_size` is 0, the contents of `p_data_length` will
77  * be set to zero.
78  *
79  * \param[in] uid The uid value
80  * \param[in] data_offset The starting offset of the data requested
81  * \param[in] data_size The amount of data requested
82  * \param[out] p_data On success, the buffer where the data will
83  * be placed
84  * \param[out] p_data_length On success, this will contain size of the data
85  * placed in `p_data`
86  *
87  * \return A status indicating the success/failure of the operation
88  *
89  * \retval PSA_SUCCESS The operation completed successfully
90  * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the
91  * provided `uid` value was not found in
92  * the storage
93  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the
94  * physical storage has failed (Fatal
95  * error)
96  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the
97  * provided arguments (`p_data`,
98  * `p_data_length`) is invalid, for example
99  * is `NULL` or references memory the
100  * caller cannot access. In addition, this
101  * can also happen if `data_offset` is
102  * larger than the size of the data
103  * associated with `uid`
104  */
106  size_t data_offset,
107  size_t data_size,
108  void *p_data,
109  size_t *p_data_length);
110 
111 /**
112  * \brief Retrieve the metadata about the provided uid
113  *
114  * Retrieves the metadata stored for a given `uid` as a `psa_storage_info_t`
115  * structure.
116  *
117  * \param[in] uid The `uid` value
118  * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will
119  * be populated with the metadata
120  *
121  * \return A status indicating the success/failure of the operation
122  *
123  * \retval PSA_SUCCESS The operation completed successfully
124  * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided
125  * uid value was not found in the storage
126  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical
127  * storage has failed (Fatal error)
128  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the
129  * provided pointers(`p_info`)
130  * is invalid, for example is `NULL` or
131  * references memory the caller cannot
132  * access
133  */
135  struct psa_storage_info_t *p_info);
136 
137 /**
138  * \brief Remove the provided uid and its associated data from the storage
139  *
140  * Deletes the data from internal storage.
141  *
142  * \param[in] uid The `uid` value
143  *
144  * \return A status indicating the success/failure of the operation
145  *
146  * \retval PSA_SUCCESS The operation completed successfully
147  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more
148  * of the given arguments were invalid (null
149  * pointer, wrong flags and so on)
150  * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided
151  * uid value was not found in the storage
152  * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided
153  * uid value was created with
154  * PSA_STORAGE_FLAG_WRITE_ONCE
155  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical
156  * storage has failed (Fatal error)
157  */
159 
160 #ifdef __cplusplus
161 }
162 #endif
163 
164 #endif // PSA_INTERNAL_TRUSTED_STORAGE_H
uint64_t psa_storage_uid_t
A type for UIDs used for identifying data.
psa_status_t psa_its_set(psa_storage_uid_t uid, uint32_t data_length, const void *p_data, psa_storage_create_flags_t create_flags)
create a new or modify an existing uid/value pair
psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info)
Retrieve the metadata about the provided uid.
psa_status_t psa_its_get(psa_storage_uid_t uid, uint32_t data_offset, uint32_t data_length, void *p_data, size_t *p_data_length)
Retrieve the value associated with a provided uid.
psa_status_t psa_its_remove(psa_storage_uid_t uid)
Remove the provided key and its associated data from the storage.
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.