1*5b69db07SJason Zhu /* 2*5b69db07SJason Zhu * Copyright (C) 2016 The Android Open Source Project 3*5b69db07SJason Zhu * 4*5b69db07SJason Zhu * Permission is hereby granted, free of charge, to any person 5*5b69db07SJason Zhu * obtaining a copy of this software and associated documentation 6*5b69db07SJason Zhu * files (the "Software"), to deal in the Software without 7*5b69db07SJason Zhu * restriction, including without limitation the rights to use, copy, 8*5b69db07SJason Zhu * modify, merge, publish, distribute, sublicense, and/or sell copies 9*5b69db07SJason Zhu * of the Software, and to permit persons to whom the Software is 10*5b69db07SJason Zhu * furnished to do so, subject to the following conditions: 11*5b69db07SJason Zhu * 12*5b69db07SJason Zhu * The above copyright notice and this permission notice shall be 13*5b69db07SJason Zhu * included in all copies or substantial portions of the Software. 14*5b69db07SJason Zhu * 15*5b69db07SJason Zhu * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 16*5b69db07SJason Zhu * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 17*5b69db07SJason Zhu * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 18*5b69db07SJason Zhu * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 19*5b69db07SJason Zhu * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 20*5b69db07SJason Zhu * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 21*5b69db07SJason Zhu * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22*5b69db07SJason Zhu * SOFTWARE. 23*5b69db07SJason Zhu */ 24*5b69db07SJason Zhu 25*5b69db07SJason Zhu /* 26*5b69db07SJason Zhu #if !defined(AVB_INSIDE_LIBAVB_H) && !defined(AVB_COMPILATION) 27*5b69db07SJason Zhu #error "Never include this file directly, include libavb.h instead." 28*5b69db07SJason Zhu #endif 29*5b69db07SJason Zhu */ 30*5b69db07SJason Zhu 31*5b69db07SJason Zhu #ifndef AVB_DESCRIPTOR_H_ 32*5b69db07SJason Zhu #define AVB_DESCRIPTOR_H_ 33*5b69db07SJason Zhu 34*5b69db07SJason Zhu #include <android_avb/avb_sysdeps.h> 35*5b69db07SJason Zhu 36*5b69db07SJason Zhu #ifdef __cplusplus 37*5b69db07SJason Zhu extern "C" { 38*5b69db07SJason Zhu #endif 39*5b69db07SJason Zhu 40*5b69db07SJason Zhu /* Well-known descriptor tags. 41*5b69db07SJason Zhu * 42*5b69db07SJason Zhu * AVB_DESCRIPTOR_TAG_PROPERTY: see |AvbPropertyDescriptor| struct. 43*5b69db07SJason Zhu * AVB_DESCRIPTOR_TAG_HASHTREE: see |AvbHashtreeDescriptor| struct. 44*5b69db07SJason Zhu * AVB_DESCRIPTOR_TAG_HASH: see |AvbHashDescriptor| struct. 45*5b69db07SJason Zhu * AVB_DESCRIPTOR_TAG_KERNEL_CMDLINE: see |AvbKernelCmdlineDescriptor| struct. 46*5b69db07SJason Zhu * AVB_DESCRIPTOR_TAG_CHAIN_PARTITION: see |AvbChainPartitionDescriptor| struct. 47*5b69db07SJason Zhu */ 48*5b69db07SJason Zhu typedef enum { 49*5b69db07SJason Zhu AVB_DESCRIPTOR_TAG_PROPERTY, 50*5b69db07SJason Zhu AVB_DESCRIPTOR_TAG_HASHTREE, 51*5b69db07SJason Zhu AVB_DESCRIPTOR_TAG_HASH, 52*5b69db07SJason Zhu AVB_DESCRIPTOR_TAG_KERNEL_CMDLINE, 53*5b69db07SJason Zhu AVB_DESCRIPTOR_TAG_CHAIN_PARTITION, 54*5b69db07SJason Zhu } AvbDescriptorTag; 55*5b69db07SJason Zhu 56*5b69db07SJason Zhu /* The header for a serialized descriptor. 57*5b69db07SJason Zhu * 58*5b69db07SJason Zhu * A descriptor always have two fields, a |tag| (denoting its type, 59*5b69db07SJason Zhu * see the |AvbDescriptorTag| enumeration) and the size of the bytes 60*5b69db07SJason Zhu * following, |num_bytes_following|. 61*5b69db07SJason Zhu * 62*5b69db07SJason Zhu * For padding, |num_bytes_following| is always a multiple of 8. 63*5b69db07SJason Zhu */ 64*5b69db07SJason Zhu typedef struct AvbDescriptor { 65*5b69db07SJason Zhu uint64_t tag; 66*5b69db07SJason Zhu uint64_t num_bytes_following; 67*5b69db07SJason Zhu } AVB_ATTR_PACKED AvbDescriptor; 68*5b69db07SJason Zhu 69*5b69db07SJason Zhu /* Copies |src| to |dest| and validates, byte-swapping fields in the 70*5b69db07SJason Zhu * process if needed. Returns true if valid, false if invalid. 71*5b69db07SJason Zhu * 72*5b69db07SJason Zhu * Data following the struct is not validated nor copied. 73*5b69db07SJason Zhu */ 74*5b69db07SJason Zhu bool avb_descriptor_validate_and_byteswap( 75*5b69db07SJason Zhu const AvbDescriptor* src, AvbDescriptor* dest) AVB_ATTR_WARN_UNUSED_RESULT; 76*5b69db07SJason Zhu 77*5b69db07SJason Zhu /* Signature for callback function used in avb_descriptor_foreach(). 78*5b69db07SJason Zhu * The passed in descriptor is given by |descriptor| and the 79*5b69db07SJason Zhu * |user_data| passed to avb_descriptor_foreach() function is in 80*5b69db07SJason Zhu * |user_data|. Return true to continue iterating, false to stop 81*5b69db07SJason Zhu * iterating. 82*5b69db07SJason Zhu * 83*5b69db07SJason Zhu * Note that |descriptor| points into the image passed to 84*5b69db07SJason Zhu * avb_descriptor_foreach() - all fields need to be byteswapped! 85*5b69db07SJason Zhu */ 86*5b69db07SJason Zhu typedef bool AvbDescriptorForeachFunc(const AvbDescriptor* descriptor, 87*5b69db07SJason Zhu void* user_data); 88*5b69db07SJason Zhu 89*5b69db07SJason Zhu /* Convenience function to iterate over all descriptors in an vbmeta 90*5b69db07SJason Zhu * image. 91*5b69db07SJason Zhu * 92*5b69db07SJason Zhu * The function given by |foreach_func| will be called for each 93*5b69db07SJason Zhu * descriptor. The given function should return true to continue 94*5b69db07SJason Zhu * iterating, false to stop. 95*5b69db07SJason Zhu * 96*5b69db07SJason Zhu * The |user_data| parameter will be passed to |foreach_func|. 97*5b69db07SJason Zhu * 98*5b69db07SJason Zhu * Returns false if the iteration was short-circuited, that is if 99*5b69db07SJason Zhu * an invocation of |foreach_func| returned false. 100*5b69db07SJason Zhu * 101*5b69db07SJason Zhu * Before using this function, you MUST verify |image_data| with 102*5b69db07SJason Zhu * avb_vbmeta_image_verify() and reject it unless it's signed by a known 103*5b69db07SJason Zhu * good public key. Additionally, |image_data| must be word-aligned. 104*5b69db07SJason Zhu */ 105*5b69db07SJason Zhu bool avb_descriptor_foreach(const uint8_t* image_data, 106*5b69db07SJason Zhu size_t image_size, 107*5b69db07SJason Zhu AvbDescriptorForeachFunc foreach_func, 108*5b69db07SJason Zhu void* user_data); 109*5b69db07SJason Zhu 110*5b69db07SJason Zhu /* Gets all descriptors in a vbmeta image. 111*5b69db07SJason Zhu * 112*5b69db07SJason Zhu * The return value is a NULL-pointer terminated array of 113*5b69db07SJason Zhu * AvbDescriptor pointers. Free with avb_free() when you are done with 114*5b69db07SJason Zhu * it. If |out_num_descriptors| is non-NULL, the number of descriptors 115*5b69db07SJason Zhu * will be returned there. 116*5b69db07SJason Zhu * 117*5b69db07SJason Zhu * Note that each AvbDescriptor pointer in the array points into 118*5b69db07SJason Zhu * |image_data| - all fields need to be byteswapped! 119*5b69db07SJason Zhu * 120*5b69db07SJason Zhu * Before using this function, you MUST verify |image_data| with 121*5b69db07SJason Zhu * avb_vbmeta_image_verify() and reject it unless it's signed by a known 122*5b69db07SJason Zhu * good public key. Additionally, |image_data| must be word-aligned. 123*5b69db07SJason Zhu */ 124*5b69db07SJason Zhu const AvbDescriptor** avb_descriptor_get_all(const uint8_t* image_data, 125*5b69db07SJason Zhu size_t image_size, 126*5b69db07SJason Zhu size_t* out_num_descriptors) 127*5b69db07SJason Zhu AVB_ATTR_WARN_UNUSED_RESULT; 128*5b69db07SJason Zhu 129*5b69db07SJason Zhu #ifdef __cplusplus 130*5b69db07SJason Zhu } 131*5b69db07SJason Zhu #endif 132*5b69db07SJason Zhu 133*5b69db07SJason Zhu #endif /* AVB_DESCRIPTOR_H_ */ 134