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 */ 237