1Abstracting a Chain of Trust 2============================ 3 4 5.. section-numbering:: 6 :suffix: . 7 8.. contents:: 9 10The aim of this document is to describe the authentication framework implemented 11in the Trusted Firmware. This framework fulfills the following 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 82TBBR-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 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 framewotk to load the image and calls the 163Authentication module to authenticate it, following the CoT from ROT to Image. 164 165TF 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 ARM 378 TF. 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 funcion 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 auth_method_desc_t img_auth_methods[AUTH_METHOD_NUM]; 609 auth_param_desc_t authenticated_data[COT_MAX_VERIFIED_PARAMS]; 610 } auth_img_desc_t; 611 612A CoT is defined as an array of ``auth_image_desc_t`` structures linked together 613by the ``parent`` field. Those nodes with no parent must be authenticated using 614the 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 an 628array of image descriptors and it is registered in the framework using the macro 629``REGISTER_COT(cot_desc)``, where 'cot\_desc' must be the name of the array 630(passing a pointer or any other type of indirection will cause the registration 631process to fail). 632 633The number of images participating in the boot process depends on the CoT. There 634is, however, a minimum set of images that are mandatory in the Trusted Firmware 635and thus all 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 array defines the authentication methods that must 677 be checked to consider an image authenticated. Each method consists of a 678 type and a list of parameter descriptors. A parameter descriptor consists of 679 a type and a cookie which will point to specific information required to 680 extract that parameter from the image (i.e. if the parameter is stored in an 681 x509v3 extension, the cookie will point to the extension OID). Depending on 682 the method type, a different number of parameters must be specified. 683 Supported methods are: 684 685 - ``AUTH_METHOD_HASH``: the hash of the image must match the hash extracted 686 from the parent image. The following parameter descriptors must be 687 specified: 688 689 - ``data``: data to be hashed (obtained from current image) 690 - ``hash``: reference hash (obtained from parent image) 691 692 - ``AUTH_METHOD_SIG``: the image (usually a certificate) must be signed with 693 the private key whose public part is extracted from the parent image (or 694 the platform if the parent is NULL). The following parameter descriptors 695 must be specified: 696 697 - ``pk``: the public key (obtained from parent image) 698 - ``sig``: the digital signature (obtained from current image) 699 - ``alg``: the signature algorithm used (obtained from current image) 700 - ``data``: the data to be signed (obtained from current image) 701 702- ``authenticated_data``: this array indicates what authentication parameters 703 must be extracted from an image once it has been authenticated. Each 704 parameter consists of a parameter descriptor and the buffer address/size 705 to store the parameter. The CoT is responsible for allocating the required 706 memory to store the parameters. 707 708In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters 709extracted from the certificates. In the case of the TBBR CoT, these parameters 710are hashes and public keys. In DER format, an RSA-2048 public key requires 294 711bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication 712process, some of the buffers may be reused at different stages during the boot. 713 714Next in that file, the parameter descriptors are defined. These descriptors will 715be used to extract the parameter data from the corresponding image. 716 717Example: the BL31 Chain of Trust 718^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 719 720Four image descriptors form the BL31 Chain of Trust: 721 722.. code:: asm 723 724 [TRUSTED_KEY_CERT_ID] = { 725 .img_id = TRUSTED_KEY_CERT_ID, 726 .img_type = IMG_CERT, 727 .parent = NULL, 728 .img_auth_methods = { 729 [0] = { 730 .type = AUTH_METHOD_SIG, 731 .param.sig = { 732 .pk = &subject_pk, 733 .sig = &sig, 734 .alg = &sig_alg, 735 .data = &raw_data, 736 } 737 } 738 }, 739 .authenticated_data = { 740 [0] = { 741 .type_desc = &trusted_world_pk, 742 .data = { 743 .ptr = (void *)trusted_world_pk_buf, 744 .len = (unsigned int)PK_DER_LEN 745 } 746 }, 747 [1] = { 748 .type_desc = &non_trusted_world_pk, 749 .data = { 750 .ptr = (void *)non_trusted_world_pk_buf, 751 .len = (unsigned int)PK_DER_LEN 752 } 753 } 754 } 755 }, 756 [SOC_FW_KEY_CERT_ID] = { 757 .img_id = SOC_FW_KEY_CERT_ID, 758 .img_type = IMG_CERT, 759 .parent = &cot_desc[TRUSTED_KEY_CERT_ID], 760 .img_auth_methods = { 761 [0] = { 762 .type = AUTH_METHOD_SIG, 763 .param.sig = { 764 .pk = &trusted_world_pk, 765 .sig = &sig, 766 .alg = &sig_alg, 767 .data = &raw_data, 768 } 769 } 770 }, 771 .authenticated_data = { 772 [0] = { 773 .type_desc = &soc_fw_content_pk, 774 .data = { 775 .ptr = (void *)content_pk_buf, 776 .len = (unsigned int)PK_DER_LEN 777 } 778 } 779 } 780 }, 781 [SOC_FW_CONTENT_CERT_ID] = { 782 .img_id = SOC_FW_CONTENT_CERT_ID, 783 .img_type = IMG_CERT, 784 .parent = &cot_desc[SOC_FW_KEY_CERT_ID], 785 .img_auth_methods = { 786 [0] = { 787 .type = AUTH_METHOD_SIG, 788 .param.sig = { 789 .pk = &soc_fw_content_pk, 790 .sig = &sig, 791 .alg = &sig_alg, 792 .data = &raw_data, 793 } 794 } 795 }, 796 .authenticated_data = { 797 [0] = { 798 .type_desc = &soc_fw_hash, 799 .data = { 800 .ptr = (void *)soc_fw_hash_buf, 801 .len = (unsigned int)HASH_DER_LEN 802 } 803 } 804 } 805 }, 806 [BL31_IMAGE_ID] = { 807 .img_id = BL31_IMAGE_ID, 808 .img_type = IMG_RAW, 809 .parent = &cot_desc[SOC_FW_CONTENT_CERT_ID], 810 .img_auth_methods = { 811 [0] = { 812 .type = AUTH_METHOD_HASH, 813 .param.hash = { 814 .data = &raw_data, 815 .hash = &soc_fw_hash, 816 } 817 } 818 } 819 } 820 821The **Trusted Key certificate** is signed with the ROT private key and contains 822the Trusted World public key and the Non-Trusted World public key as x509v3 823extensions. This must be specified in the image descriptor using the 824``img_auth_methods`` and ``authenticated_data`` arrays, respectively. 825 826The Trusted Key certificate is authenticated by checking its digital signature 827using the ROTPK. Four parameters are required to check a signature: the public 828key, the algorithm, the signature and the data that has been signed. Therefore, 829four parameter descriptors must be specified with the authentication method: 830 831- ``subject_pk``: parameter descriptor of type ``AUTH_PARAM_PUB_KEY``. This type 832 is used to extract a public key from the parent image. If the cookie is an 833 OID, the key is extracted from the corresponding x509v3 extension. If the 834 cookie is NULL, the subject public key is retrieved. In this case, because 835 the parent image is NULL, the public key is obtained from the platform 836 (this key will be the ROTPK). 837- ``sig``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to extract 838 the signature from the certificate. 839- ``sig_alg``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to 840 extract the signature algorithm from the certificate. 841- ``raw_data``: parameter descriptor of type ``AUTH_PARAM_RAW_DATA``. It is used 842 to extract the data to be signed from the certificate. 843 844Once the signature has been checked and the certificate authenticated, the 845Trusted World public key needs to be extracted from the certificate. A new entry 846is created in the ``authenticated_data`` array for that purpose. In that entry, 847the corresponding parameter descriptor must be specified along with the buffer 848address to store the parameter value. In this case, the ``tz_world_pk`` descriptor 849is used to extract the public key from an x509v3 extension with OID 850``TRUSTED_WORLD_PK_OID``. The BL31 key certificate will use this descriptor as 851parameter in the signature authentication method. The key is stored in the 852``plat_tz_world_pk_buf`` buffer. 853 854The **BL31 Key certificate** is authenticated by checking its digital signature 855using the Trusted World public key obtained previously from the Trusted Key 856certificate. In the image descriptor, we specify a single authentication method 857by signature whose public key is the ``tz_world_pk``. Once this certificate has 858been authenticated, we have to extract the BL31 public key, stored in the 859extension specified by ``bl31_content_pk``. This key will be copied to the 860``plat_content_pk`` buffer. 861 862The **BL31 certificate** is authenticated by checking its digital signature 863using the BL31 public key obtained previously from the BL31 Key certificate. 864We specify the authentication method using ``bl31_content_pk`` as public key. 865After authentication, we need to extract the BL31 hash, stored in the extension 866specified by ``bl31_hash``. This hash will be copied to the ``plat_bl31_hash_buf`` 867buffer. 868 869The **BL31 image** is authenticated by calculating its hash and matching it 870with the hash obtained from the BL31 certificate. The image descriptor contains 871a single authentication method by hash. The parameters to the hash method are 872the reference hash, ``bl31_hash``, and the data to be hashed. In this case, it is 873the whole image, so we specify ``raw_data``. 874 875The image parser library 876~~~~~~~~~~~~~~~~~~~~~~~~ 877 878The image parser module relies on libraries to check the image integrity and 879extract the authentication parameters. The number and type of parser libraries 880depend on the images used in the CoT. Raw images do not need a library, so 881only an x509v3 library is required for the TBBR CoT. 882 883ARM platforms will use an x509v3 library based on mbed TLS. This library may be 884found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three 885functions: 886 887.. code:: c 888 889 void init(void); 890 int check_integrity(void *img, unsigned int img_len); 891 int get_auth_param(const auth_param_type_desc_t *type_desc, 892 void *img, unsigned int img_len, 893 void **param, unsigned int *param_len); 894 895The library is registered in the framework using the macro 896``REGISTER_IMG_PARSER_LIB()``. Each time the image parser module needs to access 897an image of type ``IMG_CERT``, it will call the corresponding function exported 898in this file. 899 900The build system must be updated to include the corresponding library and 901mbed TLS sources. ARM platforms use the ``arm_common.mk`` file to pull the 902sources. 903 904The cryptographic library 905~~~~~~~~~~~~~~~~~~~~~~~~~ 906 907The cryptographic module relies on a library to perform the required operations, 908i.e. verify a hash or a digital signature. ARM platforms will use a library 909based on mbed TLS, which can be found in 910``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the 911authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports 912three functions: 913 914.. code:: c 915 916 void init(void); 917 int verify_signature(void *data_ptr, unsigned int data_len, 918 void *sig_ptr, unsigned int sig_len, 919 void *sig_alg, unsigned int sig_alg_len, 920 void *pk_ptr, unsigned int pk_len); 921 int verify_hash(void *data_ptr, unsigned int data_len, 922 void *digest_info_ptr, unsigned int digest_info_len); 923 924The mbedTLS library algorithm support is configured by the 925``TF_MBEDTLS_KEY_ALG`` variable which can take in 3 values: `rsa`, `ecdsa` or 926`rsa+ecdsa`. This variable allows the Makefile to include the corresponding 927sources in the build for the various algorthms. Setting the variable to 928`rsa+ecdsa` enables support for both rsa and ecdsa algorithms in the mbedTLS 929library. 930 931Note: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can 932be defined in the platform Makefile. It will make mbed TLS use an implementation 933of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%). 934 935-------------- 936 937*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* 938 939.. _Trusted Board Boot: ./trusted-board-boot.rst 940.. _Platform Porting Guide: ./porting-guide.rst 941