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