package chromeos_update_engine

Get desktop application:
View/edit binary Protocol Buffers messages

• repeated InstallOperation install_operations = 1

  Only present in major version = 1. List of install operations for the kernel and rootfs partitions. For major version = 2 see the |partitions| field.

• repeated InstallOperation kernel_install_operations = 2

• optional uint32 block_size = 3

  (At time of writing) usually 4096

• optional uint64 signatures_offset = 4

  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_size = 5

• optional PartitionInfo old_kernel_info = 6

  Only present in major version = 1. Partition metadata used to validate the update. For major version = 2 see the |partitions| field.

• optional PartitionInfo new_kernel_info = 7

• optional PartitionInfo old_rootfs_info = 8

• optional PartitionInfo new_rootfs_info = 9

• optional ImageInfo old_image_info = 10

  old_image_info will only be present for delta images.

• optional ImageInfo new_image_info = 11

• optional uint32 minor_version = 12

  The minor version, also referred as "delta version", of the payload. Minor version 0 is full payload, everything else is delta payload.

• repeated PartitionUpdate partitions = 13

  Only present in major version >= 2. List of partitions that will be updated, in the order they will be updated. This field replaces the |install_operations|, |kernel_install_operations| and the |{old,new}_{kernel,rootfs}_info| fields used in major version = 1. This array can have more than two partitions if needed, and they are identified by the partition name.

• optional int64 max_timestamp = 14

  The maximum timestamp of the OS allowed to apply this payload. Can be used to prevent downgrading the OS.

• optional DynamicPartitionMetadata dynamic_partition_metadata = 15

  Metadata related to all dynamic partitions.

Used in: DynamicPartitionMetadata

• required string name = 1

  Name of the group.

• optional uint64 size = 2

  Maximum size of the group. The sum of sizes of all partitions in the group must not exceed the maximum size of the group.

• repeated string partition_names = 3

  A list of partitions that belong to the group.

Metadata related to all dynamic partitions.

Used in: DeltaArchiveManifest

• repeated DynamicPartitionGroup groups = 1

  All updatable groups present in |partitions| of this DeltaArchiveManifest. - If an updatable group is on the device but not in the manifest, it is not updated. Hence, the group will not be resized, and partitions cannot be added to or removed from the group. - If an updatable group is in the manifest but not on the device, the group is added to the device.

• optional bool snapshot_enabled = 2

  Whether dynamic partitions have snapshots during the update. If this is set to true, the update_engine daemon creates snapshots for all dynamic partitions if possible. If this is unset, the update_engine daemon MUST NOT create snapshots for dynamic partitions.

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.

Used in: InstallOperation, PartitionUpdate

• optional uint64 start_block = 1

• optional uint64 num_blocks = 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.

Used in: DeltaArchiveManifest

• optional string board = 1

• optional string key = 2

• optional string channel = 3

• optional string version = 4

• optional string build_channel = 5

  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_version = 6

Used in: DeltaArchiveManifest, PartitionUpdate

• required InstallOperation.Type type = 1

• optional uint64 data_offset = 2

  Only minor version 6 or newer support 64 bits |data_offset| and |data_length|, older client will read them as uint32. The offset into the delta file (after the protobuf) where the data (if any) is stored

• optional uint64 data_length = 3

  The length of the data in the delta file

• repeated Extent src_extents = 4

  Ordered list of extents that are read from (if any) and written to.

• optional uint64 src_length = 5

  Byte length of src, equal to the number of blocks in src_extents * block_size. It is used for BSDIFF and SOURCE_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.

• repeated Extent dst_extents = 6

• optional uint64 dst_length = 7

  Byte length of dst, equal to the number of blocks in dst_extents * block_size. Used for BSDIFF and SOURCE_BSDIFF, but not in any other operation.

• optional bytes data_sha256_hash = 8

  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 src_sha256_hash = 9

  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.

Used in: InstallOperation

• 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 = 4

  On minor version 2 or newer, these operations are supported:

  Copy from source to target partition

• SOURCE_BSDIFF = 5

  Like BSDIFF, but read from source partition

• REPLACE_XZ = 8

  On minor version 3 or newer and on major version 2 or newer, these operations are supported:

  Replace destination extents w/ attached xz data.

• ZERO = 6

  On minor version 4 or newer, these operations are supported:

  Write zeros in the destination.

• DISCARD = 7

  Discard the destination blocks, reading as undefined.

• BROTLI_BSDIFF = 10

  Like SOURCE_BSDIFF, but compressed with brotli.

• PUFFDIFF = 9

  On minor version 5 or newer, these operations are supported:

  The data is in puffdiff format.

Used in: DeltaArchiveManifest, PartitionUpdate

• optional uint64 size = 1

• optional bytes hash = 2

Describes the update to apply to a single partition.

Used in: DeltaArchiveManifest

• required string partition_name = 1

  A platform-specific name to identify the partition set being updated. For example, in Chrome OS this could be "ROOT" or "KERNEL".

• optional bool run_postinstall = 2

  Whether this partition carries a filesystem with post-install program that must be run to finalize the update process. See also |postinstall_path| and |filesystem_type|.

• optional string postinstall_path = 3

  The path of the executable program to run during the post-install step, relative to the root of this filesystem. If not set, the default "postinst" will be used. This setting is only used when |run_postinstall| is set and true.

• optional string filesystem_type = 4

  The filesystem type as passed to the mount(2) syscall when mounting the new filesystem to run the post-install program. If not set, a fixed list of filesystems will be attempted. This setting is only used if |run_postinstall| is set and true.

• repeated Signatures.Signature new_partition_signature = 5

  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.

• optional PartitionInfo old_partition_info = 6

• optional PartitionInfo new_partition_info = 7

• repeated InstallOperation operations = 8

  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.

• optional bool postinstall_optional = 9

  Whether a failure in the postinstall step for this partition should be ignored.

• optional Extent hash_tree_data_extent = 10

  On minor version 6 or newer, these fields are supported: The extent for data covered by verity hash tree.

• optional Extent hash_tree_extent = 11

  The extent to store verity hash tree.

• optional string hash_tree_algorithm = 12

  The hash algorithm used in verity hash tree.

• optional bytes hash_tree_salt = 13

  The salt used for verity hash tree.

• optional Extent fec_data_extent = 14

  The extent for data covered by FEC.

• optional Extent fec_extent = 15

  The extent to store FEC.

• optional uint32 fec_roots = 16

  The number of FEC roots.

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.

• repeated Signatures.Signature signatures = 1

Used in: PartitionUpdate, Signatures

• optional uint32 version = 1

• optional bytes data = 2

• optional fixed32 unpadded_signature_size = 3

  The DER encoded signature size of EC keys is nondeterministic for different input of sha256 hash. However, we need the size of the serialized signatures protobuf string to be fixed before signing; because this size is part of the content to be signed. Therefore, we always pad the signature data to the maximum possible signature size of a given key. And the payload verifier will truncate the signature to its correct size based on the value of |unpadded_signature_size|.