#include <grpc/support/port_platform.h>
#include <stdbool.h>
#include <string.h>
#include <grpc/grpc.h>
#include "src/core/tsi/alts/crypt/gsec.h"

Include dependency graph for alts_crypter.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	alts_crypter

struct	alts_crypter_vtable

Typedefs
typedef struct alts_crypter	alts_crypter

typedef struct alts_crypter_vtable	alts_crypter_vtable

Functions
void	alts_crypter_destroy (alts_crypter *crypter)

size_t	alts_crypter_num_overhead_bytes (const alts_crypter *crypter)

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)

grpc_status_code	alts_seal_crypter_create (gsec_aead_crypter gc, bool is_client, size_t overflow_size, alts_crypter crypter, char *error_details)

grpc_status_code	alts_unseal_crypter_create (gsec_aead_crypter gc, bool is_client, size_t overflow_size, alts_crypter crypter, char *error_details)

Typedef Documentation

◆ alts_crypter

typedef struct alts_crypter alts_crypter

An alts_crypter interface for an ALTS record protocol providing seal/unseal functionality. The interface is thread-compatible.

Definition at line 36 of file alts_crypter.h.

◆ alts_crypter_vtable

typedef struct alts_crypter_vtable alts_crypter_vtable

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);

...

Function Documentation

◆ alts_crypter_destroy()

void alts_crypter_destroy ( alts_crypter * crypter )

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.

Definition at line 59 of file alts_crypter.cc.

◆ alts_crypter_num_overhead_bytes()

size_t alts_crypter_num_overhead_bytes ( const alts_crypter * crypter )

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.

Definition at line 50 of file alts_crypter.cc.

◆ alts_crypter_process_in_place()

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 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).

Definition at line 34 of file alts_crypter.cc.

◆ alts_seal_crypter_create()

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 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).

Definition at line 88 of file alts_seal_privacy_integrity_crypter.cc.

◆ alts_unseal_crypter_create()

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 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.