/* Copyright 2020 Google LLC. All Rights Reserved. This file and proprietary
   source code may only be used and distributed under the Widevine Master
   License Agreement. */

#ifndef OEMCRYPTO_TA_GENERATION_NUMBER_INTERFACE_H_
#define OEMCRYPTO_TA_GENERATION_NUMBER_INTERFACE_H_

#include <stdint.h>

#include "OEMCryptoCENC.h"

/**
 * Prepare to load the generation number. If the generation number is loaded
 * asynchronously, this should initialize that process so that the next call to
 * TEE_LoadGenerationNumber does not block for too long.
 *
 * TODO(b/160022428): define and document "too long".
 *
 * The generation number should be stored in secure persistent storage. By
 * *persistent* we mean that the generation number should not be changed by
 * shutting down and later restarting the system. By *secure* we mean that the
 * user should not be able to modify the generation number. In particular, the
 * user should not be able to revert the generation number to a previous value.
 *
 * Returns true on success. On failure, initialization of the TA will fail.
 */
bool TEE_PrepareGenerationNumber(void);

/**
 * Load the usage table generation number. This is called once, on first use of
 * the usage table. This is expected to block until a value is available. It is
 * the porting interface's responsibility to fail if this blocks too
 * long. Returns true on success. A return value of false will fail OEMCrypto
 * initialization. If the generation number has never been saved before, a
 * random number should be generated -- this is NOT an error.
 */
bool TEE_LoadGenerationNumber(uint64_t* value);

/**
 * Save the generation number.
 *
 * If the generation number is saved asynchronously, then it is OK for the first
 * call to this function to begin a save process and then return true.
 * Subsequent calls will verify that the previous save has completed
 * successfully. If the previous save resulted in an error, then this call will
 * return false. If the previous call has not completed, then this call should
 * block until the previous save finishes before initializing a new save. If the
 * previous call was successful, then this call will initialize a new save and
 * return true. It is the porting interface's responsibility to fail if this
 * blocks too long.
 *
 * If the generation number is saved synchronously, then this function should
 * attempt to save the generation number and return true if the save was
 * successful.
 *
 * Returns true on success. A return value of false will fail the current
 * attempt to save the usage table. If a failure actually indicates that the
 * previous save had failed, then the usage table will be saved with a
 * generation number skew of 1. When the usage table is loaded with a generation
 * skew of 1, it will result in a warning, but not a failure.
 */
bool TEE_SaveGenerationNumber(uint64_t value);

#endif /* OEMCRYPTO_TA_GENERATION_NUMBER_INTERFACE_H_ */