legacy-libs/grpc/deps/grpc/src/core/tsi/alts/frame_protector/frame_handler.h

   1 /*
   2  *
   3  * Copyright 2018 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may 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,
  13  * WITHOUT 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  */
  18
  19 #ifndef GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H
  20 #define GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include <stdbool.h>
  25 #include <stdlib.h>
  26
  27 const size_t kFrameMessageType = 0x06;
  28 const size_t kFrameLengthFieldSize = 4;
  29 const size_t kFrameMessageTypeFieldSize = 4;
  30 const size_t kFrameMaxSize = 1024 * 1024;
  31 const size_t kFrameHeaderSize =
  32     kFrameLengthFieldSize + kFrameMessageTypeFieldSize;
  33
  34 /**
  35  * Implementation of frame reader and frame writer. All APIs in the
  36  * header are thread-compatible.
  37  */
  38
  39 /**
  40  * Main struct for a frame writer. It reads frames from an input buffer, and
  41  * writes the contents as raw bytes. It does not own the input buffer.
  42  */
  43 typedef struct alts_frame_writer {
  44   const unsigned char* input_buffer;
  45   unsigned char header_buffer[kFrameHeaderSize];
  46   size_t input_bytes_written;
  47   size_t header_bytes_written;
  48   size_t input_size;
  49 } alts_frame_writer;
  50
  51 /**
  52  * Main struct for a frame reader. It reads raw bytes and puts the framed
  53  * result into an output buffer. It does not own the output buffer.
  54  */
  55 typedef struct alts_frame_reader {
  56   unsigned char* output_buffer;
  57   unsigned char header_buffer[kFrameHeaderSize];
  58   size_t header_bytes_read;
  59   size_t output_bytes_read;
  60   size_t bytes_remaining;
  61 } alts_frame_reader;
  62
  63 /**
  64  * This method creates a frame writer instance and initializes its internal
  65  * states.
  66  */
  67 alts_frame_writer* alts_create_frame_writer();
  68
  69 /**
  70  * This method resets internal states of a frame writer and prepares to write
  71  * a single frame. It does not take ownership of payload_buffer.
  72  * The payload_buffer must outlive the writer.
  73  *
  74  * - writer: a frame writer instance.
  75  * - buffer: a buffer storing full payload data to be framed.
  76  * - length: size of payload data.
  77  *
  78  * The method returns true on success and false otherwise.
  79  */
  80 bool alts_reset_frame_writer(alts_frame_writer* writer,
  81                              const unsigned char* buffer, size_t length);
  82
  83 /**
  84  * This method writes up to bytes_size bytes of a frame to output.
  85  *
  86  * - writer: a frame writer instance.
  87  * - output: an output buffer used to store the frame.
  88  * - bytes_size: an in/out parameter that stores the size of output buffer
  89  *   before the call, and gets written the number of frame bytes written to the
  90  *   buffer.
  91  *
  92  * The method returns true on success and false otherwise.
  93  */
  94 bool alts_write_frame_bytes(alts_frame_writer* writer, unsigned char* output,
  95                             size_t* bytes_size);
  96
  97 /**
  98  * This method checks if a reset can be called to write a new frame. It returns
  99  * true if it's the first time to frame a payload, or the current frame has
 100  * been finished processing. It returns false if it's not ready yet to start a
 101  * new frame (e.g., more payload data needs to be accumulated to process the
 102  * current frame).
 103  *
 104  * if (alts_is_frame_writer_done(writer)) {
 105  *   // a new frame can be written, call reset.
 106  *   alts_reset_frame_writer(writer, payload_buffer, payload_size);
 107  * } else {
 108  *   // accumulate more payload data until a full frame can be written.
 109  * }
 110  *
 111  * - writer: a frame writer instance.
 112  */
 113 bool alts_is_frame_writer_done(alts_frame_writer* writer);
 114
 115 /**
 116  * This method returns the number of bytes left to write before a complete frame
 117  * is formed.
 118  *
 119  * - writer: a frame writer instance.
 120  */
 121 size_t alts_get_num_writer_bytes_remaining(alts_frame_writer* writer);
 122
 123 /**
 124  * This method destroys a frame writer instance.
 125  *
 126  * - writer: a frame writer instance.
 127  */
 128 void alts_destroy_frame_writer(alts_frame_writer* writer);
 129
 130 /**
 131  * This method creates a frame reader instance and initializes its internal
 132  * states.
 133  */
 134 alts_frame_reader* alts_create_frame_reader();
 135
 136 /**
 137  * This method resets internal states of a frame reader (including setting its
 138  * output_buffer with buffer), and prepares to write processed bytes to
 139  * an output_buffer. It does not take ownership of buffer. The buffer must
 140  * outlive reader.
 141  *
 142  * - reader: a frame reader instance.
 143  * - buffer: an output buffer used to store deframed results.
 144  *
 145  * The method returns true on success and false otherwise.
 146  */
 147 bool alts_reset_frame_reader(alts_frame_reader* reader, unsigned char* buffer);
 148
 149 /**
 150  * This method processes up to the number of bytes given in bytes_size. It may
 151  * choose not to process all the bytes, if, for instance, more bytes are
 152  * given to the method than required to complete the current frame.
 153  *
 154  * - reader: a frame reader instance.
 155  * - bytes: a buffer that stores data to be processed.
 156  * - bytes_size: an in/out parameter that stores the size of bytes before the
 157  *   call and gets written the number of bytes processed.
 158  *
 159  * The method returns true on success and false otherwise.
 160  */
 161 bool alts_read_frame_bytes(alts_frame_reader* reader,
 162                            const unsigned char* bytes, size_t* bytes_size);
 163
 164 /**
 165  * This method checks if a frame length has been read.
 166  *
 167  * - reader: a frame reader instance.
 168  *
 169  * The method returns true if a frame length has been read and false otherwise.
 170  */
 171 bool alts_has_read_frame_length(alts_frame_reader* reader);
 172
 173 /**
 174  * This method returns the number of bytes the frame reader intends to write.
 175  * It may only be called if alts_has_read_frame_length() returns true.
 176  *
 177  * - reader: a frame reader instance.
 178  */
 179 size_t alts_get_reader_bytes_remaining(alts_frame_reader* reader);
 180
 181 /**
 182  * This method resets output_buffer but does not otherwise modify other internal
 183  * states of a frame reader instance. After being set, the new output_buffer
 184  * will hold the deframed payload held by the original output_buffer. It does
 185  * not take ownership of buffer. The buffer must outlive the reader.
 186  * To distinguish between two reset methods on a frame reader,
 187  *
 188  * if (alts_fh_is_frame_reader_done(reader)) {
 189  *   // if buffer contains a full payload to be deframed, call reset.
 190  *   alts_reset_frame_reader(reader, buffer);
 191  * }
 192  *
 193  * // if remaining buffer space is not enough to hold a full payload
 194  * if (buffer_space_remaining < alts_get_reader_bytes_remaining(reader)) {
 195  *   // allocate enough space for a new buffer, copy back data processed so far,
 196  *   // and call reset.
 197  *   alts_reset_reader_output_buffer(reader, new_buffer).
 198  * }
 199  *
 200  * - reader: a frame reader instance.
 201  * - buffer: a buffer used to set reader's output_buffer.
 202  */
 203 void alts_reset_reader_output_buffer(alts_frame_reader* reader,
 204                                      unsigned char* buffer);
 205
 206 /**
 207  * This method checks if reset can be called to start processing a new frame.
 208  * If true and reset was previously called, a full frame has been processed and
 209  * the content of the frame is available in output_buffer.
 210
 211  * - reader: a frame reader instance.
 212  */
 213 bool alts_is_frame_reader_done(alts_frame_reader* reader);
 214
 215 /**
 216  * This method returns output_bytes_read of a frame reader instance.
 217  *
 218  * - reader: a frame reader instance.
 219  */
 220 size_t alts_get_output_bytes_read(alts_frame_reader* reader);
 221
 222 /**
 223  * This method returns output_buffer of a frame reader instance.
 224  *
 225  * - reader: a frame reader instance.
 226  */
 227 unsigned char* alts_get_output_buffer(alts_frame_reader* reader);
 228
 229 /**
 230  * This method destroys a frame reader instance.
 231  *
 232  * - reader: a frame reader instance.
 233  */
 234 void alts_destroy_frame_reader(alts_frame_reader* reader);
 235
 236 #endif /* GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H */