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