include/tee/ta_vx_helper.h

/*
 * Copyright (c) 2019 The Fuchsia Authors
 *
 * SPDX-License-Identifier:	BSD-3-Clause
 */

#ifndef _TA_VX_HELPER_H_
#define _TA_VX_HELPER_H_

#include <common.h>
#include <tee/ta_vx.h>

/**
 * Note: if CONFIG_TA_VX isn't enabled, these functions will still exist,
 * but they will all fail.
 *
 * This is useful due to the tight integration of this code with our boot
 * logic; it's best to avoid scattering #ifdefs throughout the verified boot
 * code, which we would have to do if these functions didn't exist.
 */

/**
 * ta_vx_lock() - Locks the device.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_lock(void);

/**
 * ta_vx_lock_if_ephemerally_unlocked()
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_lock_if_ephemerally_unlocked(void);

/**
 * ta_vx_unlock() - Unlocks the device.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_unlock(void);

/**
 * ta_vx_is_unlocked() - Check if device is unlocked.
 * @unlocked: Writes true to this location if unlocked, false otherwise
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_is_unlocked(bool *unlocked);

/**
 * ta_vx_read_rollback_index() - Read the rollback index.
 * @slot: The rollback index slot to read.
 * @rollback_index: Location to write the rollback index.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_read_rollback_index(uint32_t slot, uint64_t *rollback_index);

/**
 * ta_vx_write_rollback_index() - Write the rollback index.
 * @slot: The rollback index slot to write.
 * @rollback_index: The rollback index to write.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_write_rollback_index(uint32_t slot, uint64_t rollback_index);

/**
 * ta_vx_read_persistent_value() - Read a named persistent value
 * @name: Non-empty NUL-terminated string.
 * @buf: Buffer to write value into.
 * @buf_len: Length of buf.
 * @bytes_read: Location to write the number of bytes read into buf.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_read_persistent_value(const char *name, void *buf, size_t buf_len,
				size_t *bytes_read);

/**
 * ta_vx_write_persistent_value() - Write/update a named persistent value
 * @name: Non-empty NUL-terminated string.
 * @val_buf: Buffer holding the value to write.
 * @val_buf_len: Length of val_buf.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_write_persistent_value(const char *name, const void *val_buf,
				 size_t val_buf_len);

/**
 * ta_vx_delete_persistent_value() - Delete a named persistent value
 * @name: Non-empty NUL-terminated string.
 *
 * Return: 0 if successful (including when specified value is not found),
 * non-zero error code on failure.
 */
int ta_vx_delete_persistent_value(const char *name);

/**
 * ta_vx_cprng_draw() - Draw random bytes.
 * @buf: Buffer to receive the random bytes.
 * @buf_len: Size of buffer and number of random bytes to draw.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_cprng_draw(void *buf, size_t buf_len);

/**
 * ta_vx_exit_bootloader_or_panic() - Finalize verified execution policies and
 * 		configurations. Panics on any error.
 */
void ta_vx_exit_bootloader_or_panic(void);

/**
 * ta_vx_read_perm_attr() - Read permanent attributes
 * @buf: Buffer to write value into.
 * @buf_len: Length of buf.
 * @bytes_read: Location to write the number of bytes read into buf.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_read_perm_attr(void *buf, size_t buf_len, size_t *bytes_read);

/**
 * ta_vx_write_perm_attr() - Write permanent attributes
 * @val_buf: Buffer holding the value to write.
 * @val_buf_len: Length of val_buf.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_write_perm_attr(const void *val_buf, size_t val_buf_len);

/**
 * ta_vx_get_rpmb_status() - Query RPMB provisioning status
 *
 * @out_status: Receives status bit flags as defined in tee/ta_vx.h for
 * 		TA_VX_CMD_GET_RPMB_STATUS. Can be NULL.
 * @out_write_count: Current write counter value of the RPMB partition.
 *		Can be NULL.
 *
 * Return: 0 if successful, non-zero error code otherwise.
 */
int ta_vx_get_rpmb_status(uint32_t *out_status, uint32_t *out_write_count);

/**
 * ta_vx_provision_rpmb() - Provision RPMB authentication key and initialize
 * device lock state to VX_UNLOCKED.
 *
 * Programming will only be attempted if a key has not been already programmed
 * AND RPMB provisioing is not disabled in OTP.
 *
 * Return: 0 if attempted and successful, non-zero code otherwise.
 */
int ta_vx_provision_rpmb(void);

/**
 * ta_vx_reroute_rpmb_till_reboot() - Reroute RPMB traffic till reboot for
 * testing.
 *
 * Return: 0 if successful, non-zero code otherwise.
 */
int ta_vx_reroute_rpmb_till_reboot(void);

/**
 * ta_vx_reroute_rpmb_to_software() - Persistently reroute RPMB traffic.
 *
 * Return: 0 if successful, non-zero code otherwise.
 */
int ta_vx_reroute_rpmb_to_software(void);

/**
 * ta_vx_reroute_rpmb_to_hardware() - Permanently restore RPMB traffic.
 *
 * Return: 0 if successful, non-zero code otherwise.
 */
int ta_vx_reroute_rpmb_to_hardware(void);

/**
 * ta_vx_read_perm_attr_hash() - Read permanent attributes hash
 * @buf: Buffer to write value into.
 * @buf_len: Length of buf.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_read_perm_attr_hash(void *buf, size_t buf_len);

/**
 * ta_vx_delete_perm_attr() - Delete permanent attributes if
 * lockdown is not enabled.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_delete_perm_attr(void);

/**
 * ta_vx_get_perm_attr_status() - Get permanent attributes
 * status.
 *
 * @out_status: Receives status bit flags as defined in tee/ta_vx.h for
 * 		TA_VX_CMD_GET_PERM_ATTR_STATUS. Can be NULL.
 */
int ta_vx_get_perm_attr_status(uint32_t *status);

/**
 * ta_vx_lock_perm_attr() - Lock permanent attributes
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_lock_perm_attr(void);

/**
 * ta_vx_provision_usb_hash() - Provision USBBOOT hash
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_provision_usb_hash(void);

/**
 * ta_vx_get_perm_attr_status() - Get USBBOOT provision
 * status.
 *
 * @out_status: Receives status bit flags as defined in tee/ta_vx.h for
 * 		TA_VX_CMD_GET_USBBOOT_STATUS. Can be NULL.
 */
int ta_vx_get_usbboot_status(uint32_t *status);

/**
 * ta_vx_getvar_all() - Query hardware capabilities
 *
 * @out_caps: Receives VX_HARDWARE_* flags as defined in tee/ta_vx.h
 *
 * Return: 0 if successful, non-zero error code otherwise.
 */
int ta_vx_getvar_all(uint32_t *out_caps);

#ifdef CONFIG_TA_VX_TESTS
/**
 * ta_vx_run_tests() - Run tests defined in the VX TA.
 *
 * @name: Partial name of the tests to run.
 *
 * Return: 0 if successful, non-zero error code on failure.
 */
int ta_vx_run_tests(const char *name);
#endif  // CONFIG_TA_VX_TESTS

#endif // _TA_VX_HELPER_H_