libavb_aftl/avb_aftl_verify.h

/*
 * Copyright (C) 2020 The Android Open Source Project
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
#if !defined(AVB_INSIDE_LIBAVB_AFTL_H) && !defined(AVB_COMPILATION)
#error "Never include this file directly, include libavb_aftl.h instead."
#endif

#ifndef AVB_AFTL_VERIFY_H_
#define AVB_AFTL_VERIFY_H_

#include <libavb/libavb.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
  // When the verification succeeded.
  AFTL_SLOT_VERIFY_RESULT_OK,

  // If at some point during the verification, a memory allocation failed. This
  // could be the case when handling a large number of log keys or inclusion
  // proofs.
  AFTL_SLOT_VERIFY_RESULT_ERROR_OOM,

  // If at some point during the verification, we were not able to access some
  // devices. This can be the case when reading the AftlImage from the
  // partition.
  AFTL_SLOT_VERIFY_RESULT_ERROR_IO,

  // The VBMeta hash in the inclusion proof is not matching the VBMeta image
  // hash.
  AFTL_SLOT_VERIFY_RESULT_ERROR_VBMETA_HASH_MISMATCH,

  // The root hash of the reconstructed tree do not match the value contained in
  // the inclusion proof.
  AFTL_SLOT_VERIFY_RESULT_ERROR_TREE_HASH_MISMATCH,

  // The inclusion proof signature cannot be verified by the given key.
  AFTL_SLOT_VERIFY_RESULT_ERROR_INVALID_PROOF_SIGNATURE,

  // A generic error occurred during the verification.
  AFTL_SLOT_VERIFY_RESULT_ERROR_VERIFICATION,

  // At least one of the VBMetas did not have an AftlImage attached.
  AFTL_SLOT_VERIFY_RESULT_ERROR_IMAGE_NOT_FOUND,

  // Some content of one of the AFTLImages was found corrupted.
  AFTL_SLOT_VERIFY_RESULT_ERROR_INVALID_IMAGE,

  // Returned if the caller passed invalid parameters, for example if the prior
  // call to avb_slot_verify failed.
  AFTL_SLOT_VERIFY_RESULT_ERROR_INVALID_ARGUMENT

} AftlSlotVerifyResult;

/* The entry point of AFTL validation. It uses the AvbSlotVerifyData structure,
 * |slot_verify_data|, generated by a prior call to the avb_slot_verify
 * function, and a transparency log key to validate the inclusion proof(s)
 * attached to each VBMeta images.
 *
 * The caller is responsible for ensuring that the previous call to
 * avb_slot_verify succeeded. If |slot_verify_data| is incomplete or NULL,
 * AFTL_SLOT_VERIFY_RESULT_ERROR_INVALID_ARGUMENT will be returned.
 *
 * The AftlImage structure is located after the VBMetaImage structure. Uses
 * |ops| to read the partition where the VBMeta was loaded from.
 *
 * For each inclusion proof found, the following three validation steps are
 * performed:
 *   1. Match the VBMeta image hash with the hash in the tree leaf.
 *   2. Match the root hash of the Merkle tree with the hash in the proof.
 *   3. Verify the signature of the proof using the transparency log public key.
 * See the definition of AftlSlotVerifyResult for all the possible return
 * values.
 */

AftlSlotVerifyResult aftl_slot_verify(AvbOps* ops,
                                      AvbSlotVerifyData* slot_verify_data,
                                      uint8_t* key_bytes,
                                      size_t key_size);
#ifdef __cplusplus
}
#endif

#endif /* AVB_AFTL_VERIFY_H_ */