aboutsummaryrefslogtreecommitdiff
path: root/components/service/secure_storage/backend/storage_backend.h
blob: 682451cf8fb8918842b49379c9feca546e1cb620 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
/*
 * Copyright (c) 2021, Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

#ifndef __STORAGE_BACKEND_H__
#define __STORAGE_BACKEND_H__

#include <stdint.h>
#include <stddef.h>
#include <psa/storage_common.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \brief Common storage backend interface
 *
 * A concrete storage backend provides an implementation of this
 * interface.
 */
struct storage_backend_interface
{
    /**
     * \brief Create a new, or modify an existing, uid/value pair
     *
     * Stores data in the storage backend.
     *
     * \param[in] context       The concrete backend context
     * \param[in] client_id     Identifier of the asset's owner (client)
     * \param[in] uid           The identifier for the data
     * \param[in] data_length   The size in bytes of the data in `p_data`
     * \param[in] create_flags  The flags that the data will be stored with
     *
     * \return A status indicating the success/failure of the operation
     *
     * \retval PSA_SUCCESS                     The operation completed successfully
     * \retval PSA_ERROR_NOT_PERMITTED         The operation failed because the
     *                                         provided `uid` value was already
     *                                         created with
     *                                         TS_SECURE_STORAGE_FLAG_WRITE_ONCE
     * \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
     * \retval PSA_ERROR_INSUFFICIENT_STORAGE  The operation failed because there
     *                                         was insufficient space on the
     *                                         storage medium
     * \retval PSA_ERROR_STORAGE_FAILURE       The operation failed because the
     *                                         physical storage has failed (Fatal
     *                                         error)
     * \retval PSA_ERROR_INVALID_ARGUMENT      The operation failed because one
     *                                         of the provided pointers (`p_data`)
     *                                         is invalid, for example is `NULL` or
     *                                         references memory the caller cannot
     *                                         access
     */
    psa_status_t (*set)(void *context,
                            uint32_t client_id,
                            uint64_t uid,
                            size_t data_length,
                            const void *p_data,
                            uint32_t create_flags);

    /**
     * \brief Retrieve data associated with a provided UID
     *
     * Retrieves up to `data_size` bytes of the data associated with `uid`, starting
     * at `data_offset` bytes from the beginning of the data. Upon successful
     * completion, the data will be placed in the `p_data` buffer, which must be at
     * least `data_size` bytes in size. The length of the data returned will be in
     * `p_data_length`. If `data_size` is 0, the contents of `p_data_length` will
     * be set to zero.
     *
     * \param[in]  context        The concrete backend context
     * \param[in]  client_id      Identifier of the asset's owner (client)
     * \param[in]  uid            The uid value
     * \param[in]  data_offset    The starting offset of the data requested
     * \param[in]  data_size      The amount of data requested
     * \param[out] p_data_length  On success, this will contain size of the data
     *                            placed in `p_data`.
     *
     * \return A status indicating the success/failure of the operation
     *
     * \retval PSA_SUCCESS                 The operation completed successfully
     * \retval PSA_ERROR_DOES_NOT_EXIST    The operation failed because the
     *                                     provided `uid` value was not found in
     *                                     the storage
     * \retval PSA_ERROR_STORAGE_FAILURE   The operation failed because the
     *                                     physical storage has failed (Fatal
     *                                     error)
     * \retval PSA_ERROR_INVALID_ARGUMENT  The operation failed because one of the
     *                                     provided arguments (`p_data`,
     *                                     `p_data_length`) is invalid, for example
     *                                     is `NULL` or references memory the
     *                                     caller cannot access. In addition, this
     *                                     can also happen if `data_offset` is
     *                                     larger than the size of the data
     *                                     associated with `uid`.
     */
    psa_status_t (*get)(void *context,
                            uint32_t client_id,
                            uint64_t uid,
                            size_t data_offset,
                            size_t data_size,
                            void *p_data,
                            size_t *p_data_length);

    /**
     * \brief Retrieve the metadata about the provided uid
     *
     * Retrieves the metadata stored for a given `uid` as a `secure_storage_response_get_info`
     * structure.
     *
     * \param[in]  context    The concrete backend context
     * \param[in]  client_id  Identifier of the asset's owner (client)
     * \param[in]  uid        The `uid` value
     * \param[out] p_info     A pointer to the `psa_storage_info_t` struct that will
     *                        be populated with the metadata
     *
     * \return A status indicating the success/failure of the operation
     *
     * \retval PSA_SUCCESS                 The operation completed successfully
     * \retval PSA_ERROR_DOES_NOT_EXIST    The operation failed because the provided
     *                                     uid value was not found in the storage
     * \retval PSA_ERROR_STORAGE_FAILURE   The operation failed because the physical
     *                                     storage has failed (Fatal error)
     * \retval PSA_ERROR_INVALID_ARGUMENT  The operation failed because one of the
     *                                     provided pointers(`p_info`)
     *                                     is invalid, for example is `NULL` or
     *                                     references memory the caller cannot
     *                                     access
     */
    psa_status_t (*get_info)(void *context,
                                uint32_t client_id,
                                uint64_t uid,
                                struct psa_storage_info_t *p_info);

    /**
     * \brief Remove the specified asset from the storage
     *
     * Deletes the data from storage backend.
     *
     * \param[in] context    The concrete backend context
     * \param[in] client_id  Identifier of the asset's owner (client)
     * \param[in] uid        The `uid` value
     *
     * \return A status indicating the success/failure of the operation
     *
     * \retval PSA_SUCCESS                 The operation completed successfully
     * \retval PSA_ERROR_INVALID_ARGUMENT  The operation failed because one or more
     *                                     of the given arguments were invalid (null
     *                                     pointer, wrong flags and so on)
     * \retval PSA_ERROR_DOES_NOT_EXIST    The operation failed because the provided
     *                                     uid value was not found in the storage
     * \retval PSA_ERROR_NOT_PERMITTED     The operation failed because the provided
     *                                     uid value was created with
     *                                     TS_SECURE_STORAGE_FLAG_WRITE_ONCE
     * \retval PSA_ERROR_STORAGE_FAILURE   The operation failed because the physical
     *                                     storage has failed (Fatal error)
     */
    psa_status_t (*remove)(void *context,
                                uint32_t client_id,
                                uint64_t uid);
};

/**
 * \brief Common storage backend instance
 *
 * Used by a storage frontend to make an association with a backend.
 */
struct storage_backend
{
    /**
     * \brief The backend context
     *
     * Points to bandend specific instance data.
     */
    void *context;

    /**
     * \brief The backend interface
     *
     * A concrete backend provides an implementation of this interface.
     */
    const struct storage_backend_interface *interface;
};

#ifdef __cplusplus
}
#endif

#endif /* __STORAGE_BACKEND_H__ */