5.2.1.1.Chain of Trust

A CoT is basically a sequence of authentication images which usually starts witha root of trust and culminates in a single data image. The following diagramillustrates how this maps to a CoT for the BL31 image described in theTBBR-Client specification.

+------------------++-------------------+|ROTPK/ROTPKHash|------>|TrustedKey|+------------------+|Certificate||(AuthImage)|/+-------------------+/|/|/|/|Lv+------------------++-------------------+|TrustedWorld|------>|BL31Key||PublicKey||Certificate|+------------------+|(AuthImage)|+-------------------+/|/|/|/|/v+------------------+L+-------------------+|BL31Content|------>|BL31Content||CertificatePK||Certificate|+------------------+|(AuthImage)|+-------------------+/|/|/|/|/v+------------------+L+-------------------+|BL31Hash|------>|BL31Image||||(DataImage)|+------------------+||+-------------------+DIAGRAM2.

The root of trust is usually a public key (ROTPK) that has been burnt in theplatform and cannot be modified.

5.2.1.2.Image types

Images in a CoT are categorised as authentication and data images. Anauthentication image contains information to authenticate a data image oranother authentication image. A data image is usually a boot loader binary, butit could be any other data that requires authentication.

5.2.1.3.Component responsibilities

For every image in a Chain of Trust, the following high level operations areperformed to verify it:

1. Allocate memory for the image either statically or at runtime.

2. Identify the image and load it in the allocated memory.

3. Check the integrity of the image as per its type.

4. Authenticate the image as per the cryptographic algorithms used.

5. If the image is an authentication image, extract the information that willbe used to authenticate the next image in the CoT.

In Diagram 1, each component is responsible for one or more of these operations.The responsibilities are briefly described below.

void(*init)(void);int(*verify_signature)(/* Data to verify. */void*data_ptr,unsignedintdata_len,/* Bit string of the signature in DER format. */void*sig_ptr,unsignedintsig_len,/* ASN1 SignatureAlgorithm struct. */void*sig_alg,unsignedintsig_alg_len,/* ASN1 SubjectPublicKeyInfo struct. */void*pk_ptr,unsignedintpk_len);int(*calc_hash)(/* SHA256, SHA384 and SHA512 can be used. */enumcrypto_md_algoalg/* Data to hash. */void*data_ptr,unsignedintdata_len,/* Buffer to store the output. */unsignedcharoutput[CRYPTO_MD_MAX_SIZE]);int(*verify_hash)(/* Data to verify. */void*data_ptr,unsignedintdata_len,/* ASN1 DigestInfo struct. */void*digest_info_ptr,unsignedintdigest_info_len);int(*auth_decrypt)(/* Currently AES-GCM is the only supported alg. */enumcrypto_dec_algodec_algo,/* Data to decrypt. */void*data_ptr,size_tlen,/* Decryption key. */constvoid*key,unsignedintkey_len,unsignedintkey_flags,/* Initialization vector. */constvoid*iv,unsignedintiv_len,/* Authentication tag. */constvoid*tag,unsignedinttag_len);

REGISTER_CRYPTO_LIB(_name,_init,_verify_signature,_verify_hash,_calc_hash,_auth_decrypt,_convert_pk);

int(*convert_pk)(void*full_pk_ptr,unsignedintfull_pk_len,void**hashed_pk_ptr,unsignedint*hashed_pk_len);

5.2.1.4.Authentication methods

The AM supports the following authentication methods:

1. Hash

2. Digital signature

The platform may specify these methods in the CoT in case it decides to definea custom CoT instead of reusing a predefined one.

If a data image uses multiple methods, then all the methods must be a part ofthe same CoT. The number and type of parameters are method specific. Theseparameters should be obtained from the parent image using the IPM.

1. Hash

   Parameters:

   1. A pointer to data to hash

   2. Length of the data

   3. A pointer to the hash

   4. Length of the hash

   The hash will be represented by the DER encoding of the following ASN.1type:

   DigestInfo::=SEQUENCE{digestAlgorithmDigestAlgorithmIdentifier,digestDigest}

   This ASN.1 structure makes it possible to remove any assumption about thetype of hash algorithm used as this information accompanies the hash. Thisshould allow the Cryptography Library (CL) to support multiple hashalgorithm implementations.

