rt-thread/bsp/imx6ul/platform/include/hab_defines.h

/*
 * Copyright (c) 2008-2012, Freescale Semiconductor, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * o Redistributions of source code must retain the above copyright notice, this list
 *   of conditions and the following disclaimer.
 *
 * o Redistributions in binary form must reproduce the above copyright notice, this
 *   list of conditions and the following disclaimer in the documentation and/or
 *   other materials provided with the distribution.
 *
 * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
 *   contributors may be used to endorse or promote products derived from this
 *   software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*!
 * @file hab_defines.h
 * @brief defines for data structures and macros used for enabling secure boot
 *
 * @ingroup diag_init
 */
#ifndef HAB_DEFINES_H
#define HAB_DEFINES_H
/*===========================================================================
                            INCLUDE FILES
=============================================================================*/
#include <stdint.h>             /* for integer types */
#include <stdbool.h>            /* for bool type */
#include <stddef.h>             /* for NULL and offsetof() */
/*===========================================================================
                              CONSTANTS
=============================================================================*/
/** @addtogroup struct
 *  @{ 
 */

#define HDR_BYTES 4  /* cannot use sizeof(hab_hdr_t) in preprocessor */

/** @name External data structure tags
 * @anchor dat_tag
 *
 * Tag values 0x00 .. 0xef are reserved for HAB.  Values 0xf0 .. 0xff
 * are available for custom use.
 */
/*@{*/
#define HAB_TAG_IVT  0xd1       /**< Image Vector Table */
#define HAB_TAG_DCD  0xd2       /**< Device Configuration Data */
#define HAB_TAG_CSF  0xd4       /**< Command Sequence File */
#define HAB_TAG_CRT  0xd7       /**< Certificate */
#define HAB_TAG_SIG  0xd8       /**< Signature */
#define HAB_TAG_EVT  0xdb       /**< Event */
#define HAB_TAG_RVT  0xdd       /**< ROM Vector Table */
#define HAB_TAG_WRP  0x81       /**< Wrapped Key */
#define HAB_TAG_MAC  0xac       /**< Message Authentication Code */
/* Values 00 ... 7e reserved for internal use.  Values b0 ... cf reserved for
 * CSF commands.  Values e0 ... ef reserved for key types.
 *
 * Available values: 82, 84, 87, 88, 8b, 8d, 8e, 90, 93, 95, 96, 99, 9a,
 * 9c, 9f, a0, a3, a5, a6, a9, aa, af
 *
 * Custom values: f0, f3, f5, f6, f9, fa, fc, ff
 */
/*@}*/

/** @name HAB version */
/*@{*/
#define HAB_MAJOR_VERSION  4    /**< Major version of this HAB release */
#define HAB_MINOR_VERSION  1    /**< Minor version of this HAB release */
#define HAB_VER_MAJ_WIDTH 4     /**< Major version field width  */
#define HAB_VER_MAJ_SHIFT 4     /**< Major version field offset  */
#define HAB_VER_MIN_WIDTH 4     /**< Minor version field width  */
#define HAB_VER_MIN_SHIFT 0     /**< Minor version field offset  */
/** Full version of this HAB release @hideinitializer */
#define HAB_VERSION HAB_VER(HAB_MAJOR_VERSION, HAB_MINOR_VERSION) 
/** Base version for this HAB release @hideinitializer */
#define HAB_BASE_VERSION HAB_VER(HAB_MAJOR_VERSION, 0) 

/*@}*/

/*  @} struct */

/*---------------------------------------------------------------------------*/

/** @addtogroup cmd
 *  @{ 
 */

/** @name Command tags
 * @anchor cmd_tag
 *
 * Tag values 0xb0 .. 0xcf are reserved for HAB.  Values 0xf0 .. 0xff
 * are available for custom use.
 */
/*@{*/
#define HAB_CMD_SET       0xb1  /**< Set */
#define HAB_CMD_INS_KEY   0xbe  /**< Install Key */
#define HAB_CMD_AUT_DAT   0xca  /**< Authenticate Data */
#define HAB_CMD_WRT_DAT   0xcc  /**< Write Data */
#define HAB_CMD_CHK_DAT   0xcf  /**< Check Data */
#define HAB_CMD_NOP       0xc0  /**< No Operation */
#define HAB_CMD_INIT      0xb4  /**< Initialise */
#define HAB_CMD_UNLK      0xb2  /**< Unlock */
#ifdef HAB_FUTURE
#define HAB_CMD_RMV_KEY         /**< Remove Key */
#define HAB_CMD_INS_REF         /**< Install Reference Data */
#define HAB_CMD_INS_PLG         /**< Install Plugin */
#define HAB_CMD_RMV_PLG         /**< Remove Plugin */
#define HAB_CMD_CHK_VER         /**< Check SW Version */
#endif
/* Remaining values: b7, b8, bb, bd, c3, c5, c6, c9 */
/*@}*/

/*  @} cmd */

/*---------------------------------------------------------------------------*/

/** @addtogroup pcl
 *  @{ 
 */

/** @name Protocol tags
 * @anchor pcl_tag 
 *
 * Tag values 0x00 .. 0xef are reserved for HAB.  Values 0xf0 .. 0xff are
 * available for custom use.
 */
/*@{*/
#define HAB_PCL_SRK      0x03   /**< SRK certificate format */
#define HAB_PCL_X509     0x09   /**< X.509v3 certificate format */
#define HAB_PCL_CMS      0xc5   /**< CMS/PKCS#7 signature format */
#define HAB_PCL_BLOB     0xbb   /**< SHW-specific wrapped key format */
#define HAB_PCL_AEAD     0xa3   /**< Proprietary AEAD MAC format */
#ifdef HAB_FUTURE
#define HAB_PCL_WTLS     0x05   /**< OMA WTLS certificate format */
#define HAB_PCL_FSL      0x0f   /**< FSL bound signature protocol */
#define HAB_PCL_HMAC     0x30   /**< NIST HMAC message authentication */
#define HAB_PCL_CBCMAC   0x33   /**< CBC-MAC message authentication */
#endif
/*@}*/

/* Available values: 06, 0a, 0c, 11, 12, 14, 17, 18, 1b, 1d, 1e, 21, 22, 24,
 * 27, 28, 2b, 2d, 2e, 35, 36, 39, 3a, 3c, 3f, 41, 42, 44, 47, 48, 4b, 4d, 4e,
 * 50, 53, 55, 56, 59, 5a, 5c, 5f, 60, 63, 65, 66, 69, 6a, 6c, 6f, 71, 72, 74,
 * 77, 78, 7b, 7d, 7e, 81, 82, 84, 87, 88, 8b, 8d, 8e, 90, 93, 95, 96, 99, 9a,
 * 9c, 9f, a0, a5, a6, a9, aa, ac, af, b1, b2, b4, b7, b8, bd, be, c0, c3, c6,
 * c9, ca, cc, cf, d1, d2, d4, d7, d8, db, dd, de, e1, e2, e4, e7, e8, eb, ed,
 * ee
 *
 * Custom values: f0, f3, f5, f6, f9, fa, fc, ff
 */

/*  @} pcl */

/*---------------------------------------------------------------------------*/

/** @addtogroup alg
 *  @{ 
 */

/** @name Algorithm types
 * @anchor alg_typ
 *
 * The most-significant nibble of an algorithm ID denotes the algorithm
 * type.  Algorithms of the same type share the same interface.
 *
 * Types 0x0 .. 0xc are reserved for HAB.  Types 0xd .. 0xf are available for
 * custom use.  Within each reserved type N in 0 .. c, tag values 0xN0 .. 0xNc
 * are reserved for HAB.  Values 0xNd .. 0xNf are available for custom use.
 */
/*@{*/
#define HAB_ALG_ANY      0x0    /**< Algorithm type ANY */
#define HAB_ALG_HASH     0x1    /**< Hash algorithm type */
#define HAB_ALG_SIG      0x2    /**< Signature algorithm type */
#define HAB_ALG_FF       0x3    /**< Finite field arithmetic */
#define HAB_ALG_EC       0x4    /**< Elliptic curve arithmetic */
#define HAB_ALG_CIPHER   0x5    /**< Cipher algorithm type */
#define HAB_ALG_MODE     0x6    /**< Cipher/hash modes */
#define HAB_ALG_WRAP     0x7    /**< Key wrap algorithm type */
/*@}*/

/** @name Algorithm type ANY
 *
 * Algorithms of type ANY have no common interface: the protocol must know
 * what to do.
 */
/*@{*/
#ifdef HAB_FUTURE
#define HAB_ALG_RANDOM          /**< Random number generation */
#endif
/* Available values: 03, 05, 06, 09, 0a, 0c, 0f
 */
/*@}*/

/** @name Hash algorithms */
/*@{*/
#define HAB_ALG_SHA1     0x11   /**< SHA-1 algorithm ID */
#define HAB_ALG_SHA256   0x17   /**< SHA-256 algorithm ID */
#define HAB_ALG_SHA512   0x1b   /**< SHA-512 algorithm ID */
/* Available values: 0x14, 0x12, 18, 1d, 1e
 */
/*@}*/

/** @name Signature algorithms */
/*@{*/
#define HAB_ALG_PKCS1    0x21   /**< PKCS#1 RSA signature algorithm  */
#ifdef HAB_FUTURE
#define HAB_ALG_DSA             /**< NIST DSA signature algorithm */
#define HAB_ALG_ECDSA           /**< NIST ECDSA signature algorithm */
#endif
/* Available values: 22, 24, 27, 28, 2b, 2d, 2e
 */
/*@}*/

/** @name Cipher algorithms */
/*@{*/
#define HAB_ALG_AES      0x55   /**< AES algorithm ID */
/* Available values: 50, 53, 56, 59, 5a, 5c, 5f
 */
/*@}*/

/** @name Cipher or hash modes */
/*@{*/
#define HAB_MODE_CCM      0x66  /**< Counter with CBC-MAC */
#ifdef HAB_FUTURE
#define HAB_MODE_HMAC           /**< HMAC hash mode */
#endif
/* Available values: 60, 63, 65, 69, 6a, 6c, 6f
 */
/*@}*/

/** @name Key wrap algorithms */
/*@{*/
#define HAB_ALG_BLOB      0x71  /**< SHW-specific key wrap */
/* Available values: 72, 74, 77, 78, 7b, 7d, 7e
 */
/*@}*/

/* Available values: 81, 82, 84, 87, 88, 8b, 8d, 8e, 90, 93, 95, 96, 99, 9a,
 * 9c, 9f, a0, a3, a5, a6, a9, aa, ac, af, b1, b2, b4, b7, b8, bb, bd, be, c0,
 * c3, c5, c6, c9, ca, cc, cf, d1, d2, d4, d7, d8, db, dd, de, e1, e2, e4, e7,
 * e8, eb, ed, ee, f0, f3, f5, f6, f9, fa, fc, ff
 */

/*  @} alg */

/*---------------------------------------------------------------------------*/

/** @addtogroup eng
 *  @{ 
 */

/** @name Engine plugin tags 
 *  @anchor eng_tag
 *
 * Tag values 0x00 .. 0xef and 0xff are reserved for HAB.  Values 0xf0 .. 0xfe
 * are available for custom use.
 */
