blob: 1a53e2292e50cfbc6b9281640037d00e86e2f971 [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Authentication Framework & Chain of Trust
2=========================================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
Dan Handley610e7e12018-03-01 18:44:00 +00004The aim of this document is to describe the authentication framework
5implemented in Trusted Firmware-A (TF-A). This framework fulfills the
6following requirements:
Douglas Raillardd7c21b72017-06-28 15:23:03 +01007
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
Sandrine Bailleux30918422019-04-24 10:41:24 +020077`TBBR-Client specification`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010078
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
Dan Handley610e7e12018-03-01 18:44:00 +0000150TF-A Generic code and IO framework (GEN/IO)
151^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100152
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
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000157Generic code calls the IO framework to load the image and calls the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100158Authentication module to authenticate it, following the CoT from ROT to Image.
159
Dan Handley610e7e12018-03-01 18:44:00 +0000160TF-A Platform Port (PP)
161^^^^^^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100162
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
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100206 SCP_BL2, BL31, BL32 each of which have a separate CoT. (This
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100207 responsibility has not been described in this document but should be
208 trivial to implement).
209
210#. Reusing memory meant for a data image to verify authentication images e.g.
211 in the CoT described in Diagram 2, each certificate can be loaded and
212 verified in the memory reserved by the platform for the BL31 image. By the
213 time BL31 (the data image) is loaded, all information to authenticate it
214 will have been extracted from the parent image i.e. BL31 content
215 certificate. It is assumed that the size of an authentication image will
216 never exceed the size of a data image. It should be possible to verify this
217 at build time using asserts.
218
219Cryptographic Module (CM)
220^^^^^^^^^^^^^^^^^^^^^^^^^
221
222The CM is responsible for providing an API to:
223
224#. Verify a digital signature.
225#. Verify a hash.
226
227The CM does not include any cryptography related code, but it relies on an
228external library to perform the cryptographic operations. A Crypto-Library (CL)
229linking the CM and the external library must be implemented. The following
230functions must be provided by the CL:
231
232.. code:: c
233
234 void (*init)(void);
235 int (*verify_signature)(void *data_ptr, unsigned int data_len,
236 void *sig_ptr, unsigned int sig_len,
237 void *sig_alg, unsigned int sig_alg_len,
238 void *pk_ptr, unsigned int pk_len);
239 int (*verify_hash)(void *data_ptr, unsigned int data_len,
240 void *digest_info_ptr, unsigned int digest_info_len);
241
242These functions are registered in the CM using the macro:
243
244.. code:: c
245
246 REGISTER_CRYPTO_LIB(_name, _init, _verify_signature, _verify_hash);
247
248``_name`` must be a string containing the name of the CL. This name is used for
249debugging purposes.
250
251Image Parser Module (IPM)
252^^^^^^^^^^^^^^^^^^^^^^^^^
253
254The IPM is responsible for:
255
256#. Checking the integrity of each image loaded by the IO framework.
257#. Extracting parameters used for authenticating an image based upon a
258 description provided by the platform in the CoT descriptor.
259
260Images may have different formats (for example, authentication images could be
261x509v3 certificates, signed ELF files or any other platform specific format).
262The IPM allows to register an Image Parser Library (IPL) for every image format
263used in the CoT. This library must implement the specific methods to parse the
264image. The IPM obtains the image format from the CoT and calls the right IPL to
265check the image integrity and extract the authentication parameters.
266
267See Section "Describing the image parsing methods" for more details about the
268mechanism the IPM provides to define and register IPLs.
269
270Authentication methods
271~~~~~~~~~~~~~~~~~~~~~~
272
273The AM supports the following authentication methods:
274
275#. Hash
276#. Digital signature
277
278The platform may specify these methods in the CoT in case it decides to define
279a custom CoT instead of reusing a predefined one.
280
281If a data image uses multiple methods, then all the methods must be a part of
282the same CoT. The number and type of parameters are method specific. These
283parameters should be obtained from the parent image using the IPM.
284
285#. Hash
286
287 Parameters:
288
289 #. A pointer to data to hash
290 #. Length of the data
291 #. A pointer to the hash
292 #. Length of the hash
293
294 The hash will be represented by the DER encoding of the following ASN.1
295 type:
296
297 ::
298
299 DigestInfo ::= SEQUENCE {
300 digestAlgorithm DigestAlgorithmIdentifier,
301 digest Digest
302 }
303
304 This ASN.1 structure makes it possible to remove any assumption about the
305 type of hash algorithm used as this information accompanies the hash. This
306 should allow the Cryptography Library (CL) to support multiple hash
307 algorithm implementations.
308
309#. Digital Signature
310
311 Parameters:
312
313 #. A pointer to data to sign
314 #. Length of the data
315 #. Public Key Algorithm
316 #. Public Key value
317 #. Digital Signature Algorithm
318 #. Digital Signature value
319
320 The Public Key parameters will be represented by the DER encoding of the
321 following ASN.1 type:
322
323 ::
324
325 SubjectPublicKeyInfo ::= SEQUENCE {
326 algorithm AlgorithmIdentifier{PUBLIC-KEY,{PublicKeyAlgorithms}},
327 subjectPublicKey BIT STRING }
328
329 The Digital Signature Algorithm will be represented by the DER encoding of
330 the following ASN.1 types.
331
332 ::
333
334 AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE {
335 algorithm ALGORITHM.&id({IOSet}),
336 parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL
337 }
338
339 The digital signature will be represented by:
340
341 ::
342
343 signature ::= BIT STRING
344
345The authentication framework will use the image descriptor to extract all the
346information related to authentication.
347
348Specifying a Chain of Trust
349---------------------------
350
351A CoT can be described as a set of image descriptors linked together in a
352particular order. The order dictates the sequence in which they must be
353verified. Each image has a set of properties which allow the AM to verify it.
354These properties are described below.
355
356The PP is responsible for defining a single or multiple CoTs for a data image.
357Unless otherwise specified, the data structures described in the following
358sections are populated by the PP statically.
359
360Describing the image parsing methods
361~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
362
363The parsing method refers to the format of a particular image. For example, an
364authentication image that represents a certificate could be in the X.509v3
365format. A data image that represents a boot loader stage could be in raw binary
366or ELF format. The IPM supports three parsing methods. An image has to use one
367of the three methods described below. An IPL is responsible for interpreting a
368single parsing method. There has to be one IPL for every method used by the
369platform.
370
371#. Raw format: This format is effectively a nop as an image using this method
Dan Handley610e7e12018-03-01 18:44:00 +0000372 is treated as being in raw binary format e.g. boot loader images used by
373 TF-A. This method should only be used by data images.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100374
375#. X509V3 method: This method uses industry standards like X.509 to represent
376 PKI certificates (authentication images). It is expected that open source
377 libraries will be available which can be used to parse an image represented
378 by this method. Such libraries can be used to write the corresponding IPL
379 e.g. the X.509 parsing library code in mbed TLS.
380
381#. Platform defined method: This method caters for platform specific
382 proprietary standards to represent authentication or data images. For
383 example, The signature of a data image could be appended to the data image
384 raw binary. A header could be prepended to the combined blob to specify the
385 extents of each component. The platform will have to implement the
386 corresponding IPL to interpret such a format.
387
388The following enum can be used to define these three methods.
389
390.. code:: c
391
392 typedef enum img_type_enum {
393 IMG_RAW, /* Binary image */
394 IMG_PLAT, /* Platform specific format */
395 IMG_CERT, /* X509v3 certificate */
396 IMG_MAX_TYPES,
397 } img_type_t;
398
399An IPL must provide functions with the following prototypes:
400
401.. code:: c
402
403 void init(void);
404 int check_integrity(void *img, unsigned int img_len);
405 int get_auth_param(const auth_param_type_desc_t *type_desc,
406 void *img, unsigned int img_len,
407 void **param, unsigned int *param_len);
408
409An IPL for each type must be registered using the following macro:
410
Paul Beesley493e3492019-03-13 15:11:04 +0000411.. code:: c
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100412
413 REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param)
414
415- ``_type``: one of the types described above.
416- ``_name``: a string containing the IPL name for debugging purposes.
417- ``_init``: initialization function pointer.
418- ``_check_int``: check image integrity function pointer.
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000419- ``_get_param``: extract authentication parameter function pointer.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100420
421The ``init()`` function will be used to initialize the IPL.
422
423The ``check_integrity()`` function is passed a pointer to the memory where the
424image has been loaded by the IO framework and the image length. It should ensure
425that the image is in the format corresponding to the parsing method and has not
426been tampered with. For example, RFC-2459 describes a validation sequence for an
427X.509 certificate.
428
429The ``get_auth_param()`` function is passed a parameter descriptor containing
430information about the parameter (``type_desc`` and ``cookie``) to identify and
431extract the data corresponding to that parameter from an image. This data will
432be used to verify either the current or the next image in the CoT sequence.
433
434Each image in the CoT will specify the parsing method it uses. This information
435will be used by the IPM to find the right parser descriptor for the image.
436
437Describing the authentication method(s)
438~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
439
440As part of the CoT, each image has to specify one or more authentication methods
441which will be used to verify it. As described in the Section "Authentication
442methods", there are three methods supported by the AM.
443
444.. code:: c
445
446 typedef enum {
447 AUTH_METHOD_NONE,
448 AUTH_METHOD_HASH,
449 AUTH_METHOD_SIG,
450 AUTH_METHOD_NUM
451 } auth_method_type_t;
452
453The AM defines the type of each parameter used by an authentication method. It
454uses this information to:
455
456#. Specify to the ``get_auth_param()`` function exported by the IPM, which
457 parameter should be extracted from an image.
458
459#. Correctly marshall the parameters while calling the verification function
460 exported by the CM and PP.
461
462#. Extract authentication parameters from a parent image in order to verify a
463 child image e.g. to verify the certificate image, the public key has to be
464 obtained from the parent image.
465
466.. code:: c
467
468 typedef enum {
469 AUTH_PARAM_NONE,
470 AUTH_PARAM_RAW_DATA, /* Raw image data */
471 AUTH_PARAM_SIG, /* The image signature */
472 AUTH_PARAM_SIG_ALG, /* The image signature algorithm */
473 AUTH_PARAM_HASH, /* A hash (including the algorithm) */
474 AUTH_PARAM_PUB_KEY, /* A public key */
475 } auth_param_type_t;
476
477The AM defines the following structure to identify an authentication parameter
478required to verify an image.
479
480.. code:: c
481
482 typedef struct auth_param_type_desc_s {
483 auth_param_type_t type;
484 void *cookie;
485 } auth_param_type_desc_t;
486
487``cookie`` is used by the platform to specify additional information to the IPM
488which enables it to uniquely identify the parameter that should be extracted
489from an image. For example, the hash of a BL3x image in its corresponding
490content certificate is stored in an X509v3 custom extension field. An extension
491field can only be identified using an OID. In this case, the ``cookie`` could
492contain the pointer to the OID defined by the platform for the hash extension
493field while the ``type`` field could be set to ``AUTH_PARAM_HASH``. A value of 0 for
494the ``cookie`` field means that it is not used.
495
496For each method, the AM defines a structure with the parameters required to
497verify the image.
498
499.. code:: c
500
501 /*
502 * Parameters for authentication by hash matching
503 */
504 typedef struct auth_method_param_hash_s {
505 auth_param_type_desc_t *data; /* Data to hash */
506 auth_param_type_desc_t *hash; /* Hash to match with */
507 } auth_method_param_hash_t;
508
509 /*
510 * Parameters for authentication by signature
511 */
512 typedef struct auth_method_param_sig_s {
513 auth_param_type_desc_t *pk; /* Public key */
514 auth_param_type_desc_t *sig; /* Signature to check */
515 auth_param_type_desc_t *alg; /* Signature algorithm */
516 auth_param_type_desc_t *tbs; /* Data signed */
517 } auth_method_param_sig_t;
518
519The AM defines the following structure to describe an authentication method for
520verifying an image
521
522.. code:: c
523
524 /*
525 * Authentication method descriptor
526 */
527 typedef struct auth_method_desc_s {
528 auth_method_type_t type;
529 union {
530 auth_method_param_hash_t hash;
531 auth_method_param_sig_t sig;
532 } param;
533 } auth_method_desc_t;
534
535Using the method type specified in the ``type`` field, the AM finds out what field
536needs to access within the ``param`` union.
537
538Storing Authentication parameters
539~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
540
541A parameter described by ``auth_param_type_desc_t`` to verify an image could be
542obtained from either the image itself or its parent image. The memory allocated
543for loading the parent image will be reused for loading the child image. Hence
544parameters which are obtained from the parent for verifying a child image need
545to have memory allocated for them separately where they can be stored. This
546memory must be statically allocated by the platform port.
547
548The AM defines the following structure to store the data corresponding to an
549authentication parameter.
550
551.. code:: c
552
553 typedef struct auth_param_data_desc_s {
554 void *auth_param_ptr;
555 unsigned int auth_param_len;
556 } auth_param_data_desc_t;
557
558The ``auth_param_ptr`` field is initialized by the platform. The ``auth_param_len``
559field is used to specify the length of the data in the memory.
560
561For parameters that can be obtained from the child image itself, the IPM is
562responsible for populating the ``auth_param_ptr`` and ``auth_param_len`` fields
563while executing the ``img_get_auth_param()`` function.
564
565The AM defines the following structure to enable an image to describe the
566parameters that should be extracted from it and used to verify the next image
567(child) in a CoT.
568
569.. code:: c
570
571 typedef struct auth_param_desc_s {
572 auth_param_type_desc_t type_desc;
573 auth_param_data_desc_t data;
574 } auth_param_desc_t;
575
576Describing an image in a CoT
577~~~~~~~~~~~~~~~~~~~~~~~~~~~~
578
579An image in a CoT is a consolidation of the following aspects of a CoT described
580above.
581
582#. A unique identifier specified by the platform which allows the IO framework
583 to locate the image in a FIP and load it in the memory reserved for the data
584 image in the CoT.
585
586#. A parsing method which is used by the AM to find the appropriate IPM.
587
588#. Authentication methods and their parameters as described in the previous
589 section. These are used to verify the current image.
590
591#. Parameters which are used to verify the next image in the current CoT. These
592 parameters are specified only by authentication images and can be extracted
593 from the current image once it has been verified.
594
595The following data structure describes an image in a CoT.
596
597.. code:: c
598
599 typedef struct auth_img_desc_s {
600 unsigned int img_id;
601 const struct auth_img_desc_s *parent;
602 img_type_t img_type;
Joel Hutton1fdcc902019-02-22 16:40:16 +0000603 const auth_method_desc_t *const img_auth_methods;
604 const auth_param_desc_t *const authenticated_data;
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100605 } auth_img_desc_t;
606
Joel Hutton1fdcc902019-02-22 16:40:16 +0000607A CoT is defined as an array of pointers to ``auth_image_desc_t`` structures
608linked together by the ``parent`` field. Those nodes with no parent must be
609authenticated using the ROTPK stored in the platform.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100610
611Implementation example
612----------------------
613
614This section is a detailed guide explaining a trusted boot implementation using
615the authentication framework. This example corresponds to the Applicative
616Functional Mode (AFM) as specified in the TBBR-Client document. It is
617recommended to read this guide along with the source code.
618
619The TBBR CoT
620~~~~~~~~~~~~
621
Joel Hutton1fdcc902019-02-22 16:40:16 +0000622The CoT can be found in ``drivers/auth/tbbr/tbbr_cot.c``. This CoT consists of
623an array of pointers to image descriptors and it is registered in the framework
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100624using the macro ``REGISTER_COT(cot_desc)``, where ``cot_desc`` must be the name
Joel Hutton1fdcc902019-02-22 16:40:16 +0000625of the array (passing a pointer or any other type of indirection will cause the
626registration process to fail).
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100627
Joel Hutton1fdcc902019-02-22 16:40:16 +0000628The number of images participating in the boot process depends on the CoT.
629There is, however, a minimum set of images that are mandatory in TF-A and thus
630all CoTs must present:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100631
632- ``BL2``
633- ``SCP_BL2`` (platform specific)
634- ``BL31``
635- ``BL32`` (optional)
636- ``BL33``
637
638The TBBR specifies the additional certificates that must accompany these images
639for a proper authentication. Details about the TBBR CoT may be found in the
Paul Beesleyf8640672019-04-12 14:19:42 +0100640:ref:`Trusted Board Boot` document.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100641
Paul Beesleyf8640672019-04-12 14:19:42 +0100642Following the :ref:`Porting Guide`, a platform must provide unique
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100643identifiers for all the images and certificates that will be loaded during the
644boot process. If a platform is using the TBBR as a reference for trusted boot,
645these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``.
Dan Handley610e7e12018-03-01 18:44:00 +0000646Arm platforms include this file in ``include/plat/arm/common/arm_def.h``. Other
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100647platforms may also include this file or provide their own identifiers.
648
649**Important**: the authentication module uses these identifiers to index the
650CoT array, so the descriptors location in the array must match the identifiers.
651
652Each image descriptor must specify:
653
654- ``img_id``: the corresponding image unique identifier defined by the platform.
655- ``img_type``: the image parser module uses the image type to call the proper
656 parsing library to check the image integrity and extract the required
657 authentication parameters. Three types of images are currently supported:
658
659 - ``IMG_RAW``: image is a raw binary. No parsing functions are available,
660 other than reading the whole image.
661 - ``IMG_PLAT``: image format is platform specific. The platform may use this
662 type for custom images not directly supported by the authentication
663 framework.
664 - ``IMG_CERT``: image is an x509v3 certificate.
665
666- ``parent``: pointer to the parent image descriptor. The parent will contain
667 the information required to authenticate the current image. If the parent
668 is NULL, the authentication parameters will be obtained from the platform
669 (i.e. the BL2 and Trusted Key certificates are signed with the ROT private
670 key, whose public part is stored in the platform).
Joel Hutton1fdcc902019-02-22 16:40:16 +0000671- ``img_auth_methods``: this points to an array which defines the
672 authentication methods that must be checked to consider an image
673 authenticated. Each method consists of a type and a list of parameter
674 descriptors. A parameter descriptor consists of a type and a cookie which
675 will point to specific information required to extract that parameter from
676 the image (i.e. if the parameter is stored in an x509v3 extension, the
677 cookie will point to the extension OID). Depending on the method type, a
678 different number of parameters must be specified. This pointer should not be
679 NULL.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100680 Supported methods are:
681
682 - ``AUTH_METHOD_HASH``: the hash of the image must match the hash extracted
683 from the parent image. The following parameter descriptors must be
684 specified:
685
686 - ``data``: data to be hashed (obtained from current image)
687 - ``hash``: reference hash (obtained from parent image)
688
689 - ``AUTH_METHOD_SIG``: the image (usually a certificate) must be signed with
690 the private key whose public part is extracted from the parent image (or
691 the platform if the parent is NULL). The following parameter descriptors
692 must be specified:
693
694 - ``pk``: the public key (obtained from parent image)
695 - ``sig``: the digital signature (obtained from current image)
696 - ``alg``: the signature algorithm used (obtained from current image)
697 - ``data``: the data to be signed (obtained from current image)
698
Joel Hutton1fdcc902019-02-22 16:40:16 +0000699- ``authenticated_data``: this array pointer indicates what authentication
700 parameters must be extracted from an image once it has been authenticated.
701 Each parameter consists of a parameter descriptor and the buffer
702 address/size to store the parameter. The CoT is responsible for allocating
703 the required memory to store the parameters. This pointer may be NULL.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100704
705In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters
706extracted from the certificates. In the case of the TBBR CoT, these parameters
Justin Chadwell82b06b32019-07-29 17:18:21 +0100707are hashes and public keys. In DER format, an RSA-4096 public key requires 550
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100708bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication
709process, some of the buffers may be reused at different stages during the boot.
710
711Next in that file, the parameter descriptors are defined. These descriptors will
712be used to extract the parameter data from the corresponding image.
713
714Example: the BL31 Chain of Trust
715^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
716
717Four image descriptors form the BL31 Chain of Trust:
718
Sandrine Bailleuxf5a91002019-02-08 10:50:28 +0100719.. code:: c
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100720
Joel Hutton1fdcc902019-02-22 16:40:16 +0000721 static const auth_img_desc_t trusted_key_cert = {
722 .img_id = TRUSTED_KEY_CERT_ID,
723 .img_type = IMG_CERT,
724 .parent = NULL,
725 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) {
726 [0] = {
727 .type = AUTH_METHOD_SIG,
728 .param.sig = {
729 .pk = &subject_pk,
730 .sig = &sig,
731 .alg = &sig_alg,
732 .data = &raw_data
733 }
734 },
735 [1] = {
736 .type = AUTH_METHOD_NV_CTR,
737 .param.nv_ctr = {
738 .cert_nv_ctr = &trusted_nv_ctr,
739 .plat_nv_ctr = &trusted_nv_ctr
740 }
741 }
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100742 },
Joel Hutton1fdcc902019-02-22 16:40:16 +0000743 .authenticated_data = (const auth_param_desc_t[COT_MAX_VERIFIED_PARAMS]) {
744 [0] = {
745 .type_desc = &trusted_world_pk,
746 .data = {
747 .ptr = (void *)trusted_world_pk_buf,
748 .len = (unsigned int)PK_DER_LEN
749 }
750 },
751 [1] = {
752 .type_desc = &non_trusted_world_pk,
753 .data = {
754 .ptr = (void *)non_trusted_world_pk_buf,
755 .len = (unsigned int)PK_DER_LEN
756 }
757 }
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100758 }
Joel Hutton1fdcc902019-02-22 16:40:16 +0000759 };
760 static const auth_img_desc_t soc_fw_key_cert = {
761 .img_id = SOC_FW_KEY_CERT_ID,
762 .img_type = IMG_CERT,
763 .parent = &trusted_key_cert,
764 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) {
765 [0] = {
766 .type = AUTH_METHOD_SIG,
767 .param.sig = {
768 .pk = &trusted_world_pk,
769 .sig = &sig,
770 .alg = &sig_alg,
771 .data = &raw_data
772 }
773 },
774 [1] = {
775 .type = AUTH_METHOD_NV_CTR,
776 .param.nv_ctr = {
777 .cert_nv_ctr = &trusted_nv_ctr,
778 .plat_nv_ctr = &trusted_nv_ctr
779 }
780 }
781 },
782 .authenticated_data = (const auth_param_desc_t[COT_MAX_VERIFIED_PARAMS]) {
783 [0] = {
784 .type_desc = &soc_fw_content_pk,
785 .data = {
786 .ptr = (void *)content_pk_buf,
787 .len = (unsigned int)PK_DER_LEN
788 }
789 }
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100790 }
Joel Hutton1fdcc902019-02-22 16:40:16 +0000791 };
792 static const auth_img_desc_t soc_fw_content_cert = {
793 .img_id = SOC_FW_CONTENT_CERT_ID,
794 .img_type = IMG_CERT,
795 .parent = &soc_fw_key_cert,
796 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) {
797 [0] = {
798 .type = AUTH_METHOD_SIG,
799 .param.sig = {
800 .pk = &soc_fw_content_pk,
801 .sig = &sig,
802 .alg = &sig_alg,
803 .data = &raw_data
804 }
805 },
806 [1] = {
807 .type = AUTH_METHOD_NV_CTR,
808 .param.nv_ctr = {
809 .cert_nv_ctr = &trusted_nv_ctr,
810 .plat_nv_ctr = &trusted_nv_ctr
811 }
812 }
813 },
814 .authenticated_data = (const auth_param_desc_t[COT_MAX_VERIFIED_PARAMS]) {
815 [0] = {
816 .type_desc = &soc_fw_hash,
817 .data = {
818 .ptr = (void *)soc_fw_hash_buf,
819 .len = (unsigned int)HASH_DER_LEN
820 }
821 },
822 [1] = {
823 .type_desc = &soc_fw_config_hash,
824 .data = {
825 .ptr = (void *)soc_fw_config_hash_buf,
826 .len = (unsigned int)HASH_DER_LEN
827 }
828 }
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100829 }
Joel Hutton1fdcc902019-02-22 16:40:16 +0000830 };
831 static const auth_img_desc_t bl31_image = {
832 .img_id = BL31_IMAGE_ID,
833 .img_type = IMG_RAW,
834 .parent = &soc_fw_content_cert,
835 .img_auth_methods = (const auth_method_desc_t[AUTH_METHOD_NUM]) {
836 [0] = {
837 .type = AUTH_METHOD_HASH,
838 .param.hash = {
839 .data = &raw_data,
840 .hash = &soc_fw_hash
841 }
842 }
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100843 }
Joel Hutton1fdcc902019-02-22 16:40:16 +0000844 };
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100845
846The **Trusted Key certificate** is signed with the ROT private key and contains
847the Trusted World public key and the Non-Trusted World public key as x509v3
848extensions. This must be specified in the image descriptor using the
849``img_auth_methods`` and ``authenticated_data`` arrays, respectively.
850
851The Trusted Key certificate is authenticated by checking its digital signature
852using the ROTPK. Four parameters are required to check a signature: the public
853key, the algorithm, the signature and the data that has been signed. Therefore,
854four parameter descriptors must be specified with the authentication method:
855
856- ``subject_pk``: parameter descriptor of type ``AUTH_PARAM_PUB_KEY``. This type
857 is used to extract a public key from the parent image. If the cookie is an
858 OID, the key is extracted from the corresponding x509v3 extension. If the
859 cookie is NULL, the subject public key is retrieved. In this case, because
860 the parent image is NULL, the public key is obtained from the platform
861 (this key will be the ROTPK).
862- ``sig``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to extract
863 the signature from the certificate.
864- ``sig_alg``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to
865 extract the signature algorithm from the certificate.
866- ``raw_data``: parameter descriptor of type ``AUTH_PARAM_RAW_DATA``. It is used
867 to extract the data to be signed from the certificate.
868
869Once the signature has been checked and the certificate authenticated, the
870Trusted World public key needs to be extracted from the certificate. A new entry
871is created in the ``authenticated_data`` array for that purpose. In that entry,
872the corresponding parameter descriptor must be specified along with the buffer
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100873address to store the parameter value. In this case, the ``trusted_world_pk``
874descriptor is used to extract the public key from an x509v3 extension with OID
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100875``TRUSTED_WORLD_PK_OID``. The BL31 key certificate will use this descriptor as
876parameter in the signature authentication method. The key is stored in the
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100877``trusted_world_pk_buf`` buffer.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100878
879The **BL31 Key certificate** is authenticated by checking its digital signature
880using the Trusted World public key obtained previously from the Trusted Key
881certificate. In the image descriptor, we specify a single authentication method
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100882by signature whose public key is the ``trusted_world_pk``. Once this certificate
883has been authenticated, we have to extract the BL31 public key, stored in the
884extension specified by ``soc_fw_content_pk``. This key will be copied to the
885``content_pk_buf`` buffer.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100886
887The **BL31 certificate** is authenticated by checking its digital signature
888using the BL31 public key obtained previously from the BL31 Key certificate.
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100889We specify the authentication method using ``soc_fw_content_pk`` as public key.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100890After authentication, we need to extract the BL31 hash, stored in the extension
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100891specified by ``soc_fw_hash``. This hash will be copied to the
892``soc_fw_hash_buf`` buffer.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100893
894The **BL31 image** is authenticated by calculating its hash and matching it
895with the hash obtained from the BL31 certificate. The image descriptor contains
896a single authentication method by hash. The parameters to the hash method are
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100897the reference hash, ``soc_fw_hash``, and the data to be hashed. In this case,
898it is the whole image, so we specify ``raw_data``.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100899
900The image parser library
901~~~~~~~~~~~~~~~~~~~~~~~~
902
903The image parser module relies on libraries to check the image integrity and
904extract the authentication parameters. The number and type of parser libraries
905depend on the images used in the CoT. Raw images do not need a library, so
906only an x509v3 library is required for the TBBR CoT.
907
Dan Handley610e7e12018-03-01 18:44:00 +0000908Arm platforms will use an x509v3 library based on mbed TLS. This library may be
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100909found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three
910functions:
911
912.. code:: c
913
914 void init(void);
915 int check_integrity(void *img, unsigned int img_len);
916 int get_auth_param(const auth_param_type_desc_t *type_desc,
917 void *img, unsigned int img_len,
918 void **param, unsigned int *param_len);
919
920The library is registered in the framework using the macro
921``REGISTER_IMG_PARSER_LIB()``. Each time the image parser module needs to access
922an image of type ``IMG_CERT``, it will call the corresponding function exported
923in this file.
924
925The build system must be updated to include the corresponding library and
Dan Handley610e7e12018-03-01 18:44:00 +0000926mbed TLS sources. Arm platforms use the ``arm_common.mk`` file to pull the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100927sources.
928
929The cryptographic library
930~~~~~~~~~~~~~~~~~~~~~~~~~
931
932The cryptographic module relies on a library to perform the required operations,
Dan Handley610e7e12018-03-01 18:44:00 +0000933i.e. verify a hash or a digital signature. Arm platforms will use a library
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100934based on mbed TLS, which can be found in
935``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the
936authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports
Sumit Gargc0c369c2019-11-15 18:47:53 +0530937four functions:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100938
939.. code:: c
940
941 void init(void);
942 int verify_signature(void *data_ptr, unsigned int data_len,
943 void *sig_ptr, unsigned int sig_len,
944 void *sig_alg, unsigned int sig_alg_len,
945 void *pk_ptr, unsigned int pk_len);
946 int verify_hash(void *data_ptr, unsigned int data_len,
947 void *digest_info_ptr, unsigned int digest_info_len);
Sumit Gargc0c369c2019-11-15 18:47:53 +0530948 int auth_decrypt(enum crypto_dec_algo dec_algo, void *data_ptr,
949 size_t len, const void *key, unsigned int key_len,
950 unsigned int key_flags, const void *iv,
951 unsigned int iv_len, const void *tag,
952 unsigned int tag_len)
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100953
Justin Chadwell82b06b32019-07-29 17:18:21 +0100954The mbedTLS library algorithm support is configured by both the
955``TF_MBEDTLS_KEY_ALG`` and ``TF_MBEDTLS_KEY_SIZE`` variables.
956
957- ``TF_MBEDTLS_KEY_ALG`` can take in 3 values: `rsa`, `ecdsa` or `rsa+ecdsa`.
958 This variable allows the Makefile to include the corresponding sources in
959 the build for the various algorithms. Setting the variable to `rsa+ecdsa`
960 enables support for both rsa and ecdsa algorithms in the mbedTLS library.
961
962- ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values
963 include 1024, 2048, 3072 and 4096.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100964
Sumit Gargc0c369c2019-11-15 18:47:53 +0530965- ``TF_MBEDTLS_USE_AES_GCM`` enables the authenticated decryption support based
966 on AES-GCM algorithm. Valid values are 0 and 1.
967
Paul Beesleyba3ed402019-03-13 16:20:44 +0000968.. note::
969 If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
970 be defined in the platform Makefile. It will make mbed TLS use an
971 implementation of SHA-256 with smaller memory footprint (~1.5 KB less) but
972 slower (~30%).
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100973
974--------------
975
Sandrine Bailleuxaf0f9602020-03-02 13:09:22 +0100976*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100977
Sandrine Bailleux30918422019-04-24 10:41:24 +0200978.. _TBBR-Client specification: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a