third_party/grpc/src/core/tsi/alts/frame_protector/frame_handler.h

/*
 *
 * Copyright 2018 gRPC authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

#ifndef GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H
#define GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H

#include <grpc/support/port_platform.h>

#include <stdbool.h>
#include <stdlib.h>

const size_t kFrameMessageType = 0x06;
const size_t kFrameLengthFieldSize = 4;
const size_t kFrameMessageTypeFieldSize = 4;
const size_t kFrameMaxSize = 1024 * 1024;
const size_t kFrameHeaderSize =
    kFrameLengthFieldSize + kFrameMessageTypeFieldSize;

/**
 * Implementation of frame reader and frame writer. All APIs in the
 * header are thread-compatible.
 */

/**
 * Main struct for a frame writer. It reads frames from an input buffer, and
 * writes the contents as raw bytes. It does not own the input buffer.
 */
typedef struct alts_frame_writer {
  const unsigned char* input_buffer;
  unsigned char header_buffer[kFrameHeaderSize];
  size_t input_bytes_written;
  size_t header_bytes_written;
  size_t input_size;
} alts_frame_writer;

/**
 * Main struct for a frame reader. It reads raw bytes and puts the framed
 * result into an output buffer. It does not own the output buffer.
 */
typedef struct alts_frame_reader {
  unsigned char* output_buffer;
  unsigned char header_buffer[kFrameHeaderSize];
  size_t header_bytes_read;
  size_t output_bytes_read;
  size_t bytes_remaining;
} alts_frame_reader;

/**
 * This method creates a frame writer instance and initializes its internal
 * states.
 */
alts_frame_writer* alts_create_frame_writer();

/**
 * This method resets internal states of a frame writer and prepares to write
 * a single frame. It does not take ownership of payload_buffer.
 * The payload_buffer must outlive the writer.
 *
 * - writer: a frame writer instance.
 * - buffer: a buffer storing full payload data to be framed.
 * - length: size of payload data.
 *
 * The method returns true on success and false otherwise.
 */
bool alts_reset_frame_writer(alts_frame_writer* writer,
                             const unsigned char* buffer, size_t length);

/**
 * This method writes up to bytes_size bytes of a frame to output.
 *
 * - writer: a frame writer instance.
 * - output: an output buffer used to store the frame.
 * - bytes_size: an in/out parameter that stores the size of output buffer
 *   before the call, and gets written the number of frame bytes written to the
 *   buffer.
 *
 * The method returns true on success and false otherwise.
 */
bool alts_write_frame_bytes(alts_frame_writer* writer, unsigned char* output,
                            size_t* bytes_size);

/**
 * This method checks if a reset can be called to write a new frame. It returns
 * true if it's the first time to frame a payload, or the current frame has
 * been finished processing. It returns false if it's not ready yet to start a
 * new frame (e.g., more payload data needs to be accumulated to process the
 * current frame).
 *
 * if (alts_is_frame_writer_done(writer)) {
 *   // a new frame can be written, call reset.
 *   alts_reset_frame_writer(writer, payload_buffer, payload_size);
 * } else {
 *   // accumulate more payload data until a full frame can be written.
 * }
 *
 * - writer: a frame writer instance.
 */
bool alts_is_frame_writer_done(alts_frame_writer* writer);

/**
 * This method returns the number of bytes left to write before a complete frame
 * is formed.
 *
 * - writer: a frame writer instance.
 */
size_t alts_get_num_writer_bytes_remaining(alts_frame_writer* writer);

/**
 * This method destroys a frame writer instance.
 *
 * - writer: a frame writer instance.
 */
void alts_destroy_frame_writer(alts_frame_writer* writer);

/**
 * This method creates a frame reader instance and initializes its internal
 * states.
 */
alts_frame_reader* alts_create_frame_reader();

/**
 * This method resets internal states of a frame reader (including setting its
 * output_buffer with buffer), and prepares to write processed bytes to
 * an output_buffer. It does not take ownership of buffer. The buffer must
 * outlive reader.
 *
 * - reader: a frame reader instance.
 * - buffer: an output buffer used to store deframed results.
 *
 * The method returns true on success and false otherwise.
 */
bool alts_reset_frame_reader(alts_frame_reader* reader, unsigned char* buffer);

/**
 * This method processes up to the number of bytes given in bytes_size. It may
 * choose not to process all the bytes, if, for instance, more bytes are
 * given to the method than required to complete the current frame.
 *
 * - reader: a frame reader instance.
 * - bytes: a buffer that stores data to be processed.
 * - bytes_size: an in/out parameter that stores the size of bytes before the
 *   call and gets written the number of bytes processed.
 *
 * The method returns true on success and false otherwise.
 */
bool alts_read_frame_bytes(alts_frame_reader* reader,
                           const unsigned char* bytes, size_t* bytes_size);

/**
 * This method checks if a frame length has been read.
 *
 * - reader: a frame reader instance.
 *
 * The method returns true if a frame length has been read and false otherwise.
 */
bool alts_has_read_frame_length(alts_frame_reader* reader);

/**
 * This method returns the number of bytes the frame reader intends to write.
 * It may only be called if alts_has_read_frame_length() returns true.
 *
 * - reader: a frame reader instance.
 */
size_t alts_get_reader_bytes_remaining(alts_frame_reader* reader);

/**
 * This method resets output_buffer but does not otherwise modify other internal
 * states of a frame reader instance. After being set, the new output_buffer
 * will hold the deframed payload held by the original output_buffer. It does
 * not take ownership of buffer. The buffer must outlive the reader.
 * To distinguish between two reset methods on a frame reader,
 *
 * if (alts_fh_is_frame_reader_done(reader)) {
 *   // if buffer contains a full payload to be deframed, call reset.
 *   alts_reset_frame_reader(reader, buffer);
 * }
 *
 * // if remaining buffer space is not enough to hold a full payload
 * if (buffer_space_remaining < alts_get_reader_bytes_remaining(reader)) {
 *   // allocate enough space for a new buffer, copy back data processed so far,
 *   // and call reset.
 *   alts_reset_reader_output_buffer(reader, new_buffer).
 * }
 *
 * - reader: a frame reader instance.
 * - buffer: a buffer used to set reader's output_buffer.
 */
void alts_reset_reader_output_buffer(alts_frame_reader* reader,
                                     unsigned char* buffer);

/**
 * This method checks if reset can be called to start processing a new frame.
 * If true and reset was previously called, a full frame has been processed and
 * the content of the frame is available in output_buffer.

 * - reader: a frame reader instance.
 */
bool alts_is_frame_reader_done(alts_frame_reader* reader);

/**
 * This method returns output_bytes_read of a frame reader instance.
 *
 * - reader: a frame reader instance.
 */
size_t alts_get_output_bytes_read(alts_frame_reader* reader);

/**
 * This method returns output_buffer of a frame reader instance.
 *
 * - reader: a frame reader instance.
 */
unsigned char* alts_get_output_buffer(alts_frame_reader* reader);

/**
 * This method destroys a frame reader instance.
 *
 * - reader: a frame reader instance.
 */
void alts_destroy_frame_reader(alts_frame_reader* reader);

#endif /* GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_FRAME_HANDLER_H */