dif_keymgr_dpe.h

Go to the documentation of this file.

// Copyright lowRISC contributors (OpenTitan project).
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
 
#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KEYMGR_DPE_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KEYMGR_DPE_H_
 
/**
 * @file
 * @brief <a href="/book/hw/ip/keymgr_dpe/">Key Manager DPE</a> Device Interface
 * Functions
 */
 
#include <stdint.h>
 
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
 
#include "sw/device/lib/dif/autogen/dif_keymgr_dpe_autogen.h"
 
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus
 
/**
 * SW-visible key manager DPE states.
 *
 * Key manager RTL has more than 4 finite state machine (FSM) states, but it
 * simply truncates the reported state into four states given below. The reason
 * behind this truncation is that FSM lingers on some states temporarily (i.e.
 * few clock cycles) and the transition into the next state does not require
 * further invocation.
 *
 * From SW point of view, key manager FSM transitions follow a sequence
 * sequential manner and these transitions are irreversible until a power cycle.
 */
typedef enum dif_keymgr_dpe_state {
  kDifKeymgrDpeStateReset = 0,
  kDifKeymgrDpeStateAvailable = 1,
  kDifKeymgrDpeStateDisabled = 2,
  kDifKeymgrDpeStateInvalid = 3
} dif_keymgr_dpe_state_t;
 
/**
 * Enumeration for side load slot clearing.
 */
typedef enum dif_keymgr_sideload_clr {
  kDifKeymgrDpeSideLoadClearNone = 0,
  kDifKeymgrDpeSideLoadClearAes = 1,
  kDifKeymgrDpeSideLoadClearKmac = 2,
  kDifKeymgrDpeSideLoadClearOtbn = 3,
  kDifKeymgrDpeSideLoadClearHmac = 4,
  // Using different value than those enumerated above should clear all slots,
  // so we can use the mask value of this field to denote ALL case.
  kDifKeymgrDpeSideLoadClearAll = 7,
} dif_keymgr_dpe_sideload_clr_t;
 
/**
 * Runtime configuration for keymgr dpe.
 */
typedef struct dif_keymgr_dpe_config {
  /**
   * Number of keymgr_dpe cycles before the entropy is reseeded.
   *
   * Keymgr dpe uses random values generated by the entropy source for
   * initializing its state and clearing sideload keys. This value determines
   * the frequency at which this random value is updated.
   */
  uint16_t entropy_reseed_interval;
} dif_keymgr_dpe_config_t;
 
/**
 * Input parameters for advancing a DPE context/slot.
 */
typedef struct dif_keymgr_dpe_advance_params {
  /**
   * This value is used by key manager as input to DICE computation and can be
   * either a value that represents the measurement of a boot stage or simply a
   * tag from a manifest.
   */
  uint32_t binding_value[8];
 
  /**
   * Maximum allowed version for keys to be generated at a state. This value is
   * stored inside keymgr slot so that it can later be compared against the
   * `key_version` input provided along with generation request.
   */
  uint32_t max_key_version;
 
  /**
   * The source slot to be used as parent DPE context.
   */
  uint32_t slot_src_sel;
 
  /**
   * The destination slot which recieves the derived child DPE context.
   */
  uint32_t slot_dst_sel;
 
  /**
   * The slot policy bits for the derived child DPE context.
   */
  uint32_t slot_policy;
} dif_keymgr_dpe_advance_params_t;
 
/**
 * Output metadata from one HW slot
 */
typedef struct dif_keymgr_dpe_metadata {
  /**
   * Maximum allowed version for keys to be generated from this DPE context
   */
  uint32_t max_key_version;
 
  /**
   * The current boot_stage of this DPE context.
   */
  uint32_t boot_stage;
 
  /**
   * The current slot policy bits for this DPE context, using the same bit
   * layout as the `SLOT_POLICY` register.
   */
  uint32_t slot_policy;
 
  /**
   * Validity of this DPE context.
   */
  uint32_t valid;
} dif_keymgr_dpe_metadata_t;
 
/**
 * Key destination of a versioned key generation operation.
 *
 * Regardless of whether the generated key is SW or sideload key, HW uses a
 * unique diversification constant for each cryptographic use case. In the case
 * of sideload key, this enum value is also used to determine the target
 * peripheral port to which the generated key is loaded.
 */
