docs/design/auth-framework.rst

10    particular image/certificate.
75 a root of trust and culminates in a single data image. The following diagram
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
127 another authentication image. A data image is usually a boot loader binary, but
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.
154 particular image in BL1 or BL2. For each BL image that requires authentication,
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
165 #. Specifying the CoT for each image that needs to be authenticated. Details of
168    each image.
170 #. Statically allocating memory for each parameter in each image which is
176    extract authentication parameters contained in an image, e.g. if the
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
188 #. Export a custom IPM if a proprietary image format is being used (described
197    other things, the authentication and image parsing methods must be specified
203 #. Tracking which images have been verified. In case an image is a part of
210 #. Reusing memory meant for a data image to verify authentication images e.g.
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
325 #. Checking the integrity of each image loaded by the IO framework.
326 #. Extracting parameters used for authenticating an image based upon a
331 The IPM allows to register an Image Parser Library (IPL) for every image format
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
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.
414 The authentication framework will use the image descriptor to extract all the
420 A CoT can be described as a set of image descriptors linked together in a
422 verified. Each image has a set of properties which allow the AM to verify it.
425 The PP is responsible for defining a single or multiple CoTs for a data image.
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
434 format. A data image that represents a boot loader stage could be in raw binary
435 or ELF format. The IPM supports three parsing methods. An image has to use one
440 #. Raw format: This format is effectively a nop as an image using this method
446    libraries will be available which can be used to parse an image represented
452    example, The signature of a data image could be appended to the data image
462         IMG_RAW,            /* Binary image */
487 -  ``_check_int``: check image integrity function pointer.
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
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.
509 As part of the CoT, each image has to specify one or more authentication methods
526    parameter should be extracted from an image.
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
533    obtained from the parent image.
539         AUTH_PARAM_RAW_DATA,    /* Raw image data */
540         AUTH_PARAM_SIG,         /* The image signature */
541         AUTH_PARAM_SIG_ALG,     /* The image signature algorithm */
548 required to verify an image.
559 from an image. For example, the hash of a BL3x image in its corresponding
567 verify the image.
590 verifying an image
611 A parameter described by ``auth_param_type_desc_t`` to verify an image could be
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
631 For parameters that can be obtained from the child image itself, the IPM is
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
646 Describing an image in a CoT
649 An image in a CoT is a consolidation of the following aspects of a CoT described
653    to locate the image in a FIP and load it in the memory reserved for the data
654    image in the CoT.
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.
665 The following data structure describes an image in a CoT.
695 This CoT consists of an array of pointers to image descriptors and it is
724 Each image descriptor must specify:
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
731    -  ``IMG_RAW``: image is a raw binary. No parsing functions are available,
732       other than reading the whole image.
733    -  ``IMG_PLAT``: image format is platform specific. The platform may use this
736    -  ``IMG_CERT``: image is an x509v3 certificate.
738 -  ``parent``: pointer to the parent image descriptor. The parent will contain
739    the information required to authenticate the current image. If the parent
744    authentication methods that must be checked to consider an image
748    the image (i.e. if the parameter is stored in an x509v3 extension, the
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
758       -  ``data``: data to be hashed (obtained from current image)
759       -  ``hash``: reference hash (obtained from parent image)
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
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)
772    parameters must be extracted from an image once it has been authenticated.
784 be used to extract the parameter data from the corresponding image.
789 Four image descriptors form the BL31 Chain of Trust:
920 extensions. This must be specified in the image descriptor using the
929    is used to extract a public key from the parent image. If the cookie is an
932    the parent image is NULL, the public key is obtained from the platform
953 certificate. In the image descriptor, we specify a single authentication method
966 The **BL31 image** is authenticated by calculating its hash and matching it
967 with the hash obtained from the BL31 certificate. The image descriptor contains
970 it is the whole image, so we specify ``raw_data``.
972 The image parser library
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
994 an image of type ``IMG_CERT``, it will call the corresponding function exported