2. Digital Signature

   Parameters:

   1. A pointer to data to sign

   2. Length of the data

   3. Public Key Algorithm

   4. Public Key value

   5. Digital Signature Algorithm

   6. Digital Signature value

   The Public Key parameters will be represented by the DER encoding of thefollowing ASN.1 type:

   SubjectPublicKeyInfo::=SEQUENCE{algorithmAlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}},subjectPublicKeyBITSTRING}

   The Digital Signature Algorithm will be represented by the DER encoding ofthe following ASN.1 types.

   AlgorithmIdentifier{ALGORITHM:IOSet}::=SEQUENCE{algorithmALGORITHM.&id({IOSet}),parametersALGORITHM.&Type({IOSet}{@algorithm})OPTIONAL}

   The digital signature will be represented by:

   signature::=BITSTRING

The authentication framework will use the image descriptor to extract all theinformation related to authentication.

5.2.2.1.Describing the image parsing methods

The parsing method refers to the format of a particular image. For example, anauthentication image that represents a certificate could be in the X.509v3format. A data image that represents a boot loader stage could be in raw binaryor ELF format. The IPM supports three parsing methods. An image has to use oneof the three methods described below. An IPL is responsible for interpreting asingle parsing method. There has to be one IPL for every method used by theplatform.

1. Raw format: This format is effectively a nop as an image using this methodis treated as being in raw binary format e.g. boot loader images used byTF-A. This method should only be used by data images.

2. X509V3 method: This method uses industry standards like X.509 to representPKI certificates (authentication images). It is expected that open sourcelibraries will be available which can be used to parse an image representedby this method. Such libraries can be used to write the corresponding IPLe.g. the X.509 parsing library code in mbed TLS.

3. Platform defined method: This method caters for platform specificproprietary standards to represent authentication or data images. Forexample, The signature of a data image could be appended to the data imageraw binary. A header could be prepended to the combined blob to specify theextents of each component. The platform will have to implement thecorresponding IPL to interpret such a format.

The following enum can be used to define these three methods.

typedefenumimg_type_enum{IMG_RAW,/* Binary image */IMG_PLAT,/* Platform specific format */IMG_CERT,/* X509v3 certificate */IMG_MAX_TYPES,}img_type_t;

An IPL must provide functions with the following prototypes:

voidinit(void);intcheck_integrity(void*img,unsignedintimg_len);intget_auth_param(constauth_param_type_desc_t*type_desc,void*img,unsignedintimg_len,void**param,unsignedint*param_len);

An IPL for each type must be registered using the following macro:

REGISTER_IMG_PARSER_LIB(_type,_name,_init,_check_int,_get_param)

• _type: one of the types described above.

• _name: a string containing the IPL name for debugging purposes.

• _init: initialization function pointer.

• _check_int: check image integrity function pointer.

• _get_param: extract authentication parameter function pointer.

Theinit() function will be used to initialize the IPL.

Thecheck_integrity() function is passed a pointer to the memory where theimage has been loaded by the IO framework and the image length. It should ensurethat the image is in the format corresponding to the parsing method and has notbeen tampered with. For example, RFC-2459 describes a validation sequence for anX.509 certificate.

Theget_auth_param() function is passed a parameter descriptor containinginformation about the parameter (type_desc andcookie) to identify andextract the data corresponding to that parameter from an image. This data willbe used to verify either the current or the next image in the CoT sequence.

Each image in the CoT will specify the parsing method it uses. This informationwill be used by the IPM to find the right parser descriptor for the image.

5.2.2.2.Describing the authentication method(s)

As part of the CoT, each image has to specify one or more authentication methodswhich will be used to verify it. As described in the Section “Authenticationmethods”, there are three methods supported by the AM.

typedefenum{AUTH_METHOD_NONE,AUTH_METHOD_HASH,AUTH_METHOD_SIG,AUTH_METHOD_NUM}auth_method_type_t;

The AM defines the type of each parameter used by an authentication method. Ituses this information to:

1. Specify to theget_auth_param() function exported by the IPM, whichparameter should be extracted from an image.

2. Correctly marshall the parameters while calling the verification functionexported by the CM and PP.

3. Extract authentication parameters from a parent image in order to verify achild image e.g. to verify the certificate image, the public key has to beobtained from the parent image.

typedefenum{AUTH_PARAM_NONE,AUTH_PARAM_RAW_DATA,/* Raw image data */AUTH_PARAM_SIG,/* The image signature */AUTH_PARAM_SIG_ALG,/* The image signature algorithm */AUTH_PARAM_HASH,/* A hash (including the algorithm) */AUTH_PARAM_PUB_KEY,/* A public key */AUTH_PARAM_NV_CTR,/* A non-volatile counter */}auth_param_type_t;

The AM defines the following structure to identify an authentication parameterrequired to verify an image.

