1 # Copyright (c) 2013 The Chromium OS Authors. All rights reserved. 2 # Use of this source code is governed by a BSD-style license that can be 3 # found in the LICENSE file. 4 5 """Tools for reading, verifying and applying Chrome OS update payloads.""" 6 7 from __future__ import print_function 8 9 import hashlib 10 import struct 11 12 from update_payload import applier 13 from update_payload import block_tracer 14 from update_payload import checker 15 from update_payload import common 16 from update_payload import update_metadata_pb2 17 from update_payload.error import PayloadError 18 19 20 # 21 # Helper functions. 22 # 23 def _ReadInt(file_obj, size, is_unsigned, hasher=None): 24 """Reads a binary-encoded integer from a file. 25 26 It will do the correct conversion based on the reported size and whether or 27 not a signed number is expected. Assumes a network (big-endian) byte 28 ordering. 29 30 Args: 31 file_obj: a file object 32 size: the integer size in bytes (2, 4 or 8) 33 is_unsigned: whether it is signed or not 34 hasher: an optional hasher to pass the value through 35 36 Returns: 37 An "unpacked" (Python) integer value. 38 39 Raises: 40 PayloadError if an read error occurred. 41 """ 42 return struct.unpack(common.IntPackingFmtStr(size, is_unsigned), 43 common.Read(file_obj, size, hasher=hasher))[0] 44 45 46 # 47 # Update payload. 48 # 49 class Payload(object): 50 """Chrome OS update payload processor.""" 51 52 class _PayloadHeader(object): 53 """Update payload header struct.""" 54 55 # Header constants; sizes are in bytes. 56 _MAGIC = 'CrAU' 57 _VERSION_SIZE = 8 58 _MANIFEST_LEN_SIZE = 8 59 _METADATA_SIGNATURE_LEN_SIZE = 4 60 61 def __init__(self): 62 self.version = None 63 self.manifest_len = None 64 self.metadata_signature_len = None 65 self.size = None 66 67 def ReadFromPayload(self, payload_file, hasher=None): 68 """Reads the payload header from a file. 69 70 Reads the payload header from the |payload_file| and updates the |hasher| 71 if one is passed. The parsed header is stored in the _PayloadHeader 72 instance attributes. 73 74 Args: 75 payload_file: a file object 76 hasher: an optional hasher to pass the value through 77 78 Returns: 79 None. 80 81 Raises: 82 PayloadError if a read error occurred or the header is invalid. 83 """ 84 # Verify magic 85 magic = common.Read(payload_file, len(self._MAGIC), hasher=hasher) 86 if magic != self._MAGIC: 87 raise PayloadError('invalid payload magic: %s' % magic) 88 89 self.version = _ReadInt(payload_file, self._VERSION_SIZE, True, 90 hasher=hasher) 91 self.manifest_len = _ReadInt(payload_file, self._MANIFEST_LEN_SIZE, True, 92 hasher=hasher) 93 self.size = (len(self._MAGIC) + self._VERSION_SIZE + 94 self._MANIFEST_LEN_SIZE) 95 self.metadata_signature_len = 0 96 97 if self.version == common.BRILLO_MAJOR_PAYLOAD_VERSION: 98 self.size += self._METADATA_SIGNATURE_LEN_SIZE 99 self.metadata_signature_len = _ReadInt( 100 payload_file, self._METADATA_SIGNATURE_LEN_SIZE, True, 101 hasher=hasher) 102 103 104 def __init__(self, payload_file, payload_file_offset=0): 105 """Initialize the payload object. 106 107 Args: 108 payload_file: update payload file object open for reading 109 payload_file_offset: the offset of the actual payload 110 """ 111 self.payload_file = payload_file 112 self.payload_file_offset = payload_file_offset 113 self.manifest_hasher = None 114 self.is_init = False 115 self.header = None 116 self.manifest = None 117 self.data_offset = None 118 self.metadata_signature = None 119 self.metadata_size = None 120 121 def _ReadHeader(self): 122 """Reads and returns the payload header. 123 124 Returns: 125 A payload header object. 126 127 Raises: 128 PayloadError if a read error occurred. 129 """ 130 header = self._PayloadHeader() 131 header.ReadFromPayload(self.payload_file, self.manifest_hasher) 132 return header 133 134 def _ReadManifest(self): 135 """Reads and returns the payload manifest. 136 137 Returns: 138 A string containing the payload manifest in binary form. 139 140 Raises: 141 PayloadError if a read error occurred. 142 """ 143 if not self.header: 144 raise PayloadError('payload header not present') 145 146 return common.Read(self.payload_file, self.header.manifest_len, 147 hasher=self.manifest_hasher) 148 149 def _ReadMetadataSignature(self): 150 """Reads and returns the metadata signatures. 151 152 Returns: 153 A string containing the metadata signatures protobuf in binary form or 154 an empty string if no metadata signature found in the payload. 155 156 Raises: 157 PayloadError if a read error occurred. 158 """ 159 if not self.header: 160 raise PayloadError('payload header not present') 161 162 return common.Read( 163 self.payload_file, self.header.metadata_signature_len, 164 offset=self.payload_file_offset + self.header.size + 165 self.header.manifest_len) 166 167 def ReadDataBlob(self, offset, length): 168 """Reads and returns a single data blob from the update payload. 169 170 Args: 171 offset: offset to the beginning of the blob from the end of the manifest 172 length: the blob's length 173 174 Returns: 175 A string containing the raw blob data. 176 177 Raises: 178 PayloadError if a read error occurred. 179 """ 180 return common.Read(self.payload_file, length, 181 offset=self.payload_file_offset + self.data_offset + 182 offset) 183 184 def Init(self): 185 """Initializes the payload object. 186 187 This is a prerequisite for any other public API call. 188 189 Raises: 190 PayloadError if object already initialized or fails to initialize 191 correctly. 192 """ 193 if self.is_init: 194 raise PayloadError('payload object already initialized') 195 196 self.manifest_hasher = hashlib.sha256() 197 198 # Read the file header. 199 self.payload_file.seek(self.payload_file_offset) 200 self.header = self._ReadHeader() 201 202 # Read the manifest. 203 manifest_raw = self._ReadManifest() 204 self.manifest = update_metadata_pb2.DeltaArchiveManifest() 205 self.manifest.ParseFromString(manifest_raw) 206 207 # Read the metadata signature (if any). 208 metadata_signature_raw = self._ReadMetadataSignature() 209 if metadata_signature_raw: 210 self.metadata_signature = update_metadata_pb2.Signatures() 211 self.metadata_signature.ParseFromString(metadata_signature_raw) 212 213 self.metadata_size = self.header.size + self.header.manifest_len 214 self.data_offset = self.metadata_size + self.header.metadata_signature_len 215 216 self.is_init = True 217 218 def Describe(self): 219 """Emits the payload embedded description data to standard output.""" 220 def _DescribeImageInfo(description, image_info): 221 """Display info about the image.""" 222 def _DisplayIndentedValue(name, value): 223 print(' {:<14} {}'.format(name+':', value)) 224 225 print('%s:' % description) 226 _DisplayIndentedValue('Channel', image_info.channel) 227 _DisplayIndentedValue('Board', image_info.board) 228 _DisplayIndentedValue('Version', image_info.version) 229 _DisplayIndentedValue('Key', image_info.key) 230 231 if image_info.build_channel != image_info.channel: 232 _DisplayIndentedValue('Build channel', image_info.build_channel) 233 234 if image_info.build_version != image_info.version: 235 _DisplayIndentedValue('Build version', image_info.build_version) 236 237 if self.manifest.HasField('old_image_info'): 238 _DescribeImageInfo('Old Image', self.manifest.old_image_info) 239 240 if self.manifest.HasField('new_image_info'): 241 _DescribeImageInfo('New Image', self.manifest.new_image_info) 242 243 def _AssertInit(self): 244 """Raises an exception if the object was not initialized.""" 245 if not self.is_init: 246 raise PayloadError('payload object not initialized') 247 248 def ResetFile(self): 249 """Resets the offset of the payload file to right past the manifest.""" 250 self.payload_file.seek(self.payload_file_offset + self.data_offset) 251 252 def IsDelta(self): 253 """Returns True iff the payload appears to be a delta.""" 254 self._AssertInit() 255 return (self.manifest.HasField('old_kernel_info') or 256 self.manifest.HasField('old_rootfs_info') or 257 any(partition.HasField('old_partition_info') 258 for partition in self.manifest.partitions)) 259 260 def IsFull(self): 261 """Returns True iff the payload appears to be a full.""" 262 return not self.IsDelta() 263 264 def Check(self, pubkey_file_name=None, metadata_sig_file=None, 265 report_out_file=None, assert_type=None, block_size=0, 266 rootfs_part_size=0, kernel_part_size=0, allow_unhashed=False, 267 disabled_tests=()): 268 """Checks the payload integrity. 269 270 Args: 271 pubkey_file_name: public key used for signature verification 272 metadata_sig_file: metadata signature, if verification is desired 273 report_out_file: file object to dump the report to 274 assert_type: assert that payload is either 'full' or 'delta' 275 block_size: expected filesystem / payload block size 276 rootfs_part_size: the size of (physical) rootfs partitions in bytes 277 kernel_part_size: the size of (physical) kernel partitions in bytes 278 allow_unhashed: allow unhashed operation blobs 279 disabled_tests: list of tests to disable 280 281 Raises: 282 PayloadError if payload verification failed. 283 """ 284 self._AssertInit() 285 286 # Create a short-lived payload checker object and run it. 287 helper = checker.PayloadChecker( 288 self, assert_type=assert_type, block_size=block_size, 289 allow_unhashed=allow_unhashed, disabled_tests=disabled_tests) 290 helper.Run(pubkey_file_name=pubkey_file_name, 291 metadata_sig_file=metadata_sig_file, 292 rootfs_part_size=rootfs_part_size, 293 kernel_part_size=kernel_part_size, 294 report_out_file=report_out_file) 295 296 def Apply(self, new_kernel_part, new_rootfs_part, old_kernel_part=None, 297 old_rootfs_part=None, bsdiff_in_place=True, bspatch_path=None, 298 puffpatch_path=None, truncate_to_expected_size=True): 299 """Applies the update payload. 300 301 Args: 302 new_kernel_part: name of dest kernel partition file 303 new_rootfs_part: name of dest rootfs partition file 304 old_kernel_part: name of source kernel partition file (optional) 305 old_rootfs_part: name of source rootfs partition file (optional) 306 bsdiff_in_place: whether to perform BSDIFF operations in-place (optional) 307 bspatch_path: path to the bspatch binary (optional) 308 puffpatch_path: path to the puffpatch binary (optional) 309 truncate_to_expected_size: whether to truncate the resulting partitions 310 to their expected sizes, as specified in the 311 payload (optional) 312 313 Raises: 314 PayloadError if payload application failed. 315 """ 316 self._AssertInit() 317 318 # Create a short-lived payload applier object and run it. 319 helper = applier.PayloadApplier( 320 self, bsdiff_in_place=bsdiff_in_place, bspatch_path=bspatch_path, 321 puffpatch_path=puffpatch_path, 322 truncate_to_expected_size=truncate_to_expected_size) 323 helper.Run(new_kernel_part, new_rootfs_part, 324 old_kernel_part=old_kernel_part, 325 old_rootfs_part=old_rootfs_part) 326 327 def TraceBlock(self, block, skip, trace_out_file, is_kernel): 328 """Traces the origin(s) of a given dest partition block. 329 330 The tracing tries to find origins transitively, when possible (it currently 331 only works for move operations, where the mapping of src/dst is 332 one-to-one). It will dump a list of operations and source blocks 333 responsible for the data in the given dest block. 334 335 Args: 336 block: the block number whose origin to trace 337 skip: the number of first origin mappings to skip 338 trace_out_file: file object to dump the trace to 339 is_kernel: trace through kernel (True) or rootfs (False) operations 340 """ 341 self._AssertInit() 342 343 # Create a short-lived payload block tracer object and run it. 344 helper = block_tracer.PayloadBlockTracer(self) 345 helper.Run(block, skip, trace_out_file, is_kernel) 346
