From 806492e271720726ed7a61f8b8c0353b66d147c1 Mon Sep 17 00:00:00 2001 From: Wang_Weigen Date: Wed, 11 Jan 2023 14:32:41 +0800 Subject: [PATCH] =?UTF-8?q?1=E3=80=81modify=20the=20'link.lds'=20file=20ac?= =?UTF-8?q?croding=20to=20sdk;2=E3=80=81add=20irq=20enable=20and=20disable?= =?UTF-8?q?=20function?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Ubiquitous/XiZi_AIoT/.config | 18 + .../XiZi_AIoT/hardkernel/abstraction/isr.h | 2 +- .../arm/armv7-a/cortex-a9/arch_interrupt.h | 8 + .../arch/arm/armv7-a/cortex-a9/boot.S | 35 +- .../arch/arm/armv7-a/cortex-a9/exception.S | 2 +- .../arch/arm/armv7-a/cortex-a9/interrupt.c | 29 +- .../services/boards/imx6q-sabrelite/Makefile | 2 +- .../services/boards/imx6q-sabrelite/config.mk | 2 +- .../boards/imx6q-sabrelite/hab_defines.h | 2222 +++++++++++++++++ .../imx6q-sabrelite/include/hab_defines.h | 2222 +++++++++++++++++ .../services/boards/imx6q-sabrelite/ivt.c | 82 + .../services/boards/imx6q-sabrelite/link.lds | 98 +- 12 files changed, 4684 insertions(+), 38 deletions(-) create mode 100644 Ubiquitous/XiZi_AIoT/.config create mode 100755 Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/hab_defines.h create mode 100755 Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/include/hab_defines.h create mode 100755 Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/ivt.c diff --git a/Ubiquitous/XiZi_AIoT/.config b/Ubiquitous/XiZi_AIoT/.config new file mode 100644 index 000000000..307c2f4c0 --- /dev/null +++ b/Ubiquitous/XiZi_AIoT/.config @@ -0,0 +1,18 @@ +# +# Automatically generated file; DO NOT EDIT. +# XiZi_AIoT Project Configuration +# +CONFIG_BOARD_IMX6Q_SABRELITE_EVB=y +CONFIG_ARCH_ARM=y + +# +# imx6q sabrelite feature +# + +# +# Lib +# +CONFIG_LIB=y +CONFIG_LIB_POSIX=y +CONFIG_LIB_NEWLIB=y +# CONFIG_LIB_MUSLLIB is not set diff --git a/Ubiquitous/XiZi_AIoT/hardkernel/abstraction/isr.h b/Ubiquitous/XiZi_AIoT/hardkernel/abstraction/isr.h index edd939952..584e9b578 100644 --- a/Ubiquitous/XiZi_AIoT/hardkernel/abstraction/isr.h +++ b/Ubiquitous/XiZi_AIoT/hardkernel/abstraction/isr.h @@ -81,7 +81,7 @@ struct InterruptServiceRoutines { extern struct InterruptServiceRoutines isrManager ; -unsigned long DisableLocalInterrupt(); +uint32_t DisableLocalInterrupt(); void EnableLocalInterrupt(unsigned long level); #define DISABLE_INTERRUPT DisableLocalInterrupt diff --git a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/arch_interrupt.h b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/arch_interrupt.h index 95233993c..b26d3e80c 100644 --- a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/arch_interrupt.h +++ b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/arch_interrupt.h @@ -22,6 +22,14 @@ int32_t ArchEnableHwIrq(uint32_t irq_num); int32_t ArchDisableHwIrq(uint32_t irq_num); +//! @brief +typedef enum { + CPU_0, + CPU_1, + CPU_2, + CPU_3, +} cpuid_e; + struct ExceptionStackRegister { uint32_t r0; diff --git a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/boot.S b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/boot.S index a10b5ef7a..49d0d456f 100644 --- a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/boot.S +++ b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/boot.S @@ -1,18 +1,8 @@ - -@ .equ Mode_USR, 0x10 -@ .equ Mode_FIQ, 0x11 -@ .equ Mode_IRQ, 0x12 -@ .equ Mode_SVC, 0x13 -@ .equ Mode_ABT, 0x17 -@ .equ Mode_UND, 0x1B -@ .equ Mode_SYS, 0x1F #include -@ .equ I_BIT, 0x80 @ when I bit is set, IRQ is disabled -@ .equ F_BIT, 0x40 @ when F bit is set, FIQ is disabled - -.equ STACK_SIZE, 0x00000100 +.global ExceptionVectors +.section ".startup","ax" .globl _reset _reset: @@ -30,7 +20,6 @@ _reset: bic r0, #(1 << 0) /* mmu */ mcr p15, 0, r0, c1, c0, 0 - ldr r0, =stack_top @ Set the startup stack for svc @@ -39,26 +28,38 @@ _reset: @ Enter Undefined Instruction Mode and set its Stack Pointer msr cpsr_c, #MODE_UND|I_BIT|F_BIT mov sp, r0 - sub r0, r0, #STACK_SIZE + sub r0, r0, #EXCEPTION_STACK_SIZE @ Enter Abort Mode and set its Stack Pointer msr cpsr_c, #MODE_ABT|I_BIT|F_BIT mov sp, r0 - sub r0, r0, #STACK_SIZE + sub r0, r0, #EXCEPTION_STACK_SIZE @ Enter FIQ Mode and set its Stack Pointer msr cpsr_c, #MODE_FIQ|I_BIT|F_BIT mov sp, r0 - sub r0, r0, #STACK_SIZE + sub r0, r0, #EXCEPTION_STACK_SIZE @ Enter IRQ Mode and set its Stack Pointer msr cpsr_c, #MODE_IRQ|I_BIT|F_BIT mov sp, r0 - sub r0, r0, #STACK_SIZE + sub r0, r0, #EXCEPTION_STACK_SIZE /* come back to SVC mode */ msr cpsr_c, #MODE_SVC|I_BIT|F_BIT + /* + * copy the vector table into the RAM vectors + * this assumes that the RAM vectors size is divisible by 3 words (12 bytes) + */ + ldr r1,=__ram_vectors_start + ldr r2,=__ram_vectors_end + ldr r3,=ExceptionVectors +1: cmp r1,r2 + ldmlt r3!,{r4,r5,r6} + stmlt r1!,{r4,r5,r6} + blt 1b + /* clear .bss */ mov r0, #0 /* get a zero */ ldr r1,=__bss_start /* bss start */ diff --git a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/exception.S b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/exception.S index e8ee24286..bc9a68213 100644 --- a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/exception.S +++ b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/exception.S @@ -1,6 +1,6 @@ #include -.section .vectors, "ax" +.section .text.vectors, "ax" .code 32 .globl ExceptionVectors diff --git a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/interrupt.c b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/interrupt.c index 635857aa8..3105805d1 100755 --- a/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/interrupt.c +++ b/Ubiquitous/XiZi_AIoT/hardkernel/arch/arm/armv7-a/cortex-a9/interrupt.c @@ -3,24 +3,43 @@ #include #include -unsigned long __attribute__((naked)) DisableLocalInterrupt() +uint32_t DisableLocalInterrupt(void) { - + uint32_t intSave; + __asm__ __volatile__( + "mrs %0, cpsr \n" + "cpsid if " + : "=r"(intSave) + : + : "memory"); + return intSave; } -void __attribute__((naked)) EnableLocalInterrupt(unsigned long level) +void EnableLocalInterrupt(unsigned long level) { - + uint32_t intSave; + __asm__ __volatile__( + "mrs %0, cpsr \n" + "cpsie if " + : "=r"(intSave) + : + : "memory"); + return; } int32_t ArchEnableHwIrq(uint32_t irq_num) { - + // gic_set_irq_priority(irq_num, priority); + gic_set_irq_security(irq_num, false); // set IRQ as non-secure + // gic_set_cpu_target(irq_num, CPU_0, true); + gic_enable_irq(irq_num, true); return 0; } int32_t ArchDisableHwIrq(uint32_t irq_num) { + gic_enable_irq(irq_num, false); + // gic_set_cpu_target(irq_num, CPU_0, false); return 0; } diff --git a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/Makefile b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/Makefile index 683e42a90..e929933ca 100644 --- a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/Makefile +++ b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/Makefile @@ -1,4 +1,4 @@ -SRC_FILES := board.c +SRC_FILES := board.c ivt.c SRC_DIR := third_party_driver diff --git a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/config.mk b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/config.mk index ee27915c9..d36fb19fe 100644 --- a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/config.mk +++ b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/config.mk @@ -15,7 +15,7 @@ endif # export LINK_LWIP := $(KERNEL_ROOT)/resources/ethernet/LwIP/liblwip.a # endif -export DEFINES := -DHAVE_CCONFIG_H -DSTM32F407xx -DUSE_HAL_DRIVER -DHAVE_SIGINFO +export DEFINES := -DHAVE_CCONFIG_H export USING_NEWLIB =1 export USING_VFS = 1 diff --git a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/hab_defines.h b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/hab_defines.h new file mode 100755 index 000000000..1fcf5d544 --- /dev/null +++ b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/hab_defines.h @@ -0,0 +1,2222 @@ +/* + * 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 /* for integer types */ +#include /* for bool type */ +#include /* 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 = ; + 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 */ diff --git a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/include/hab_defines.h b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/include/hab_defines.h new file mode 100755 index 000000000..1fcf5d544 --- /dev/null +++ b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/include/hab_defines.h @@ -0,0 +1,2222 @@ +/* + * 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 /* for integer types */ +#include /* for bool type */ +#include /* 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 = ; + 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 */ diff --git a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/ivt.c b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/ivt.c new file mode 100755 index 000000000..e49b865c9 --- /dev/null +++ b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/ivt.c @@ -0,0 +1,82 @@ +/* + * Copyright (c) 2010-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. + */ + +#include + +extern unsigned * _start_image_add; +extern unsigned * __start_boot_data; +extern unsigned * _image_size; + +extern unsigned * __hab_data; + +extern uint8_t input_dcd_hdr[]; + +extern void _reset(void); + +struct hab_ivt input_ivt __attribute__ ((section (".ivt"))) ={ + /** @ref hdr word with tag #HAB_TAG_IVT, length and HAB version fields + * (see @ref data) + */ + IVT_HDR(sizeof(struct hab_ivt), HAB_VER(4, 0)), + /** Absolute address of the first instruction to execute from the + * image + */ + (hab_image_entry_f)_reset, + + /** Reserved in this version of HAB: should be NULL. */ + NULL, + /** Absolute address of the image DCD: may be NULL. */ + &input_dcd_hdr, + /** Absolute address of the Boot Data: may be NULL, but not interpreted + * any further by HAB + */ + &__start_boot_data, + /** Absolute address of the IVT.*/ + (const void*) (&input_ivt), + + /** Absolute address of the image CSF.*/ + (const void*) &__hab_data, + + /** Reserved in this version of HAB: should be zero. */ + 0 +}; + +typedef struct { + uint32_t start; /**< Start address of the image */ + uint32_t size; /**< Size of the image */ + uint32_t plugin; /**< Plugin flag */ +} boot_data_t; + +boot_data_t bd __attribute__ ((section (".boot_data"))) ={ + (uint32_t) &_start_image_add, + (uint32_t) &_image_size, + 0, +}; + diff --git a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/link.lds b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/link.lds index d6e856d1a..67abbe98d 100644 --- a/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/link.lds +++ b/Ubiquitous/XiZi_AIoT/services/boards/imx6q-sabrelite/link.lds @@ -1,17 +1,88 @@ -STACK_SIZE = 4096; +STACK_SIZE = 48*1024; +L1_PAGE_TABLE_SIZE = 16K; +RAM_VECTORS_SIZE = 72; +OUTPUT_FORMAT("elf32-littlearm") OUTPUT_ARCH(arm) +MEMORY +{ + OCRAM (rwx) : ORIGIN = 0x00900000, LENGTH = 256K + DDR (rwx) : ORIGIN = 0x10000000, LENGTH = 2048M +} + SECTIONS { - . = 0x80100000; +/* + * -- OCRAM -- + * + * Nothing in OCRAM can be loaded at boot, because the boot image must be a contiguous + * region of memory. + */ + /* MMU L1 page table */ + .l1_page_table (NOLOAD) : + { + __l1_page_table_start = .; + . += L1_PAGE_TABLE_SIZE; + } > OCRAM + + /* allocate a heap in ocram */ + .heap.ocram (NOLOAD) : ALIGN(4) + { + __heap_ocram_start = .; + . += LENGTH(OCRAM) - L1_PAGE_TABLE_SIZE - RAM_VECTORS_SIZE ; + __heap_ocram_end = .; + } > OCRAM + + /* RAM vector table comes at the end of OCRAM */ + .ram_vectors (ORIGIN(OCRAM) + LENGTH(OCRAM) - RAM_VECTORS_SIZE) (NOLOAD) : + { + __ram_vectors_start = .; + . += RAM_VECTORS_SIZE; + __ram_vectors_end = .; + } > OCRAM + +/* + * -- DDR -- + */ + + /* -- read-only sections -- */ + + _start_image_add = ORIGIN(DDR); + + .ivt (ORIGIN(DDR)) : + { + . = . + 0x400; + *(.ivt) + } > DDR + + .boot_data : + { + __start_boot_data = .; + *(.boot_data) + } > DDR + + /* aligned to ease the hexdump read of generated binary */ + .dcd_hdr : ALIGN(16) + { + __start_dcd = .; + *(.dcd_hdr) + } > DDR + .dcd_wrt_cmd : + { + *(.dcd_wrt_cmd) + } > DDR + .dcd_data : + { + *(.dcd_data) + } > DDR __text_start = .; .text : { - *(.vectors) + *(.startup) *(.text) *(.text.*) @@ -23,11 +94,14 @@ SECTIONS KEEP(*(.isrtbl)) __isrtbl_end = .; . = ALIGN(4); - } + } > DDR __text_end = .; __rodata_start = .; - .rodata : { *(.rodata) *(.rodata.*) } + .rodata : + { + *(.rodata) *(.rodata.*) + } > DDR __rodata_end = .; . = ALIGN(4); @@ -37,7 +111,7 @@ SECTIONS KEEP(*(SORT(.ctors.*))) KEEP(*(.ctors)) PROVIDE(__ctors_end__ = .); - } + } > DDR .dtors : { @@ -45,14 +119,14 @@ SECTIONS KEEP(*(SORT(.dtors.*))) KEEP(*(.dtors)) PROVIDE(__dtors_end__ = .); - } + } > DDR - . = ALIGN(16 * 1024); + /* . = ALIGN(16 * 1024); .l1_page_table : { __l1_page_table_start = .; . += 16K; - } + } */ . = ALIGN(8); __data_start = .; @@ -60,7 +134,7 @@ SECTIONS { *(.data) *(.data.*) - } + } > DDR __data_end = .; . = ALIGN(8); @@ -71,7 +145,7 @@ SECTIONS *(.bss.*) *(COMMON) . = ALIGN(4); - } + } > DDR . = ALIGN(4); __bss_end = .; @@ -81,7 +155,7 @@ SECTIONS . += STACK_SIZE; __stacks_end = .; stack_top = .; - } + } > DDR /* Stabs debugging sections. */ .stab 0 : { *(.stab) }