typedefstructauth_param_type_desc_s{auth_param_type_ttype;void*cookie;}auth_param_type_desc_t;

cookie is used by the platform to specify additional information to the IPMwhich enables it to uniquely identify the parameter that should be extractedfrom an image. For example, the hash of a BL3x image in its correspondingcontent certificate is stored in an X509v3 custom extension field. An extensionfield can only be identified using an OID. In this case, thecookie couldcontain the pointer to the OID defined by the platform for the hash extensionfield while thetype field could be set toAUTH_PARAM_HASH. A value of 0 forthecookie field means that it is not used.

For each method, the AM defines a structure with the parameters required toverify the image.

/* * Parameters for authentication by hash matching */typedefstructauth_method_param_hash_s{auth_param_type_desc_t*data;/* Data to hash */auth_param_type_desc_t*hash;/* Hash to match with */}auth_method_param_hash_t;/* * Parameters for authentication by signature */typedefstructauth_method_param_sig_s{auth_param_type_desc_t*pk;/* Public key */auth_param_type_desc_t*sig;/* Signature to check */auth_param_type_desc_t*alg;/* Signature algorithm */auth_param_type_desc_t*tbs;/* Data signed */}auth_method_param_sig_t;

The AM defines the following structure to describe an authentication method forverifying an image

/* * Authentication method descriptor */typedefstructauth_method_desc_s{auth_method_type_ttype;union{auth_method_param_hash_thash;auth_method_param_sig_tsig;}param;}auth_method_desc_t;

Using the method type specified in thetype field, the AM finds out what fieldneeds to access within theparam union.

5.2.2.3.Storing Authentication parameters

A parameter described byauth_param_type_desc_t to verify an image could beobtained from either the image itself or its parent image. The memory allocatedfor loading the parent image will be reused for loading the child image. Henceparameters which are obtained from the parent for verifying a child image needto have memory allocated for them separately where they can be stored. Thismemory must be statically allocated by the platform port.

The AM defines the following structure to store the data corresponding to anauthentication parameter.

typedefstructauth_param_data_desc_s{void*auth_param_ptr;unsignedintauth_param_len;}auth_param_data_desc_t;

Theauth_param_ptr field is initialized by the platform. Theauth_param_lenfield is used to specify the length of the data in the memory.

For parameters that can be obtained from the child image itself, the IPM isresponsible for populating theauth_param_ptr andauth_param_len fieldswhile executing theimg_get_auth_param() function.

The AM defines the following structure to enable an image to describe theparameters that should be extracted from it and used to verify the next image(child) in a CoT.

typedefstructauth_param_desc_s{auth_param_type_desc_ttype_desc;auth_param_data_desc_tdata;}auth_param_desc_t;

5.2.2.4.Describing an image in a CoT

An image in a CoT is a consolidation of the following aspects of a CoT describedabove.

1. A unique identifier specified by the platform which allows the IO frameworkto locate the image in a FIP and load it in the memory reserved for the dataimage in the CoT.

2. A parsing method which is used by the AM to find the appropriate IPM.

3. Authentication methods and their parameters as described in the previoussection. These are used to verify the current image.

4. Parameters which are used to verify the next image in the current CoT. Theseparameters are specified only by authentication images and can be extractedfrom the current image once it has been verified.

The following data structure describes an image in a CoT.

typedefstructauth_img_desc_s{unsignedintimg_id;conststructauth_img_desc_s*parent;img_type_timg_type;constauth_method_desc_t*constimg_auth_methods;constauth_param_desc_t*constauthenticated_data;}auth_img_desc_t;

A CoT is defined as an array of pointers toauth_image_desc_t structureslinked together by theparent field. Those nodes with no parent must beauthenticated using the ROTPK stored in the platform.

5.2.3.1.The TBBR CoT

CoT specific to BL1 and BL2 can be found indrivers/auth/tbbr/tbbr_cot_bl1.canddrivers/auth/tbbr/tbbr_cot_bl2.c respectively. The common CoT used acrossBL1 and BL2 can be found indrivers/auth/tbbr/tbbr_cot_common.c.This CoT consists of an array of pointers to image descriptors and it isregistered in the framework using the macroREGISTER_COT(cot_desc), wherecot_desc must be the name of the array (passing a pointer or any othertype of indirection will cause the registration process to fail).

The number of images participating in the boot process depends on the CoT.There is, however, a minimum set of images that are mandatory in TF-A and thusall CoTs must present:

• BL2

• SCP_BL2 (platform specific)

• BL31

• BL32 (optional)

• BL33

