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