Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
psa_crypto_its.h
Go to the documentation of this file.
1 /** \file psa_crypto_its.h
2  * \brief Interface of trusted storage that crypto is built on.
3  */
4 /*
5  * Copyright The Mbed TLS Contributors
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License"); you may
9  * not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 
21 #ifndef PSA_CRYPTO_ITS_H
22 #define PSA_CRYPTO_ITS_H
23 
24 #include <stddef.h>
25 #include <stdint.h>
26 
27 #include <psa/crypto_types.h>
28 #include <psa/crypto_values.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /** \brief Flags used when creating a data entry
35  */
36 typedef uint32_t psa_storage_create_flags_t;
37 
38 /** \brief A type for UIDs used for identifying data
39  */
40 typedef uint64_t psa_storage_uid_t;
41 
42 #define PSA_STORAGE_FLAG_NONE 0 /**< No flags to pass */
43 #define PSA_STORAGE_FLAG_WRITE_ONCE (1 << 0) /**< The data associated with the uid will not be able to be modified or deleted. Intended to be used to set bits in `psa_storage_create_flags_t`*/
44 
45 /**
46  * \brief A container for metadata associated with a specific uid
47  */
48 struct psa_storage_info_t
49 {
50  uint32_t size; /**< The size of the data associated with a uid **/
51  psa_storage_create_flags_t flags; /**< The flags set when the uid was created **/
52 };
53 
54 /** Flag indicating that \ref psa_storage_create and \ref psa_storage_set_extended are supported */
55 #define PSA_STORAGE_SUPPORT_SET_EXTENDED (1 << 0)
56 
57 /** \brief PSA storage specific error codes
58  */
59 #define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149)
60 #define PSA_ERROR_DATA_CORRUPT ((psa_status_t)-152)
61 
62 #define PSA_ITS_API_VERSION_MAJOR 1 /**< The major version number of the PSA ITS API. It will be incremented on significant updates that may include breaking changes */
63 #define PSA_ITS_API_VERSION_MINOR 1 /**< The minor version number of the PSA ITS API. It will be incremented in small updates that are unlikely to include breaking changes */
64 
65 /**
66  * \brief create a new or modify an existing uid/value pair
67  *
68  * \param[in] uid the identifier for the data
69  * \param[in] data_length The size in bytes of the data in `p_data`
70  * \param[in] p_data A buffer containing the data
71  * \param[in] create_flags The flags that the data will be stored with
72  *
73  * \return A status indicating the success/failure of the operation
74  *
75  * \retval #PSA_SUCCESS The operation completed successfully
76  * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided `uid` value was already created with PSA_STORAGE_WRITE_ONCE_FLAG
77  * \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
78  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there was insufficient space on the storage medium
79  * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
80  * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`)
81  * is invalid, for example is `NULL` or references memory the caller cannot access
82  */
83 psa_status_t psa_its_set(psa_storage_uid_t uid,
84  uint32_t data_length,
85  const void *p_data,
86  psa_storage_create_flags_t create_flags);
87 
88 /**
89  * \brief Retrieve the value associated with a provided uid
90  *
91  * \param[in] uid The uid value
92  * \param[in] data_offset The starting offset of the data requested
93  * \param[in] data_length the amount of data requested (and the minimum allocated size of the `p_data` buffer)
94  * \param[out] p_data The buffer where the data will be placed upon successful completion
95  * \param[out] p_data_length The amount of data returned in the p_data buffer
96  *
97  *
98  * \return A status indicating the success/failure of the operation
99  *
100  * \retval #PSA_SUCCESS The operation completed successfully
101  * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided `uid` value was not found in the storage
102  * \retval #PSA_ERROR_INVALID_SIZE The operation failed because the data associated with provided uid is larger than `data_size`
103  * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
104  * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`, `p_data_length`)
105  * is invalid. For example is `NULL` or references memory the caller cannot access.
106  * In addition, this can also happen if an invalid offset was provided.
107  */
108 psa_status_t psa_its_get(psa_storage_uid_t uid,
109  uint32_t data_offset,
110  uint32_t data_length,
111  void *p_data,
112  size_t *p_data_length );
113 
114 /**
115  * \brief Retrieve the metadata about the provided uid
116  *
117  * \param[in] uid The uid value
118  * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will be populated with the metadata
119  *
120  * \return A status indicating the success/failure of the operation
121  *
122  * \retval #PSA_SUCCESS The operation completed successfully
123  * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage
124  * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
125  * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_info`)
126  * is invalid, for example is `NULL` or references memory the caller cannot access
127  */
128 psa_status_t psa_its_get_info(psa_storage_uid_t uid,
129  struct psa_storage_info_t *p_info);
130 
131 /**
132  * \brief Remove the provided key and its associated data from the storage
133  *
134  * \param[in] uid The uid value
135  *
136  * \return A status indicating the success/failure of the operation
137  *
138  * \retval #PSA_SUCCESS The operation completed successfully
139  * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided key value was not found in the storage
140  * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided key value was created with PSA_STORAGE_WRITE_ONCE_FLAG
141  * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
142  */
143 psa_status_t psa_its_remove(psa_storage_uid_t uid);
144 
145 #ifdef __cplusplus
146 }
147 #endif
148 
149 #endif /* PSA_CRYPTO_ITS_H */
psa_its_set
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_its_get_info
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_its_get
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_its_remove
psa_status_t psa_its_remove(psa_storage_uid_t uid)
Remove the provided key and its associated data from the storage.
psa_storage_info_t::size
uint32_t size
The size of the data associated with a uid.
Definition: psa_crypto_its.h:50
psa_storage_create_flags_t
uint32_t psa_storage_create_flags_t
Flags used when creating a data entry.
Definition: psa_crypto_its.h:36
psa_storage_info_t
A container for metadata associated with a specific uid.
Definition: TARGET_MBED_PSA_SRV/inc/psa/storage_common.h:48
psa_storage_info_t::flags
psa_storage_create_flags_t flags
The flags set when the uid was created.
Definition: TARGET_MBED_PSA_SRV/inc/psa/storage_common.h:51
psa_storage_uid_t
uint64_t psa_storage_uid_t
A type for UIDs used for identifying data.
Definition: psa_crypto_its.h:40
psa_status_t
int32_t psa_status_t
Function return status.
Definition: TARGET_MBED_PSA_SRV/inc/psa/crypto_types.h:55
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.