The TBBR specifies the additional certificates that must accompany these imagesfor a proper authentication. Details about the TBBR CoT may be found in theTrusted Board Boot document.

Following thePorting Guide, a platform must provide uniqueidentifiers for all the images and certificates that will be loaded during theboot process. If a platform is using the TBBR as a reference for trusted boot,these identifiers can be obtained frominclude/common/tbbr/tbbr_img_def.h.Arm platforms include this file ininclude/plat/arm/common/arm_def.h. Otherplatforms may also include this file or provide their own identifiers.

Important: the authentication module uses these identifiers to index theCoT array, so the descriptors location in the array must match the identifiers.

Each image descriptor must specify:

• img_id: the corresponding image unique identifier defined by the platform.

• img_type: the image parser module uses the image type to call the properparsing library to check the image integrity and extract the requiredauthentication parameters. Three types of images are currently supported:

  • IMG_RAW: image is a raw binary. No parsing functions are available,other than reading the whole image.

  • IMG_PLAT: image format is platform specific. The platform may use thistype for custom images not directly supported by the authenticationframework.

  • IMG_CERT: image is an x509v3 certificate.

• parent: pointer to the parent image descriptor. The parent will containthe information required to authenticate the current image. If the parentis NULL, the authentication parameters will be obtained from the platform(i.e. the BL2 and Trusted Key certificates are signed with the ROT privatekey, whose public part is stored in the platform).

• img_auth_methods: this points to an array which defines theauthentication methods that must be checked to consider an imageauthenticated. Each method consists of a type and a list of parameterdescriptors. A parameter descriptor consists of a type and a cookie whichwill point to specific information required to extract that parameter fromthe image (i.e. if the parameter is stored in an x509v3 extension, thecookie will point to the extension OID). Depending on the method type, adifferent number of parameters must be specified. This pointer should not beNULL.Supported methods are:

  • AUTH_METHOD_HASH: the hash of the image must match the hash extractedfrom the parent image. The following parameter descriptors must bespecified:

    • data: data to be hashed (obtained from current image)

    • hash: reference hash (obtained from parent image)

  • AUTH_METHOD_SIG: the image (usually a certificate) must be signed withthe private key whose public part is extracted from the parent image (orthe platform if the parent is NULL). The following parameter descriptorsmust be specified:

    • pk: the public key (obtained from parent image)

    • sig: the digital signature (obtained from current image)

    • alg: the signature algorithm used (obtained from current image)

    • data: the data to be signed (obtained from current image)

• authenticated_data: this array pointer indicates what authenticationparameters must be extracted from an image once it has been authenticated.Each parameter consists of a parameter descriptor and the bufferaddress/size to store the parameter. The CoT is responsible for allocatingthe required memory to store the parameters. This pointer may be NULL.

In thetbbr_cot*.c file, a set of buffers are allocated to store the parametersextracted from the certificates. In the case of the TBBR CoT, these parametersare hashes and public keys. In DER format, an RSA-4096 public key requires 550bytes, and a hash requires 51 bytes. Depending on the CoT and the authenticationprocess, some of the buffers may be reused at different stages during the boot.

Next in that file, the parameter descriptors are defined. These descriptors willbe used to extract the parameter data from the corresponding image.

