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