include/tee/ta_vx.h

/* SPDX-License-Identifier: BSD-2-Clause */
/* Copyright (c) 2018, Linaro Limited    */
/* Copyright (c) 2019-2020, Google       */

#ifndef __TA_VX_H
#define __TA_VX_H

#define TA_VX_UUID { 0x99dc95b2, 0x938e, 0x47eb, \
		      { 0x80, 0xe8, 0x94, 0x04, 0xae, 0x8a, 0x13, 0x85 } }

#define TA_VX_MAX_ROLLBACK_LOCATIONS	32
#define TA_VX_NONCE_SIZE	32

typedef enum vx_lock_state {
	VX_LOCKED = 0,
	VX_UNLOCKED = 1,
} vx_lock_state_t;

/*
 * Gets the rollback index corresponding to the given rollback index slot.
 *
 * in	params[0].value.a:	rollback index slot
 * out	params[1].value.a:	upper 32 bits of rollback index
 * out	params[1].value.b:	lower 32 bits of rollback index
 */
#define TA_VX_CMD_READ_ROLLBACK_INDEX	0

/*
 * Updates the rollback index corresponding to the given rollback index slot.
 *
 * Will refuse to update a slot with a lower value.
 *
 * in	params[0].value.a:	rollback index slot
 * in	params[1].value.a:	upper 32 bits of rollback index
 * in	params[1].value.b:	lower 32 bits of rollback index
 */
#define TA_VX_CMD_WRITE_ROLLBACK_INDEX	1

/*
 * Gets the lock state of the device.
 *
 * out	params[0].value.a:	VX_LOCKED/VX_UNLOCKED defined above.
 */
#define TA_VX_CMD_READ_LOCK_STATE	2

/*
 * Sets the lock state of the device.
 *
 * If the lock state is changed all rollback slots will be reset to 0
 *
 * in	params[0].value.a:	VX_LOCKED/VX_UNLOCKED defined above.
 */
#define TA_VX_CMD_WRITE_LOCK_STATE	3

/*
 * Reads a persistent value corresponding to the given name.
 *
 * in		params[0].memref:	persistent value name
 * inout	params[1].memref:	read persistent value buffer
 */
#define TA_VX_CMD_READ_PERSIST_VALUE	4

/*
 * Writes a persistent value corresponding to the given name.
 *
 * in	params[0].memref:	persistent value name
 * in	params[1].memref:	persistent value buffer to write
 */
#define TA_VX_CMD_WRITE_PERSIST_VALUE	5

/*
 * Notifies the TA that the main Bootloader is exiting.
 */
#define TA_VX_CMD_EXIT_BOOTLOADER	6

/*
 * Regenerates the random nonce associated with the device lock state.
 *
 * This command is now deprecated. New code should use TA_VX_CMD_REFRESH_NONCE(
 * kFDRNonceID, kFDRNonceIDSize);
 */
#define TA_VX_CMD_REFRESH_LOCK_STATE_NONCE	7

/*
 * Read the current random nonce associated with the device lock state.
 *
 * This command is now deprecated. New code should use TA_VX_CMD_GET_NONCE(
 * kFDRNonceID, kFDRNonceIDSize);
 *
 * inout	params[0].memref:	Caller allocated buffer to receive
 * 					the nonce. The buffer must be at least
 * 					TA_VX_NONCE_SIZE bytes.
 */
#define TA_VX_CMD_GET_LOCK_STATE_NONCE	8

/*
 * Enumerate named persistent values.
 *
 * out		params[0].value.a:	total found.
 * inout	params[1].memref:	Buffer to receive all names in the
 * 					format: name1\0name2\0...
 */
#define TA_VX_CMD_ENUMERATE_PERSIST_VALUES	9


/*
 * Draw random bytes from the TEE's CPRNG.
 *
 * inout	params[0].memref:	Buffer to receive all the random bytes
 */
#define TA_VX_CMD_CPRNG_DRAW	10

/*
 * Delete a persistent value by name.
 *
 * Does nothing and returns success if such a value does not exist.
 *
 * in	params[0].memref:	persistent value name
 */
#define TA_VX_CMD_DELETE_PERSIST_VALUE	11

/*
 * Writes permanent attributes data
 *
 * in	params[0].memref:	permanent attributes buffer to write
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_WRITE_PERM_ATTR	12

/*
 * Reads permanent attributes data
 *
 * inout	params[0].memref:	read permanent attributes buffer
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_READ_PERM_ATTR	13

enum vx_rpmb_status {
	VX_RPMB_AUTH_KEY_PROGRAMMED  = 0x01,
	VX_RPMB_AUTH_KEY_VERIFIED    = 0x02,
	VX_RPMB_PROVISIONING_ALLOWED = 0x04,
};

/* Reads the RPMB provisioning status.
 *
 * Args:
 *   out params[0].value.a:  Status flags (VX_RPMB_*).
 *   out params[0].value.b:  Write counter value [0 ~ MAX_UINT32).
 *
 * Returns:
 *   TEE_SUCCESS if status determination has been definitive and successful.
 *   Otherwise TEE_ERROR_*.
 */
#define TA_VX_CMD_GET_RPMB_STATUS	14

