Class Update

Namespace

Pamoja.Update

Assembly

Pamoja.Update.dll

Signing releases and checking the ones that arrive.

public static class Update

Inheritance

object

Update

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

BlockDescriptor

What a transport calls a block carrying a signed update, for a field that names the convention.

public const string BlockDescriptor = "PJU1"

Field Value

string

FormatRaw

The payload format meaning the payload is the image itself.

public const byte FormatRaw = 1

Field Value

byte

StructureVersion

The manifest structure version this build writes.

public const byte StructureVersion = 1

Field Value

byte

Methods

DecodeManifest(ReadOnlySpan<byte>)

Reads a manifest body back from its bytes.

public static Manifest DecodeManifest(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The encoded manifest body.

Returns

Manifest

The manifest.

Remarks

This reads what a manifest claims; it proves nothing about who wrote it. Use VerifyEnvelope(ReadOnlySpan<byte>, ReadOnlySpan<byte>) to read one whose signature was checked.

Exceptions

PamojaException

The bytes are not a well-formed manifest.

EncodeManifest(Manifest)

Encodes the body of a manifest, which is what a signature covers.

public static byte[] EncodeManifest(Manifest manifest)

Parameters

manifest Manifest

The manifest to encode.

Returns

byte[]

The encoded body.

Exceptions

PamojaException

The manifest could not be encoded.

EnvelopeBody(ReadOnlySpan<byte>)

Copies out the signed body of an envelope, unchecked.

public static byte[] EnvelopeBody(ReadOnlySpan<byte> envelope)

Parameters

envelope ReadOnlySpan<byte>

The signed envelope.

Returns

byte[]

The signed body.

Remarks

This is what a gateway relays onward unchanged.

Exceptions

PamojaException

The envelope is malformed.

FrameBlock(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Writes a signed update into one block, for a transport that moves blocks.

public static byte[] FrameBlock(ReadOnlySpan<byte> envelope, ReadOnlySpan<byte> image)

Parameters

envelope ReadOnlySpan<byte>

The signed manifest.

image ReadOnlySpan<byte>

The image it describes.

Returns

byte[]

The block to hand to a transport.

Remarks

The block is the signed manifest and the image behind a header that says where each begins. Nothing in the header is trusted: every rule that decides whether the image runs is still the manifest's.

Exceptions

PamojaException

The envelope is longer than a header can describe.

ImageDigest(ReadOnlySpan<byte>)

Hashes a complete image, for a publisher filling in a manifest.

public static byte[] ImageDigest(ReadOnlySpan<byte> image)

Parameters

image ReadOnlySpan<byte>

The complete image the release carries.

Returns

byte[]

The 32-byte digest to put in a Manifest.

Remarks

The manifest commits to a SHA-256 over the image, and this is that hash, so a publisher does not need a hashing library of its own just to name the image it is releasing.

Exceptions

PamojaException

The native call failed.

OpenDelegation(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Opens a signed delegation against the anchor that signed it.

public static Delegation OpenDelegation(ReadOnlySpan<byte> envelope, ReadOnlySpan<byte> anchorPublicKey)

Parameters

envelope ReadOnlySpan<byte>

The signed delegation envelope.

anchorPublicKey ReadOnlySpan<byte>

The anchor key.

Returns

Delegation

The verified delegation.

Exceptions

ArgumentException

anchorPublicKey is not 32 bytes.

PamojaException

The delegation is not from the anchor.

SignDelegation(Delegation, DeviceIdentity)

Signs a delegation, naming a release key the anchor stands behind.

public static byte[] SignDelegation(Delegation delegation, DeviceIdentity anchor)

Parameters

delegation Delegation

The statement to sign.

anchor DeviceIdentity

The anchor identity, the root of the trust.

Returns

byte[]

The signed delegation envelope.

Remarks

Keeping the anchor offline and rotating a release key under it is the arrangement to prefer, because the key that signs day to day is the one most likely to be stolen.

Exceptions

PamojaException

The delegation could not be signed.

SignManifest(Manifest, DeviceIdentity)

Signs a manifest into the envelope offered to a device.

public static byte[] SignManifest(Manifest manifest, DeviceIdentity author)

Parameters

manifest Manifest

What the release says about itself.

author DeviceIdentity

The identity signing the release.

Returns

byte[]

The signed envelope.

Exceptions

PamojaException

The manifest could not be signed.

SplitBlock(ReadOnlySpan<byte>)

Reads a block back into the signed manifest and the image.

public static (byte[] Envelope, byte[] Image) SplitBlock(ReadOnlySpan<byte> block)

Parameters

block ReadOnlySpan<byte>

The block as it arrived.

Returns

(byte[] Envelope, byte[] Image)

The signed manifest and the image it describes.

Exceptions

PamojaException

The block does not carry this convention's header.

VerifyEnvelope(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Verifies an envelope and reads the manifest inside it.

public static Manifest VerifyEnvelope(ReadOnlySpan<byte> envelope, ReadOnlySpan<byte> publicKey)

Parameters

envelope ReadOnlySpan<byte>

The signed envelope.

publicKey ReadOnlySpan<byte>

The key expected to have signed it.

Returns

Manifest

The verified manifest.

Exceptions

ArgumentException

publicKey is not 32 bytes.

PamojaException

The signature is not from that key.