xref: /rk3399_rockchip-uboot/include/android_avb/avb_ops.h (revision 5b69db0720b90f33ecb7fb666b196bfc90404185)

/*
 * Copyright (C) 2016 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_H) && !defined(AVB_COMPILATION)
#error "Never include this file directly, include libavb.h instead."
#endif
*/

#ifndef AVB_OPS_H_
#define AVB_OPS_H_

#include <android_avb/avb_sysdeps.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Return codes used for I/O operations.
 *
 * AVB_IO_RESULT_OK is returned if the requested operation was
 * successful.
 *
 * AVB_IO_RESULT_ERROR_IO is returned if the underlying hardware (disk
 * or other subsystem) encountered an I/O error.
 *
 * AVB_IO_RESULT_ERROR_OOM is returned if unable to allocate memory.
 *
 * AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION is returned if the requested
 * partition does not exist.
 *
 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION is returned if the
 * range of bytes requested to be read or written is outside the range
 * of the partition.
 */
typedef enum {
	AVB_IO_RESULT_OK,
	AVB_IO_RESULT_ERROR_OOM,
	AVB_IO_RESULT_ERROR_IO,
	AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION,
	AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION
} AvbIOResult;

struct AvbOps;
typedef struct AvbOps AvbOps;

/* Forward-declaration of operations in libavb_ab. */
struct AvbABOps;

/* Forward-declaration of operations in libavb_atx. */
struct AvbAtxOps;

/* High-level operations/functions/methods that are platform
 * dependent.
 *
 * Operations may be added in the future so when implementing it
 * always make sure to zero out sizeof(AvbOps) bytes of the struct to
 * ensure that unimplemented operations are set to NULL.
 */
struct AvbOps {
	/* This pointer can be used by the application/bootloader using
	 * libavb and is typically used in each operation to get a pointer
	 * to platform-specific resources. It cannot be used by libraries.
	 */
	void* user_data;

	/* If libavb_ab is used, this should point to the
	 * AvbABOps. Otherwise it must be set to NULL.
	 */
	struct AvbABOps* ab_ops;

	/* If libavb_atx is used, this should point to the
	 * AvbAtxOps. Otherwise it must be set to NULL.
	 */
	struct AvbAtxOps* atx_ops;

	/* Reads |num_bytes| from offset |offset| from partition with name
	 * |partition| (NUL-terminated UTF-8 string). If |offset| is
	 * negative, its absolute value should be interpreted as the number
	 * of bytes from the end of the partition.
	 *
	 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if
	 * there is no partition with the given name,
	 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested
	 * |offset| is outside the partition, and AVB_IO_RESULT_ERROR_IO if
	 * there was an I/O error from the underlying I/O subsystem.  If the
	 * operation succeeds as requested AVB_IO_RESULT_OK is returned and
	 * the data is available in |buffer|.
	 *
	 * The only time partial I/O may occur is if reading beyond the end
	 * of the partition. In this case the value returned in
	 * |out_num_read| may be smaller than |num_bytes|.
	 */
	AvbIOResult (*read_from_partition)(AvbOps* ops,
                                       const char* partition,
                                       int64_t offset,
                                       size_t num_bytes,
                                       void* buffer,
                                       size_t* out_num_read);

	/* Writes |num_bytes| from |bffer| at offset |offset| to partition
	 * with name |partition| (NUL-terminated UTF-8 string). If |offset|
	 * is negative, its absolute value should be interpreted as the
	 * number of bytes from the end of the partition.
	 *
	 * This function returns AVB_IO_RESULT_ERROR_NO_SUCH_PARTITION if
	 * there is no partition with the given name,
	 * AVB_IO_RESULT_ERROR_RANGE_OUTSIDE_PARTITION if the requested
	 * byterange goes outside the partition, and AVB_IO_RESULT_ERROR_IO
	 * if there was an I/O error from the underlying I/O subsystem.  If
	 * the operation succeeds as requested AVB_IO_RESULT_OK is
	 * returned.
	 *
	 * This function never does any partial I/O, it either transfers all
	 * of the requested bytes or returns an error.
	 */
	AvbIOResult (*write_to_partition)(AvbOps* ops,
                                      const char* partition,
                                      int64_t offset,
                                      size_t num_bytes,
                                      const void* buffer);

