pamoja.update

  1"""Idiomatic signed-update facade.
  2
  3A device that cannot be fixed in the field is a device that has to be visited,
  4and some of them are a day's travel away. Signed updates make that a network
  5operation instead: a release carries a manifest naming who it is for and what it
  6hashes to, a device refuses anything not signed by the key it trusts, and an
  7image that fails to confirm itself is rolled back to the one that worked.
  8"""
  9
 10from __future__ import annotations
 11
 12import enum
 13
 14from pamoja._native import (
 15    BootDecision,
 16    Delegation,
 17    ImageVerifier,
 18    Manifest,
 19    Progress,
 20    SlotRecord,
 21    Updater,
 22    decode_manifest,
 23    encode_manifest,
 24    envelope_body,
 25    open_delegation,
 26    verify_envelope,
 27)
 28from pamoja._native import frame_update_block as _frame_block
 29from pamoja._native import sign_delegation as _sign_delegation
 30from pamoja._native import split_update_block as _split_block
 31from pamoja._native import update_block_descriptor as _block_descriptor
 32from pamoja._native import image_digest as _image_digest
 33from pamoja._native import sign_manifest as _sign_manifest
 34from pamoja._native import update_format_raw as _format_raw
 35from pamoja._native import update_structure_version as _structure_version
 36from pamoja.security import DeviceIdentity
 37
 38__all__ = [
 39    "BLOCK_DESCRIPTOR",
 40    "FORMAT_RAW",
 41    "STRUCTURE_VERSION",
 42    "BootAction",
 43    "BootDecision",
 44    "Delegation",
 45    "ImageVerifier",
 46    "Manifest",
 47    "Progress",
 48    "SlotRecord",
 49    "SlotState",
 50    "Updater",
 51    "decode_manifest",
 52    "encode_manifest",
 53    "envelope_body",
 54    "open_delegation",
 55    "sign_delegation",
 56    "frame_block",
 57    "image_digest",
 58    "sign_manifest",
 59    "split_block",
 60    "verify_envelope",
 61]
 62
 63#: The manifest structure version this build writes.
 64STRUCTURE_VERSION = _structure_version()
 65
 66#: The payload format meaning the payload is the image itself, byte for byte.
 67FORMAT_RAW = _format_raw()
 68
 69
 70class SlotState(str, enum.Enum):
 71    """What a device believes about one slot."""
 72
 73    #: Nothing has been written here.
 74    EMPTY = "Empty"
 75    #: An image is arriving, and ``written`` says how much of it has.
 76    RECEIVING = "Receiving"
 77    #: A complete image that matched its manifest, not yet tried.
 78    STAGED = "Staged"
 79    #: Being tried for the first time; it reverts unless it confirms.
 80    PENDING = "Pending"
 81    #: Tried and confirmed working.
 82    CONFIRMED = "Confirmed"
 83    #: Tried and did not confirm, so it will not be tried again.
 84    FAILED = "Failed"
 85
 86
 87class BootAction(str, enum.Enum):
 88    """What a bootloader should do with what it found."""
 89
 90    #: Nothing new to try; run the confirmed image.
 91    CONFIRMED = "Confirmed"
 92    #: A staged image is being tried for the first time.
 93    TRYING = "Trying"
 94    #: A pending image never confirmed, so it was failed.
 95    REVERTED = "Reverted"
 96
 97
 98def image_digest(image: bytes) -> bytes:
 99    """Hash a complete image, for a publisher filling in a manifest.
100
101    The manifest commits to a SHA-256 over the image, and this is that hash, so a
102    publisher does not need a hashing library of its own just to name the image it
103    is releasing.
104
105    :param image: The complete image the release carries.
106    :returns: The 32-byte digest to put in a :class:`Manifest`.
107    """
108    return _image_digest(bytes(image))
109
110
111def sign_manifest(manifest: Manifest, author: DeviceIdentity) -> bytes:
112    """Sign a manifest into the envelope that is offered to a device.
113
114    :param manifest: What the release says about itself.
115    :param author: The identity signing the release.
116    :returns: The signed envelope.
117    """
118    return _sign_manifest(manifest, DeviceIdentity.native(author))
119
120
121def sign_delegation(delegation: Delegation, anchor: DeviceIdentity) -> bytes:
122    """Sign a delegation, naming a release key the anchor stands behind.
123
124    Keeping the anchor offline and rotating a release key under it is the
125    arrangement to prefer, because the key that signs day to day is the one most
126    likely to be stolen.
127
128    :param delegation: The statement to sign.
129    :param anchor: The anchor identity, which is the root of the trust.
130    :returns: The signed delegation envelope.
131    """
132    return _sign_delegation(delegation, DeviceIdentity.native(anchor))
133
134
135#: What a transport calls a block carrying a signed update, for a field that names the
136#: convention.
137BLOCK_DESCRIPTOR = _block_descriptor()
138
139
140def frame_block(envelope: bytes, image: bytes) -> bytes:
141    """Write a signed update into one block, for a transport that moves blocks.
142
143    The block is the signed manifest and the image behind a header that says where each
144    begins. Nothing in the header is trusted: every rule that decides whether the image
145    runs is still the manifest's.
146
147    :param envelope: The signed manifest.
148    :param image: The image it describes.
149    :returns: The block to hand to a transport.
150    """
151    return _frame_block(bytes(envelope), bytes(image))
152
153
154def split_block(block: bytes) -> tuple[bytes, bytes]:
155    """Read a block back into the signed manifest and the image.
156
157    :param block: The block as it arrived.
158    :returns: The signed manifest and the image.
159    :raises Refusal: If the block does not carry this convention's header.
160    """
161    return _split_block(bytes(block))