/*@{*/
#define HAB_ENG_ANY      0x00   /**< First compatible engine will be
                                 * selected automatically (no engine
                                 * configuration parameters are allowed).
                                 */
#define HAB_ENG_SCC      0x03   /**< Security controller */
#define HAB_ENG_RTIC     0x05   /**< Run-time integrity checker */
#define HAB_ENG_SAHARA   0x06   /**< Crypto accelerator */
#define HAB_ENG_CSU      0x0a   /**< Central Security Unit */
#define HAB_ENG_SRTC     0x0c   /**< Secure clock */
#ifdef HAB_FUTURE
#define HAB_ENG_RNG      0x09   /**< Standalone random number generator */
#define HAB_ENG_SJC      0x0f   /**< Secure JTAG controller */
#define HAB_ENG_WDOG     0x11   /**< Watchdog timer */
#define HAB_ENG_SRC      0x12   /**< System Reset Controller */
#define HAB_ENG_SPBA     0x14   /**< Shared Peripheral Bus Arbiter */
#define HAB_ENG_IIM      0x17   /**< Fuse controller */
#define HAB_ENG_IOMUX    0x18   /**< IO multiplexer */
#endif
#define HAB_ENG_DCP      0x1b   /**< Data Co-Processor */
#define HAB_ENG_CAAM     0x1d   /**< Cryptographic Acceleration and
                                     Assurance Module */
#define HAB_ENG_SNVS     0x1e   /**< Secure Non-Volatile Storage */
#define HAB_ENG_OCOTP    0x21   /**< Fuse controller */
/** @cond rom */
#define HAB_ENG_DTCP     0x22   /**< DTCP co-processor */
#define HAB_ENG_ROM      0x36   /**< Protected ROM area */
#define HAB_ENG_HDCP     0x24   /**< HDCP co-processor */
#define HAB_ENG_RTL      0x77   /**< @rom RTL simulation engine */
/** @endcond */
#define HAB_ENG_SW       0xff   /**< Software engine */
/* Available values: 27, 28, 2b, 2d, 2e, 30, 33, 35,
 * 39, 3a, 3c, 3f, 41, 42, 44, 47, 48, 4b, 4d, 4e, 50, 53, 55, 56, 59, 5a,
 * 5c, 5f, 60, 63, 65, 66, 69, 6a, 6c, 6f, 71, 72, 74, 78, 7b, 7d, 7e, 81,
 * 82, 84, 87, 88, 8b, 8d, 8e, 90, 93, 95, 96, 99, 9a, 9c, 9f, a0, a3, a5, a6,
 * a9, aa, ac, af, b1, b2, b4, b7, b8, bb, bd, be, c0, c3, c5, c6, c9, ca, cc,
 * cf, d1, d2, d4, d7, d8, db, dd, de, e1, e2, e4, e7, e8, eb, ed, ee
 *
 * Custom values: f0, f3, f5, f6, f9, fa, fc
 */
/*@}*/

/*  @} eng */

/*---------------------------------------------------------------------------*/

/** @addtogroup sah
 *  @{ 
 */

/** Maximum data blocks in a single hash  */
#define HAB_SAHARA_BLOCK_MAX 12

/** @cond rom */
/** @rom DMA storage requirement
 *
 * This figure is derived in several parts:
 * - each hash operation needs a 6-word descriptor structure
 * - each data block needs a 3-word link structure
 * - the result needs a 3-word link structure
 * - at least 40 bytes are required for SHA-256 result and memory manager
 * overhead: 64 bytes allows some small overhead.
 */
#define HAB_SAHARA_DMA_MIN_BYTES (24 + HAB_SAHARA_BLOCK_MAX * 12 + 12 + 64)
/** @endcond */

/*  @} sah */

/*---------------------------------------------------------------------------*/

/** @addtogroup dcp
 *  @{ 
 */

/** Maximum data blocks in a single hash */
#define HAB_DCP_BLOCK_MAX 6

/** @cond rom */
/** @rom DMA storage requirement
 *
 * This figure is derived in two parts:
 * - each data block needs an 8-word work packet (descriptor)
 * - at least 40 bytes are required for SHA-256 result and memory manager
 * overhead: 64 bytes allows some small overhead.
 */
#define HAB_DCP_DMA_MIN_BYTES (64 + HAB_DCP_BLOCK_MAX * 32)
/** @endcond */

/*  @} dcp */

/*---------------------------------------------------------------------------*/

/** @addtogroup rtic
 *  @{ 
 */

/** Maximum data blocks in a single hash */
#define HAB_RTIC_BLOCK_MAX 2

/*  @} rtic */

/*---------------------------------------------------------------------------*/

/** @addtogroup scc
 *  @{ 
 */

/** @cond rom */
/** @rom DMA storage requirement
 *
 * This figure is derived in several stages, and assumes plaintext and
 * ciphertext buffers are both allocated in the DMA region :
 * - 4 blocks of plaintext required
 * - 4 blocks of ciphertext required
 * - each block is 16 bytes long
 * - the plaintext address must be block-aligned (up to 15 bytes overhead)
 * - the ciphertext address must be block-aligned (up to 3 bytes overhead)
 * - at least 8 bytes of memory manager overhead: allow 32 for comfort
 */
#define HAB_SCC_DMA_MIN_BYTES ( (4+4)*16 + 15 + 3 + 32)
/** @endcond */

/*  @} scc */

/*---------------------------------------------------------------------------*/

/** @addtogroup caam
 *  @{ 
 */

/** Maximum data blocks in an @ref cmd_aut_dat command */
#define HAB_CAAM_BLOCK_MAX 8

/** @cond rom */
/** @rom Hash DMA storage requirement
 *
 * This figure is derived in several parts:
 * - each hash operation needs
 *   - a 7-word descriptor, and
 *   - a 32-byte result buffer (for SHA-256),
 *   - giving a base requirement of (7*4 + 32) = 60 bytes
 * - each data block needs a 4-word link structure
 * - memory manager overhead is at least 8 bytes: 16 bytes allows flexibility
 */
#define HAB_CAAM_HSH_DMA_MIN_BYTES (60 + HAB_CAAM_BLOCK_MAX * 16 + 16)

/** @rom AEAD DMA storage requirement
 *
 * This figure is derived in several parts:
 * - each AEAD operation needs
 *   - a 16-word descriptor, 
 *   - a 32-byte initial context value (B0 and CTR0), and
 *   - a 16-byte MAC value,
 *   - giving a base requirement of (16*4 + 32 + 16) = 112 bytes
 * - each data block needs a 4-word link structure
 * - memory manager overhead is at least 8 bytes: 16 bytes allows flexibility
 */
#define HAB_CAAM_CCM_DMA_MIN_BYTES (112 + HAB_CAAM_BLOCK_MAX * 16 + 16)

/** @rom RNG DMA storage requirement
 *
 * This figure is derived in several parts:
 * - each DRNG test operation allocates a DMA area with
 *   - a 1-word header, and
 *   - a 3-word job ring area, and
 *   - a 54-word descriptor,
 *   - requiring a total 58*4 = 232 bytes
 * - each DRNG test operation also allocates a DMA area with
 *   - a 1-word header, and
 *   - a 32-byte result buffer
 *   - requiring a total 4 + 32 = 36 bytes
 */
#define HAB_CAAM_RNG_DMA_MIN_BYTES (232 + 32)
/** @endcond */

/*  @} caam */

/*---------------------------------------------------------------------------*/

/** @addtogroup key
 *  @{ 
 */

/** @name Key types
 * @anchor key_types
 *
 * Tag values 0xe0 .. 0xef are reserved for HAB.  Values 0xf0 .. 0xff
 * are available for custom use.
 */
/*@{*/
#define HAB_KEY_PUBLIC 0xe1     /**< Public key type: data present */
#define HAB_KEY_SECRET 0xe2     /**< Secret key type: data present */
#define HAB_KEY_MASTER 0xed     /**< Master KEK type */
#define HAB_KEY_HASH   0xee     /**< Any key type: hash only */
/* Available values: e4, e7, e8, eb
 *
 * Custom values: f0, f3, f5, f6, f9, fa, fc, ff
 */
/*@}*/

/** @name Public key store indices */
/*@{*/
#define HAB_IDX_SRK 0           /**< Super-Root Key index */
#define HAB_IDX_CSFK 1          /**< CSF key index */
/*@}*/

/** @name Key Counts */
/*@{*/
#define HAB_SRK_MIN 1           /**< Minimum Super-Root Key count */
#define HAB_SRK_MAX 4           /**< Maximum Super-Root Key count */
#define HAB_KEY_PUBLIC_MAX 5    /**< Maximum installed public key count
                                 *   (incl Super-Root Key)
                                 */
#define HAB_KEY_SECRET_MAX 4    /**< Maximum installed secret key count
                                 *   (excl Master KEKs)
                                 */
/*@}*/

/*  @} key */

/*---------------------------------------------------------------------------*/

#ifdef HAB_FUTURE
/** @addtogroup key_ecdsa
 *  @{ 
 */

/** @name Bitfield definitions */
/*@{*/
#define HAB_KEY_ECDSA_FLG_WIDTH 8 /**< Width of @a flg field */
#define HAB_KEY_ECDSA_FLG_SHIFT 0 /**< Offset of @a flg field */
#define HAB_KEY_ECDSA_TYP_WIDTH 8 /**< Width of @a typ field */
#define HAB_KEY_ECDSA_TYP_SHIFT 24 /**< Offset of @a typ field */
#define HAB_KEY_ECDSA_SIZ_WIDTH 8 /**< Width of @a siz field */
#define HAB_KEY_ECDSA_SIZ_SHIFT 16 /**< Offset of @a siz field */
#define HAB_KEY_ECDSA_REDBITS_WIDTH 16 /**< Width of @a red_bits field */
#define HAB_KEY_ECDSA_REDBITS_SHIFT 0 /**< Offset of @a red_bits field */
/*@}*/

/*  @} key_ecdsa */
#endif

/*---------------------------------------------------------------------------*/

/** @addtogroup key_pkcs1
 *  @{ 
 */

/** @name Bitfield definitions */
/*@{*/
#define HAB_KEY_PKCS1_FLG_WIDTH 8 /**< Width of @a flg field */
#define HAB_KEY_PKCS1_FLG_SHIFT 0 /**< Offset of @a flg field */
#define HAB_KEY_PKCS1_MODBYTES_WIDTH 16 /**< Width of mod_bytes field */
#define HAB_KEY_PKCS1_MODBYTES_SHIFT 16 /**< Offset of mod_bytes field */
#define HAB_KEY_PKCS1_EXPBYTES_WIDTH 16 /**< Width of exp_bytes field */
#define HAB_KEY_PKCS1_EXPBYTES_SHIFT 0 /**< Offset of exp_bytes field */
/*@}*/

/** @name Binding flag bitfield definitions */
/*@}*/
#define HAB_KEY_BND_FLG_WIDTH 5 /**< Width of binding flags */
#define HAB_KEY_BND_FLG_SHIFT 2 /**< Offset of binding flags */
/*@}*/

/*  @} key_pkcs1 */

/*---------------------------------------------------------------------------*/

/** @addtogroup cmd_wrt_dat
 *  @{
 */

/** @name Parameter bitfield definitions.
 *
 *  Apply to both @ref cmd_wrt_dat and @ref cmd_chk_dat commands. */
