• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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