1Authentication Framework & Chain of Trust 2========================================= 3 4The aim of this document is to describe the authentication framework 5implemented in Trusted Firmware-A (TF-A). This framework fulfills the 6following requirements: 7 8#. It should be possible for a platform port to specify the Chain of Trust in 9 terms of certificate hierarchy and the mechanisms used to verify a 10 particular image/certificate. 11 12#. The framework should distinguish between: 13 14 - The mechanism used to encode and transport information, e.g. DER encoded 15 X.509v3 certificates to ferry Subject Public Keys, hashes and non-volatile 16 counters. 17 18 - The mechanism used to verify the transported information i.e. the 19 cryptographic libraries. 20 21The framework has been designed following a modular approach illustrated in the 22next diagram: 23 24:: 25 26 +---------------+---------------+------------+ 27 | Trusted | Trusted | Trusted | 28 | Firmware | Firmware | Firmware | 29 | Generic | IO Framework | Platform | 30 | Code i.e. | (IO) | Port | 31 | BL1/BL2 (GEN) | | (PP) | 32 +---------------+---------------+------------+ 33 ^ ^ ^ 34 | | | 35 v v v 36 +-----------+ +-----------+ +-----------+ 37 | | | | | Image | 38 | Crypto | | Auth | | Parser | 39 | Module |<->| Module |<->| Module | 40 | (CM) | | (AM) | | (IPM) | 41 | | | | | | 42 +-----------+ +-----------+ +-----------+ 43 ^ ^ 44 | | 45 v v 46 +----------------+ +-----------------+ 47 | Cryptographic | | Image Parser | 48 | Libraries (CL) | | Libraries (IPL) | 49 +----------------+ +-----------------+ 50 | | 51 | | 52 | | 53 v v 54 +-----------------+ 55 | Misc. Libs e.g. | 56 | ASN.1 decoder | 57 | | 58 +-----------------+ 59 60 DIAGRAM 1. 61 62This document describes the inner details of the authentication framework and 63the abstraction mechanisms available to specify a Chain of Trust. 64 65Framework design 66---------------- 67 68This section describes some aspects of the framework design and the rationale 69behind them. These aspects are key to verify a Chain of Trust. 70 71Chain of Trust 72~~~~~~~~~~~~~~ 73 74A CoT is basically a sequence of authentication images which usually starts with 75a root of trust and culminates in a single data image. The following diagram 76illustrates how this maps to a CoT for the BL31 image described in the 77`TBBR-Client specification`_. 78 79:: 80 81 +------------------+ +-------------------+ 82 | ROTPK/ROTPK Hash |------>| Trusted Key | 83 +------------------+ | Certificate | 84 | (Auth Image) | 85 /+-------------------+ 86 / | 87 / | 88 / | 89 / | 90 L v 91 +------------------+ +-------------------+ 92 | Trusted World |------>| BL31 Key | 93 | Public Key | | Certificate | 94 +------------------+ | (Auth Image) | 95 +-------------------+ 96 / | 97 / | 98 / | 99 / | 100 / v 101 +------------------+ L +-------------------+ 102 | BL31 Content |------>| BL31 Content | 103 | Certificate PK | | Certificate | 104 +------------------+ | (Auth Image) | 105 +-------------------+ 106 / | 107 / | 108 / | 109 / | 110 / v 111 +------------------+ L +-------------------+ 112 | BL31 Hash |------>| BL31 Image | 113 | | | (Data Image) | 114 +------------------+ | | 115 +-------------------+ 116 117 DIAGRAM 2. 118 119The root of trust is usually a public key (ROTPK) that has been burnt in the 120platform and cannot be modified. 121 122Image types 123~~~~~~~~~~~ 124 125Images in a CoT are categorised as authentication and data images. An 126authentication image contains information to authenticate a data image or 127another authentication image. A data image is usually a boot loader binary, but 128it could be any other data that requires authentication. 129 130Component responsibilities 131~~~~~~~~~~~~~~~~~~~~~~~~~~ 132 133For every image in a Chain of Trust, the following high level operations are 134performed to verify it: 135 136#. Allocate memory for the image either statically or at runtime. 137 138#. Identify the image and load it in the allocated memory. 139 140#. Check the integrity of the image as per its type. 141 142#. Authenticate the image as per the cryptographic algorithms used. 143 144#. If the image is an authentication image, extract the information that will 145 be used to authenticate the next image in the CoT. 146 147In Diagram 1, each component is responsible for one or more of these operations. 148The responsibilities are briefly described below. 149 150TF-A Generic code and IO framework (GEN/IO) 151^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 152 153These components are responsible for initiating the authentication process for a 154particular image in BL1 or BL2. For each BL image that requires authentication, 155the Generic code asks recursively the Authentication module what is the parent 156image until either an authenticated image or the ROT is reached. Then the 157Generic code calls the IO framework to load the image and calls the 158Authentication module to authenticate it, following the CoT from ROT to Image. 159 160TF-A Platform Port (PP) 161^^^^^^^^^^^^^^^^^^^^^^^ 162 163The platform is responsible for: 164 165#. Specifying the CoT for each image that needs to be authenticated. Details of 166 how a CoT can be specified by the platform are explained later. The platform 167 also specifies the authentication methods and the parsing method used for 168 each image. 169 170#. Statically allocating memory for each parameter in each image which is 171 used for verifying the CoT, e.g. memory for public keys, hashes etc. 172 173#. Providing the ROTPK or a hash of it. 174 175#. Providing additional information to the IPM to enable it to identify and 176 extract authentication parameters contained in an image, e.g. if the 177 parameters are stored as X509v3 extensions, the corresponding OID must be 178 provided. 179 180#. Fulfill any other memory requirements of the IPM and the CM (not currently 181 described in this document). 182 183#. Export functions to verify an image which uses an authentication method that 184 cannot be interpreted by the CM, e.g. if an image has to be verified using a 185 NV counter, then the value of the counter to compare with can only be 186 provided by the platform. 187 188#. Export a custom IPM if a proprietary image format is being used (described 189 later). 190 191Authentication Module (AM) 192^^^^^^^^^^^^^^^^^^^^^^^^^^ 193 194It is responsible for: 195 196#. Providing the necessary abstraction mechanisms to describe a CoT. Amongst 197 other things, the authentication and image parsing methods must be specified 198 by the PP in the CoT. 199 200#. Verifying the CoT passed by GEN by utilising functionality exported by the 201 PP, IPM and CM. 202 203#. Tracking which images have been verified. In case an image is a part of 204 multiple CoTs then it should be verified only once e.g. the Trusted World 205 Key Certificate in the TBBR-Client spec. contains information to verify 206 SCP_BL2, BL31, BL32 each of which have a separate CoT. (This 207 responsibility has not been described in this document but should be 208 trivial to implement). 209 210#. Reusing memory meant for a data image to verify authentication images e.g. 211 in the CoT described in Diagram 2, each certificate can be loaded and 212 verified in the memory reserved by the platform for the BL31 image. By the 213 time BL31 (the data image) is loaded, all information to authenticate it 214 will have been extracted from the parent image i.e. BL31 content 215 certificate. It is assumed that the size of an authentication image will 216 never exceed the size of a data image. It should be possible to verify this 217 at build time using asserts. 218 219Cryptographic Module (CM) 220^^^^^^^^^^^^^^^^^^^^^^^^^ 221 222The CM is responsible for providing an API to: 223 224#. Verify a digital signature. 225#. Verify a hash. 226 227The CM does not include any cryptography related code, but it relies on an 228external library to perform the cryptographic operations. A Crypto-Library (CL) 229linking the CM and the external library must be implemented. The following 230functions must be provided by the CL: 231 232.. code:: c 233 234 void (*init)(void); 235 int (*verify_signature)(void *data_ptr, unsigned int data_len, 236 void *sig_ptr, unsigned int sig_len, 237 void *sig_alg, unsigned int sig_alg_len, 238 void *pk_ptr, unsigned int pk_len); 239 int (*calc_hash)(enum crypto_md_algo alg, void *data_ptr, 240 unsigned int data_len, 241 unsigned char output[CRYPTO_MD_MAX_SIZE]) 242 int (*verify_hash)(void *data_ptr, unsigned int data_len, 243 void *digest_info_ptr, unsigned int digest_info_len); 244 int (*auth_decrypt)(enum crypto_dec_algo dec_algo, void *data_ptr, 245 size_t len, const void *key, unsigned int key_len, 246 unsigned int key_flags, const void *iv, 247 unsigned int iv_len, const void *tag, 248 unsigned int tag_len); 249 250These functions are registered in the CM using the macro: 251 252.. code:: c 253 254 REGISTER_CRYPTO_LIB(_name, 255 _init, 256 _verify_signature, 257 _calc_hash, 258 _verify_hash, 259 _auth_decrypt); 260 261``_name`` must be a string containing the name of the CL. This name is used for 262debugging purposes. 263 264Crypto module provides a function ``_calc_hash`` to calculate and 265return the hash of the given data using the provided hash algorithm. 266This function is mainly used in the ``MEASURED_BOOT`` and ``DRTM_SUPPORT`` 267features to calculate the hashes of various images/data. 268 269Image Parser Module (IPM) 270^^^^^^^^^^^^^^^^^^^^^^^^^ 271 272The IPM is responsible for: 273 274#. Checking the integrity of each image loaded by the IO framework. 275#. Extracting parameters used for authenticating an image based upon a 276 description provided by the platform in the CoT descriptor. 277 278Images may have different formats (for example, authentication images could be 279x509v3 certificates, signed ELF files or any other platform specific format). 280The IPM allows to register an Image Parser Library (IPL) for every image format 281used in the CoT. This library must implement the specific methods to parse the 282image. The IPM obtains the image format from the CoT and calls the right IPL to 283check the image integrity and extract the authentication parameters. 284 285See Section "Describing the image parsing methods" for more details about the 286mechanism the IPM provides to define and register IPLs. 287 288Authentication methods 289~~~~~~~~~~~~~~~~~~~~~~ 290 291The AM supports the following authentication methods: 292 293#. Hash 294#. Digital signature 295 296The platform may specify these methods in the CoT in case it decides to define 297a custom CoT instead of reusing a predefined one. 298 299If a data image uses multiple methods, then all the methods must be a part of 300the same CoT. The number and type of parameters are method specific. These 301parameters should be obtained from the parent image using the IPM. 302 303#. Hash 304 305 Parameters: 306 307 #. A pointer to data to hash 308 #. Length of the data 309 #. A pointer to the hash 310 #. Length of the hash 311 312 The hash will be represented by the DER encoding of the following ASN.1 313 type: 314 315 :: 316 317 DigestInfo ::= SEQUENCE { 318 digestAlgorithm DigestAlgorithmIdentifier, 319 digest Digest 320 } 321 322 This ASN.1 structure makes it possible to remove any assumption about the 323 type of hash algorithm used as this information accompanies the hash. This 324 should allow the Cryptography Library (CL) to support multiple hash 325 algorithm implementations. 326 327#. Digital Signature 328 329 Parameters: 330 331 #. A pointer to data to sign 332 #. Length of the data 333 #. Public Key Algorithm 334 #. Public Key value 335 #. Digital Signature Algorithm 336 #. Digital Signature value 337 338 The Public Key parameters will be represented by the DER encoding of the 339 following ASN.1 type: 340 341 :: 342 343 SubjectPublicKeyInfo ::= SEQUENCE { 344 algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}}, 345 subjectPublicKey BIT STRING } 346 347 The Digital Signature Algorithm will be represented by the DER encoding of 348 the following ASN.1 types. 349 350 :: 351 352 AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE { 353 algorithm ALGORITHM.&id({IOSet}), 354 parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL 355 } 356 357 The digital signature will be represented by: 358 359 :: 360 361 signature ::= BIT STRING 362 363The authentication framework will use the image descriptor to extract all the 364information related to authentication. 365 366Specifying a Chain of Trust 367--------------------------- 368 369A CoT can be described as a set of image descriptors linked together in a 370particular order. The order dictates the sequence in which they must be 371verified. Each image has a set of properties which allow the AM to verify it. 372These properties are described below. 373 374The PP is responsible for defining a single or multiple CoTs for a data image. 375Unless otherwise specified, the data structures described in the following 376sections are populated by the PP statically. 377 378Describing the image parsing methods 379~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 380 381The parsing method refers to the format of a particular image. For example, an 382authentication image that represents a certificate could be in the X.509v3 383format. A data image that represents a boot loader stage could be in raw binary 384or ELF format. The IPM supports three parsing methods. An image has to use one 385of the three methods described below. An IPL is responsible for interpreting a 386single parsing method. There has to be one IPL for every method used by the 387platform. 388 389#. Raw format: This format is effectively a nop as an image using this method 390 is treated as being in raw binary format e.g. boot loader images used by 391 TF-A. This method should only be used by data images. 392 393#. X509V3 method: This method uses industry standards like X.509 to represent 394 PKI certificates (authentication images). It is expected that open source 395 libraries will be available which can be used to parse an image represented 396 by this method. Such libraries can be used to write the corresponding IPL 397 e.g. the X.509 parsing library code in mbed TLS. 398 399#. Platform defined method: This method caters for platform specific 400 proprietary standards to represent authentication or data images. For 401 example, The signature of a data image could be appended to the data image 402 raw binary. A header could be prepended to the combined blob to specify the 403 extents of each component. The platform will have to implement the 404 corresponding IPL to interpret such a format. 405 406The following enum can be used to define these three methods. 407 408.. code:: c 409 410 typedef enum img_type_enum { 411 IMG_RAW, /* Binary image */ 412 IMG_PLAT, /* Platform specific format */ 413 IMG_CERT, /* X509v3 certificate */ 414 IMG_MAX_TYPES, 415 } img_type_t; 416 417An IPL must provide functions with the following prototypes: 418 419.. code:: c 420 421 void init(void); 422 int check_integrity(void *img, unsigned int img_len); 423 int get_auth_param(const auth_param_type_desc_t *type_desc, 424 void *img, unsigned int img_len, 425 void **param, unsigned int *param_len); 426 427An IPL for each type must be registered using the following macro: 428 429.. code:: c 430 431 REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param) 432 433- ``_type``: one of the types described above. 434- ``_name``: a string containing the IPL name for debugging purposes. 435- ``_init``: initialization function pointer. 436- ``_check_int``: check image integrity function pointer. 437- ``_get_param``: extract authentication parameter function pointer. 438 439The ``init()`` function will be used to initialize the IPL. 440 441The ``check_integrity()`` function is passed a pointer to the memory where the 442image has been loaded by the IO framework and the image length. It should ensure 443that the image is in the format corresponding to the parsing method and has not 444been tampered with. For example, RFC-2459 describes a validation sequence for an 445X.509 certificate. 446 447The ``get_auth_param()`` function is passed a parameter descriptor containing 448information about the parameter (``type_desc`` and ``cookie``) to identify and 449extract the data corresponding to that parameter from an image. This data will 450be used to verify either the current or the next image in the CoT sequence. 451 452Each image in the CoT will specify the parsing method it uses. This information 453will be used by the IPM to find the right parser descriptor for the image. 454 455Describing the authentication method(s) 456~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 457 458As part of the CoT, each image has to specify one or more authentication methods 459which will be used to verify it. As described in the Section "Authentication 460methods", there are three methods supported by the AM. 461 462.. code:: c 463 464 typedef enum { 465 AUTH_METHOD_NONE, 466 AUTH_METHOD_HASH, 467 AUTH_METHOD_SIG, 468 AUTH_METHOD_NUM 469 } auth_method_type_t; 470 471The AM defines the type of each parameter used by an authentication method. It 472uses this information to: 473 474#. Specify to the ``get_auth_param()`` function exported by the IPM, which 475 parameter should be extracted from an image. 476 477#. Correctly marshall the parameters while calling the verification function 478 exported by the CM and PP. 479 480#. Extract authentication parameters from a parent image in order to verify a 481 child image e.g. to verify the certificate image, the public key has to be 482 obtained from the parent image. 483 484.. code:: c 485 486 typedef enum { 487 AUTH_PARAM_NONE, 488 AUTH_PARAM_RAW_DATA, /* Raw image data */ 489 AUTH_PARAM_SIG, /* The image signature */ 490 AUTH_PARAM_SIG_ALG, /* The image signature algorithm */ 491 AUTH_PARAM_HASH, /* A hash (including the algorithm) */ 492 AUTH_PARAM_PUB_KEY, /* A public key */ 493 } auth_param_type_t; 494 495The AM defines the following structure to identify an authentication parameter 496required to verify an image. 497 498.. code:: c 499 500 typedef struct auth_param_type_desc_s { 501 auth_param_type_t type; 502 void *cookie; 503 } auth_param_type_desc_t; 504 505``cookie`` is used by the platform to specify additional information to the IPM 506which enables it to uniquely identify the parameter that should be extracted 507from an image. For example, the hash of a BL3x image in its corresponding 508content certificate is stored in an X509v3 custom extension field. An extension 509field can only be identified using an OID. In this case, the ``cookie`` could 510contain the pointer to the OID defined by the platform for the hash extension 511field while the ``type`` field could be set to ``AUTH_PARAM_HASH``. A value of 0 for 512the ``cookie`` field means that it is not used. 513 514For each method, the AM defines a structure with the parameters required to 515verify the image. 516 517.. code:: c 518 519 /* 520 * Parameters for authentication by hash matching 521 */ 522 typedef struct auth_method_param_hash_s { 523 auth_param_type_desc_t *data; /* Data to hash */ 524 auth_param_type_desc_t *hash; /* Hash to match with */ 525 } auth_method_param_hash_t; 526 527 /* 528 * Parameters for authentication by signature 529 */ 530 typedef struct auth_method_param_sig_s { 531 auth_param_type_desc_t *pk; /* Public key */ 532 auth_param_type_desc_t *sig; /* Signature to check */ 533 auth_param_type_desc_t *alg; /* Signature algorithm */ 534 auth_param_type_desc_t *tbs; /* Data signed */ 535 } auth_method_param_sig_t; 536 537The AM defines the following structure to describe an authentication method for 538verifying an image 539 540.. code:: c 541 542 /* 543 * Authentication method descriptor 544 */ 545 typedef struct auth_method_desc_s { 546 auth_method_type_t type; 547 union { 548 auth_method_param_hash_t hash; 549 auth_method_param_sig_t sig; 550 } param; 551 } auth_method_desc_t; 552 553Using the method type specified in the ``type`` field, the AM finds out what field 554needs to access within the ``param`` union. 555 556Storing Authentication parameters 557~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 558 559A parameter described by ``auth_param_type_desc_t`` to verify an image could be 560obtained from either the image itself or its parent image. The memory allocated 561for loading the parent image will be reused for loading the child image. Hence 562parameters which are obtained from the parent for verifying a child image need 563to have memory allocated for them separately where they can be stored. This 564memory must be statically allocated by the platform port. 565 566The AM defines the following structure to store the data corresponding to an 567authentication parameter. 568 569.. code:: c 570 571 typedef struct auth_param_data_desc_s { 572 void *auth_param_ptr; 573 unsigned int auth_param_len; 574 } auth_param_data_desc_t; 575 576The ``auth_param_ptr`` field is initialized by the platform. The ``auth_param_len`` 577field is used to specify the length of the data in the memory. 578 579For parameters that can be obtained from the child image itself, the IPM is 580responsible for populating the ``auth_param_ptr`` and ``auth_param_len`` fields 581while executing the ``img_get_auth_param()`` function. 582 583The AM defines the following structure to enable an image to describe the 584parameters that should be extracted from it and used to verify the next image 585(child) in a CoT. 586 587.. code:: c 588 589 typedef struct auth_param_desc_s { 590 auth_param_type_desc_t type_desc; 591 auth_param_data_desc_t data; 592 } auth_param_desc_t; 593 594Describing an image in a CoT 595~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 596 597An image in a CoT is a consolidation of the following aspects of a CoT described 598above. 599 600#. A unique identifier specified by the platform which allows the IO framework 601 to locate the image in a FIP and load it in the memory reserved for the data 602 image in the CoT. 603 604#. A parsing method which is used by the AM to find the appropriate IPM. 605 606#. Authentication methods and their parameters as described in the previous 607 section. These are used to verify the current image. 608 609#. Parameters which are used to verify the next image in the current CoT. These 610 parameters are specified only by authentication images and can be extracted 611 from the current image once it has been verified. 612 613The following data structure describes an image in a CoT. 614 615.. code:: c 616 617 typedef struct auth_img_desc_s { 618 unsigned int img_id; 619 const struct auth_img_desc_s *parent; 620 img_type_t img_type; 621 const auth_method_desc_t *const img_auth_methods; 622 const auth_param_desc_t *const authenticated_data; 623 } auth_img_desc_t; 624 625A CoT is defined as an array of pointers to ``auth_image_desc_t`` structures 626linked together by the ``parent`` field. Those nodes with no parent must be 627authenticated using the ROTPK stored in the platform. 628 629Implementation example 630---------------------- 631 632This section is a detailed guide explaining a trusted boot implementation using 633the authentication framework. This example corresponds to the Applicative 634Functional Mode (AFM) as specified in the TBBR-Client document. It is 635recommended to read this guide along with the source code. 636 637The TBBR CoT 638~~~~~~~~~~~~ 639 640CoT specific to BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_bl1.c`` 641and ``drivers/auth/tbbr/tbbr_cot_bl2.c`` respectively. The common CoT used across 642BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_common.c``. 643This CoT consists of an array of pointers to image descriptors and it is 644registered in the framework using the macro ``REGISTER_COT(cot_desc)``, where 645``cot_desc`` must be the name of the array (passing a pointer or any other 646type of indirection will cause the registration process to fail). 647 648The number of images participating in the boot process depends on the CoT. 649There is, however, a minimum set of images that are mandatory in TF-A and thus 650all CoTs must present: 651 652- ``BL2`` 653- ``SCP_BL2`` (platform specific) 654- ``BL31`` 655- ``BL32`` (optional) 656- ``BL33`` 657 658The TBBR specifies the additional certificates that must accompany these images 659for a proper authentication. Details about the TBBR CoT may be found in the 660:ref:`Trusted Board Boot` document. 661 662Following the :ref:`Porting Guide`, a platform must provide unique 663identifiers for all the images and certificates that will be loaded during the 664boot process. If a platform is using the TBBR as a reference for trusted boot, 665these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``. 666Arm platforms include this file in ``include/plat/arm/common/arm_def.h``. Other 667platforms may also include this file or provide their own identifiers. 668 669**Important**: the authentication module uses these identifiers to index the 670CoT array, so the descriptors location in the array must match the identifiers. 671 672Each image descriptor must specify: 673 674- ``img_id``: the corresponding image unique identifier defined by the platform. 675- ``img_type``: the image parser module uses the image type to call the proper 676 parsing library to check the image integrity and extract the required 677 authentication parameters. Three types of images are currently supported: 678 679 - ``IMG_RAW``: image is a raw binary. No parsing functions are available, 680 other than reading the whole image. 681 - ``IMG_PLAT``: image format is platform specific. The platform may use this 682 type for custom images not directly supported by the authentication 683 framework. 684 - ``IMG_CERT``: image is an x509v3 certificate. 685 686- ``parent``: pointer to the parent image descriptor. The parent will contain 687 the information required to authenticate the current image. If the parent 688 is NULL, the authentication parameters will be obtained from the platform 689 (i.e. the BL2 and Trusted Key certificates are signed with the ROT private 690 key, whose public part is stored in the platform). 691- ``img_auth_methods``: this points to an array which defines the 692 authentication methods that must be checked to consider an image 693 authenticated. Each method consists of a type and a list of parameter 694 descriptors. A parameter descriptor consists of a type and a cookie which 695 will point to specific information required to extract that parameter from 696 the image (i.e. if the parameter is stored in an x509v3 extension, the 697 cookie will point to the extension OID). Depending on the method type, a 698 different number of parameters must be specified. This pointer should not be 699 NULL. 700 Supported methods are: 701 702 - ``AUTH_METHOD_HASH``: the hash of the image must match the hash extracted 703 from the parent image. The following parameter descriptors must be 704 specified: 705 706 - ``data``: data to be hashed (obtained from current image) 707 - ``hash``: reference hash (obtained from parent image) 708 709 - ``AUTH_METHOD_SIG``: the image (usually a certificate) must be signed with 710 the private key whose public part is extracted from the parent image (or 711 the platform if the parent is NULL). The following parameter descriptors 712 must be specified: 713 714 - ``pk``: the public key (obtained from parent image) 715 - ``sig``: the digital signature (obtained from current image) 716 - ``alg``: the signature algorithm used (obtained from current image) 717 - ``data``: the data to be signed (obtained from current image) 718 719- ``authenticated_data``: this array pointer indicates what authentication 720 parameters must be extracted from an image once it has been authenticated. 721 Each parameter consists of a parameter descriptor and the buffer 722 address/size to store the parameter. The CoT is responsible for allocating 723 the required memory to store the parameters. This pointer may be NULL. 724 725In the ``tbbr_cot*.c`` file, a set of buffers are allocated to store the parameters 726extracted from the certificates. In the case of the TBBR CoT, these parameters 727are hashes and public keys. In DER format, an RSA-4096 public key requires 550 728bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication 729process, some of the buffers may be reused at different stages during the boot. 730 731Next in that file, the parameter descriptors are defined. These descriptors will 732be used to extract the parameter data from the corresponding image. 733 734Example: the BL31 Chain of Trust 735^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 736 737Four image descriptors form the BL31 Chain of Trust: 738 739.. code:: c 740 741 static const auth_img_desc_t trusted_key_cert = { 742 .img_id = TRUSTED_KEY_CERT_ID, 743 .img_type = IMG_CERT, 744 .parent = NULL, 745 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) { 746 [0] = { 747 .type = AUTH_METHOD_SIG, 748 .param.sig = { 749 .pk = &subject_pk, 750 .sig = &sig, 751 .alg = &sig_alg, 752 .data = &raw_data 753 } 754 }, 755 [1] = { 756 .type = AUTH_METHOD_NV_CTR, 757 .param.nv_ctr = { 758 .cert_nv_ctr = &trusted_nv_ctr, 759 .plat_nv_ctr = &trusted_nv_ctr 760 } 761 } 762 }, 763 .authenticated_data = (const auth_param_desc_t[COT_MAX_VERIFIED_PARAMS]) { 764 [0] = { 765 .type_desc = &trusted_world_pk, 766 .data = { 767 .ptr = (void *)trusted_world_pk_buf, 768 .len = (unsigned int)PK_DER_LEN 769 } 770 }, 771 [1] = { 772 .type_desc = &non_trusted_world_pk, 773 .data = { 774 .ptr = (void *)non_trusted_world_pk_buf, 775 .len = (unsigned int)PK_DER_LEN 776 } 777 } 778 } 779 }; 780 static const auth_img_desc_t soc_fw_key_cert = { 781 .img_id = SOC_FW_KEY_CERT_ID, 782 .img_type = IMG_CERT, 783 .parent = &trusted_key_cert, 784 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) { 785 [0] = { 786 .type = AUTH_METHOD_SIG, 787 .param.sig = { 788 .pk = &trusted_world_pk, 789 .sig = &sig, 790 .alg = &sig_alg, 791 .data = &raw_data 792 } 793 }, 794 [1] = { 795 .type = AUTH_METHOD_NV_CTR, 796 .param.nv_ctr = { 797 .cert_nv_ctr = &trusted_nv_ctr, 798 .plat_nv_ctr = &trusted_nv_ctr 799 } 800 } 801 }, 802 .authenticated_data = (const auth_param_desc_t[COT_MAX_VERIFIED_PARAMS]) { 803 [0] = { 804 .type_desc = &soc_fw_content_pk, 805 .data = { 806 .ptr = (void *)content_pk_buf, 807 .len = (unsigned int)PK_DER_LEN 808 } 809 } 810 } 811 }; 812 static const auth_img_desc_t soc_fw_content_cert = { 813 .img_id = SOC_FW_CONTENT_CERT_ID, 814 .img_type = IMG_CERT, 815 .parent = &soc_fw_key_cert, 816 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) { 817 [0] = { 818 .type = AUTH_METHOD_SIG, 819 .param.sig = { 820 .pk = &soc_fw_content_pk, 821 .sig = &sig, 822 .alg = &sig_alg, 823 .data = &raw_data 824 } 825 }, 826 [1] = { 827 .type = AUTH_METHOD_NV_CTR, 828 .param.nv_ctr = { 829 .cert_nv_ctr = &trusted_nv_ctr, 830 .plat_nv_ctr = &trusted_nv_ctr 831 } 832 } 833 }, 834 .authenticated_data = (const auth_param_desc_t[COT_MAX_VERIFIED_PARAMS]) { 835 [0] = { 836 .type_desc = &soc_fw_hash, 837 .data = { 838 .ptr = (void *)soc_fw_hash_buf, 839 .len = (unsigned int)HASH_DER_LEN 840 } 841 }, 842 [1] = { 843 .type_desc = &soc_fw_config_hash, 844 .data = { 845 .ptr = (void *)soc_fw_config_hash_buf, 846 .len = (unsigned int)HASH_DER_LEN 847 } 848 } 849 } 850 }; 851 static const auth_img_desc_t bl31_image = { 852 .img_id = BL31_IMAGE_ID, 853 .img_type = IMG_RAW, 854 .parent = &soc_fw_content_cert, 855 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) { 856 [0] = { 857 .type = AUTH_METHOD_HASH, 858 .param.hash = { 859 .data = &raw_data, 860 .hash = &soc_fw_hash 861 } 862 } 863 } 864 }; 865 866The **Trusted Key certificate** is signed with the ROT private key and contains 867the Trusted World public key and the Non-Trusted World public key as x509v3 868extensions. This must be specified in the image descriptor using the 869``img_auth_methods`` and ``authenticated_data`` arrays, respectively. 870 871The Trusted Key certificate is authenticated by checking its digital signature 872using the ROTPK. Four parameters are required to check a signature: the public 873key, the algorithm, the signature and the data that has been signed. Therefore, 874four parameter descriptors must be specified with the authentication method: 875 876- ``subject_pk``: parameter descriptor of type ``AUTH_PARAM_PUB_KEY``. This type 877 is used to extract a public key from the parent image. If the cookie is an 878 OID, the key is extracted from the corresponding x509v3 extension. If the 879 cookie is NULL, the subject public key is retrieved. In this case, because 880 the parent image is NULL, the public key is obtained from the platform 881 (this key will be the ROTPK). 882- ``sig``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to extract 883 the signature from the certificate. 884- ``sig_alg``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to 885 extract the signature algorithm from the certificate. 886- ``raw_data``: parameter descriptor of type ``AUTH_PARAM_RAW_DATA``. It is used 887 to extract the data to be signed from the certificate. 888 889Once the signature has been checked and the certificate authenticated, the 890Trusted World public key needs to be extracted from the certificate. A new entry 891is created in the ``authenticated_data`` array for that purpose. In that entry, 892the corresponding parameter descriptor must be specified along with the buffer 893address to store the parameter value. In this case, the ``trusted_world_pk`` 894descriptor is used to extract the public key from an x509v3 extension with OID 895``TRUSTED_WORLD_PK_OID``. The BL31 key certificate will use this descriptor as 896parameter in the signature authentication method. The key is stored in the 897``trusted_world_pk_buf`` buffer. 898 899The **BL31 Key certificate** is authenticated by checking its digital signature 900using the Trusted World public key obtained previously from the Trusted Key 901certificate. In the image descriptor, we specify a single authentication method 902by signature whose public key is the ``trusted_world_pk``. Once this certificate 903has been authenticated, we have to extract the BL31 public key, stored in the 904extension specified by ``soc_fw_content_pk``. This key will be copied to the 905``content_pk_buf`` buffer. 906 907The **BL31 certificate** is authenticated by checking its digital signature 908using the BL31 public key obtained previously from the BL31 Key certificate. 909We specify the authentication method using ``soc_fw_content_pk`` as public key. 910After authentication, we need to extract the BL31 hash, stored in the extension 911specified by ``soc_fw_hash``. This hash will be copied to the 912``soc_fw_hash_buf`` buffer. 913 914The **BL31 image** is authenticated by calculating its hash and matching it 915with the hash obtained from the BL31 certificate. The image descriptor contains 916a single authentication method by hash. The parameters to the hash method are 917the reference hash, ``soc_fw_hash``, and the data to be hashed. In this case, 918it is the whole image, so we specify ``raw_data``. 919 920The image parser library 921~~~~~~~~~~~~~~~~~~~~~~~~ 922 923The image parser module relies on libraries to check the image integrity and 924extract the authentication parameters. The number and type of parser libraries 925depend on the images used in the CoT. Raw images do not need a library, so 926only an x509v3 library is required for the TBBR CoT. 927 928Arm platforms will use an x509v3 library based on mbed TLS. This library may be 929found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three 930functions: 931 932.. code:: c 933 934 void init(void); 935 int check_integrity(void *img, unsigned int img_len); 936 int get_auth_param(const auth_param_type_desc_t *type_desc, 937 void *img, unsigned int img_len, 938 void **param, unsigned int *param_len); 939 940The library is registered in the framework using the macro 941``REGISTER_IMG_PARSER_LIB()``. Each time the image parser module needs to access 942an image of type ``IMG_CERT``, it will call the corresponding function exported 943in this file. 944 945The build system must be updated to include the corresponding library and 946mbed TLS sources. Arm platforms use the ``arm_common.mk`` file to pull the 947sources. 948 949The cryptographic library 950~~~~~~~~~~~~~~~~~~~~~~~~~ 951 952The cryptographic module relies on a library to perform the required operations, 953i.e. verify a hash or a digital signature. Arm platforms will use a library 954based on mbed TLS, which can be found in 955``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the 956authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports 957below functions: 958 959.. code:: c 960 961 void init(void); 962 int verify_signature(void *data_ptr, unsigned int data_len, 963 void *sig_ptr, unsigned int sig_len, 964 void *sig_alg, unsigned int sig_alg_len, 965 void *pk_ptr, unsigned int pk_len); 966 int crypto_mod_calc_hash(enum crypto_md_algo alg, void *data_ptr, 967 unsigned int data_len, 968 unsigned char output[CRYPTO_MD_MAX_SIZE]) 969 int verify_hash(void *data_ptr, unsigned int data_len, 970 void *digest_info_ptr, unsigned int digest_info_len); 971 int auth_decrypt(enum crypto_dec_algo dec_algo, void *data_ptr, 972 size_t len, const void *key, unsigned int key_len, 973 unsigned int key_flags, const void *iv, 974 unsigned int iv_len, const void *tag, 975 unsigned int tag_len) 976 977The mbedTLS library algorithm support is configured by both the 978``TF_MBEDTLS_KEY_ALG`` and ``TF_MBEDTLS_KEY_SIZE`` variables. 979 980- ``TF_MBEDTLS_KEY_ALG`` can take in 3 values: `rsa`, `ecdsa` or `rsa+ecdsa`. 981 This variable allows the Makefile to include the corresponding sources in 982 the build for the various algorithms. Setting the variable to `rsa+ecdsa` 983 enables support for both rsa and ecdsa algorithms in the mbedTLS library. 984 985- ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values 986 include 1024, 2048, 3072 and 4096. 987 988- ``TF_MBEDTLS_USE_AES_GCM`` enables the authenticated decryption support based 989 on AES-GCM algorithm. Valid values are 0 and 1. 990 991.. note:: 992 If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can 993 be defined in the platform Makefile. It will make mbed TLS use an 994 implementation of SHA-256 with smaller memory footprint (~1.5 KB less) but 995 slower (~30%). 996 997-------------- 998 999*Copyright (c) 2017-2023, Arm Limited and Contributors. All rights reserved.* 1000 1001.. _TBBR-Client specification: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a 1002