docs/design/auth-framework.rst

4 The aim of this document is to describe the authentication framework
5 implemented in Trusted Firmware-A (TF-A). This framework fulfills the
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
18    -  The mechanism used to verify the transported information i.e. the
21 The framework has been designed following a modular approach illustrated in the
62 This document describes the inner details of the authentication framework and
63 the abstraction mechanisms available to specify a Chain of Trust.
68 This section describes some aspects of the framework design and the rationale
76 illustrates how this maps to a CoT for the BL31 image described in the
119 The root of trust is usually a public key (ROTPK) that has been burnt in the
133 For every image in a Chain of Trust, the following high level operations are
136 #. Allocate memory for the image either statically or at runtime.
138 #. Identify the image and load it in the allocated memory.
140 #. Check the integrity of the image as per its type.
142 #. Authenticate the image as per the cryptographic algorithms used.
144 #. If the image is an authentication image, extract the information that will
145    be used to authenticate the next image in the CoT.
153 These components are responsible for initiating the authentication process for a
155 the Generic code asks recursively the Authentication module what is the parent
156 image until either an authenticated image or the ROT is reached. Then the
157 Generic code calls the IO framework to load the image and calls the
158 Authentication module to authenticate it, following the CoT from ROT to Image.
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
171    used for verifying the CoT, e.g. memory for public keys, hashes etc.
173 #. Providing the ROTPK or a hash of it.
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
180 #. Fulfill any other memory requirements of the IPM and the CM (not currently
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.
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.
200 #. Verifying the CoT passed by GEN by utilising functionality exported by the
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
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
228 external library to perform the cryptographic operations. A Crypto-Library (CL)
229 linking the CM and the external library must be implemented. The following
230 functions must be provided by the CL:
238                             /* Bit string of the signature in DER format. */
249                             /* Buffer to store the output. */
257                             /* Currently AES-GCM is the only supported alg. */
269 The above functions return values from the enum ``crypto_ret_value``.
270 The functions are registered in the CM using the macro:
282 ``_name`` must be a string containing the name of the CL. This name is used for
286 the specific CM and CL.
291 The ``_calc_hash`` function is mainly used in the ``MEASURED_BOOT``
292 and ``DRTM_SUPPORT`` features to calculate the hashes of various images/data.
295 authenticated decryption, providing guarantees on the authenticity
296 of encrypted data. This function is used when the optional encrypted
302 (_convert_pk). It is only used if the platform saves a hash of the ROTPK.
303 Most platforms save the hash of the ROTPK, but some may save slightly different
304 information - e.g the hash of the ROTPK plus some related information.
305 Defining this function allows to transform the ROTPK used to verify
306 the signature to the buffer (a platform specific public key) which
317 -  ``hashed_pk_ptr``: to return a pointer to a buffer, which hash should be the one saved in OTP.
325 #. Checking the integrity of each image loaded by the IO framework.
327    description provided by the platform in the CoT descriptor.
332 used in the CoT. This library must implement the specific methods to parse the
333 image. The IPM obtains the image format from the CoT and calls the right IPL to
334 check the image integrity and extract the authentication parameters.
336 See Section "Describing the image parsing methods" for more details about the
337 mechanism the IPM provides to define and register IPLs.
342 The AM supports the following authentication methods:
347 The platform may specify these methods in the CoT in case it decides to define
350 If a data image uses multiple methods, then all the methods must be a part of
351 the same CoT. The number and type of parameters are method specific. These
352 parameters should be obtained from the parent image using the IPM.
359    #. Length of the data
360    #. A pointer to the hash
361    #. Length of the hash
363    The hash will be represented by the DER encoding of the following ASN.1
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
383    #. Length of the data
389    The Public Key parameters will be represented by the DER encoding of the
398    The Digital Signature Algorithm will be represented by the DER encoding of
399    the following ASN.1 types.
414 The authentication framework will use the image descriptor to extract all the
421 particular order. The order dictates the sequence in which they must be
422 verified. Each image has a set of properties which allow the AM to verify it.
426 Unless otherwise specified, the data structures described in the following
427 sections are populated by the PP statically.
429 Describing the image parsing methods
432 The parsing method refers to the format of a particular image. For example, an
433 authentication image that represents a certificate could be in the X.509v3
436 of the three methods described below. An IPL is responsible for interpreting a
437 single parsing method. There has to be one IPL for every method used by the
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.
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
468 An IPL must provide functions with the following prototypes:
478 An IPL for each type must be registered using the following macro:
484 -  ``_type``: one of the types described above.
485 -  ``_name``: a string containing the IPL name for debugging purposes.
490 The ``init()`` function will be used to initialize the IPL.
492 The ``check_integrity()`` function is passed a pointer to the memory where the
493 image has been loaded by the IO framework and the image length. It should ensure
494 that the image is in the format corresponding to the parsing method and has not
499 information about the parameter (``type_desc`` and ``cookie``) to identify and
500 extract the data corresponding to that parameter from an image. This data will
501 be used to verify either the current or the next image in the CoT sequence.
503 Each image in the CoT will specify the parsing method it uses. This information
504 will be used by the IPM to find the right parser descriptor for the image.
506 Describing the authentication method(s)
509 As part of the CoT, each image has to specify one or more authentication methods
510 which will be used to verify it. As described in the Section "Authentication
511 methods", there are three methods supported by the AM.
522 The AM defines the type of each parameter used by an authentication method. It
525 #. Specify to the ``get_auth_param()`` function exported by the IPM, which
528 #. Correctly marshall the parameters while calling the verification function
529    exported by the CM and PP.
532    child image e.g. to verify the certificate image, the public key has to be
533    obtained from the parent image.
542         AUTH_PARAM_HASH,        /* A hash (including the algorithm) */
547 The AM defines the following structure to identify an authentication parameter
557 ``cookie`` is used by the platform to specify additional information to the IPM
558 which enables it to uniquely identify the parameter that should be extracted
559 from an image. For example, the hash of a BL3x image in its corresponding
561 field can only be identified using an OID. In this case, the ``cookie`` could
562 contain the pointer to the OID defined by the platform for the hash extension
563 field while the ``type`` field could be set to ``AUTH_PARAM_HASH``. A value of 0 for
564 the ``cookie`` field means that it is not used.
566 For each method, the AM defines a structure with the parameters required to
567 verify the image.
589 The AM defines the following structure to describe an authentication method for
605 Using the method type specified in the ``type`` field, the AM finds out what field
606 needs to access within the ``param`` union.
612 obtained from either the image itself or its parent image. The memory allocated
613 for loading the parent image will be reused for loading the child image. Hence
614 parameters which are obtained from the parent for verifying a child image need
616 memory must be statically allocated by the platform port.
618 The AM defines the following structure to store the data corresponding to an
628 The ``auth_param_ptr`` field is initialized by the platform. The ``auth_param_len``
629 field is used to specify the length of the data in the memory.
631 For parameters that can be obtained from the child image itself, the IPM is
632 responsible for populating the ``auth_param_ptr`` and ``auth_param_len`` fields
633 while executing the ``img_get_auth_param()`` function.
635 The AM defines the following structure to enable an image to describe the
636 parameters that should be extracted from it and used to verify the next image
649 An image in a CoT is a consolidation of the following aspects of a CoT described
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.
656 #. A parsing method which is used by the AM to find the appropriate IPM.
658 #. Authentication methods and their parameters as described in the previous
659    section. These are used to verify the current image.
661 #. Parameters which are used to verify the next image in the current CoT. These
663    from the current image once it has been verified.
678 linked together by the ``parent`` field. Those nodes with no parent must be
679 authenticated using the ROTPK stored in the platform.
685 the authentication framework. This example corresponds to the Applicative
686 Functional Mode (AFM) as specified in the TBBR-Client document. It is
687 recommended to read this guide along with the source code.
696 registered 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
698 type of indirection will cause the registration process to fail).
700 The number of images participating in the boot process depends on the CoT.
710 The TBBR specifies the additional certificates that must accompany these images
711 for a proper authentication. Details about the TBBR CoT may be found in the
714 Following the :ref:`Porting Guide`, a platform must provide unique
715 identifiers for all the images and certificates that will be loaded during the
716 boot process. If a platform is using the TBBR as a reference for trusted boot,
721 **Important**: the authentication module uses these identifiers to index the
722 CoT array, so the descriptors location in the array must match the identifiers.
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
732       other than reading the whole image.
734       type for custom images not directly supported by the authentication
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
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
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
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
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)
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.
777 In the ``tbbr_cot*.c`` file, a set of buffers are allocated to store the parameters
778 extracted from the certificates. In the case of the TBBR CoT, these parameters
780 bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication
781 process, some of the buffers may be reused at different stages during the boot.
783 Next in that file, the parameter descriptors are defined. These descriptors will
784 be used to extract the parameter data from the corresponding image.
786 Example: the BL31 Chain of Trust
789 Four image descriptors form the BL31 Chain of Trust:
918 The **Trusted Key certificate** is signed with the ROT private key and contains
919 the Trusted World public key and the Non-Trusted World public key as x509v3
920 extensions. This must be specified in the image descriptor using the
924 using the ROTPK. Four parameters are required to check a signature: the public
925 key, the algorithm, the signature and the data that has been signed. Therefore,
926 four parameter descriptors must be specified with the authentication method:
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).
935    the signature from the certificate.
937    extract the signature algorithm from the certificate.
939    to extract the data to be signed from the certificate.
941 Once the signature has been checked and the certificate authenticated, the
942 Trusted World public key needs to be extracted from the certificate. A new entry
943 is created in the ``authenticated_data`` array for that purpose. In that entry,
944 the corresponding parameter descriptor must be specified along with the buffer
945 address to store the parameter value. In this case, the ``trusted_world_pk``
946 descriptor is used to extract the public key from an x509v3 extension with OID
948 parameter in the signature authentication method. The key is stored in the
952 using the Trusted World public key obtained previously from the Trusted Key
953 certificate. In the image descriptor, we specify a single authentication method
954 by signature whose public key is the ``trusted_world_pk``. Once this certificate
955 has been authenticated, we have to extract the BL31 public key, stored in the
956 extension specified by ``soc_fw_content_pk``. This key will be copied to the
960 using the BL31 public key obtained previously from the BL31 Key certificate.
961 We specify the authentication method using ``soc_fw_content_pk`` as public key.
962 After authentication, we need to extract the BL31 hash, stored in the extension
963 specified by ``soc_fw_hash``. This hash will be copied to the
967 with the hash obtained from the BL31 certificate. The image descriptor contains
968 a single authentication method by hash. The parameters to the hash method are
969 the reference hash, ``soc_fw_hash``, and the data to be hashed. In this case,
970 it is the whole image, so we specify ``raw_data``.
975 The image parser module relies on libraries to check the image integrity and
976 extract the authentication parameters. The number and type of parser libraries
977 depend on the images used in the CoT. Raw images do not need a library, so
978 only an x509v3 library is required for the TBBR CoT.
992 The library is registered in the framework using the macro
993 ``REGISTER_IMG_PARSER_LIB()``. Each time the image parser module needs to access
994 an image of type ``IMG_CERT``, it will call the corresponding function exported
997 The build system must be updated to include the corresponding library and
998 mbed TLS sources. Arm platforms use the ``arm_common.mk`` file to pull the
1010 ``mbedtls_psa_crypto.c`` will replace ``mbedtls_crypto.c`` as the default Arm
1011 CM. Both libraries are registered in the authentication framework using
1012 the macro ``REGISTER_CRYPTO_LIB()``. These libraries implement the following
1023      - Initialize the heap for mbedTLS.
1024      - Initialize the heap for mbedTLS and call ``psa_crypto_init``.
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.
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.
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.
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.
1043 The mbedTLS library algorithm support is configured by both the
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.
1051 -  ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values
1054 -  ``TF_MBEDTLS_USE_AES_GCM`` enables the authenticated decryption support based
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