typedef enum dif_keymgr_dpe_key_dest {
  /**
   * Diversify the generated key for no HW IP (and don't sideload it).
   */
  kDifKeymgrDpeKeyDestNone = 0,
  /**
   * Diversify the generated key for AES (and load it to AES peripheral port if
   * sideload key).
   */
  kDifKeymgrDpeKeyDestAes = 1,
  /**
   * Diversify the generated key for KMAC (and load it to KMAC peripheral port
   * if sideload key).
   */
  kDifKeymgrDpeKeyDestKmac = 2,
  /**
   * Diversify the generated key for OTBN (and load it to OTBN peripheral port
   * if sideload key).
   */
  kDifKeymgrDpeKeyDestOtbn = 3,
  /**
   * Diversify the generated key for HMAC (and load it to HMAC peripheral port
   * if sideload key).
   */
  kDifKeymgrDpeKeyDestHmac = 4,
} dif_keymgr_dpe_key_dest_t;
 
/**
 * Input parameters for advancing a DPE context/slot.
 */
typedef struct dif_keymgr_dpe_generate_params {
  /**
   * Destination for {AES, KMAC, OTBN, HMAC}, which is used for diversification.
   */
  dif_keymgr_dpe_key_dest_t key_dest;
 
  /**
   * Set to true, if this is a sideload key, otherwise set to false.
   */
  bool sideload_key;
 
  /**
   * Salt value used as input for key generation (i.e. becomes part of the
   * message payload sent to KMAC during computation).
   */
  uint32_t salt[8];
 
  /**
   * The key version used for generating versioned key. This value should not be
   * greater than the `max_key_version` value stored inside the source slot that
   * is used to generate the key.
   */
  uint32_t version;
 
  /**
   * The source slot from which the key is derived.
   */
  uint32_t slot_src_sel;
} dif_keymgr_dpe_generate_params_t;
 
/**
 * Input parameters for erasing a DPE context/slot.
 */
typedef struct dif_keymgr_dpe_erase_params {
  /**
   * Index for the slot to be erased.
   */
  uint32_t slot_dst_sel;
} dif_keymgr_dpe_erase_params_t;
 
/**
 * Useed to represent the output of SW generated key.
 */
typedef struct dif_keymgr_dpe_output {
  uint32_t value[2][8];
} dif_keymgr_dpe_output_t;
 
/**
 * Status code bit flags.
 *
 * See also: `dif_keymgr_dpe_status_codes_t`.
 */
typedef enum dif_keymgr_dpe_status_code {
  /**
   * Key manager is idle.
   */
  kDifKeymgrDpeStatusCodeIdle = 1 << 0,
  /**
   * Software invoked an invalid operation.
   */
  kDifKeymgrDpeStatusCodeInvalidOperation = 1 << 1,
  /**
   * Key manager issued invalid data to KMAC interface.
   */
  kDifKeymgrDpeStatusCodeInvalidKmacInput = 1 << 2,
  /**
   * Key manager encountered invalid state.
   */
  kDifKeymgrDpeStatusCodeInvalidState = 1 << 3,
 
} dif_keymgr_dpe_status_code_t;
 
/**
 * Define mask for error fields of `dif_keymgr_dpe_status_code_t`.
 */
static const bitfield_field32_t kIdleBitfield = (bitfield_field32_t){
    .mask = 0x1,
    .index = 0,
};
 
/**
 * Define mask for idle field of `dif_keymgr_dpe_status_code_t`.
 */
static const bitfield_field32_t kErrorBitfield = (bitfield_field32_t){
    .mask = 0x7,
    .index = 1,
};
 
/**
 * A bit vector of status codes.
 *
 * The following snippet can be used to check if key manager is idle:
 *
 *   `bool is_idle = (status_codes & kDifKeymgrDpeStatusCodeIdle);`
 *
 * The following snippet can be used to check if key manager is idle and
 * error-free:
 *
 *   `bool is_idle_and_ok = (status_codes == kDifKeymgrDpeStatusCodeIdle);`
 *
 * See also: `dif_keymgr_dpe_status_code_t`.
 */
typedef uint8_t dif_keymgr_dpe_status_codes_t;
 
/**
 * Initializes the keymgr_pde block by performing an advance operation.
 *
 * The hardware does not have an explicit initialize command. Initialization is
 * simple the first advance call without software binding, max version or
 * policy registers set. Use this call before calling
 * `dif_keymgr_dpe_advance_state()`.
 *
 * @param keymgr_dpe A key manager handle.
 * @param slot_dst_sel Target slot used to latch the UDS key.
 * @return The result of the operation.
 */
