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