1 /* 2 * Copyright The Mbed TLS Contributors 3 * SPDX-License-Identifier: Apache-2.0 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); you may 6 * not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 * This file is part of mbed TLS (https://tls.mbed.org) 18 */ 19 20 /** 21 * \file mps_reader.h 22 * 23 * \brief This file defines reader objects, which together with their 24 * sibling writer objects form the basis for the communication 25 * between the various layers of the Mbed TLS messaging stack, 26 * as well as the communication between the messaging stack and 27 * the (D)TLS handshake protocol implementation. 28 * 29 * Readers provide a means of transferring incoming data from 30 * a 'producer' providing it in chunks of arbitrary size, to 31 * a 'consumer' which fetches and processes it in chunks of 32 * again arbitrary, and potentially different, size. 33 * 34 * Readers can thus be seen as datagram-to-stream converters, 35 * and they abstract away the following two tasks from the user: 36 * 1. The pointer arithmetic of stepping through a producer- 37 * provided chunk in smaller chunks. 38 * 2. The merging of incoming data chunks in case the 39 * consumer requests data in larger chunks than what the 40 * producer provides. 41 * 42 * The basic abstract flow of operation is the following: 43 * - Initially, the reader is in 'producing mode'. 44 * - The producer hands an incoming data buffer to the reader, 45 * moving it from 'producing' to 'consuming' mode. 46 * - The consumer subsequently fetches and processes the buffer 47 * content. Once that's done -- or partially done and a consumer's 48 * request can't be fulfilled -- the producer revokes the reader's 49 * access to the incoming data buffer, putting the reader back to 50 * producing mode. 51 * - The producer subsequently gathers more incoming data and hands 52 * it to the reader until it switches back to consuming mode 53 * if enough data is available for the last consumer request to 54 * be satisfiable. 55 * - Repeat the above. 56 * 57 * The abstract states of the reader from the producer's and 58 * consumer's perspective are as follows: 59 * 60 * - From the perspective of the consumer, the state of the 61 * reader consists of the following: 62 * - A byte stream representing (concatenation of) the data 63 * received through calls to mbedtls_mps_reader_get(), 64 * - A marker within that byte stream indicating which data 65 * can be considered processed, and hence need not be retained, 66 * when the reader is passed back to the producer via 67 * mbedtls_mps_reader_reclaim(). 68 * The marker is set via mbedtls_mps_reader_commit() 69 * which places it at the end of the current byte stream. 70 * The consumer need not be aware of the distinction between consumer 71 * and producer mode, because it only interfaces with the reader 72 * when the latter is in consuming mode. 73 * 74 * - From the perspective of the producer, the reader's state is one of: 75 * - Attached: The reader is in consuming mode. 76 * - Unset: No incoming data buffer is currently managed by the reader, 77 * and all previously handed incoming data buffers have been 78 * fully processed. More data needs to be fed into the reader 79 * via mbedtls_mps_reader_feed(). 80 * 81 * - Accumulating: No incoming data buffer is currently managed by the 82 * reader, but some data from the previous incoming data 83 * buffer hasn't been processed yet and is internally 84 * held back. 85 * The Attached state belongs to consuming mode, while the Unset and 86 * Accumulating states belong to producing mode. 87 * 88 * Transitioning from the Unset or Accumulating state to Attached is 89 * done via successful calls to mbedtls_mps_reader_feed(), while 90 * transitioning from Attached to either Unset or Accumulating (depending 91 * on what has been processed) is done via mbedtls_mps_reader_reclaim(). 92 * 93 * The following diagram depicts the producer-state progression: 94 * 95 * +------------------+ reclaim 96 * | Unset +<-------------------------------------+ get 97 * +--------|---------+ | +------+ 98 * | | | | 99 * | | | | 100 * | feed +---------+---+--+ | 101 * +--------------------------------------> <---+ 102 * | Attached | 103 * +--------------------------------------> <---+ 104 * | feed, enough data available +---------+---+--+ | 105 * | to serve previous consumer request | | | 106 * | | | | 107 * +--------+---------+ | +------+ 108 * +----> Accumulating |<-------------------------------------+ commit 109 * | +---+--------------+ reclaim, previous read request 110 * | | couldn't be fulfilled 111 * | | 112 * +--------+ 113 * feed, need more data to serve 114 * previous consumer request 115 * | 116 * | 117 * producing mode | consuming mode 118 * | 119 * 120 */ 121 122 #ifndef MBEDTLS_READER_H 123 #define MBEDTLS_READER_H 124 125 #include <stdio.h> 126 127 #include "mps_common.h" 128 #include "mps_error.h" 129 130 struct mbedtls_mps_reader; 131 typedef struct mbedtls_mps_reader mbedtls_mps_reader; 132 133 /* 134 * Structure definitions 135 */ 136 137 struct mbedtls_mps_reader { 138 unsigned char *frag; /*!< The fragment of incoming data managed by 139 * the reader; it is provided to the reader 140 * through mbedtls_mps_reader_feed(). The reader 141 * does not own the fragment and does not 142 * perform any allocation operations on it, 143 * but does have read and write access to it. 144 * 145 * The reader is in consuming mode if 146 * and only if \c frag is not \c NULL. */ 147 mbedtls_mps_stored_size_t frag_len; 148 /*!< The length of the current fragment. 149 * Must be 0 if \c frag == \c NULL. */ 150 mbedtls_mps_stored_size_t commit; 151 /*!< The offset of the last commit, relative 152 * to the first byte in the fragment, if 153 * no accumulator is present. If an accumulator 154 * is present, it is viewed as a prefix to the 155 * current fragment, and this variable contains 156 * an offset from the beginning of the accumulator. 157 * 158 * This is only used when the reader is in 159 * consuming mode, i.e. \c frag != \c NULL; 160 * otherwise, its value is \c 0. */ 161 mbedtls_mps_stored_size_t end; 162 /*!< The offset of the end of the last chunk 163 * passed to the user through a call to 164 * mbedtls_mps_reader_get(), relative to the first 165 * byte in the fragment, if no accumulator is 166 * present. If an accumulator is present, it is 167 * viewed as a prefix to the current fragment, and 168 * this variable contains an offset from the 169 * beginning of the accumulator. 170 * 171 * This is only used when the reader is in 172 * consuming mode, i.e. \c frag != \c NULL; 173 * otherwise, its value is \c 0. */ 174 mbedtls_mps_stored_size_t pending; 175 /*!< The amount of incoming data missing on the 176 * last call to mbedtls_mps_reader_get(). 177 * In particular, it is \c 0 if the last call 178 * was successful. 179 * If a reader is reclaimed after an 180 * unsuccessful call to mbedtls_mps_reader_get(), 181 * this variable is used to have the reader 182 * remember how much data should be accumulated 183 * so that the call to mbedtls_mps_reader_get() 184 * succeeds next time. 185 * This is only used when the reader is in 186 * consuming mode, i.e. \c frag != \c NULL; 187 * otherwise, its value is \c 0. */ 188 189 /* The accumulator is only needed if we need to be able to pause 190 * the reader. A few bytes could be saved by moving this to a 191 * separate struct and using a pointer here. */ 192 193 unsigned char *acc; /*!< The accumulator is used to gather incoming 194 * data if a read-request via mbedtls_mps_reader_get() 195 * cannot be served from the current fragment. */ 196 mbedtls_mps_stored_size_t acc_len; 197 /*!< The total size of the accumulator. */ 198 mbedtls_mps_stored_size_t acc_available; 199 /*!< The number of bytes currently gathered in 200 * the accumulator. This is both used in 201 * producing and in consuming mode: 202 * While producing, it is increased until 203 * it reaches the value of \c acc_remaining below. 204 * While consuming, it is used to judge if a 205 * get request can be served from the 206 * accumulator or not. 207 * Must not be larger than \c acc_len. */ 208 union { 209 mbedtls_mps_stored_size_t acc_remaining; 210 /*!< This indicates the amount of data still 211 * to be gathered in the accumulator. It is 212 * only used in producing mode. 213 * Must be at most acc_len - acc_available. */ 214 mbedtls_mps_stored_size_t frag_offset; 215 /*!< If an accumulator is present and in use, this 216 * field indicates the offset of the current 217 * fragment from the beginning of the 218 * accumulator. If no accumulator is present 219 * or the accumulator is not in use, this is \c 0. 220 * It is only used in consuming mode. 221 * Must not be larger than \c acc_available. */ 222 } acc_share; 223 }; 224 225 /* 226 * API organization: 227 * A reader object is usually prepared and maintained 228 * by some lower layer and passed for usage to an upper 229 * layer, and the API naturally splits according to which 230 * layer is supposed to use the respective functions. 231 */ 232 233 /* 234 * Maintenance API (Lower layer) 235 */ 236 237 /** 238 * \brief Initialize a reader object 239 * 240 * \param reader The reader to be initialized. 241 * \param acc The buffer to be used as a temporary accumulator 242 * in case get requests through mbedtls_mps_reader_get() 243 * exceed the buffer provided by mbedtls_mps_reader_feed(). 244 * This buffer is owned by the caller and exclusive use 245 * for reading and writing is given to the reader for the 246 * duration of the reader's lifetime. It is thus the caller's 247 * responsibility to maintain (and not touch) the buffer for 248 * the lifetime of the reader, and to properly zeroize and 249 * free the memory after the reader has been destroyed. 250 * \param acc_len The size in Bytes of \p acc. 251 * 252 * \return \c 0 on success. 253 * \return A negative \c MBEDTLS_ERR_READER_XXX error code on failure. 254 */ 255 int mbedtls_mps_reader_init(mbedtls_mps_reader *reader, 256 unsigned char *acc, 257 mbedtls_mps_size_t acc_len); 258 259 /** 260 * \brief Free a reader object 261 * 262 * \param reader The reader to be freed. 263 * 264 * \return \c 0 on success. 265 * \return A negative \c MBEDTLS_ERR_READER_XXX error code on failure. 266 */ 267 int mbedtls_mps_reader_free(mbedtls_mps_reader *reader); 268 269 /** 270 * \brief Pass chunk of data for the reader to manage. 271 * 272 * \param reader The reader context to use. The reader must be 273 * in producing mode. 274 * \param buf The buffer to be managed by the reader. 275 * \param buflen The size in Bytes of \p buffer. 276 * 277 * \return \c 0 on success. In this case, the reader will be 278 * moved to consuming mode and obtains read access 279 * of \p buf until mbedtls_mps_reader_reclaim() 280 * is called. It is the responsibility of the caller 281 * to ensure that the \p buf persists and is not changed 282 * between successful calls to mbedtls_mps_reader_feed() 283 * and mbedtls_mps_reader_reclaim(). 284 * \return \c MBEDTLS_ERR_MPS_READER_NEED_MORE if more input data is 285 * required to fulfill a previous request to mbedtls_mps_reader_get(). 286 * In this case, the reader remains in producing mode and 287 * takes no ownership of the provided buffer (an internal copy 288 * is made instead). 289 * \return Another negative \c MBEDTLS_ERR_READER_XXX error code on 290 * different kinds of failures. 291 */ 292 int mbedtls_mps_reader_feed(mbedtls_mps_reader *reader, 293 unsigned char *buf, 294 mbedtls_mps_size_t buflen); 295 296 /** 297 * \brief Reclaim reader's access to the current input buffer. 298 * 299 * \param reader The reader context to use. The reader must be 300 * in consuming mode. 301 * \param paused If not \c NULL, the integer at address \p paused will be 302 * modified to indicate whether the reader has been paused 303 * (value \c 1) or not (value \c 0). Pausing happens if there 304 * is uncommitted data and a previous request to 305 * mbedtls_mps_reader_get() has exceeded the bounds of the 306 * input buffer. 307 * 308 * \return \c 0 on success. 309 * \return A negative \c MBEDTLS_ERR_READER_XXX error code on failure. 310 */ 311 int mbedtls_mps_reader_reclaim(mbedtls_mps_reader *reader, 312 int *paused); 313 314 /* 315 * Usage API (Upper layer) 316 */ 317 318 /** 319 * \brief Request data from the reader. 320 * 321 * \param reader The reader context to use. The reader must 322 * be in consuming mode. 323 * \param desired The desired amount of data to be read, in Bytes. 324 * \param buffer The address to store the buffer pointer in. 325 * This must not be \c NULL. 326 * \param buflen The address to store the actual buffer 327 * length in, or \c NULL. 328 * 329 * \return \c 0 on success. In this case, \c *buf holds the 330 * address of a buffer of size \c *buflen 331 * (if \c buflen != \c NULL) or \c desired 332 * (if \c buflen == \c NULL). The user has read access 333 * to the buffer and guarantee of stability of the data 334 * until the next call to mbedtls_mps_reader_reclaim(). 335 * \return #MBEDTLS_ERR_MPS_READER_OUT_OF_DATA if there is not enough 336 * data available to serve the get request. In this case, the 337 * reader remains intact and in consuming mode, and the consumer 338 * should retry the call after a successful cycle of 339 * mbedtls_mps_reader_reclaim() and mbedtls_mps_reader_feed(). 340 * If, after such a cycle, the consumer requests a different 341 * amount of data, the result is implementation-defined; 342 * progress is guaranteed only if the same amount of data 343 * is requested after a mbedtls_mps_reader_reclaim() and 344 * mbedtls_mps_reader_feed() cycle. 345 * \return Another negative \c MBEDTLS_ERR_READER_XXX error 346 * code for different kinds of failure. 347 * 348 * \note Passing \c NULL as \p buflen is a convenient way to 349 * indicate that fragmentation is not tolerated. 350 * It's functionally equivalent to passing a valid 351 * address as buflen and checking \c *buflen == \c desired 352 * afterwards. 353 */ 354 int mbedtls_mps_reader_get(mbedtls_mps_reader *reader, 355 mbedtls_mps_size_t desired, 356 unsigned char **buffer, 357 mbedtls_mps_size_t *buflen); 358 359 /** 360 * \brief Mark data obtained from mbedtls_mps_reader_get() as processed. 361 * 362 * This call indicates that all data received from prior calls to 363 * mbedtls_mps_reader_get() has been or will have been 364 * processed when mbedtls_mps_reader_reclaim() is called, 365 * and thus need not be backed up. 366 * 367 * This function has no user observable effect until 368 * mbedtls_mps_reader_reclaim() is called. In particular, 369 * buffers received from mbedtls_mps_reader_get() remain 370 * valid until mbedtls_mps_reader_reclaim() is called. 371 * 372 * \param reader The reader context to use. 373 * 374 * \return \c 0 on success. 375 * \return A negative \c MBEDTLS_ERR_READER_XXX error code on failure. 376 * 377 */ 378 int mbedtls_mps_reader_commit(mbedtls_mps_reader *reader); 379 380 #endif /* MBEDTLS_READER_H */ 381