/* Provisions the RPMB partition.
 *
 * Steps:
 * 1. If the authentication key is not programmed AND RPMB provisioning is
 *    allowed as indicated by an OTP bit, program and verify the key.
 * 2. Initialize device lock state to VX_UNLOCKED.
 * 3. Blow the RPMB provisioning disable bit to never ever attempt programming
 *    the RPMB key again.
 *
 * The secret key to be programmed is derived in the TEE-OS from the hardware
 * unique key (HUK) and the eMMC device ID. A TEE supplicant must be running on
 * the REE side to feed RPMB partition information to TEE upon request.
 *
 * Since eMMC and SoC are separate silicon packages and communications between
 * them are not authenticated until the shared key is programmed (as plaintext
 * across the bus), RPMB provisioning must be carried out in a trusted
 * environment (read factory). Once provisioning is done, it will never be
 * attempted again because of the blown OTP bit without replacing the SoC.
 *
 * Args: None
 *
 * Returns:
 *   TEE_SUCCESS if RPMB has been successfully provisioned a new key and the
 *   device lock state has been initialized to VX_UNLOCKED.
 *
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_PROVISION_RPMB	15

/*
 * Reads the permanent attributes hash
 *
 * inout	params[0].memref:	read permanent attributes hash buffer
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_READ_PERM_ATTR_HASH	16

/*
 * Lock permanent attributes. Permanent attributes can't be changed
 * after locking.
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_LOCK_PERM_ATTR 17

typedef enum {
	VX_PERM_ATTR_PROGRAMMED = (1 << 0),
	VX_PERM_ATTR_LOCKED = (1 << 1),
	VX_PERM_ATTR_HARDCODED = (1 << 2),
} perm_attr_status_t;

/*
 * Get the current permanent attributes status
 *
 * out  params[0].value.a:  Status flags (VX_PERM_ATTR_*).
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_GET_PERM_ATTR_STATUS	18

/*
 * Deletes permanent attributes (fails if locked).
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_DELETE_PERM_ATTR 19

typedef enum vx_option {
	/* If set, automatically provisions RPMB if RPMB is not already
	 * provisioned. Default unset. */
	VX_OPTION_AUTO_PROVISION_RPMB = (1 << 1),
	/* For testing use. e.g. The Bootloader uses this to make sure options
	 * CAN NOT be set after issuing CMD_EXIT_BOOTLOADER. */
	VX_OPTION_FOR_TESTING         = (1 << 3),
} vx_option_t;

/*
 * Sets certain options for the VX TA.
 *
 * This command is only available to the Bootloader.
 *
 * in  params[0].value.a:  Options flags to set (VX_OPTION_*).
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_SET_OPTIONS	20

/*
 * Unsets certain options for the VX TA.
 *
 * This command is only available to the Bootloader.
 *
 * in  params[0].value.a:  Options flags to unset (VX_OPTION_*).
 *
 * Returns
 *   TEE_SUCCESS on success,
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_UNSET_OPTIONS	21

/* Provisions the USBBOOT password hash.
 *
 * Args: None
 *
 * Returns:
 *   TEE_SUCCESS if USBBOOT password hash has been successfully provisioned.
 *
 *   TEE_ERROR_* otherwise.
 */
#define TA_VX_CMD_PROVISION_USBBOOT_PWD_HASH	22

enum vx_usbboot_status {
	/* If set, USBBOOT password hash was provisioned.
	 * Default unset. */
	VX_USBBOOT_PWD_PROVISIONED = (1 << 0),
	/* If set, USBBOOT password hash value is locked and its OTP area
     * can't be changed. Default unset. */
	VX_USBBOOT_PWD_LOCKED = (1 << 1),
	/* If set, USBBOOT password usage was turned on. Default unset. */
	VX_USBBOOT_PWD_ENABLED = (1 << 2),
};

/* Reads the USBBOOT provisioning status.
 *
 * Args:
 *   out params[0].value.a:  Status flags (VX_USBBOOT_*).
 *
 * Returns:
 *   TEE_SUCCESS if status determination has been definitive and successful.
 *   Otherwise TEE_ERROR_*.
 */
#define TA_VX_CMD_GET_USBBOOT_STATUS	23

/**
 * Persistent Nonces Management.
 */

/*
 * Get a nonce by ID. The nonce is generated if not already exists.
 *
 * in		params[0].memref:	Nonce ID (arbitrary bytes, length > 0).
 * inout	params[1].memref:	Caller allocated buffer to receive
 * 					the nonce. The buffer must be at least
 * 					TA_VX_NONCE_SIZE bytes.
 */
#define TA_VX_CMD_GET_NONCE	0x101

/*
 * Refresh/rotate a nonce by ID. The nonce is generated if not found.
 *
 * in		params[0].memref:	Nonce ID (arbitrary bytes, length > 0).
 *
 * Returns TEE_ERROR_NOT_SUPPORTED if the underlying hardware does not support
 * rotations.
 */
#define TA_VX_CMD_REFRESH_NONCE	0x102

/*
 * Run internal tests defined in the VX TA.
 *
 * These tests are disabled by default and is meant to be manually enabled
 * as needed in ta/vx/Makefile by setting CFG_TA_VX_TESTS=y.
 *
 * in	params[0].memref:	name of tests to run (matches *${name}*).
 */
#define TA_VX_CMD_RUN_TESTS	0xFF01

#endif /*__TA_VX_H*/