blob: b95a04041dee52bbfc3144c19b468026e10b603f [file] [log] [blame]
Darin Petkov36a58222010-10-07 22:00:09 -07001// Copyright (c) 2010 The Chromium OS Authors. All rights reserved.
adlr@google.com3defe6a2009-12-04 20:57:17 +00002// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// Update file format: A delta update file contains all the deltas needed
6// to update a system from one specific version to another specific
7// version. The update format is represented by this struct pseudocode:
8// struct delta_update_file {
9// char magic[4] = "CrAU";
Andrew de los Reyes0c440052010-08-20 11:25:54 -070010// uint64 file_format_version = 1;
Andrew de los Reyes1e338b82010-01-22 14:57:27 -080011// uint64 manifest_size; // Size of protobuf DeltaArchiveManifest
12// // The Bzip2 compressed DeltaArchiveManifest
13// char manifest[];
adlr@google.com3defe6a2009-12-04 20:57:17 +000014//
15// // Data blobs for files, no specific format. The specific offset
16// // and length of each data blob is recorded in the DeltaArchiveManifest.
17// struct {
18// char data[];
19// } blobs[];
20//
Andrew de los Reyes94f025d2010-08-16 17:17:27 -070021// // These two are not signed:
22// uint64 signatures_message_size;
23// char signatures_message[];
24//
adlr@google.com3defe6a2009-12-04 20:57:17 +000025// };
26
Andrew de los Reyes1e338b82010-01-22 14:57:27 -080027// The DeltaArchiveManifest protobuf is an ordered list of InstallOperation
28// objects. These objects are stored in a linear array in the
29// DeltaArchiveManifest. Each operation is applied in order by the client.
adlr@google.com3defe6a2009-12-04 20:57:17 +000030
Andrew de los Reyes1e338b82010-01-22 14:57:27 -080031// The DeltaArchiveManifest also contains the initial and final
32// checksums for the device.
adlr@google.com3defe6a2009-12-04 20:57:17 +000033
Andrew de los Reyes1e338b82010-01-22 14:57:27 -080034// The client will perform each InstallOperation in order, beginning even
35// before the entire delta file is downloaded (but after at least the
36// protobuf is downloaded). The types of operations are explained:
37// - REPLACE: Replace the dst_extents on the drive with the attached data,
38// zero padding out to block size.
39// - REPLACE_BZ: bzip2-uncompress the attached data and write it into
40// dst_extents on the drive, zero padding to block size.
41// - MOVE: Copy the data in src_extents to dst_extents. Extents may overlap,
42// so it may be desirable to read all src_extents data into memory before
43// writing it out.
44// - BSDIFF: Read src_length bytes from src_extents into memory, perform
45// bspatch with attached data, write new data to dst_extents, zero padding
46// to block size.
adlr@google.com3defe6a2009-12-04 20:57:17 +000047
48package chromeos_update_engine;
Alex Deymob8f16a12014-06-10 18:59:22 -070049option optimize_for = LITE_RUNTIME;
adlr@google.com3defe6a2009-12-04 20:57:17 +000050
Andrew de los Reyes1e338b82010-01-22 14:57:27 -080051// Data is packed into blocks on disk, always starting from the beginning
52// of the block. If a file's data is too large for one block, it overflows
53// into another block, which may or may not be the following block on the
54// physical partition. An ordered list of extents is another
55// representation of an ordered list of blocks. For example, a file stored
56// in blocks 9, 10, 11, 2, 18, 12 (in that order) would be stored in
57// extents { {9, 3}, {2, 1}, {18, 1}, {12, 1} } (in that order).
58// In general, files are stored sequentially on disk, so it's more efficient
59// to use extents to encode the block lists (this is effectively
60// run-length encoding).
61// A sentinel value (kuint64max) as the start block denotes a sparse-hole
62// in a file whose block-length is specified by num_blocks.
adlr@google.com3defe6a2009-12-04 20:57:17 +000063
Andrew de los Reyes94f025d2010-08-16 17:17:27 -070064// Signatures: Updates may be signed by the OS vendor. The client verifies
65// an update's signature by hashing the entire download. The section of the
Jay Srinivasan74475bf2012-09-13 19:26:26 -070066// download that contains the signature is at the end of the file, so when
Andrew de los Reyes94f025d2010-08-16 17:17:27 -070067// signing a file, only the part up to the signature part is signed.
68// Then, the client looks inside the download's Signatures message for a
69// Signature message that it knows how to handle. Generally, a client will
70// only know how to handle one type of signature, but an update may contain
71// many signatures to support many different types of client. Then client
72// selects a Signature message and uses that, along with a known public key,
73// to verify the download. The public key is expected to be part of the
74// client.
75
Andrew de los Reyes1e338b82010-01-22 14:57:27 -080076message Extent {
77 optional uint64 start_block = 1;
78 optional uint64 num_blocks = 2;
adlr@google.com3defe6a2009-12-04 20:57:17 +000079}
80
Andrew de los Reyes94f025d2010-08-16 17:17:27 -070081message Signatures {
82 message Signature {
83 optional uint32 version = 1;
Andrew de los Reyes0c440052010-08-20 11:25:54 -070084 optional bytes data = 2;
Andrew de los Reyes94f025d2010-08-16 17:17:27 -070085 }
86 repeated Signature signatures = 1;
87}
88
Darin Petkov36a58222010-10-07 22:00:09 -070089message PartitionInfo {
90 optional uint64 size = 1;
91 optional bytes hash = 2;
92}
93
Don Garrett0dd39852013-04-03 16:55:42 -070094// Describe an image we are based on in a human friendly way.
95// Examples:
96// dev-channel, x86-alex, 1.2.3, mp-v3
97// nplusone-channel, x86-alex, 1.2.4, mp-v3, dev-channel, 1.2.3
98//
99// All fields will be set, if this message is present.
100message ImageInfo {
101 optional string board = 1;
102 optional string key = 2;
103 optional string channel = 3;
104 optional string version = 4;
105
106 // If these values aren't present, they should be assumed to match
107 // the equivalent value above. They are normally only different for
108 // special image types such as nplusone images.
109 optional string build_channel = 5;
110 optional string build_version = 6;
111}
112
Alex Deymoa12ee112015-08-12 22:19:32 -0700113message InstallOperation {
114 enum Type {
115 REPLACE = 0; // Replace destination extents w/ attached data
116 REPLACE_BZ = 1; // Replace destination extents w/ attached bzipped data
117 MOVE = 2; // Move source extents to destination extents
118 BSDIFF = 3; // The data is a bsdiff binary diff
119 // SOURCE_COPY and SOURCE_BSDIFF are only supported on minor version 2.
120 SOURCE_COPY = 4; // Copy from source to target partition
121 SOURCE_BSDIFF = 5; // Like BSDIFF, but read from source partition
Andrew de los Reyes1e338b82010-01-22 14:57:27 -0800122 }
Alex Deymoa12ee112015-08-12 22:19:32 -0700123 required Type type = 1;
124 // The offset into the delta file (after the protobuf)
125 // where the data (if any) is stored
126 optional uint32 data_offset = 2;
127 // The length of the data in the delta file
128 optional uint32 data_length = 3;
129
130 // Ordered list of extents that are read from (if any) and written to.
131 repeated Extent src_extents = 4;
132 // Byte length of src, equal to the number of blocks in src_extents *
133 // block_size. It is used for BSDIFF, because we need to pass that
134 // external program the number of bytes to read from the blocks we pass it.
135 // This is not used in any other operation.
136 optional uint64 src_length = 5;
137
138 repeated Extent dst_extents = 6;
139 // Byte length of dst, equal to the number of blocks in dst_extents *
140 // block_size. Used for BSDIFF, but not in any other operation.
141 optional uint64 dst_length = 7;
142
143 // Optional SHA 256 hash of the blob associated with this operation.
144 // This is used as a primary validation for http-based downloads and
145 // as a defense-in-depth validation for https-based downloads. If
146 // the operation doesn't refer to any blob, this field will have
147 // zero bytes.
148 optional bytes data_sha256_hash = 8;
149}
150
151message DeltaArchiveManifest {
Andrew de los Reyes1e338b82010-01-22 14:57:27 -0800152 repeated InstallOperation install_operations = 1;
Andrew de los Reyesf4c7ef12010-04-30 10:37:00 -0700153 repeated InstallOperation kernel_install_operations = 2;
Andrew de los Reyes1e338b82010-01-22 14:57:27 -0800154
155 // (At time of writing) usually 4096
Andrew de los Reyesf4c7ef12010-04-30 10:37:00 -0700156 optional uint32 block_size = 3 [default = 4096];
Andrew de los Reyes94f025d2010-08-16 17:17:27 -0700157
158 // If signatures are present, the offset into the blobs, generally
Andrew de los Reyes932bc4c2010-08-23 18:14:09 -0700159 // tacked onto the end of the file, and the length. We use an offset
160 // rather than a bool to allow for more flexibility in future file formats.
161 // If either is absent, it means signatures aren't supported in this
Andrew de los Reyes94f025d2010-08-16 17:17:27 -0700162 // file.
163 optional uint64 signatures_offset = 4;
Andrew de los Reyes932bc4c2010-08-23 18:14:09 -0700164 optional uint64 signatures_size = 5;
Darin Petkov36a58222010-10-07 22:00:09 -0700165
166 // Partition data that can be used to validate the update.
167 optional PartitionInfo old_kernel_info = 6;
168 optional PartitionInfo new_kernel_info = 7;
169 optional PartitionInfo old_rootfs_info = 8;
170 optional PartitionInfo new_rootfs_info = 9;
Don Garrett0dd39852013-04-03 16:55:42 -0700171
172 // old_image_info will only be present for delta images.
173 optional ImageInfo old_image_info = 10;
174
175 optional ImageInfo new_image_info = 11;
Don Garrettb8dd1d92013-11-22 17:40:02 -0800176
177 optional uint32 minor_version = 12 [default = 0];
Andrew de los Reyes1e338b82010-01-22 14:57:27 -0800178}