77f7ef98c0
This is the initial code drop of the reference implementation and test cases for the Widevine Whitebox API. In this drop, the full reference implementation for the AEAD white-box is provided and all test cases verifying the top-level behave have are enabled. Since the implementations can vary so much the testing is mostly left to verifying the return codes for specific parameter conditions. A full reference implementation for the license white-box is provided, however not all tests are implemented or enabled. A number of tests have been disabled as they required a loaded license and test licenses are still being worked on. The two license white-box API functions that are the further from competition are ProcessLicenseResponse() and MaskedDecryt(). ProcessLicenseResponse() is still being worked on and MaskedDecrypt() is waiting on Decrypt() to be fully functional. Most tests focus on verifying return code for specific parameter conditions, but as test licenses are created, tests looking to test the internal behaviour of license management will be added to ProcessLicenseResponse(), Decrypt(), and MaskedDecrypt().
133 lines
4.9 KiB
C
133 lines
4.9 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/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_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.
|
|
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_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_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_
|