/*@{*/
#define HAB_CMD_WRT_DAT_FLAGS_WIDTH 5   /**< @a flags field width */
#define HAB_CMD_WRT_DAT_FLAGS_SHIFT 3   /**< @a flags field offset */
#define HAB_CMD_WRT_DAT_BYTES_WIDTH 3   /**< @a bytes field width */
#define HAB_CMD_WRT_DAT_BYTES_SHIFT 0   /**< @a bytes field offset */
/*@}*/

/*  @} cmd_wrt_dat */

/*---------------------------------------------------------------------------*/

/** @addtogroup bnd_obj
 *  @{
 */

/** @name Binding object IDs 
 * @anchor bnd_ids
 *
 * The ASN.1 object identifiers used to identify HAB binding attributes are
 * defined in the following arc:
 *
@verbatim
      id-fsl  OBJECT IDENTIFIER ::= {
           joint-iso-itu-t(2) country(16) us(840) organization(1) fsl(123456) }
  
      id-habBnd OBJECT IDENTIFIER  ::=  {
           id-fsl hab(32) binding-objects(16) }

      id-habBnd-dat OBJECT IDENTIFIER  ::=  {
           id-habBnd dat(1) }

      id-habBnd-cfg OBJECT IDENTIFIER  ::=  {
           id-habBnd cfg(3) }

      id-habBnd-fid OBJECT IDENTIFIER  ::=  {
           id-habBnd fid(5) }

      id-habBnd-mid OBJECT IDENTIFIER  ::=  {
           id-habBnd mid(6) }

      id-habBnd-cid OBJECT IDENTIFIER  ::=  {
           id-habBnd cid(9) }
@endverbatim
 *
 * The ASN.1 object identifiers used to identify HAB binding attributes are
 * single component extensions of id-habBnd using a component value less than
 * 128 (so that the component can be DER-encoded in a single byte).
 *
 * The DER encoding of an object identifier in this arc is the concatenation
 * of the DER prefix with the single byte identifier for the required binding
 * object. Binding object attribute values are encoded as an ASN.1 SET with
 * a single OCTET STRING member.
 */
/*@{*/

/** DER prefix
 *
 * @todo update description and encoding of binding object identifiers with
 * real fsl value instead of fsl(123456) encoded as 0x87, 0xc4, 0x40, and
 * confirm chosen values for hab(32) and binding-objects(16).
 */
#define HAB_BND_DER_PREFIX \
    {0x06, 0x0a, 0x60, 0x86, 0x48, 0x01, 0x87, 0xc4, 0x40, 0x20, 0x10}
#define HAB_BND_DAT 0x01        /**< Data type (mandatory) */
#define HAB_BND_CFG 0x03        /**< Security configuration */
#define HAB_BND_FID 0x05        /**< Fabrication UID */
#define HAB_BND_MID 0x06        /**< Manufacturing ID */
#define HAB_BND_CID 0x09        /**< Caller ID */
/* Available values: 0a, 0c, 0f, 11, 12, 14, 17, 18, 1b, 1d, 1e, 21, 22, 24,
 * 27, 28, 2b, 2d, 2e, 30, 33, 35, 36, 39, 3a, 3c, 3f, 41, 42, 44, 47, 48, 4b,
 * 4d, 4e, 50, 53, 55, 56, 59, 5a, 5c, 5f, 60, 63, 65, 66, 69, 6a, 6c, 6f, 71,
 * 72, 74, 77, 78, 7b, 7d, 7e
 */
/*@}*/


/** @name Caller IDs
 *
 * Only the ROM caller ID is defined, but other caller IDs may be defined by
 * later boot stages.
 */
/*@{*/
#define HAB_CID_ROM 0   /**< ROM Caller ID */
/*@}*/

/*  @} bnd_obj */

#ifdef HAB_FUTURE
/** @addtogroup sig_fsl
 *  @{
 */

#define HAB_BND_DAT_BYTES 512   /**< Maximum binding data size */

/*  @} sig_fsl */
#endif

/*===========================================================================
                                MACROS
=============================================================================*/
/*
 *    Helper macros
 */
#define HAB_CMD_UNS     0xff

#define DEFAULT_IMG_KEY_IDX     2

#define GEN_MASK(width)                         \
    ((1UL << (width)) - 1)

#define GEN_FIELD(f, width, shift)              \
    (((f) & GEN_MASK(width)) << (shift))

#define PACK_UINT32(a, b, c, d)                          \
    ((uint32_t) ( (((uint32_t)(a) & 0xFF) << 24)          \
                  |(((uint32_t)(b) & 0xFF) << 16)         \
                  |(((uint32_t)(c) & 0xFF) << 8)          \
                  |(((uint32_t)(d) & 0xFF)) ) )

#define EXPAND_UINT32(w)                                                \
    (uint8_t)((w)>>24), (uint8_t)((w)>>16), (uint8_t)((w)>>8), (uint8_t)(w)

#define EXPAND_UINT16(w)                                                \
    (uint8_t)((w)>>8), (uint8_t)(w)

#define HDR(tag, bytes, par)                                            \
    (uint8_t)(tag), (uint8_t)((bytes)>>8), (uint8_t)(bytes), (uint8_t)(par)

#define HAB_VER(maj, min)                                       \
    (GEN_FIELD((maj), HAB_VER_MAJ_WIDTH, HAB_VER_MAJ_SHIFT)     \
     | GEN_FIELD((min), HAB_VER_MIN_WIDTH, HAB_VER_MIN_SHIFT))

#define DCD_DATA(addr, data)    EXPAND_UINT32(addr), EXPAND_UINT32(data)

/*
 *    CSF header
 */

#define CSF_HDR(bytes, HABVER)                  \
    HDR(HAB_TAG_CSF, (bytes), HABVER)
    
    
/*
 *    DCD  header
 */

#define DCD_HDR(bytes, HABVER)                  \
    HDR(HAB_TAG_DCD, (bytes), HABVER)

/*
 *   IVT  header (goes in the struct's hab_hdr_t field, not a byte array)
 */
#define IVT_HDR(bytes, HABVER)                  \
    {HAB_TAG_IVT, {(uint8_t)((bytes)>>8), (uint8_t)(bytes)}, HABVER}

/*
 *    Write Data     
 */

#define WRT_DAT(flags, bytes, address, val_msk)                         \
    HDR(HAB_CMD_WRT_DAT, WRT_DAT_BYTES, WRT_DAT_PAR((flags), (bytes))), \
        EXPAND_UINT32(address),                                         \
        EXPAND_UINT32(val_msk)

#define WRT_DAT_BYTES 12

#define MULTI_WRT_DAT(flags, bytes, address1, val_msk1, address2,       \
                            val_msk2, address3, val_msk3)               \
    HDR(HAB_CMD_WRT_DAT, MULTI_WRT_DAT_BYTES, WRT_DAT_PAR((flags), (bytes))), \
        EXPAND_UINT32(address1),                                        \
        EXPAND_UINT32(val_msk1),                                        \
        EXPAND_UINT32(address2),                                        \
        EXPAND_UINT32(val_msk2),                                        \
        EXPAND_UINT32(address3),                                        \
        EXPAND_UINT32(val_msk3)

#define MULTI_WRT_DAT_BYTES 28

#define WRT_DAT_PAR(flags, bytes)               \
    (GEN_FIELD((flags),                         \
               HAB_CMD_WRT_DAT_FLAGS_WIDTH,     \
               HAB_CMD_WRT_DAT_FLAGS_SHIFT)     \
     | GEN_FIELD((bytes),                       \
                 HAB_CMD_WRT_DAT_BYTES_WIDTH,   \
                 HAB_CMD_WRT_DAT_BYTES_SHIFT))

/*
 *    Check Data (forever)
 */

#define CHK_DAT_FOREVER(flags, bytes, address, mask)                    \
    HDR(HAB_CMD_CHK_DAT, CHK_DAT_FOREVER_BYTES, WRT_DAT_PAR((flags), (bytes))), \
        EXPAND_UINT32(address),                                         \
        EXPAND_UINT32(mask)

#define CHK_DAT_FOREVER_BYTES 12

/*
 *    Check Data (polled)
 */
#define HAB_CMD_CHK_DAT_COUNT 100

#define CHK_DAT(flags, bytes, address, mask, count)                     \
    HDR(HAB_CMD_CHK_DAT, CHK_DAT_BYTES, WRT_DAT_PAR((flags), (bytes))), \
        EXPAND_UINT32(address),                                         \
        EXPAND_UINT32(mask),                                            \
        EXPAND_UINT32(count)

#define CHK_DAT_BYTES 16

/*
 *    Set (generic - used internally only, or to generate invalid commands)
 */

#define SET(bytes, itm, value)                  \
    HDR(HAB_CMD_SET, (bytes), (itm)),           \
        EXPAND_UINT32(value)

/*
 *    Set (MID location)
 */

#define SET_MID(bank, row, bit, fuses)                          \
    HDR(HAB_CMD_SET, SET_MID_BYTES, HAB_VAR_CFG_ITM_MID),       \
        (bank), (row), (bit), (fuses)

#define SET_MID_BYTES 8

/*
 *    Set (default ENG)
 */

#define SET_ENG(alg, eng, cfg)                                  \
    HDR(HAB_CMD_SET, SET_ENG_BYTES, HAB_VAR_CFG_ITM_ENG),       \
        0, (alg), (eng), (cfg)

#define SET_ENG_BYTES 8

/*
 *    Init (engine)
 */

#define INIT(eng)                                               \
    HDR(HAB_CMD_INIT, INIT_BYTES, (eng))

#define INIT_BYTES 4

/*
 *    Unlk (engine)
 */

#define UNLK(eng, ...)                          \
    UNLK_ ## eng(__VA_ARGS__)

#define UNLK_BYTES(eng, ...)                    \
    UNLK_BYTES_ ## eng(__VA_ARGS__)

