789377fed2
In this code drop we introduce the ODK dependency. The reference implementation has been updated to make use of the ODK and the related tests have been included. In addition, we have included an example of how a shared libraries can be created. This will allow make it easier to test and verify different implementations of the API. Most other changes introduce by this code drop were made to clean-up the reference implementation and limit dependencies.
134 lines
5.0 KiB
C
134 lines
5.0 KiB
C
// Copyright 2020 Google LLC. All Rights Reserved.
|
|
|
|
#ifndef WHITEBOX_API_AEAD_WHITEBOX_H_
|
|
#define WHITEBOX_API_AEAD_WHITEBOX_H_
|
|
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
#include "api/export.h"
|
|
#include "api/result.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
// The opaque type representing a single AEAD white-box instance.
|
|
typedef struct WB_Aead_Whitebox WB_Aead_Whitebox;
|
|
|
|
// Creates a new white-box instance using |whitebox_init_data|. A pointer to the
|
|
// white-box instance will be returned via |whitebox|.
|
|
//
|
|
// Args:
|
|
// whitebox_init_data (in): The implementation-specific initialization data
|
|
// needed to initialize a new white-box instance. It contains the white-box
|
|
// representation of an AES key.
|
|
//
|
|
// whitebox_init_data_size (in) : The number of bytes in |whitebox_init_data|.
|
|
//
|
|
// context (in) : The device-specific data to bind the ciphertexts to the
|
|
// device. It is used to derive a context specific key from the initial master
|
|
// key.
|
|
//
|
|
// context_size (in) : The number of bytes in |context|.
|
|
//
|
|
// whitebox (out) : The output parameter used to return the new white-box
|
|
// instance.
|
|
//
|
|
// Returns:
|
|
// WB_RESULT_OK if the white-box instance was successfully created.
|
|
//
|
|
// WB_RESULT_INVALID_PARAMETER if |whitebox_init_data| was null, if
|
|
// |whitebox_init_data| was invalid, if |whitebox_init_data_size| was zero, if
|
|
// |context| was null, if |context_size| was zero, or if |whitebox| was null.
|
|
//
|
|
// WB_RESULT_OUT_OF_MEMORY if the necessary memory could not be allocated.
|
|
WB_API WB_Result WB_Aead_Create(const uint8_t* whitebox_init_data,
|
|
size_t whitebox_init_data_size,
|
|
const uint8_t* context,
|
|
size_t context_size,
|
|
WB_Aead_Whitebox** whitebox);
|
|
|
|
// Releases all resources used by the white-box instance pointed to by
|
|
// |whitebox|.
|
|
//
|
|
// Args:
|
|
// whitebox (in) : A pointer to a white-box instance. Passing in null will
|
|
// result in a no-op.
|
|
WB_API void WB_Aead_Delete(WB_Aead_Whitebox* whitebox);
|
|
|
|
// Encrypts |input_data| and writes the cipher data, nonce and the data
|
|
// verification tag to |output_data|. The implementation should generate and use
|
|
// a random nonce internally to randomize the operation. |output_data_size|
|
|
// should be at least |input_data_size| + 22 to allow room for the nonce and the
|
|
// verification tag.
|
|
//
|
|
// Args:
|
|
// whitebox (in) : The white-box containing the keys for encryption.
|
|
//
|
|
// input_data (in) : The plaintext.
|
|
//
|
|
// input_data_size (in) : The number of bytes in |input_data|.
|
|
//
|
|
// output_data (out) : The output parameter for the ciphertext, nonce, and
|
|
// verification tag.
|
|
//
|
|
// output_data_size (in/out) : As input, this contains the max number of bytes
|
|
// that can be written to |output_data|. As output, |output_data_size| is set
|
|
// to the required size on WB_RESULT_OK and WB_RESULT_BUFFER_TOO_SMALL.
|
|
//
|
|
// Returns:
|
|
// WB_RESULT_OK if |input_data| was successfully encrypted.
|
|
//
|
|
// WB_RESULT_INVALID_PARAMETER if |whitebox| was null, if |input_data| was
|
|
// null, if |input_data_size| was zero, if |output_data| was null, or if
|
|
// |output_data_size| was null.
|
|
//
|
|
// WB_RESULT_BUFFER_TOO_SMALL if |output_data_size| (as input) was less than
|
|
// the required size.
|
|
WB_API WB_Result WB_Aead_Encrypt(const WB_Aead_Whitebox* whitebox,
|
|
const uint8_t* input_data,
|
|
size_t input_data_size,
|
|
uint8_t* output_data,
|
|
size_t* output_data_size);
|
|
|
|
// Decrypts |input_data| and writes the plaintext to |output_data|. |input_data|
|
|
// must have been encrypted using WB_Aead_Encrypt() with the same |whitebox|.
|
|
//
|
|
// Args:
|
|
// whitebox (in) : The white-box containing the keys for decryption.
|
|
//
|
|
// input_data (in) : The ciphertext, nonce and verification tag.
|
|
//
|
|
// input_data_size (in) : The number of bytes in |input_data|.
|
|
//
|
|
// output_data (out) : The output parameter for the plaintext.
|
|
//
|
|
// output_data_size (in/out) : As input, this contains the max number of bytes
|
|
// that can be written to |output_data|. As output, |output_data_size| is set
|
|
// to the required size on WB_RESULT_OK and WB_RESULT_BUFFER_TOO_SMALL.
|
|
//
|
|
// Returns:
|
|
// WB_RESULT_OK if |input_data| was successfully decrypted.
|
|
//
|
|
// WB_RESULT_INVALID_PARAMETER if |whitebox| was null, if |input_data| was
|
|
// null, if |input_data_size| was invalid, if |output_data| was null, or if
|
|
// |output_data_size| was null.
|
|
//
|
|
// WB_RESULT_BUFFER_TOO_SMALL if |output_data_size| (as input) was less than
|
|
// the required size.
|
|
//
|
|
// WB_RESULT_DATA_VERIFICATION_ERROR if |input_data| failed data verification.
|
|
// The state of |output_data| is undefined.
|
|
WB_API WB_Result WB_Aead_Decrypt(const WB_Aead_Whitebox* whitebox,
|
|
const uint8_t* input_data,
|
|
size_t input_data_size,
|
|
uint8_t* output_data,
|
|
size_t* output_data_size);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // WHITEBOX_API_AEAD_WHITEBOX_H_
|