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_SRC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H 20 #define GRPC_SRC_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 117 /// frame 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 183 /// internal states of a frame reader instance. After being set, the new 184 /// output_buffer will hold the deframed payload held by the original 185 /// output_buffer. It does not take ownership of buffer. The buffer must outlive 186 /// the reader. 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_SRC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H 237