blob: 765d9f89b98f541f4b23373fda8a3daa1e3ce230 [file] [log] [blame]
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001Abstracting 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 key algorithm (rsa, ecdsa) must be specified in the build system using the
925``TF_MBEDTLS_KEY_ALG`` variable, so the Makefile can include the corresponding
926sources in the build.
927
928Note: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
929be defined in the platform Makefile. It will make mbed TLS use an implementation
930of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
931
932--------------
933
934*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.*
935
936.. _Trusted Board Boot: ./trusted-board-boot.rst
937.. _Platform Porting Guide: ./porting-guide.rst