docs/design/auth-framework.rst

4 The aim of this document is to describe the authentication framework
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
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
18    -  The mechanism used to verify the transported information i.e. the
63 the abstraction mechanisms available to specify a Chain of Trust.
69 behind them. These aspects are key to verify a Chain of Trust.
76 illustrates how this maps to a CoT for the BL31 image described in the
126 authentication image contains information to authenticate a data image or
134 performed to verify it:
145    be used to authenticate the next image in the CoT.
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
175 #. Providing additional information to the IPM to enable it to identify and
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
196 #. Providing the necessary abstraction mechanisms to describe a CoT. Amongst
205    Key Certificate in the TBBR-Client spec. contains information to verify
208    trivial to implement).
210 #. Reusing memory meant for a data image to verify authentication images e.g.
213    time BL31 (the data image) is loaded, all information to authenticate it
216    never exceed the size of a data image. It should be possible to verify this
222 The CM is responsible for providing an API to:
228 external library to perform the cryptographic operations. A Crypto-Library (CL)
236                             /* Data to verify. */
247                             /* Data to hash. */
249                             /* Buffer to store the output. */
252                             /* Data to verify. */
259                             /* Data to decrypt. */
285 The ``_init`` function is used to perform any initialization required for
288 The ``_verify_signature`` function is used to verify certificates,
289 and ``_verify_hash`` is used to verify raw images.
292 and ``DRTM_SUPPORT`` features to calculate the hashes of various images/data.
294 The ``_auth_decrypt`` function uses an authentication tag to perform
298 ``ENCRYPT_BL32`` are set to ``1`` and ``DECRYPTION_SUPPORT`` is
299 set to ``aes_gcm``.
301 Optionally, a platform function can be provided to convert public key
305 Defining this function allows to transform the ROTPK used to verify
306 the signature to the buffer (a platform specific public key) which
315 -  ``full_pk_ptr``: Pointer to Distinguished Encoding Rules (DER) ROTPK.
317 -  ``hashed_pk_ptr``: to return a pointer to a buffer, which hash should be the one saved in OTP.
331 The IPM allows to register an Image Parser Library (IPL) for every image format
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
337 mechanism the IPM provides to define and register IPLs.
347 The platform may specify these methods in the CoT in case it decides to define
358    #. A pointer to data to hash
360    #. A pointer to the hash
373    This ASN.1 structure makes it possible to remove any assumption about the
375    should allow the Cryptography Library (CL) to support multiple hash
382    #. A pointer to data to sign
414 The authentication framework will use the image descriptor to extract all the
415 information related to authentication.
422 verified. Each image has a set of properties which allow the AM to verify it.
432 The parsing method refers to the format of a particular image. For example, an
435 or ELF format. The IPM supports three parsing methods. An image has to use one
437 single parsing method. There has to be one IPL for every method used by the
444 #. X509V3 method: This method uses industry standards like X.509 to represent
446    libraries will be available which can be used to parse an image represented
447    by this method. Such libraries can be used to write the corresponding IPL
451    proprietary standards to represent authentication or data images. For
452    example, The signature of a data image could be appended to the data image
453    raw binary. A header could be prepended to the combined blob to specify the
454    extents of each component. The platform will have to implement the
455    corresponding IPL to interpret such a format.
457 The following enum can be used to define these three methods.
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
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.
504 will be used by the IPM to find the right parser descriptor for the image.
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
523 uses this information to:
525 #. Specify to the ``get_auth_param()`` function exported by the IPM, which
531 #. Extract authentication parameters from a parent image in order to verify a
532    child image e.g. to verify the certificate image, the public key has to be
547 The AM defines the following structure to identify an authentication parameter
548 required to verify an image.
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
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
566 For each method, the AM defines a structure with the parameters required to
575         auth_param_type_desc_t *data;   /* Data to hash */
576         auth_param_type_desc_t *hash;   /* Hash to match with */
584         auth_param_type_desc_t *sig;    /* Signature to check */
589 The AM defines the following structure to describe an authentication method for
606 needs to access within the ``param`` union.
611 A parameter described by ``auth_param_type_desc_t`` to verify an image could be
615 to have memory allocated for them separately where they can be stored. This
618 The AM defines the following structure to store the data corresponding to an
629 field is used to specify the length of the data in the memory.
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
653    to locate the image in a FIP and load it in the memory reserved for the data
656 #. A parsing method which is used by the AM to find the appropriate IPM.
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
677 A CoT is defined as an array of pointers to ``auth_image_desc_t`` structures
685 the authentication framework. This example corresponds to the Applicative
687 recommended to read this guide along with the source code.
692 CoT specific to BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_bl1.c``
695 This CoT consists of an array of pointers to image descriptors and it is
698 type of indirection will cause the registration process to fail).
721 **Important**: the authentication module uses these identifiers to index the
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
738 -  ``parent``: pointer to the parent image descriptor. The parent will contain
739    the information required to authenticate the current image. If the parent
743 -  ``img_auth_methods``: this points to an array which defines the
744    authentication methods that must be checked to consider an image
747    will point to specific information required to extract that parameter from
749    cookie will point to the extension OID). Depending on the method type, a
758       -  ``data``: data to be hashed (obtained from current image)
769       -  ``data``: the data to be signed (obtained from current image)
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
784 be used to extract the parameter data from the corresponding image.
924 using the ROTPK. Four parameters are required to check a signature: the public
929    is used to extract a public key from the parent image. If the cookie is an
934 -  ``sig``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to extract
936 -  ``sig_alg``: parameter descriptor of type ``AUTH_PARAM_SIG``. It is used to
939    to extract the data to be signed from the certificate.
942 Trusted World public key needs to be extracted from the certificate. A new entry
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
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
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
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,
975 The image parser module relies on libraries to check the image integrity and
993 ``REGISTER_IMG_PARSER_LIB()``. Each time the image parser module needs to access
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
1004 The cryptographic module relies on a library to perform essential operations
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.
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
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`