--- /dev/null
+/*
+ *
+ * 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_ALTS_CRYPTER_H
+#define GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_ALTS_CRYPTER_H
+
+#include <grpc/support/port_platform.h>
+
+#include <stdbool.h>
+#include <string.h>
+
+#include <grpc/grpc.h>
+
+#include "src/core/tsi/alts/crypt/gsec.h"
+
+/**
+ * An alts_crypter interface for an ALTS record protocol providing
+ * seal/unseal functionality. The interface is thread-compatible.
+ */
+
+typedef struct alts_crypter alts_crypter;
+
+/**
+ * A typical usage of the interface would be
+ *------------------------------------------------------------------------------
+ * // Perform a seal operation. We assume the gsec_aead_crypter instance -
+ * // client_aead_crypter is created beforehand with a 16-byte key and 12-byte
+ * // nonce length.
+ *
+ * alts_crypter* client = nullptr;
+ * char* client_error_in_creation = nullptr;
+ * unsigned char* data = nullptr;
+ * grpc_status_code client_status =
+ * alts_seal_crypter_create(client_aead_crypter, 1, 5, &client,
+ * &client_error_in_creation);
+ * if (client_status == GRPC_STATUS_OK) {
+ * size_t data_size = 100;
+ * size_t num_overhead_bytes = alts_crypter_num_overhead_bytes(client);
+ * size_t data_allocated_size = data_size + num_overhead_bytes;
+ * data = gpr_malloc(data_allocated_size);
+ * char* client_error_in_seal = nullptr;
+ * // Client performs a seal operation.
+ * client_status = alts_crypter_process_in_place(client, data,
+ * data_allocated_size,
+ * &data_size,
+ * &client_error_in_seal);
+ * if (client_status != GRPC_STATUS_OK) {
+ * fprintf(stderr, "seal operation failed with error code:"
+ * "%d, message: %s\n", client_status,
+ * client_error_in_seal);
+ * }
+ * gpr_free(client_error_in_seal);
+ * } else {
+ * fprintf(stderr, "alts_crypter instance creation failed with error"
+ * "code: %d, message: %s\n", client_status,
+ * client_error_in_creation);
+ * }
+ *
+ * ...
+ *
+ * gpr_free(client_error_in_creation);
+ * alts_crypter_destroy(client);
+ *
+ * ...
+ *
+ * // Perform an unseal operation. We assume the gsec_aead_crypter instance -
+ * // server_aead_crypter is created beforehand with a 16-byte key and 12-byte
+ * // nonce length. The key used in the creation of gsec_aead_crypter instances
+ * // at server and client sides should be identical.
+ *
+ * alts_crypter* server = nullptr;
+ * char* server_error_in_creation = nullptr;
+ * grpc_status_code server_status =
+ * alts_unseal_crypter_create(server_aead_crypter, 0, 5, &server,
+ * &server_error_in_creation);
+ * if (server_status == GRPC_STATUS_OK) {
+ * size_t num_overhead_bytes = alts_crypter_num_overhead_bytes(server);
+ * size_t data_size = 100 + num_overhead_bytes;
+ * size_t data_allocated_size = data_size;
+ * char* server_error_in_unseal = nullptr;
+ * // Server performs an unseal operation.
+ * server_status = alts_crypter_process_in_place(server, data,
+ * data_allocated_size,
+ * &data_size,
+ * &server_error_in_unseal);
+ * if (server_status != GRPC_STATUS_OK) {
+ * fprintf(stderr, "unseal operation failed with error code:"
+ * "%d, message: %s\n", server_status,
+ * server_error_in_unseal);
+ * }
+ * gpr_free(server_error_in_unseal);
+ * } else {
+ * fprintf(stderr, "alts_crypter instance creation failed with error"
+ * "code: %d, message: %s\n", server_status,
+ * server_error_in_creation);
+ * }
+ *
+ * ...
+ *
+ * gpr_free(data);
+ * gpr_free(server_error_in_creation);
+ * alts_crypter_destroy(server);
+ *
+ * ...
+ *------------------------------------------------------------------------------
+ */
+
+/* V-table for alts_crypter operations */
+typedef struct alts_crypter_vtable {
+ size_t (*num_overhead_bytes)(const alts_crypter* crypter);
+ grpc_status_code (*process_in_place)(alts_crypter* crypter,
+ unsigned char* data,
+ size_t data_allocated_size,
+ size_t data_size, size_t* output_size,
+ char** error_details);
+ void (*destruct)(alts_crypter* crypter);
+} alts_crypter_vtable;
+
+/* Main struct for alts_crypter interface */
+struct alts_crypter {
+ const alts_crypter_vtable* vtable;
+};
+
+/**
+ * This method gets the number of overhead bytes needed for sealing data that
+ * is the difference in size between the protected and raw data. The counter
+ * value used in a seal or unseal operation is locally maintained (not sent or
+ * received from the other peer) and therefore, will not be counted as part of
+ * overhead bytes.
+ *
+ * - crypter: an alts_crypter instance.
+ *
+ * On success, the method returns the number of overhead bytes. Otherwise, it
+ * returns zero.
+ *
+ */
+size_t alts_crypter_num_overhead_bytes(const alts_crypter* crypter);
+
+/**
+ * This method performs either a seal or an unseal operation depending on the
+ * alts_crypter instance - crypter passed to the method. If the crypter is
+ * an instance implementing a seal operation, the method will perform a seal
+ * operation. That is, it seals raw data and stores the result in-place, and the
+ * memory allocated for data must be at least data_length +
+ * alts_crypter_num_overhead_bytes(). If the crypter is an instance
+ * implementing an unseal operation, the method will perform an unseal
+ * operation. That is, it unseals protected data and stores the result in-place.
+ * The size of unsealed data will be data_length -
+ * alts_crypter_num_overhead_bytes(). Integrity tag will be verified during
+ * the unseal operation, and if verification fails, the data will be wiped.
+ * The counters used in both seal and unseal operations are managed internally.
+ *
+ * - crypter: an alts_crypter instance.
+ * - data: if the method performs a seal operation, the data represents raw data
+ * that needs to be sealed. It also plays the role of buffer to hold the
+ * protected data as a result of seal. If the method performs an unseal
+ * operation, the data represents protected data that needs to be unsealed. It
+ * also plays the role of buffer to hold raw data as a result of unseal.
+ * - data_allocated_size: the size of data buffer. The parameter is used to
+ * check whether the result of either seal or unseal can be safely written to
+ * the data buffer.
+ * - data_size: if the method performs a seal operation, data_size
+ * represents the size of raw data that needs to be sealed, and if the method
+ * performs an unseal operation, data_size represents the size of protected
+ * data that needs to be unsealed.
+ * - output_size: size of data written to the data buffer after a seal or an
+ * unseal operation.
+ * - error_details: a buffer containing an error message if the method does not
+ * function correctly. It is legal to pass nullptr into error_details and
+ * otherwise, the parameter should be freed with gpr_free.
+ *
+ * On success, the method returns GRPC_STATUS_OK. Otherwise,
+ * it returns an error status code along with its details specified in
+ * error_details (if error_details is not nullptr).
+ */
+grpc_status_code alts_crypter_process_in_place(
+ alts_crypter* crypter, unsigned char* data, size_t data_allocated_size,
+ size_t data_size, size_t* output_size, char** error_details);
+
+/**
+ * This method creates an alts_crypter instance to be used to perform a seal
+ * operation, given a gsec_aead_crypter instance and a flag indicating if the
+ * created instance will be used at the client or server side. It takes
+ * ownership of gsec_aead_crypter instance.
+ *
+ * - gc: a gsec_aead_crypter instance used to perform AEAD encryption.
+ * - is_client: a flag indicating if the alts_crypter instance will be
+ * used at the client (is_client = true) or server (is_client =
+ * false) side.
+ * - overflow_size: overflow size of counter in bytes.
+ * - crypter: an alts_crypter instance to be returned from the method.
+ * - error_details: a buffer containing an error message if the method does
+ * not function correctly. It is legal to pass nullptr into error_details, and
+ * otherwise, the parameter should be freed with gpr_free.
+ *
+ * On success of creation, the method returns GRPC_STATUS_OK.
+ * Otherwise, it returns an error status code along with its details specified
+ * in error_details (if error_details is not nullptr).
+ */
+grpc_status_code alts_seal_crypter_create(gsec_aead_crypter* gc, bool is_client,
+ size_t overflow_size,
+ alts_crypter** crypter,
+ char** error_details);
+
+/**
+ * This method creates an alts_crypter instance used to perform an unseal
+ * operation, given a gsec_aead_crypter instance and a flag indicating if the
+ * created instance will be used at the client or server side. It takes
+ * ownership of gsec_aead_crypter instance.
+ *
+ * - gc: a gsec_aead_crypter instance used to perform AEAD decryption.
+ * - is_client: a flag indicating if the alts_crypter instance will be
+ * used at the client (is_client = true) or server (is_client =
+ * false) side.
+ * - overflow_size: overflow size of counter in bytes.
+ * - crypter: an alts_crypter instance to be returned from the method.
+ * - error_details: a buffer containing an error message if the method does
+ * not function correctly. It is legal to pass nullptr into error_details, and
+ * otherwise, the parameter should be freed with gpr_free.
+ *
+ * On success of creation, the method returns GRPC_STATUS_OK.
+ * Otherwise, it returns an error status code along with its details specified
+ * in error_details (if error_details is not nullptr).
+ */
+grpc_status_code alts_unseal_crypter_create(gsec_aead_crypter* gc,
+ bool is_client,
+ size_t overflow_size,
+ alts_crypter** crypter,
+ char** error_details);
+
+/**
+ * This method destroys an alts_crypter instance by de-allocating all of its
+ * occupied memory. A gsec_aead_crypter instance passed in at alts_crypter
+ * instance creation time will be destroyed in this method.
+ *
+ * - crypter: an alts_crypter instance.
+ */
+void alts_crypter_destroy(alts_crypter* crypter);
+
+#endif /* GRPC_CORE_TSI_ALTS_FRAME_PROTECTOR_ALTS_CRYPTER_H */
git://repos.xcallymotion.com / motion2.git / blobdiff