// 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_