	/* Checks if the given public key used to sign the 'vbmeta'
	 * partition is trusted. Boot loaders typically compare this with
	 * embedded key material generated with 'avbtool
	 * extract_public_key'.
	 *
	 * The public key is in the array pointed to by |public_key_data|
	 * and is of |public_key_length| bytes.
	 *
	 * If there is no public key metadata (set with the avbtool option
	 * --public_key_metadata) then |public_key_metadata| will be set to
	 * NULL. Otherwise this field points to the data which is
	 * |public_key_metadata_length| bytes long.
	 *
	 * If AVB_IO_RESULT_OK is returned then |out_is_trusted| is set -
	 * true if trusted or false if untrusted.
	 */
	AvbIOResult (*validate_vbmeta_public_key)(AvbOps* ops,
                                            	  const uint8_t* public_key_data,
                                            	  size_t public_key_length,
                                            	  const uint8_t* public_key_metadata,
                                            	  size_t public_key_metadata_length,
                                            	  bool* out_is_trusted);

	/* Gets the rollback index corresponding to the location given by
	 * |rollback_index_location|. The value is returned in
	 * |out_rollback_index|. Returns AVB_IO_RESULT_OK if the rollback
	 * index was retrieved, otherwise an error code.
	 *
	 * A device may have a limited amount of rollback index locations (say,
	 * one or four) so may error out if |rollback_index_location| exceeds
	 * this number.
	 */
	AvbIOResult (*read_rollback_index)(AvbOps* ops,
                                     	   size_t rollback_index_location,
                                     	   uint64_t* out_rollback_index);

	/* Sets the rollback index corresponding to the location given by
	 * |rollback_index_location| to |rollback_index|. Returns
	 * AVB_IO_RESULT_OK if the rollback index was set, otherwise an
	 * error code.
	 *
	 * A device may have a limited amount of rollback index locations (say,
	 * one or four) so may error out if |rollback_index_location| exceeds
	 * this number.
	 */
	AvbIOResult (*write_rollback_index)(AvbOps* ops,
                                      	    size_t rollback_index_location,
                                      	    uint64_t rollback_index);

	/* Gets whether the device is unlocked. The value is returned in
	 * |out_is_unlocked| (true if unlocked, false otherwise). Returns
	 * AVB_IO_RESULT_OK if the state was retrieved, otherwise an error
	 * code.
	 */
	AvbIOResult (*read_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked);
	AvbIOResult (*write_is_device_unlocked)(AvbOps* ops, bool* out_is_unlocked);

	/* Gets the unique partition GUID for a partition with name in
	 * |partition| (NUL-terminated UTF-8 string). The GUID is copied as
	 * a string into |guid_buf| of size |guid_buf_size| and will be NUL
	 * terminated. The string must be lower-case and properly
	 * hyphenated. For example:
	 *
	 *  527c1c6d-6361-4593-8842-3c78fcd39219
	 *
	 * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
	 */
	 AvbIOResult (*get_unique_guid_for_partition)(AvbOps* ops,
                                                      const char* partition,
                                                      char* guid_buf,
                                                      size_t guid_buf_size);

	/* Gets the size of a partition with the name in |partition|
	 * (NUL-terminated UTF-8 string). Returns the value in
	 * |out_size_num_bytes|.
	 *
	 * Returns AVB_IO_RESULT_OK on success, otherwise an error code.
	 */
	AvbIOResult (*get_size_of_partition)(AvbOps* ops,
                                       	     const char* partition,
                                             uint64_t* out_size_num_bytes);
};

#ifdef __cplusplus
}
#endif

#endif /* AVB_OPS_H_ */