blob: cf0d745ae7e88752f2c94c00ee0d3635abb7adf9 [file] [log] [blame]
//
// Copyright (C) 2010 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Update file format: A delta update file contains all the deltas needed
// to update a system from one specific version to another specific
// version. The update format is represented by this struct pseudocode:
// struct delta_update_file {
// char magic[4] = "CrAU";
// uint64 file_format_version = 1;
// uint64 manifest_size; // Size of protobuf DeltaArchiveManifest
// // The Bzip2 compressed DeltaArchiveManifest
// char manifest[];
//
// // Data blobs for files, no specific format. The specific offset
// // and length of each data blob is recorded in the DeltaArchiveManifest.
// struct {
// char data[];
// } blobs[];
//
// // These two are not signed:
// uint64 signatures_message_size;
// char signatures_message[];
//
// };
// The DeltaArchiveManifest protobuf is an ordered list of InstallOperation
// objects. These objects are stored in a linear array in the
// DeltaArchiveManifest. Each operation is applied in order by the client.
// The DeltaArchiveManifest also contains the initial and final
// checksums for the device.
// The client will perform each InstallOperation in order, beginning even
// before the entire delta file is downloaded (but after at least the
// protobuf is downloaded). The types of operations are explained:
// - REPLACE: Replace the dst_extents on the drive with the attached data,
// zero padding out to block size.
// - REPLACE_BZ: bzip2-uncompress the attached data and write it into
// dst_extents on the drive, zero padding to block size.
// - MOVE: Copy the data in src_extents to dst_extents. Extents may overlap,
// so it may be desirable to read all src_extents data into memory before
// writing it out.
// - BSDIFF: Read src_length bytes from src_extents into memory, perform
// bspatch with attached data, write new data to dst_extents, zero padding
// to block size.
package chromeos_update_engine;
option optimize_for = LITE_RUNTIME;
// Data is packed into blocks on disk, always starting from the beginning
// of the block. If a file's data is too large for one block, it overflows
// into another block, which may or may not be the following block on the
// physical partition. An ordered list of extents is another
// representation of an ordered list of blocks. For example, a file stored
// in blocks 9, 10, 11, 2, 18, 12 (in that order) would be stored in
// extents { {9, 3}, {2, 1}, {18, 1}, {12, 1} } (in that order).
// In general, files are stored sequentially on disk, so it's more efficient
// to use extents to encode the block lists (this is effectively
// run-length encoding).
// A sentinel value (kuint64max) as the start block denotes a sparse-hole
// in a file whose block-length is specified by num_blocks.
// Signatures: Updates may be signed by the OS vendor. The client verifies
// an update's signature by hashing the entire download. The section of the
// download that contains the signature is at the end of the file, so when
// signing a file, only the part up to the signature part is signed.
// Then, the client looks inside the download's Signatures message for a
// Signature message that it knows how to handle. Generally, a client will
// only know how to handle one type of signature, but an update may contain
// many signatures to support many different types of client. Then client
// selects a Signature message and uses that, along with a known public key,
// to verify the download. The public key is expected to be part of the
// client.
message Extent {
optional uint64 start_block = 1;
optional uint64 num_blocks = 2;
}
message Signatures {
message Signature {
optional uint32 version = 1;
optional bytes data = 2;
}
repeated Signature signatures = 1;
}
message PartitionInfo {
optional uint64 size = 1;
optional bytes hash = 2;
}
// Describe an image we are based on in a human friendly way.
// Examples:
// dev-channel, x86-alex, 1.2.3, mp-v3
// nplusone-channel, x86-alex, 1.2.4, mp-v3, dev-channel, 1.2.3
//
// All fields will be set, if this message is present.
message ImageInfo {
optional string board = 1;
optional string key = 2;
optional string channel = 3;
optional string version = 4;
// If these values aren't present, they should be assumed to match
// the equivalent value above. They are normally only different for
// special image types such as nplusone images.
optional string build_channel = 5;
optional string build_version = 6;
}
message InstallOperation {
enum Type {
REPLACE = 0; // Replace destination extents w/ attached data
REPLACE_BZ = 1; // Replace destination extents w/ attached bzipped data
MOVE = 2; // Move source extents to destination extents
BSDIFF = 3; // The data is a bsdiff binary diff
// SOURCE_COPY and SOURCE_BSDIFF are only supported on minor version 2 or
// higher.
SOURCE_COPY = 4; // Copy from source to target partition
SOURCE_BSDIFF = 5; // Like BSDIFF, but read from source partition
// ZERO and DISCARD are only supported on minor version 3.
ZERO = 6; // Write zeros in the destination.
DISCARD = 7; // Discard the destination blocks, reading as undefined.
}
required Type type = 1;
// The offset into the delta file (after the protobuf)
// where the data (if any) is stored
optional uint32 data_offset = 2;
// The length of the data in the delta file
optional uint32 data_length = 3;
// Ordered list of extents that are read from (if any) and written to.
repeated Extent src_extents = 4;
// Byte length of src, equal to the number of blocks in src_extents *
// block_size. It is used for BSDIFF, because we need to pass that
// external program the number of bytes to read from the blocks we pass it.
// This is not used in any other operation.
optional uint64 src_length = 5;
repeated Extent dst_extents = 6;
// Byte length of dst, equal to the number of blocks in dst_extents *
// block_size. Used for BSDIFF, but not in any other operation.
optional uint64 dst_length = 7;
// Optional SHA 256 hash of the blob associated with this operation.
// This is used as a primary validation for http-based downloads and
// as a defense-in-depth validation for https-based downloads. If
// the operation doesn't refer to any blob, this field will have
// zero bytes.
optional bytes data_sha256_hash = 8;
// Indicates the SHA 256 hash of the source data referenced in src_extents at
// the time of applying the operation. If present, the update_engine daemon
// MUST read and verify the source data before applying the operation.
optional bytes src_sha256_hash = 9;
}
// Describes the update to apply to a single partition.
message PartitionUpdate {
// A platform-specific name to identify the partition set being updated. For
// example, in Chrome OS this could be "ROOT" or "KERNEL".
required string partition_name = 1;
// Whether this partition carries a filesystem with a "/postinstall" script
// that must be run to finalize the update process.
optional bool run_postinstall = 2;
// If present, a list of signatures of the new_partition_info.hash signed with
// different keys. If the update_engine daemon requires vendor-signed images
// and has its public key installed, one of the signatures should be valid
// for /postinstall to run.
repeated Signatures.Signature new_partition_signature = 3;
optional PartitionInfo old_partition_info = 4;
optional PartitionInfo new_partition_info = 5;
// The list of operations to be performed to apply this PartitionUpdate. The
// associated operation blobs (in operations[i].data_offset, data_length)
// should be stored contiguously and in the same order.
repeated InstallOperation operations = 6;
}
message DeltaArchiveManifest {
// DEPRECATED. List of install operations for the kernel and rootfs
// partitions. This information is now present in the |partitions| field. If
// you set these fields instead of the ones in the PartitionUpdate, they will
// be migrated to the corresponding entries in the PartitionUpdate to support
// full payloads on legacy daemons. Delta payloads starting with minor_version
// 3 MAY NOT include these fields.
repeated InstallOperation install_operations = 1;
repeated InstallOperation kernel_install_operations = 2;
// (At time of writing) usually 4096
optional uint32 block_size = 3 [default = 4096];
// If signatures are present, the offset into the blobs, generally
// tacked onto the end of the file, and the length. We use an offset
// rather than a bool to allow for more flexibility in future file formats.
// If either is absent, it means signatures aren't supported in this
// file.
optional uint64 signatures_offset = 4;
optional uint64 signatures_size = 5;
// DEPRECATED. Partition metadata used to validate the update.
// This information is now present in the |partitions| field. If you set
// these fields instead of the ones in the PartitionUpdate, they will be
// migrated to the corresponding entries in the PartitionUpdate to support
// full payloads on legacy daemons. Delta payloads starting with minor_version
// 3 MAY NOT include these fields.
optional PartitionInfo old_kernel_info = 6;
optional PartitionInfo new_kernel_info = 7;
optional PartitionInfo old_rootfs_info = 8;
optional PartitionInfo new_rootfs_info = 9;
// old_image_info will only be present for delta images.
optional ImageInfo old_image_info = 10;
optional ImageInfo new_image_info = 11;
optional uint32 minor_version = 12 [default = 0];
// List of partitions that will be updated, in the order they will be updated.
repeated PartitionUpdate partitions = 13;
}