staticconstauth_img_desc_ttrusted_key_cert={.img_id=TRUSTED_KEY_CERT_ID,.img_type=IMG_CERT,.parent=NULL,.img_auth_methods=(constauth_method_desc_t[AUTH_METHOD_NUM]){[0]={.type=AUTH_METHOD_SIG,.param.sig={.pk=&subject_pk,.sig=&sig,.alg=&sig_alg,.data=&raw_data}},[1]={.type=AUTH_METHOD_NV_CTR,.param.nv_ctr={.cert_nv_ctr=&trusted_nv_ctr,.plat_nv_ctr=&trusted_nv_ctr}}},.authenticated_data=(constauth_param_desc_t[COT_MAX_VERIFIED_PARAMS]){[0]={.type_desc=&trusted_world_pk,.data={.ptr=(void*)trusted_world_pk_buf,.len=(unsignedint)PK_DER_LEN}},[1]={.type_desc=&non_trusted_world_pk,.data={.ptr=(void*)non_trusted_world_pk_buf,.len=(unsignedint)PK_DER_LEN}}}};staticconstauth_img_desc_tsoc_fw_key_cert={.img_id=SOC_FW_KEY_CERT_ID,.img_type=IMG_CERT,.parent=&trusted_key_cert,.img_auth_methods=(constauth_method_desc_t[AUTH_METHOD_NUM]){[0]={.type=AUTH_METHOD_SIG,.param.sig={.pk=&trusted_world_pk,.sig=&sig,.alg=&sig_alg,.data=&raw_data}},[1]={.type=AUTH_METHOD_NV_CTR,.param.nv_ctr={.cert_nv_ctr=&trusted_nv_ctr,.plat_nv_ctr=&trusted_nv_ctr}}},.authenticated_data=(constauth_param_desc_t[COT_MAX_VERIFIED_PARAMS]){[0]={.type_desc=&soc_fw_content_pk,.data={.ptr=(void*)content_pk_buf,.len=(unsignedint)PK_DER_LEN}}}};staticconstauth_img_desc_tsoc_fw_content_cert={.img_id=SOC_FW_CONTENT_CERT_ID,.img_type=IMG_CERT,.parent=&soc_fw_key_cert,.img_auth_methods=(constauth_method_desc_t[AUTH_METHOD_NUM]){[0]={.type=AUTH_METHOD_SIG,.param.sig={.pk=&soc_fw_content_pk,.sig=&sig,.alg=&sig_alg,.data=&raw_data}},[1]={.type=AUTH_METHOD_NV_CTR,.param.nv_ctr={.cert_nv_ctr=&trusted_nv_ctr,.plat_nv_ctr=&trusted_nv_ctr}}},.authenticated_data=(constauth_param_desc_t[COT_MAX_VERIFIED_PARAMS]){[0]={.type_desc=&soc_fw_hash,.data={.ptr=(void*)soc_fw_hash_buf,.len=(unsignedint)HASH_DER_LEN}},[1]={.type_desc=&soc_fw_config_hash,.data={.ptr=(void*)soc_fw_config_hash_buf,.len=(unsignedint)HASH_DER_LEN}}}};staticconstauth_img_desc_tbl31_image={.img_id=BL31_IMAGE_ID,.img_type=IMG_RAW,.parent=&soc_fw_content_cert,.img_auth_methods=(constauth_method_desc_t[AUTH_METHOD_NUM]){[0]={.type=AUTH_METHOD_HASH,.param.hash={.data=&raw_data,.hash=&soc_fw_hash}}}};

5.2.3.2.The image parser library

The image parser module relies on libraries to check the image integrity andextract the authentication parameters. The number and type of parser librariesdepend on the images used in the CoT. Raw images do not need a library, soonly an x509v3 library is required for the TBBR CoT.

Arm platforms will use an x509v3 library based on mbed TLS. This library may befound indrivers/auth/mbedtls/mbedtls_x509_parser.c. It exports threefunctions:

voidinit(void);intcheck_integrity(void*img,unsignedintimg_len);intget_auth_param(constauth_param_type_desc_t*type_desc,void*img,unsignedintimg_len,void**param,unsignedint*param_len);

The library is registered in the framework using the macroREGISTER_IMG_PARSER_LIB(). Each time the image parser module needs to accessan image of typeIMG_CERT, it will call the corresponding function exportedin this file.

The build system must be updated to include the corresponding library andmbed TLS sources. Arm platforms use thearm_common.mk file to pull thesources.

5.2.3.3.The cryptographic library

The cryptographic module relies on a library to perform essential operationssuch as verifying a hash or a digital signature.Arm platforms use a library based on mbedTLS located atdrivers/auth/mbedtls/mbedtls_crypto.c.Additionally, an experimental alternative library based on PSA Cryptois available atdrivers/auth/mbedtls/mbedtls_psa_crypto.c. In future,mbedtls_psa_crypto.c will replacembedtls_crypto.c as the default ArmCM. Both libraries are registered in the authentication framework usingthe macroREGISTER_CRYPTO_LIB(). These libraries implement the followingexported functions, their implementations are compared side-by-side below:

The mbedTLS library algorithm support is configured by both theTF_MBEDTLS_KEY_ALG andTF_MBEDTLS_KEY_SIZE variables.

• TF_MBEDTLS_KEY_ALG can take in 3 values:rsa,ecdsa orrsa+ecdsa.This variable allows the Makefile to include the corresponding sources inthe build for the various algorithms. Setting the variable torsa+ecdsaenables support for both rsa and ecdsa algorithms in the mbedTLS library.

• TF_MBEDTLS_KEY_SIZE sets the supported RSA key size for TFA. Valid valuesinclude 1024, 2048, 3072 and 4096.

• TF_MBEDTLS_USE_AES_GCM enables the authenticated decryption support basedon AES-GCM algorithm. Valid values are 0 and 1.

Copyright (c) 2017-2024, Arm Limited and Contributors. All rights reserved.