Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
protected_storage.h
Go to the documentation of this file.
1 /* Copyright (C) 2019, ARM Limited, All Rights Reserved
2  * SPDX-License-Identifier: Apache-2.0
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may
5  * not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /** @file
18 @brief This file describes the PSA Protected Storage API
19 */
20 
21 #ifndef __PSA_PROTECTED_STORAGE_H__
22 #define __PSA_PROTECTED_STORAGE_H__
23 
24 #include <stddef.h>
25 #include <stdint.h>
26 
27 #include "psa/error.h"
28 #include "psa/storage_common.h"
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 #define PSA_PS_API_VERSION_MAJOR 1 /**< The major version number of the PSA PS API. It will be incremented on significant updates that may include breaking changes */
35 #define PSA_PS_API_VERSION_MINOR 1 /**< The minor version number of the PSA PS API. It will be incremented in small updates that are unlikely to include breaking changes */
36 
37 
38 /**
39  * \brief create a new or modify an existing key/value pair
40  *
41  * \param[in] uid the identifier for the data
42  * \param[in] data_length The size in bytes of the data in `p_data`
43  * \param[in] p_data A buffer containing the data
44  * \param[in] create_flags The flags indicating the properties of the data
45  *
46  * \return A status indicating the success/failure of the operation
47 
48  * \retval PSA_SUCCESS The operation completed successfully
49  * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided uid value was already created with PSA_STORAGE_WRITE_ONCE_FLAG
50  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid.
51  * \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
52  * \retval PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there was insufficient space on the storage medium
53  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
54  * \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an unspecified internal failure
55  */
56 psa_status_t psa_ps_set(psa_storage_uid_t uid,
57  size_t data_length,
58  const void *p_data,
59  psa_storage_create_flags_t create_flags);
60 
61 /**
62  * \brief Retrieve the value for a provided uid
63  *
64  * \param[in] uid The identifier for the data
65  * \param[in] data_offset The offset within the data associated with the `uid` to start retrieving data
66  * \param[in] data_length The amount of data to read (and the minimum allocated size of the `p_data` buffer)
67  * \param[out] p_data The buffer where the data will be placed upon successful completion
68  * \param[out] p_data_length The actual amount of data returned
69  *
70  * \return A status indicating the success/failure of the operation
71  *
72  * \retval PSA_SUCCESS The operation completed successfully
73  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
74  * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage
75  * \retval PSA_ERROR_BUFFER_TOO_SMALL The operation failed because the data associated with provided uid does not fit `data_size`
76  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
77  * \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an unspecified internal failure
78  * \retval PSA_ERROR_DATA_CORRUPT The operation failed because of an authentication failure when attempting to get the key
79  * \retval PSA_ERROR_INVALID_SIGNATURE The operation failed because the data associated with the UID failed authentication
80  */
81 psa_status_t psa_ps_get(psa_storage_uid_t uid,
82  size_t data_offset,
83  size_t data_length,
84  void *p_data,
85  size_t *p_data_length);
86 
87 /**
88  * \brief Retrieve the metadata about the provided uid
89  *
90  * \param[in] uid The identifier for the data
91  * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will be populated with the metadata
92  *
93  * \return A status indicating the success/failure of the operation
94  *
95  * \retval PSA_SUCCESS The operation completed successfully
96  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
97  * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage
98  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
99  * \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an unspecified internal failure
100  * \retval PSA_ERROR_DATA_CORRUPT The operation failed because of an authentication failure when attempting to get the key
101  * \retval PSA_ERROR_INVALID_SIGNATURE The operation failed because the data associated with the UID failed authentication
102  */
103 psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info);
104 
105 /**
106  * \brief Remove the provided uid and its associated data from the storage
107  *
108  * \param[in] uid The identifier for the data to be removed
109  *
110  * \return A status indicating the success/failure of the operation
111  *
112  * \retval PSA_SUCCESS The operation completed successfully
113  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags etc.)
114  * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage
115  * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided uid value was created with psa_eps_WRITE_ONCE_FLAG
116  * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
117  * \retval PSA_ERROR_GENERIC_ERROR The operation failed because of an unspecified internal failure
118  */
119 psa_status_t psa_ps_remove(psa_storage_uid_t uid);
120 
121 /**
122  * Creates an asset based on the given identifier, the maximum size and
123  * creation flags. This create allocates the space in the secure storage
124  * area without setting any data in the asset.
125  *
126  * It is only necessary to call this function for items that will be written
127  * with the \ref psa_ps_set_extended function. If only the \ref psa_ps_set function
128  * is needed, calls to this function are redundant.
129  *
130  * If the \ref PSA_STORAGE_FLAG_WRITE_ONCE flag is passed, implementations should
131  * return \ref PSA_ERROR_NOT_SUPPORTED.
132  *
133  * This function is optional. Not all PSA Protected Storage Implementations
134  * will implement this function. Consult the documentation of your chosen
135  * platform to determine if it is present.
136  *
137  * \param[in] uid A unique identifier for the asset.
138  * \param[in] size The maximum size in bytes of the asset.
139  * \param[in] create_flags Create flags \ref psa_storage_create_flags_t.
140  *
141  * \retval PSA_SUCCESS The assest does not exist and the input parameters are correct or
142  * the asset already exists, the input parameters are the same that
143  * have been used to create the asset and the owner is the same and the current asset content is kept
144  * TDB: "Owner is the same" doesn't really make sense from a PSA perspective, as each partition
145  * has its own UID space, making other partitions' data unadressable
146  * \retval PSA_ERROR_STORAGE_FAILURE The create action has a physical storage error
147  * \retval PSA_ERROR_INSUFFICIENT_STORAGE The maximum size is bigger of the current available space
148  * \retval PSA_ERROR_NOT_SUPPORTED One or more create_flags are not valid or supported
149  * \retval PSA_ERROR_INVALID_ARGUMENT The asset exists and the input paramters are not the same as the existing asset
150  * \retval PSA_ERROR_NOT_SUPPORTED The implementation of the API does not support this function
151  * \retval PSA_ERROR_GENERIC_ERROR The operation has failed due to an unspecified error
152  */
153 psa_status_t psa_ps_create(psa_storage_uid_t uid,
154  size_t size,
155  psa_storage_create_flags_t create_flags);
156 
157 /**
158  * Sets partial data into an asset based on the given identifier, data_offset,
159  * data length and p_data.
160  *
161  * Before calling this function, the asset must have been created with a call
162  * to \ref psa_ps_create.
163  *
164  * This function is optional. Not all PSA Protected Storage Implementations
165  * will implement this function. Consult the documentation of your chosen
166  * platform to determine if it is present.
167  *
168  * \param[in] uid The unique identifier for the asset.
169  * \param[in] data_offset Offset within the asset to start the write.
170  * \param[in] data_length The size in bytes of the data in p_data to write.
171  * \param[in] p_data Pointer to a buffer which contains the data to write.
172  *
173  * \retval PSA_SUCCESS If the asset exists, the input parameters are correct and the data
174  * is correctly written in the physical storage
175  * \retval PSA_ERROR_STORAGE_FAILURE If the data is not written correctly in the physical storage
176  * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more of the given arguments were invalid (null pointer, wrong flags, etc)
177  * \retval PSA_ERROR_DOES_NOT_EXIST The specified UID was not found
178  * \retval PSA_ERROR_NOT_SUPPORTED The implementation of the API does not support this function
179  * \retval PSA_ERROR_GENERIC_ERROR The operation failed due to an unspecified error
180  * \retval PSA_ERROR_DATA_CORRUPT The operation failed because the existing data has been corrupted
181  * \retval PSA_ERROR_INVALID_SIGNATURE The operation failed because the existing data failed authentication (MAC check failed)
182  */
183 psa_status_t psa_ps_set_extended(psa_storage_uid_t uid,
184  size_t data_offset,
185  size_t data_length,
186  const void *p_data);
187 
188 /**
189  * Returns a bitmask with flags set for all of the optional features supported
190  * by the implementation.
191  *
192  * Currently defined flags are limited to:
193  * - \ref PSA_STORAGE_SUPPORT_SET_EXTENDED
194  */
195 uint32_t psa_ps_get_support(void);
196 
197 #ifdef __cplusplus
198 }
199 #endif
200 
201 
202 #endif // __PSA_PROTECTED_STORAGE_H__
storage_common.h
This file includes common definitions for PSA storage.
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)
create a new or modify an existing key/value pair
psa_ps_get_info
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.
psa_ps_create
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_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)
Sets partial data into an asset based on the given identifier, data_offset, data length and p_data...
psa_ps_get
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_ps_remove
psa_status_t psa_ps_remove(psa_storage_uid_t uid)
Remove the provided uid and its associated data from the storage.
psa_ps_get_support
uint32_t psa_ps_get_support(void)
Returns a bitmask with flags set for all of the optional features supported by the implementation...
psa_storage_uid_t
uint64_t psa_storage_uid_t
A type for UIDs used for identifying data.
Definition: storage_common.h:43
psa_storage_info_t
A container for metadata associated with a specific uid.
Definition: storage_common.h:48
psa_storage_create_flags_t
uint32_t psa_storage_create_flags_t
Flags used when creating a data entry.
Definition: storage_common.h:34
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.