docs/design/auth-framework.rst

8 #. It should be possible for a platform port to specify the Chain of Trust in
120 platform and cannot be modified.
128 it could be any other data that requires authentication.
145    be used to authenticate the next image in the CoT.
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
177    parameters are stored as X509v3 extensions, the corresponding OID must be
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
197    other things, the authentication and image parsing methods must be specified
204    multiple CoTs then it should be verified only once e.g. the Trusted World
207    responsibility has not been described in this document but should be
211    in the CoT described in Diagram 2, each certificate can be loaded and
216    never exceed the size of a data image. It should be possible to verify this
229 linking the CM and the external library must be implemented. The following
230 functions must be provided by the CL:
245                             /* SHA256, SHA384 and SHA512 can be used. */
282 ``_name`` must be a string containing the name of the CL. This name is used for
301 Optionally, a platform function can be provided to convert public key
317 -  ``hashed_pk_ptr``: to return a pointer to a buffer, which hash should be the one saved in OTP.
329 Images may have different formats (for example, authentication images could be
350 If a data image uses multiple methods, then all the methods must be a part of
352 parameters should be obtained from the parent image using the IPM.
363    The hash will be represented by the DER encoding of the following ASN.1
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
408    The digital signature will be represented by:
420 A CoT can be described as a set of image descriptors linked together in a
421 particular order. The order dictates the sequence in which they must be
433 authentication image that represents a certificate could be in the X.509v3
434 format. A data image that represents a boot loader stage could be in raw binary
437 single parsing method. There has to be one IPL for every method used by the
442    TF-A. This method should only be used by data images.
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
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
457 The following enum can be used to define these three methods.
478 An IPL for each type must be registered using the following macro:
490 The ``init()`` function will be used to initialize the IPL.
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.
510 which will be used to verify it. As described in the Section "Authentication
526    parameter should be extracted from an image.
532    child image e.g. to verify the certificate image, the public key has to be
558 which enables it to uniquely identify the parameter that should be extracted
561 field can only be identified using an OID. In this case, the ``cookie`` could
563 field while the ``type`` field could be set to ``AUTH_PARAM_HASH``. A value of 0 for
611 A parameter described by ``auth_param_type_desc_t`` to verify an image could be
613 for loading the parent image will be reused for loading the child image. Hence
615 to have memory allocated for them separately where they can be stored. This
616 memory must be statically allocated by the platform port.
631 For parameters that can be obtained from the child image itself, the IPM is
636 parameters that should be extracted from it and used to verify the next image
662    parameters are specified only by authentication images and can be extracted
678 linked together by the ``parent`` field. Those nodes with no parent must be
692 CoT specific to BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_bl1.c``
694 BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_common.c``.
697 ``cot_desc`` must be the name of the array (passing a pointer or any other
711 for a proper authentication. Details about the TBBR CoT may be found in the
715 identifiers for all the images and certificates that will be loaded during the
717 these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``.
740    is NULL, the authentication parameters will be obtained from the platform
744    authentication methods that must be checked to consider an image
750    different number of parameters must be specified. This pointer should not be
755       from the parent image. The following parameter descriptors must be
758       -  ``data``: data to be hashed (obtained from current image)
761    -  ``AUTH_METHOD_SIG``: the image (usually a certificate) must be signed with
764       must be specified:
769       -  ``data``: the data to be signed (obtained from current image)
772    parameters must be extracted from an image once it has been authenticated.
775    the required memory to store the parameters. This pointer may be NULL.
781 process, some of the buffers may be reused at different stages during the boot.
784 be used to extract the parameter data from the corresponding image.
920 extensions. This must be specified in the image descriptor using the
926 four parameter descriptors must be specified with the authentication method:
933    (this key will be the ROTPK).
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
944 the corresponding parameter descriptor must be specified along with the buffer
956 extension specified by ``soc_fw_content_pk``. This key will be copied to the
963 specified by ``soc_fw_hash``. This hash will be copied to the
969 the reference hash, ``soc_fw_hash``, and the data to be hashed. In this case,
980 Arm platforms will use an x509v3 library based on mbed TLS. This library may be
997 The build system must be updated to include the corresponding library and
1034        and then compare it against the data which is to be verified.
1036        compares this hash against the data to be verified.
1059    be defined in the platform Makefile. It will make mbed TLS use an