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
31extern "C" {
32#endif
33
34/** \brief Flags used when creating a data entry
35 */
36typedef uint32_t psa_storage_create_flags_t;
37
38/** \brief A type for UIDs used for identifying data
39 */
40typedef 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 */
48struct psa_storage_info_t {
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 */
77psa_status_t psa_its_set(psa_storage_uid_t uid,
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 */
102psa_status_t psa_its_get(psa_storage_uid_t uid,
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 */
122psa_status_t psa_its_get_info(psa_storage_uid_t uid,
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 */
137psa_status_t psa_its_remove(psa_storage_uid_t uid);
138
139#ifdef __cplusplus
140}
141#endif
142
143#endif /* PSA_CRYPTO_ITS_H */
144