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