dif_result_t dif_keymgr_dpe_initialize(const dif_keymgr_dpe_t *keymgr_dpe,
                                       uint32_t slot_dst_sel);
 
/**
 * Advances a keymgr_dpe slot with given parameters.
 *
 * @param keymgr_dpe A key manager handle.
 * @param params Struct to pass inputs consumed by HW during advance.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_advance_state(
    const dif_keymgr_dpe_t *keymgr_dpe,
    const dif_keymgr_dpe_advance_params_t *params);
 
/**
 * Erases a given keymgr_dpe slot.
 *
 * @param keymgr_dpe A key manager handle.
 * @param params A struct that selects the slot to be erased.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_erase_slot(
    const dif_keymgr_dpe_t *keymgr_dpe,
    const dif_keymgr_dpe_erase_params_t *params);
 
/**
 * Reads back the metadata of a keymgr_dpe HW slot.
 *
 * @param keymgr_dpe A key manager handle.
 * @param slot Index of the HW slot to read metadata from.
 * @param[out] metadata The maximum key version, boot stage, slot policy and
 * validity of the DPE context held in `slot`.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_get_metadata(const dif_keymgr_dpe_t *keymgr_dpe,
                                         uint32_t slot,
                                         dif_keymgr_dpe_metadata_t *metadata);
 
/**
 * Disables key manager dpe.
 *
 * This function disables keymgr dpe until the next power cycle by making
 * it transition to the "disabled" state. The "disabled" state is a terminal
 * state where the keymgr dpe is no longer operational and its secret values
 * are wiped.
 *
 * @param keymgr_dpe A key manager handle.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_disable(const dif_keymgr_dpe_t *keymgr_dpe);
 
/**
 * Generate a SW/HW key from a chosen keymgr_dpe slot.
 *
 * @param keymgr_dpe A key manager handle.
 * @param params Struct to pass inputs consumed by HW generate operation.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_generate(
    const dif_keymgr_dpe_t *keymgr_dpe,
    const dif_keymgr_dpe_generate_params_t *params);
 
/**
 * Gets the operational status of keymgr_dpe.
 *
 * This function also clears OP_STATUS and ERR_CODE registers after reading
 * them.
 *
 * @param keymgr_dpe A key manager handle.
 * @param[out] status_codes Out-param for key manager status codes.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_get_status_codes(
    const dif_keymgr_dpe_t *keymgr_dpe,
    dif_keymgr_dpe_status_codes_t *status_codes);
 
/**
 * Gets the current state of key manager.
 *
 * @param keymgr_dpe A key manager handle.
 * @param[out] state Out-param for current key manager state.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_get_state(const dif_keymgr_dpe_t *keymgr_dpe,
                                      dif_keymgr_dpe_state_t *state);
 
/**
 * Read the value of SW generated key from its related CSR. It is the
 * responsibility of the caller to check that key generation has completed.
 *
 * @param keymgr_dpe A key manager handle.
 * @param[out] output The key value in two shares.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_read_output(const dif_keymgr_dpe_t *keymgr_dpe,
                                        dif_keymgr_dpe_output_t *output);
 
/**
 * Starts or stops clearing of sideload keys.
 *
 * Selecting a sideload destination other than `kDifKeymgrDpeSideLoadClearNone`
 * causes keymgr_dpe to continuously overwrite the corresponding sideload key
 * port with randomness (Destination can either be AES, KMAC or OTBN).
 * Any value that is not one of the enumerated destinations clears all sideload
 * key ports. To resume normal operation, call this function again with
 * `kDifKeymgrDpeSideLoadClearNone` to stop the clearing.
 *
 * @param keymgr_dpe A key manager handle.
 * @param clear_dest Target sideload key.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_clear_sideload_key(
    const dif_keymgr_dpe_t *keymgr_dpe,
    dif_keymgr_dpe_sideload_clr_t clear_dest);
 
/**
 * Runtime configuration for keymgr dpe.
 *
 * @param keymgr_dpe A key manager handle.
 * @param config configuration for the keymgr dpe.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_keymgr_dpe_configure(const dif_keymgr_dpe_t *keymgr_dpe,
                                      dif_keymgr_dpe_config_t config);
 
#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus
 
#endif  // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_KEYMGR_DPE_H_