NCBI C++ ToolKit
psa_crypto_its.h
Go to the documentation of this file.

Go to the SVN repository for 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  */
37 
38 /** \brief A type for UIDs used for identifying data
39  */
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  */
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 #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 */
57 #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 */
58 
59 /**
60  * \brief create a new or modify an existing uid/value pair
61  *
62  * \param[in] uid the identifier for the data
63  * \param[in] data_length The size in bytes of the data in `p_data`
64  * \param[in] p_data A buffer containing the data
65  * \param[in] create_flags The flags that the data will be stored with
66  *
67  * \return A status indicating the success/failure of the operation
68  *
69  * \retval #PSA_SUCCESS The operation completed successfully
70  * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided `uid` value was already created with PSA_STORAGE_FLAG_WRITE_ONCE
71  * \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
72  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there was insufficient space on the storage medium
73  * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
74  * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`)
75  * is invalid, for example is `NULL` or references memory the caller cannot access
76  */
78  uint32_t data_length,
79  const void *p_data,
80  psa_storage_create_flags_t create_flags);
81 
82 /**
83  * \brief Retrieve the value associated with a provided uid
84  *
85  * \param[in] uid The uid value
86  * \param[in] data_offset The starting offset of the data requested
87  * \param[in] data_length the amount of data requested (and the minimum allocated size of the `p_data` buffer)
88  * \param[out] p_data The buffer where the data will be placed upon successful completion
89  * \param[out] p_data_length The amount of data returned in the p_data buffer
90  *
91  *
92  * \return A status indicating the success/failure of the operation
93  *
94  * \retval #PSA_SUCCESS The operation completed successfully
95  * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided `uid` value was not found in the storage
96  * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
97  * \retval #PSA_ERROR_DATA_CORRUPT The operation failed because stored data has been corrupted
98  * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_data`, `p_data_length`)
99  * is invalid. For example is `NULL` or references memory the caller cannot access.
100  * In addition, this can also happen if an invalid offset was provided.
101  */
103  uint32_t data_offset,
104  uint32_t data_length,
105  void *p_data,
106  size_t *p_data_length);
107 
108 /**
109  * \brief Retrieve the metadata about the provided uid
110  *
111  * \param[in] uid The uid value
112  * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will be populated with the metadata
113  *
114  * \return A status indicating the success/failure of the operation
115  *
116  * \retval #PSA_SUCCESS The operation completed successfully
117  * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided uid value was not found in the storage
118  * \retval #PSA_ERROR_DATA_CORRUPT The operation failed because stored data has been corrupted
119  * \retval #PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the provided pointers(`p_info`)
120  * is invalid, for example is `NULL` or references memory the caller cannot access
121  */
123  struct psa_storage_info_t *p_info);
124 
125 /**
126  * \brief Remove the provided key and its associated data from the storage
127  *
128  * \param[in] uid The uid value
129  *
130  * \return A status indicating the success/failure of the operation
131  *
132  * \retval #PSA_SUCCESS The operation completed successfully
133  * \retval #PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided key value was not found in the storage
134  * \retval #PSA_ERROR_NOT_PERMITTED The operation failed because the provided key value was created with PSA_STORAGE_FLAG_WRITE_ONCE
135  * \retval #PSA_ERROR_STORAGE_FAILURE The operation failed because the physical storage has failed (Fatal error)
136  */
138 
139 #ifdef __cplusplus
140 }
141 #endif
142 
143 #endif /* PSA_CRYPTO_ITS_H */
PSA cryptography module: type aliases.
PSA cryptography module: macros to build and analyze integer values.
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:62
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
uint32_t psa_storage_create_flags_t
Flags used when creating a data entry.
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.
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.
uint64_t psa_storage_uid_t
A type for UIDs used for identifying data.
unsigned int uint32_t
Definition: stdint.h:126
unsigned __int64 uint64_t
Definition: stdint.h:136
A container for metadata associated with a specific uid.
psa_storage_create_flags_t flags
The flags set when the uid was created.
uint32_t size
The size of the data associated with a uid.
Modified on Sat Feb 24 07:48:07 2024 by modify_doxy.py rev. 669887