#define UNLK_HDR(eng, ...)                                      \
    HDR(HAB_CMD_UNLK, UNLK_BYTES_ ## eng(__VA_ARGS__), eng)

#define UNLK_FLG(flg)  \
    0, 0, 0, (uint8_t)(flg)

#define UNLK_FLG_BYTES 4

#define UNLK_HAB_ENG_SRTC(dnc) UNLK_HDR(HAB_ENG_SRTC)
#define UNLK_BYTES_HAB_ENG_SRTC(dnc) HDR_BYTES

#define UNLK_HAB_ENG_SNVS(flg) UNLK_HDR(HAB_ENG_SNVS), UNLK_FLG(flg)
#define UNLK_BYTES_HAB_ENG_SNVS(flg) (HDR_BYTES + UNLK_FLG_BYTES)

#define UNLK_HAB_ENG_CAAM(flg) UNLK_HDR(HAB_ENG_CAAM), UNLK_FLG(flg)
#define UNLK_BYTES_HAB_ENG_CAAM(flg) (HDR_BYTES + UNLK_FLG_BYTES)

/* The next definition uses a GCC extension employing ## to swallow the
 * trailing comma in case the macro is called with only the fixed arguments
 * (i.e. flg here).  This extension appears to work in the GNU compatible mode
 * of RVDS and GHS compilers.
 */
#define UNLK_HAB_ENG_OCOTP(flg, ...)                            \
    UNLK_HDR(HAB_ENG_OCOTP, flg), UNLK_FLG(flg), ## __VA_ARGS__

#define UNLK_BYTES_HAB_ENG_OCOTP(flg, ...)              \
    (HDR_BYTES + UNLK_FLG_BYTES                         \
     + ( ((flg) & (HAB_OCOTP_UNLOCK_FIELD_RETURN        \
                   |HAB_OCOTP_UNLOCK_JTAG               \
                   |HAB_OCOTP_UNLOCK_SCS))              \
         ? STUB_FAB_UID_BYTES                           \
         : 0 ))

#if 0
/* Note: no comma after HDR().  Supplied by _VAL macro if needed */
#define UNLK(eng, val)                               \
    HDR(HAB_CMD_UNLK, UNLK_BYTES_ ## eng, (eng))     \
    UNLK_VAL_ ## eng(val)

#define UNLK_BYTES(eng)                         \
    UNLK_BYTES_ ## eng

#define UNLK_BYTES_HAB_ENG_SRTC HDR_BYTES
#define UNLK_VAL_HAB_ENG_SRTC(val)      /* no val field */
#define UNLK_BYTES_HAB_ENG_SNVS (HDR_BYTES + 4)
#define UNLK_VAL_HAB_ENG_SNVS(val) ,0,0,0,((val)&0xff)
#define UNLK_BYTES_HAB_ENG_CAAM (HDR_BYTES + 4)
#define UNLK_VAL_HAB_ENG_CAAM(val) ,0,0,0,((val)&0xff)
#endif

/*
 *    NOP
 */

#define NOP()                                                           \
    HDR(HAB_CMD_NOP, NOP_BYTES, 0xae) /* third param is ignored */

#define NOP_BYTES 4

/*
 *    Install Key (generic - used internally only)
 */

#define INS_KEY(bytes, flg, pcl, alg, src, tgt, crt)    \
    HDR(HAB_CMD_INS_KEY, (bytes), (flg)),               \
        (pcl), (alg), (src), (tgt),                     \
        EXPAND_UINT32(crt)

#define INS_KEY_BASE_BYTES 12

/*
 *    Install Key (SRK)
 */

#define INS_SRK(flg, alg, src, crt)                     \
    INS_KEY(INS_SRK_BYTES, (flg),                       \
            HAB_PCL_SRK, (alg), (src), HAB_IDX_SRK,     \
            (crt))

#define INS_SRK_BYTES INS_KEY_BASE_BYTES

/*
 *    Install Key (CSFK)
 */

#define INS_CSFK(flg, pcl, crt)                                 \
    INS_KEY(INS_CSFK_BYTES, (flg) | HAB_CMD_INS_KEY_CSF,        \
            (pcl), HAB_ALG_ANY, HAB_IDX_SRK, HAB_IDX_CSFK,      \
            (crt))

#define INS_CSFK_BYTES INS_KEY_BASE_BYTES

/*
 *    Install Key (IMGK - no hash)
 */

#define INS_IMGK(flg, pcl, src, tgt, crt)       \
    INS_KEY(INS_IMGK_BYTES, (flg),              \
            (pcl), HAB_ALG_ANY, (src), (tgt),   \
            (crt))

#define INS_IMGK_BYTES INS_KEY_BASE_BYTES


/*
 *    Install Key (IMGK - with hash). Must be followed by the crt_hsh contents
 *    (e.g. using #include).  The length field depends on using one of the
 *    standard HAB algorithm names, with no adornments like casts or
 *    parentheses.  Note that the length macro cannot be used here: the ##
 *    must appear in the body of this macro to prevent the alg parameter from
 *    being expanded first.
 */

#define INS_IMGK_HASH(flg, pcl, alg, src, tgt, crt)                     \
    INS_KEY(INS_KEY_BASE_BYTES + BYTES_ ## alg, (flg) | HAB_CMD_INS_KEY_HSH, \
            (pcl), (alg), (src), (tgt),                                 \
            (crt))

/*
 * Same as above but the hash length is fixed to the length of SHA1,
 * but the algorithm remains unchanged.
 */
#define INS_IMGK_INV_HASH(flg, pcl, alg, src, tgt, crt)                 \
    INS_KEY(INS_IMGK_HASH_BYTES(HAB_ALG_SHA1), (flg) | HAB_CMD_INS_KEY_HSH, \
            (pcl), (alg), (src), (tgt),                                 \
            (crt))


#define INS_IMGK_HASH_BYTES(alg)                \
    (INS_KEY_BASE_BYTES + BYTES_ ## alg)

#define BYTES_HAB_ALG_SHA1   20
#define BYTES_HAB_ALG_SHA256 32
#define BYTES_HAB_ALG_SHA512 64
/* dummy value for invalid hash alg - same as default hash algorithm */
#define DEFAULT_HASH_ALG_BYTES BYTES_HAB_ALG_SHA256
#define BYTES_HAB_ALG_PKCS1  DEFAULT_HASH_ALG_BYTES

/*
 *    Authenticate Data (generic - used internally only)
 */

#define AUT_DAT(bytes, flg, key, pcl, eng, cfg, sig_start)      \
    HDR(HAB_CMD_AUT_DAT, (bytes), (flg)),                       \
        (key), (pcl), (eng), (cfg),                             \
        EXPAND_UINT32(sig_start)

#define AUT_DAT_BASE_BYTES 12

/*
 *    Authenticate Data (CSF)
 */

#define AUT_CSF(flg, pcl, eng, cfg, sig_start)  \
    AUT_DAT(AUT_CSF_BYTES, (flg),               \
            HAB_IDX_CSFK, (pcl), (eng), (cfg),  \
            (sig_start))

#define AUT_CSF_BYTES AUT_DAT_BASE_BYTES

/*
 *    Authenticate Data (Image)
 */

#define AUT_IMG(blocks, flg, key, pcl, eng, cfg, sig_start)     \
    AUT_DAT(AUT_IMG_BYTES(blocks), (flg),                       \
            (key), (pcl), (eng), (cfg),                         \
            (sig_start))

#define AUT_IMG_BYTES(blocks)                   \
    (AUT_DAT_BASE_BYTES + 8*(blocks))

/** Supported widths of data commands.
 * @ingroup cmd_wrt_dat
 */
typedef enum hab_data_width
{
    HAB_DATA_WIDTH_BYTE = 1,    /**< 8-bit value */
    HAB_DATA_WIDTH_HALF = 2,    /**< 16-bit value */
    HAB_DATA_WIDTH_WORD = 4     /**< 32-bit value */
} hab_data_width_t;
    

/** Flags for Write Data commands.
 * @ingroup cmd_wrt_dat
 */
typedef enum hab_cmd_wrt_dat_flg
{
    HAB_CMD_WRT_DAT_MSK = 1,    /**< Mask/value flag: if set, only specific
                                 * bits may be overwritten at target address
                                 * (otherwise all bits may be overwritten)
                                 */
    HAB_CMD_WRT_DAT_SET = 2     /**< Set/clear flag: if #HAB_CMD_WRT_DAT_MSK
                                 * set, bits at the target address overwritten
                                 * with this flag (otherwise it is ignored)
                                 */
} hab_cmd_wrt_dat_flg_t;

/** Flags for Check Data commands.
 * @ingroup cmd_chk_dat
 */
typedef enum hab_cmd_chk_dat_flg
{
    HAB_CMD_CHK_DAT_SET = 2,    /**< Set/clear flag: bits set in mask must
                                 * match this flag
                                 */
    HAB_CMD_CHK_DAT_ANY = 4     /**< Any/all flag: if clear, all bits set in
                                 * mask must match (otherwise any bit
                                 * suffices)
                                 */
} hab_cmd_chk_dat_flg_t;

/** Flags for Authenticate Data commands.
 * @ingroup cmd_aut_dat
 */
typedef enum hab_cmd_aut_dat_flg
{
    HAB_CMD_AUT_DAT_CLR = 0,    /**< No flags set */
    HAB_CMD_AUT_DAT_ABS = 1     /**< Absolute signature address */
} hab_cmd_aut_dat_flg_t;

/** Flags for Install Key commands.
 * @ingroup cmd_ins_key
 */
typedef enum hab_cmd_ins_key_flg
{
    HAB_CMD_INS_KEY_CLR = 0,    /**< No flags set */
    HAB_CMD_INS_KEY_ABS = 1,    /**< Absolute certificate address */
    HAB_CMD_INS_KEY_CSF = 2,    /**< Install CSF key */
    HAB_CMD_INS_KEY_DAT = 4,    /**< Key binds to Data Type */
    HAB_CMD_INS_KEY_CFG = 8,    /**< Key binds to Configuration */
    HAB_CMD_INS_KEY_FID = 16,   /**< Key binds to Fabrication UID */
    HAB_CMD_INS_KEY_MID = 32,   /**< Key binds to Manufacturing ID */
    HAB_CMD_INS_KEY_CID = 64,   /**< Key binds to Caller ID */
    HAB_CMD_INS_KEY_HSH = 128   /**< Certificate hash present */
} hab_cmd_ins_key_flg_t;

/** Key flags.
 * @ingroup key_pkcs1
 *
 * @ifrom
 *
 * The binding flags given here align with those in #hab_cmd_ins_key_flg
 *
 * @endrom
 *
 */
typedef enum hab_key_flg
{
    /* Two more flag values available */
    HAB_KEY_FLG_DAT = 4,    /**< Key binds to Data Type */
    HAB_KEY_FLG_CFG = 8,    /**< Key binds to Configuration */
    HAB_KEY_FLG_FID = 16,   /**< Key binds to Fabrication UID */
    HAB_KEY_FLG_MID = 32,   /**< Key binds to Manufacturing ID */
    HAB_KEY_FLG_CID = 64,   /**< Key binds to Caller ID */
    HAB_KEY_FLG_CA  = 128   /**< CA key */
} hab_key_flg_t;

/** Secret key flags.
 * @ingroup crt_blob
 */
typedef enum hab_key_secret_flg
{
    /* Seven more flag values available */
    HAB_KEY_FLG_KEK  = 128   /**< KEK */
} hab_key_secret_flg_t;

/** Binding data types
 * @ingroup bnd_obj
 */
typedef enum hab_dat {
    HAB_DAT_CSF = 0x0f,         /**< CSF signature */
    HAB_DAT_IMG = 0x33,         /**< Image signature */
#ifdef HAB_FUTURE
    HAB_DAT_PLG = 0x3c,         /**< Plugin signature */
#endif
    HAB_DAT_MAX
} hab_dat_t;

/* Available values: 55, 5a, 66, 69, 96, 99, a5, aa, c3, cc, f0, ff
 */

/** Target check types
 * @ingroup chk_tgt
 */
typedef enum hab_target {
    HAB_TGT_MEMORY = 0x0f,      /**< Check memory white list */
    HAB_TGT_PERIPHERAL = 0xf0,  /**< Check peripheral white list */
    HAB_TGT_ANY = 0x55,         /**< Check memory & peripheral white list */
    HAB_TGT_MAX
} hab_target_t;

/** Security configuration types
 * @ingroup status
 */
typedef enum hab_config {
/** @cond rom */
    HAB_CFG_FAB = 0x00,         /**< @rom Un-programmed IC */
/** @endcond */
    HAB_CFG_RETURN = 0x33,      /**< Field Return IC */
    HAB_CFG_OPEN = 0xf0,        /**< Non-secure IC */
    HAB_CFG_CLOSED = 0xcc       /**< Secure IC */
} hab_config_t;
/* Available values: 0f, 3c, 55, 5a, 66, 69, 96, 99, a5, aa, ff
 */

/** Security state types
 * @ingroup status
 */
typedef enum hab_state {
    HAB_STATE_INITIAL = 0x33,   /**< Initialising state (transitory) */
    HAB_STATE_CHECK = 0x55,     /**< Check state (non-secure) */
    HAB_STATE_NONSECURE = 0x66, /**< Non-secure state */
    HAB_STATE_TRUSTED = 0x99,   /**< Trusted state */
    HAB_STATE_SECURE = 0xaa,    /**< Secure state */
    HAB_STATE_FAIL_SOFT = 0xcc, /**< Soft fail state */
    HAB_STATE_FAIL_HARD = 0xff, /**< Hard fail state (terminal) */
    HAB_STATE_NONE = 0xf0,      /**< No security state machine */
    HAB_STATE_MAX
} hab_state_t;
/* Available values: 00, 0f, 3c, 5a, 69, 96, a5, c3
 */

/** HAB status types
 * @ingroup status
 */
typedef enum hab_status {
    HAB_STS_ANY = 0x00,         /**< Match any status in
                                 * hab_rvt.report_event()
                                 */
    HAB_FAILURE = 0x33,         /**< Operation failed */
    HAB_WARNING = 0x69,         /**< Operation completed with warning */
    HAB_SUCCESS = 0xf0,         /**< Operation completed successfully */
    HAB_STS_MAX
} hab_status_t;

/** Failure or warning reasons
 * @ingroup evt
 *
 * Values 0x80 ... 0xff are reserved for internal use.
 */
typedef enum hab_reason {
    HAB_RSN_ANY = 0x00,         /**< Match any reason in
                                 * hab_rvt.report_event()
                                 */
    HAB_ENG_FAIL = 0x30,        /**< Engine failure. */
    HAB_INV_ADDRESS = 0x22,     /**< Invalid address: access denied. */
    HAB_INV_ASSERTION = 0x0c,   /**< Invalid assertion. */
    HAB_INV_CALL = 0x28,        /**< Function called out of sequence. */
    HAB_INV_CERTIFICATE = 0x21, /**< Invalid certificate. */
    HAB_INV_COMMAND = 0x06,     /**< Invalid command: command malformed. */
    HAB_INV_CSF = 0x11,         /**< Invalid @ref csf. */
    HAB_INV_DCD = 0x27,         /**< Invalid @ref dcd. */
    HAB_INV_INDEX = 0x0f,       /**< Invalid index: access denied. */
    HAB_INV_IVT = 0x05,         /**< Invalid @ref ivt. */
    HAB_INV_KEY = 0x1d,         /**< Invalid key. */
    HAB_INV_RETURN = 0x1e,      /**< Failed callback function. */
    HAB_INV_SIGNATURE = 0x18,   /**< Invalid signature. */
    HAB_INV_SIZE = 0x17,        /**< Invalid data size. */
    HAB_MEM_FAIL = 0x2e,        /**< Memory failure. */
    HAB_OVR_COUNT = 0x2b,       /**< Expired poll count. */
    HAB_OVR_STORAGE = 0x2d,     /**< Exhausted storage region. */
    HAB_UNS_ALGORITHM = 0x12,   /**< Unsupported algorithm. */
    HAB_UNS_COMMAND = 0x03,     /**< Unsupported command. */
    HAB_UNS_ENGINE = 0x0a,      /**< Unsupported engine. */
    HAB_UNS_ITEM = 0x24,        /**< Unsupported configuration item. */
    HAB_UNS_KEY = 0x1b,         /**< Unsupported key type or parameters. */
    HAB_UNS_PROTOCOL = 0x14,    /**< Unsupported protocol. */
    HAB_UNS_STATE = 0x09,       /**< Unsuitable state. */
    HAB_RSN_MAX
} hab_reason_t;
/* Available values: 33, 35, 36, 39, 3a, 3c, 3f, 41, 42, 44,
 * 47, 48, 4b, 4d, 4e, 50, 53, 55, 56, 59, 5a, 5c, 5f, 60, 63, 65, 66, 69, 6a,
 * 6c, 6f, 71, 72, 74, 77, 78, 7b, 7d, 7e
 */

/** Audit logging contexts.
 * @ingroup evt
 *
 * This list is sorted in order of increasing priority: where two contexts
 * might apply, the latter one is used.
 *
 * Values 0x40 .. 0x5f are reserved for internal use.
 */
typedef enum hab_context {
    HAB_CTX_ANY = 0x00,         /**< Match any context in
                                 * hab_rvt.report_event()
                                 */
/** @cond rom */
    HAB_CTX_FAB = 0xff,         /**< @rom Event logged in hab_fab_test() */
/** @endcond */
    HAB_CTX_ENTRY = 0xe1,       /**< Event logged in hab_rvt.entry() */
    HAB_CTX_TARGET = 0x33,      /**< Event logged in hab_rvt.check_target() */
    HAB_CTX_AUTHENTICATE = 0x0a, /**< Event logged in
                                  *   hab_rvt.authenticate_image() 
                                  */
    HAB_CTX_DCD = 0xdd,         /**< Event logged in hab_rvt.run_dcd() */
    HAB_CTX_CSF = 0xcf,         /**< Event logged in hab_rvt.run_csf() */
    HAB_CTX_COMMAND = 0xc0,     /**< Event logged executing @ref csf or @ref
                                 *   dcd command
                                 */
    HAB_CTX_AUT_DAT = 0xdb,     /**< Authenticated data block */
    HAB_CTX_ASSERT = 0xa0,      /**< Event logged in hab_rvt.assert() */
    HAB_CTX_EXIT = 0xee,        /**< Event logged in hab_rvt.exit() */
    HAB_CTX_MAX
} hab_context_t;

/** Assertion types.
 * @ingroup assert
 */
typedef enum hab_assertion {
    HAB_ASSERT_BLOCK = 0, /**< Assert that a memory block was authenticated */
    HAB_ASSERT_MAX
} hab_assertion_t;

/** RTIC configuration flags 
 * @ingroup rtic
 */
typedef enum hab_rtic_config {
    HAB_RTIC_IN_SWAP8 = 0x01,   /**< Set BYTE SWAP bit (reverse bytes within
                                 *   word on input to RTIC) */
    HAB_RTIC_IN_SWAP16 = 0x02,  /**< Set HALF WORD SWAP bit (reverse
                                 *   half-words within word on input to
                                 *   RTIC)  */
    HAB_RTIC_OUT_SWAP8 = 0x08,  /**< Set HASH RESULT BYTE SWAP bit (reverse
                                 *   bytes within word on output from RTIC) */
    HAB_RTIC_KEEP = 0x80        /**< Retain reference hash value for later
                                 *   monitoring */
} hab_rtic_config_t;

/** SAHARA configuration flags 
 * @ingroup sah
 */
typedef enum hab_sahara_config {
    HAB_SAHARA_IN_SWAP8 = 0x01,   /**< Set MESS BYTE SWAP bit (reverse message
                                   *   bytes within word on input to
                                   *   SAHARA) */
    HAB_SAHARA_IN_SWAP16 = 0x02,  /**< Set MESS HALF WORD SWAP bit (reverse
                                   *   message half-words within word on input
                                   *   to SAHARA)  */
    /* no SWAP32 for SAHARA message - leave 0x04 value unassigned */
    /* no SWAP8 for SAHARA descriptors/links - leave 0x08 value unassigned */
    HAB_SAHARA_DSC_BE8_16 = 0x10, /**< Interpret descriptors and links as for
                                   *   BE-8 16-bit memory. */
    HAB_SAHARA_DSC_BE8_32 = 0x20  /**< Interpret descriptors and links as for
                                   *   BE-8 32-bit memory. */
} hab_sahara_config_t;

/** CAAM configuration flags 
 * @ingroup caam
 */
typedef enum hab_caam_config {
    HAB_CAAM_IN_SWAP8 = 0x01,   /**< Set Message Byte Swap Input bit (reverse
                                 *   message bytes within word on input to
                                 *   CAAM) */
    HAB_CAAM_IN_SWAP16 = 0x02,  /**< Set Message Half Word Swap Input bit
                                 *   (reverse message half-words within word
                                 *   on input to CAAM)  */
    /* no SWAP32 for CAAM message - leave 0x04 value unassigned */
    HAB_CAAM_OUT_SWAP8 = 0x08,   /**< Set Message Byte Swap Output bit
                                  *   (reverse message bytes within word on
                                  *   output from CAAM) */
    HAB_CAAM_OUT_SWAP16 = 0x10,  /**< Set Message Half Word Swap Output bit
                                  *   (reverse message half-words within word
                                  *   on output from CAAM)  */
    /* no SWAP32 for CAAM message - leave 0x20 value unassigned */
    HAB_CAAM_DSC_SWAP8 = 0x40,   /**< Set Control Byte Swap Input/Output bits
                                  *   (reverse descriptor/link bytes within
                                  *   word on input to or output from CAAM) */
    HAB_CAAM_DSC_SWAP16 = 0x80  /**< Set Control Half Word Swap Input/Output
                                  *   bits (reverse descriptor/link half-words
                                  *   within word on input to or output from
                                  *   CAAM) */
} hab_caam_config_t;

/** CAAM unlock flags 
 * @ingroup caam
 */
typedef enum hab_caam_unlock_flag {
    HAB_CAAM_UNLOCK_MID = 0x01,   /**< Leave Job Ring and DECO master ID
                                   *   registers unlocked */
    HAB_CAAM_UNLOCK_RNG = 0x02    /**< Leave RNG state handle 0
                                   *   uninstantiated, do not generate
                                   *   descriptor keys, do not set AES DPA
                                   *   mask, do not block state handle 0 test
                                   *   instantiation */
} hab_caam_unlock_flag_t;

/** SNVS unlock flags 
 * @ingroup snvs
 */
typedef enum hab_snvs_unlock_flag {
    HAB_SNVS_UNLOCK_LP_SWR = 0x01,    /**< Leave LP SW reset unlocked */
    HAB_SNVS_UNLOCK_ZMK_WRITE = 0x02  /**< Leave Zeroisable Master Key write
                                       *   unlocked */
} hab_snvs_unlock_flag_t;

/** SNVS master keys 
 * @ingroup snvs
 *
 * @remark Note that the first two master key selections are completely
 * interchangeable.
 */
typedef enum hab_snvs_keys {
    HAB_SNVS_OTPMK = 0,                 /**< OTP master key */
    HAB_SNVS_OTPMK_ALIAS = 1,           /**< OTP master key (alias) */
    HAB_SNVS_ZMK = 2,                   /**< Zeroisable master key */
    HAB_SNVS_CMK = 3                    /**< Combined master key  */
} hab_snvs_keys_t;


/** OCOTP unlock flags 
 * @ingroup ocotp
 */
typedef enum hab_ocotp_unlock_flag {
    HAB_OCOTP_UNLOCK_FIELD_RETURN = 0x01, /**< Leave Field Return activation
                                           *   unlocked */
    HAB_OCOTP_UNLOCK_SRK_REVOKE = 0x02,   /**< Leave SRK revocation unlocked */
    HAB_OCOTP_UNLOCK_SCS = 0x04,          /**< Leave SCS register unlocked */
    HAB_OCOTP_UNLOCK_JTAG = 0x08          /**< Unlock JTAG using SCS HAB_JDE
                                           *   bit */
} hab_ocotp_unlock_flag_t;

/** DCP configuration flags 
 * @ingroup dcp
 *
 * @warning The byte-swapping controls produce unpredictable results unless
 * the input data block lengths are multiples of 4 bytes.
 */
typedef enum hab_dcp_config {
    HAB_DCP_IN_SWAP8 = 0x01,    /**< Set INPUT BYTE SWAP bit (reverse bytes
                                 *   within words on input to DCP) */
    /* no SWAP16 for DCP - leave 0x02 value unassigned */
    HAB_DCP_IN_SWAP32 = 0x04,   /**< Set INPUT WORD SWAP bit (ignored for
                                 *   hashing)  */
    HAB_DCP_OUT_SWAP8 = 0x08,   /**< Set OUPUT BYTE SWAP bit (reverse bytes
                                 *   within words on output from DCP) */
    /* no SWAP16 for DCP - leave 0x10 value unassigned */
    HAB_DCP_OUT_SWAP32 = 0x20   /**< Set OUTPUT WORD SWAP bit (ignored for
                                 *   hashing)  */
} hab_dcp_config_t;

#ifdef HAB_FUTURE
/** EC key specification types.
 * @ingroup key_ecdsa
 */
typedef enum hab_ec_spec {
    /** Named curve specification. The curve specification is a DER-encoded
     * object identifier.  Supported object identifiers are listed under @ref
     * key_ecdsa_profile "ECDSA key profile".
     */
    HAB_EC_SPEC_NAMED_CURVE = 0x01 
} hab_ec_spec_t;
#endif

/** Variable configuration items
 * @ingroup cmd_set
 */
typedef enum hab_var_cfg_itm {
    HAB_VAR_CFG_ITM_MID = 0x01, /**< Manufacturing ID (MID) fuse locations */
    HAB_VAR_CFG_ITM_ENG = 0x03  /**< Preferred engine for a given algorithm */
} hab_var_cfg_itm_t;

/*===========================================================================
                                ENUMS
=============================================================================*/

/*===========================================================================
                    STRUCTURES AND OTHER TYPEDEFS
=============================================================================*/

/** Header field components
 * @ingroup hdr
 */
typedef struct hab_hdr {
    uint8_t tag;              /**< Tag field */
    uint8_t len[2];           /**< Length field in bytes (big-endian) */
    uint8_t par;              /**< Parameters field */
} hab_hdr_t;

/** Loader callback.
 * @ingroup auth_img
 *
 * @par Purpose
 *
 * This function must be supplied by the library caller if required. It is
 * intended to finalise image loading in those boot modes where only a portion
 * of the image is loaded to a temporary initial location prior to device
 * configuration.
 * 
 * @par Operation 
 *
 * This function is called during hab_rvt.authenticate_image() between running
 * the @ref dcd and @ref csf.  The operation of this function is defined by
 * the caller.
 *
 * @param[in,out] start Initial (possibly partial) image load address on
 * entry.  Final image load address on exit.
 *
 * @param[in,out] bytes Initial (possibly partial) image size on entry.  Final
 * image size on exit.
 *
 * @param[in] boot_data Initial @ref ivt Boot Data load address.
 *
 * @remark The interpretation of the Boot Data is defined by the caller.
 * Different boot components or modes may use different boot data, or even
 * different loader callback functions.
 *
 * @warning It should not be assumed by this function that the Boot Data is
 * valid or authentic.
 *
 * @warning It is the responsibility of the loader callback to check the final
 * image load addresses using hab_rvt.check_target() prior to copying any image
 * data.
 *
 * @pre The (possibly partial) image has been loaded in the initial load
 * address, and the Boot Data is within the initial image.
 *
 * @pre The @ref dcd has been run, if provided.
 *
 * @post The final image load addresses pass hab_rvt.check_target().
 *
 * @retval #HAB_SUCCESS if all operations completed successfully,
 *
 * @retval #HAB_FAILURE otherwise.
 */
typedef hab_status_t (*hab_loader_callback_f)(
    void** start, 
    size_t* bytes, 
    const void* boot_data);

/*---------------------------------------------------------------------------*/

/** Image entry function prototype
 *  @ingroup rvt
 *
 * This typedef serves as the return type for hab_rvt.authenticate_image().  It
 * specifies a void-void function pointer, but can be cast to another function
 * pointer type if required.
 */
typedef void (*hab_image_entry_f)(void);

/*---------------------------------------------------------------------------*/

/** @ref rvt structure
 *  @ingroup rvt
 *
 * @par Format
 *
 * The @ref rvt consists of a @ref hdr followed by a list of addresses as
 * described further below.
 */
struct hab_rvt {

    /** @ref hdr with tag #HAB_TAG_RVT, length and HAB version fields
     *  (see @ref data)
     */
    hab_hdr_t hdr;

    /** Enter and initialise HAB library.
     * @ingroup entry
     *
     * @par Purpose
     *
     * This function initialises the HAB library and @ref shw plugins.  It is
     * intended for use by post-ROM boot stage components, via the @ref rvt,
     * prior to calling any other HAB functions other than
     * hab_rvt.report_event() and hab_rvt.report_status().
     * 
     * @ifrom It is also intended for use by the boot ROM via hab_rvt.entry().
     * @endrom
     * 
     * @par Operation 
     *
     * This function performs the following operations every time it is called:
     *
     * - Initialise the HAB library internal state
     * - Initialise the internal secret key store (cleared at the next
     * hab_rvt.exit())
     * - Run the entry sequence of each available @ref shw plugin
     *
     * When first called from boot ROM, this function also performs the
     * following operations prior to those given above:
     *
     * - Initialise the internal public key store (persists beyond
     * hab_rvt.exit())
     * - Run the self-test sequence of each available @ref shw plugin
     * - If a state machine is present and enabled, change the security state
     * as follows:
     *   - If the IC is configured as #HAB_CFG_OPEN or #HAB_CFG_RETURN, move to
     *   #HAB_STATE_NONSECURE
     *   - If the IC is configured as #HAB_CFG_CLOSED, move to
     *   #HAB_STATE_TRUSTED
     *   - Otherwise, leave the security state unchanged
     *
     * If any failure occurs in the operations above:
     *
     * - An audit event is logged
     * - All remaining operations are abandoned (except that all @ref shw
     * self-test and entry sequences are still executed)
     * - If a state machine is present and enabled, the security state is set
     * as follows:
     *   - @ifrom Unless the IC is configured as #HAB_CFG_FAB,@endrom move to
     *   #HAB_STATE_NONSECURE.  Note that if a security violation has been
     *   detected by the HW, the final state will be #HAB_STATE_FAIL_SOFT or
     *   #HAB_STATE_FAIL_HARD depending on the HW configuration.
     *
     * @warning Boot sequences may comprise several images with each launching
     * the next as well as alternative images should one boot device or boot
     * image be unavailable or unusable.  The authentication of each image in
     * a boot sequence must be bracketed by its own hab_rvt.entry()
     * ... hab_rvt.exit() pair in order to ensure that security state
     * information gathered for one image cannot be misapplied to another
     * image.
     *
     * @ifrom 
     *
     * @warning This applies to each boot path in boot ROM as well, except for
     * the fabrication test path.
     *
     * @endrom
     *
     * @post HAB library internal state is initialised.
     *
     * @post Available @ref shw plugins are initialised.
     *
     * @post If a failure or warning occurs during @ref shw plugin
     * initialisation, an audit event is logged with the relevant @ref eng
     * tag.  The status and reason logged are described in the relevant @ref
     * shw plugin documentation.
     *
     * @post Security state is initialised, if a state machine is present and
     * enabled.
     *
     * @retval #HAB_SUCCESS on an IC not configured as #HAB_CFG_CLOSED,
     * although unsuccessful operations will still generate audit log events,
     *
     * @retval #HAB_SUCCESS on other ICs if all commands completed
     * without failure (even if warnings were generated),
     *
     * @retval #HAB_FAILURE otherwise.
     */
    hab_status_t (*entry)(void);

    /** Finalise and exit HAB library.
     * @ingroup exit
     *
     * @par Purpose
     *
     * This function finalises the HAB library and @ref shw plugins.  It is
     * intended for use by post-ROM boot stage components, via the @ref rvt,
     * after calling other HAB functions and prior to launching the next boot
     * stage or switching to another boot path.
     *
     * @ifrom It is also intended for use by the boot ROM via hab_rvt.exit().
     * @endrom
     * 
     * @par Operation 
     *
     * This function performs the following operations:
     *
     * - Finalise the HAB library internal state
     * - Clear the internal secret key store
     * - Run the finalisation sequence of each available @ref shw plugin
     *
     * If any failure occurs, an audit event is logged and all remaining
     * operations are abandoned (except that all @ref shw exit sequences are
     * still executed).
     *
     * @warning See warnings for hab_rvt.entry().
     *
     * @post #HAB_ASSERT_BLOCK records are cleared from audit log.  Note that
     * other event records are not cleared.
     *
     * @post Any public keys installed by @ref csf commands remain active.
     *
     * @post Any secret keys installed by @ref csf commands are deleted.
     *
     * @post Available @ref shw plugins are in their final state as described
     * in the relevant sections.
     *
     * @post If a failure or warning occurs, an audit event is logged with the
     * @ref eng tag of the @ref shw plugin concerned.  The status and reason
     * logged are described in the relevant @ref shw plugin documentation.
     *
     * @retval #HAB_SUCCESS on an IC not configured as #HAB_CFG_CLOSED,
     * although unsuccessful operations will still generate audit log events,
     *
     * @retval #HAB_SUCCESS on other ICs if all commands completed
     * without failure (even if warnings were generated),
     *
     * @retval #HAB_FAILURE otherwise.
     */
    hab_status_t (*exit)(void);

    /** Check target address
     * @ingroup chk_tgt
     *
     * @par Purpose
     *
     * This function reports whether or not a given target region is allowed
     * for either peripheral configuration or image loading in memory.  It is
     * intended for use by post-ROM boot stage components, via the @ref rvt,
     * in order to avoid configuring security-sensitive peripherals, or
     * loading images over sensitive memory regions or outside recognised
     * memory devices in the address map.
     * 
     * @ifrom It is also available for use by the boot ROM, both directly via
     * hab_rvt.check_target() and indirectly via hab_rvt.authenticate_image(). 
     * @endrom
     *
     * @par Operation 
     *
     * The lists of allowed target regions vary by IC and core, and should be
     * taken from the @ref ref_rug.
     *
     * @ifrom The allowed register sets for peripheral configuration and memory
     * regions for image loading are defined in the @ref hal by
     * #hab_hal_peripheral and #hab_hal_memory respectively. @endrom
     * 
     * @param[in] type Type of target (memory, peripheral or any in which both
     * the memory and peripheral regions are checked)
     *
     * @param[in] start Address of target region
     *
     * @param[in] bytes Size of target region
     *
     * @post if the given target region goes beyond the allowed regions, an
     * audit event is logged with status #HAB_FAILURE and reason
     * #HAB_INV_ADDRESS, together with the call parameters.  See the @ref evt
     * record documentation for details.
     *
     * @post For successful commands, no audit event is logged.
     *
     * @retval #HAB_SUCCESS on an IC not configured as #HAB_CFG_CLOSED,
     * although unsuccessful operations will still generate audit log events,
     *
     * @retval #HAB_SUCCESS if the given target region lies wholly within the
     * allowed regions for the requested type of target.
     *
     * @retval #HAB_FAILURE otherwise
     */
    hab_status_t (*check_target)(hab_target_t type, 
                                 const void* start,
                                 size_t bytes);

    /** Authenticate image.
     * @ingroup auth_img
     *
     * @par Purpose
     *
     * This function combines DCD, CSF and Assert functions in a standard
     * sequence in order to authenticate a loaded image.  It is intended for
     * use by post-ROM boot stage components, via the @ref rvt.  Support for
     * images partially loaded to an initial location is provided via a
     * callback function.
     * 
     * @ifrom It is also available for use by the boot ROM via
     * hab_rvt.authenticate_image(). @endrom
     * 
     * @par Operation 
     *
     * This function performs the following sequence of operations:
     * - Check that the initial image load addresses pass
     * hab_rvt.check_target().
     * - Check that the IVT offset lies within the initial image bounds.
     * - Check that the @ref ivt @a self and @a entry pointers are not NULL
     * - Check the @ref ivt header for consistency and compatability.
     * - If provided in the @ref ivt, calculate the @ref dcd initial location,
     * check that it lies within the initial image bounds, and run the @ref
     * dcd commands.
     * - If provided in the @ref ivt, calculate the Boot Data initial location
     * and check that it lies within the initial image bounds.
     * - If provided in the parameters, invoke the callback function with the
     * initial image bounds and initial location of the @ref ivt Boot Data.
     * 
     * From this point on, the full image is assumed to be in its final
     * location. The following operations will be performed on all IC 
     * configurations (#hab_config), but will be only enforced on an IC 
     * configured as #HAB_CFG_CLOSED:
     * - Check that the final image load addresses pass hab_rvt.check_target().
     * - Check that the CSF lies within the image bounds, and run the CSF
     * commands.
     * - Check that all of the following data have been authenticated (using
     * their final locations):
     *   - IVT;
     *   - DCD (if provided);
     *   - Boot Data (initial byte if provided);
     *   - Entry point (initial word).
     *
     * @param[in] cid Caller ID, used to identify which SW issued this call.
     *
     * @param[in] ivt_offset Offset in bytes of the IVT from the image start
     * address.
     *
     * @param[in,out] start Initial (possibly partial) image load address on
     * entry.  Final image load address on exit.
     *
     * @param[in,out] bytes Initial (possibly partial) image size on entry.
     * Final image size on exit.
     *
     * @param[in] loader Callback function to load the full image to its final
     * load address.  Set to NULL if not required.
     *
     * @remark Caller ID may be bound to signatures verified using keys
     * installed with #HAB_CMD_INS_KEY_CID flag. See @ref cmd_ins_key and @ref
     * bnd_obj for details.
     *
     * @remark A @a loader callback function may be supplied even if the image
     * is already loaded to its final location on entry.
     *
     * @remark Boot Data (boot_data in @ref ivt) will be ignored if the 
     * @a loader callback function point is set to Null.
     *
     * @warning The @a loader callback function should lie within existing
     * authenticated areas. @ifrom Or within the ROM. @endrom
     *
     * @warning It is the responsibility of the caller to check the initial
     * image load addresses using hab_rvt.check_target() prior to loading the
     * initial image and calling this function.
     *
     * @warning After completion of hab_rvt.authenticate_image(), the caller
     * should test using hab_rvt.assert() that the Boot Data was
     * authenticated.
     *
     * @post The post-conditions of the functions hab_rvt.check_target(),
     * hab_rvt.run_dcd(), hab_rvt.run_csf() and hab_rvt.assert() apply also to
     * this function.  In particular, any audit events logged within the given
     * functions have the context field appropriate to that function rather
     * than #HAB_CTX_AUTHENTICATE.  In addition, the side-effects and
     * post-conditions of any callback function supplied apply.
     *
     * @post If a failure or warning occurs outside these contexts, an audit
     * event is logged with status:
     *   - #HAB_FAILURE, with further reasons:
     *     - #HAB_INV_ADDRESS: initial or final image addresses outside allowed
     *     regions
     *     - #HAB_INV_ADDRESS: IVT, DCD, Boot Data or CSF outside image bounds
     *     - #HAB_INV_ADDRESS: IVT @a self or @a entry pointer is NULL 
     *     - #HAB_INV_CALL: hab_rvt.entry() not run successfully prior to call
     *     - #HAB_INV_IVT: IVT malformed
     *     - #HAB_INV_IVT: IVT version number is less than HAB library version
     *     - #HAB_INV_RETURN: Callback function failed
     *
     * @retval entry field from @ref ivt on an IC not configured as
     * #HAB_CFG_CLOSED provided that the following conditions are met
     * (other unsuccessful operations will generate audit log events):
     *  - the @a start pointer and the pointer it locates are not NULL
     *  - the initial @ref ivt location is not NULL
     *  - the @ref ivt @ref hdr (given in the @a hdr field) is valid
     *  - the final @ref ivt location (given by the @a self field) is not NULL 
     *  - any loader callback completed successfully,
     *
     * @retval entry field from @ref ivt on other ICs if all operations
     * completed without failure (even if warnings were generated),
     *
     * @retval NULL otherwise.
     */
    hab_image_entry_f (*authenticate_image)(uint8_t cid,
                                            ptrdiff_t ivt_offset, 
                                            void** start, 
                                            size_t* bytes, 
                                            hab_loader_callback_f loader);

    /** Execute a boot configuration script.
     * @ingroup run_dcd
     *
     * @par Purpose
     *
     * This function configures the IC based upon a @ref dcd table.  It is
     * intended for use by post-ROM boot stage components, via the @ref rvt.
     * This function may be invoked as often as required for each boot stage.
     *
     * @ifrom It is also intended for use by the boot ROM, both directly via
     * hab_rvt.run_dcd() and indirectly via hab_rvt.authenticate_image().
     * @endrom
     * 
     * The difference between the configuration functionality in this function
     * and hab_rvt.run_csf() arises because the @ref dcd table is not
     * authenticated prior to running the commands.  Hence, there is a more
     * limited range of commands allowed, and a limited range of parameters to
     * allowed commands.
     * 
     * @par Operation 
     *
     * This function performs the following operations:
     * - Checks the @ref hdr for compatibility and consistency
     * - Makes an internal copy of the @ref dcd table
     * - Executes the commands in sequence from the internal copy of the @ref
     * dcd
     *
     * If any failure occurs, an audit event is logged and all remaining
     * operations are abandoned.
     *
     * @param[in] dcd   Address of the @ref dcd.
     *
     * @warning It is the responsibility of the caller to ensure that the @a
     * dcd parameter points to a valid memory location.
     *
     * @warning The @ref dcd must be authenticated by a subsequent @ref csf
     * command prior to launching the next boot image, in order to avoid
     * unauthorised configurations which may subvert secure operation.
     * Although the content of the next boot stage's CSF may be out of scope
     * for the hab_rvt.run_dcd() caller, it is possible to enforce this
     * constraint by using hab_rvt.assert() to ensure that both the DCD and
     * any pointers used to locate it have been authenticated.
     *
     * @warning Each invocation of hab_rvt.run_dcd() must occur between a pair
     * of hab_rvt.entry() and hab_rvt.exit() calls, although multiple
     * hab_rvt.run_dcd() calls (and other HAB calls) may be made in one
     * bracket.  This constraint applies whether hab_rvt.run_dcd() is
     * successful or not: a subsequent call to hab_rvt.exit() is required
     * prior to launching the authenticated image or switching to another boot
     * target.
     *
     * @post Many commands may cause side-effects. See the @ref dcd
     * documentation.
     *
     * @post If a failure or warning occurs within a command handler, an audit
     * event is logged with the offending command, copied from the DCD.  The
     * status and reason logged are described in the relevant command
     * documentation.
     *
     * @post For other failures or warning, the status logged is:
     *   - #HAB_WARNING, with further reasons:
     *     - #HAB_UNS_COMMAND: unsupported command encountered, where DCD
     *     version and HAB library version differ
     *   - #HAB_FAILURE, with further reasons:
     *     - #HAB_INV_ADDRESS: NULL @a dcd parameter
     *     - #HAB_INV_CALL: hab_rvt.entry() not run successfully prior to call
     *     - #HAB_INV_COMMAND: command not allowed in DCD
     *     - #HAB_UNS_COMMAND: unrecognised command encountered, where DCD
     *     version and HAB library version match
     *     - #HAB_INV_DCD: DCD malformed or too large
     *     - #HAB_INV_DCD: DCD version number is less than HAB library version
     * @retval #HAB_SUCCESS on an IC not configured as #HAB_CFG_CLOSED,
     * although unsuccessful operations will still generate audit log events,
     *
     * @retval #HAB_SUCCESS on other ICs if all commands completed
     * without failure (even if warnings were generated),
     *
     * @retval #HAB_FAILURE otherwise.
     */
    hab_status_t (*run_dcd)(const uint8_t* dcd);

    /** Execute an authentication script.
     * @ingroup run_csf
     *
     * @par Purpose
     *
     * This function authenticates SW images and configures the IC based upon
     * a @ref csf.  It is intended for use by post-ROM boot stage components,
     * via the @ref rvt.  This function may be invoked as often as required
     * for each boot stage.
     * 
     * @ifrom It is also available for use by the boot ROM via hab_rvt.run_csf,
     * although it is anticipated that the boot ROM will mostly call this
     * function indirectly via hab_rvt.authenticate_image(). @endrom
     *
     * @par Operation 
     *
     * This function performs the following operations:
     * - Checks the @ref hdr for compatibility and consistency
     * - Makes an internal copy of the @ref csf
     * - Executes the commands in sequence from the internal copy of the @ref
     * csf
     *
     * The internal copy of the @ref csf is authenticated by an explicit
     * command in the sequence.  Prior to authentication, a limited set of
     * commands is available to:
     * - Install a Super-Root key (unless previously installed)
     * - Install a CSF key (unless previously installed)
     * - Specify any variable configuration items
     * - Authenticate the CSF
     *
     * Subsequent to CSF authentication, the full set of commands is available.
     *
     * If any failure occurs, an audit event is logged and all remaining
     * operations are abandoned.
     *
     * @param[in] csf   Address of the @ref csf.
     *
     * @param[in] cid Caller ID, used to identify which SW issued this call.
     *
     * @remark Caller ID may be bound to signatures verified using keys
     * installed with #HAB_CMD_INS_KEY_CID flag. See @ref cmd_ins_key and @ref
     * bnd_obj for details.
     *
     * @warning It is the responsibility of the caller to ensure that the @a
     * csf parameter points to a valid memory location.
     *
     * @warning Each invocation of hab_rvt.run_csf() must occur between a pair
     * of hab_rvt.entry() and hab_rvt.exit() calls, although multiple
     * hab_rvt.run_csf() calls (and other HAB calls) may be made in one
     * bracket.  This constraint applies whether hab_rvt.run_csf() is
     * successful or not: a subsequent call to hab_rvt.exit() is required
     * prior to launching the authenticated image or switching to another boot
     * target.
     *
     * @post Many commands may cause side-effects. See the @ref csf
     * documentation.  In particular, note that keys installed by the @ref csf
     * remain available for use in subsequent operations.
     *
     * @post If a failure or warning occurs within a command handler, an audit
     * event is logged with the offending command, copied from the CSF.  The
     * status and reason logged are described in the relevant command
     * documentation.
     *
     * @post For other failures or warning, the status logged is:
     *   - #HAB_WARNING, with further reasons:
     *     - #HAB_UNS_COMMAND: unsupported command encountered, where CSF
     *     version and HAB library version differ
     *   - #HAB_FAILURE, with further reasons:
     *     - #HAB_INV_ADDRESS: NULL @a csf parameter
     *     - #HAB_INV_CALL: hab_rvt.entry() not run successfully prior to call
     *     - #HAB_INV_COMMAND: command not allowed prior to CSF authentication
     *     - #HAB_UNS_COMMAND: unrecognised command encountered, where CSF
     *     version and HAB library version match
     *     - #HAB_INV_CSF: CSF not authenticated
     *     - #HAB_INV_CSF: CSF malformed or too large
     *     - #HAB_INV_CSF: CSF version number is less than HAB library version
     *
     * @retval #HAB_SUCCESS on an IC not configured as #HAB_CFG_CLOSED,
     * although unsuccessful operations will still generate audit log events,
     *
     * @retval #HAB_SUCCESS on other ICs if all commands completed
     * without failure (even if warnings were generated),
     *
     * @retval #HAB_FAILURE otherwise.
     */
    hab_status_t (*run_csf)(const uint8_t* csf, 
                            uint8_t cid);

    /** Test an assertion against the audit log.
     * @ingroup assert
     *
     * @par Purpose
     *
     * This function allows the audit log to be interrogated.  It is intended
     * for use by post-ROM boot stage components, via the @ref rvt, to
     * determine the state of authentication operations.  This function may be
     * invoked as often as required for each boot stage.
     *
     * @ifrom It is also available for use by the boot ROM, both directly via
     * hab_rvt.assert() and indirectly via hab_rvt.authenticate_image().
     * @endrom
     *
     * @par Operation 
     *
     * This function checks the required assertion as detailed below.
     *
     * @param[in] type Assertion type.
     *
     * @param[in] data Assertion data.
     *
     * @param[in] count Data size or count.
     *
     * @par Memory block authentication:
     * For #HAB_ASSERT_BLOCK assertion type, hab_rvt.assert() checks that the
     * given memory block has been authenticated after running a CSF. The
     * parameters are interpreted as follows:
     *
     * @par
     * - @a data: memory block starting address
     * - @a count: memory block size (in bytes)
     *
     * @par 
     *
     * A simple interpretation of "memory block has been authenticated" is
     * taken, such that the given block must lie wholly within a single
     * contiguous block authenticated while running a CSF.  A given memory
     * block covered by the union of several neighboring or overlapping
     * authenticated blocks could fail the test with this interpretation, but
     * it is assumed that such cases will not arise in practice.
     *
     * @post If the assertion fails, an audit event is logged with status
     * #HAB_FAILURE and reason #HAB_INV_ASSERTION, together with the call
     * parameters.  See the @ref evt record documentation for details.
     *
     * @post For successful commands, no audit event is logged.
     *
     * @retval #HAB_SUCCESS on an IC not configured as #HAB_CFG_CLOSED,
     * although unsuccessful operations will still generate audit log events,
     *
     * @retval #HAB_SUCCESS on other ICs if the assertion is confirmed
     *
     * @retval #HAB_FAILURE otherwise
     */
    hab_status_t (*assert)(hab_assertion_t type, 
                           const void* data, 
                           uint32_t count);

    /** Report an event from the audit log.
     * @ingroup event
     *
     * @par Purpose
     *
     * This function allows the audit log to be interrogated.  It is intended
     * for use by post-ROM boot stage components, via the @ref rvt, to
     * determine the state of authentication operations.  This function may
     * be called outside an hab_rvt.entry() / hab_rvt.exit() pair.
     * 
     * @ifrom It is also available for use by the boot ROM, where it may be
     * used to report boot failures as part of a tethered boot
     * protocol. @endrom
     *
     * @par Operation 
     *
     * This function performs the following operations:
     * - Scans the audit log for a matching event
     * - Copies the required details to the output parameters (if found)
     *
     * @param[in] status Status level of required event.
     *
     * @param[in] index Index of required event at given status level.
     *
     * @param[out] event @ref evt record.
     *
     * @param[in,out] bytes Size of @a event buffer on entry, size of event
     * record on exit.
     *
     * @remark Use @a status = #HAB_STS_ANY to match any logged event,
     * regardless of the status value logged.
     *
     * @remark Use @a index = 0 to return the first matching event, @a index =
     * 1 to return the second matching event, and so on.
     *
     * @remark The data logged with each event is context-dependent.  Refer to
     * @ref evt record documentation.
     *
     * @warning Parameter @a bytes may not be NULL.
     *
     * @warning If the @a event buffer is a NULL pointer or too small to fit
     * the event record, the required size is written to @a bytes, but no 
     * part of the event record is copied to the output buffer.
     *
     * @retval #HAB_SUCCESS if the required event is found, and the event
     * record is copied to the output buffer.
     * 
     * @retval #HAB_SUCCESS if the required event is found and @a event buffer 
     * passed is a NULL pointer.
     *
     * @retval #HAB_FAILURE otherwise
     */
    hab_status_t (*report_event)(hab_status_t status,
                                 uint32_t index,
                                 uint8_t* event,
                                 size_t* bytes);

    /** Report security status.
     * @ingroup status
     *
     * @par Purpose
     *
     * This function reports the security configuration and state of the IC as
     * well as searching the audit log to determine the status of the boot
     * process.  It is intended for use by post-ROM boot stage components, via
     * the @ref rvt.  This function may be called outside an
     * hab_rvt.entry() / hab_rvt.exit() pair.
     * 
     * @ifrom It is also available for use by the boot ROM, and should be used
     * rather than the HAL function hab_hal_read_sec_cfg(). @endrom
     *
     * @par Operation 
     *
     * This function reads the fuses which indicate the security
     * configuration.  The fusemap varies by IC, and should be taken from the
     * @ref ref_rug.  It also uses the @ref shw state machine, if present and
     * enabled, to report on the security state.
     *
     * @param[out] config Security configuration, NULL if not required
     *
     * @param[out] state Security state, NULL if not required
     *
     * @remark If no @ref shw state machine is present and enabled, the state
     * #HAB_STATE_NONE will be output.
     *
     * @retval #HAB_SUCCESS if no warning or failure audit events have been
     * logged.
     *
     * @retval #HAB_WARNING otherwise, if only warning events have been logged.
     *
     * @retval #HAB_FAILURE otherwise
     */
    hab_status_t (*report_status)(hab_config_t* config, hab_state_t* state);

    /** Enter failsafe boot mode.
     * @ingroup safe
     *
     * @par Purpose
     *
     * This function provides a safe path when image authentication has failed
     * and all possible boot paths have been exhausted.  It is intended for
     * use by post-ROM boot stage components, via the @ref rvt.
     * 
     * @ifrom It is also available for use by the boot ROM via
     * hab_rvt.failsafe(). @endrom
     *
     * @par Operation 
     *
     * The precise details of this function vary by IC and core, and should be
     * taken from @ref ref_rug.
     *
     * @warning This function does not return.
     *
     * @remark Since this function does not return, it implicitly performs the
     * functionality of hab_rvt.exit() in order to ensure an appropriate
     * configuration of the @ref shw plugins.
     *
     * @remark Two typical implementations are:
     * - a low-level provisioning protocol in which an image is downloaded to
     * RAM from an external host, authenticated and launched.  The downloaded
     * image may communicate with tools on the external host to report the
     * reasons for boot failure, and may re-provision the end-product with
     * authentic boot images.
     * - a failsafe boot mode which does not allow execution to leave the ROM
     * until the IC is reset.
     */
    void (*failsafe)(void);
};

/** @ref rvt type
 * @ingroup rvt
 */
typedef struct hab_rvt hab_rvt_t;

/*---------------------------------------------------------------------------*/

/** @ref ivt structure
 * @ingroup ivt
 *
 * @par Format
 *
 * An @ref ivt consists of a @ref hdr followed by a list of addresses as
 * described further below.
 *
 * @warning The @a entry address may not be NULL.
 *
 * @warning On an IC not configured as #HAB_CFG_CLOSED, the
 * @a csf address may be NULL.  If it is not NULL, the @ref csf will be
 * processed, but any failures should be non-fatal.
 *
 * @warning On an IC configured as #HAB_CFG_CLOSED, the @a
 * csf address may not be NULL, and @ref csf failures are typically fatal.
 *
 * @remark The Boot Data located using the @a boot_data field is interpreted
 * by the HAB caller in a boot-mode specific manner.  This may be used by the
 * boot ROM as to determine the load address and boot device configuration for
 * images loaded from block devices (see @ref ref_rug for details).
 *
 * @remark All addresses given in the IVT, including the Boot Data (if
 * present) are those for the final load location. 
 *
 * @anchor ila
 *
 * @par Initial load addresses
 *
 * The @a self field is used to calculate addresses in boot modes where an
 * initial portion of the image is loaded to an initial location.  In such
 * cases, the IVT, Boot Data (if present) and DCD (if present) are used in
 * configuring the IC and loading the full image to its final location.  Only
 * the IVT, Boot Data (if present) and DCD (if present) are required to be
 * within the initial image portion.
 *
 * The method for calculating an initial load address for the DCD is
 * illustrated in the following C fragment.  Similar calculations apply to
 * other fields.
 *
@verbatim
        hab_ivt_t* ivt_initial = <initial IVT load address>;
        const void* dcd_initial = ivt_initial->dcd;
        if (ivt_initial->dcd != NULL)
            dcd_initial = (const uint8_t*)ivt_initial 
                          + (ivt_initial->dcd - ivt_initial->self)
@endverbatim
 */
struct hab_ivt {
    /** @ref hdr with tag #HAB_TAG_IVT, length and HAB version fields
     *  (see @ref data)
     */
    hab_hdr_t hdr;
    /** Absolute address of the first instruction to execute from the
     *  image
     */
    hab_image_entry_f entry;
    /** Reserved in this version of HAB: should be NULL. */
    const void* reserved1;
    /** Absolute address of the image DCD: may be NULL. */
    const void* dcd;
    /** Absolute address of the Boot Data: may be NULL, but not interpreted
     *  any further by HAB
     */
    const void* boot_data;
    /** Absolute address of the IVT.*/
    const void* self;
    /** Absolute address of the image CSF.*/
    const void* csf;
    /** Reserved in this version of HAB: should be zero. */
    uint32_t reserved2;
};

/** @ref ivt type
 * @ingroup ivt
 */
typedef struct hab_ivt hab_ivt_t;

/*===========================================================================
                         FUNCTION PROTOTYPES
=============================================================================*/
#ifdef __cplusplus
extern "C" {
#endif

#ifdef __cplusplus
}
#endif

#endif /* HAB_DEFINES_H */