Class DeviceIdentity

Namespace

Pamoja.Security

Assembly

Pamoja.Security.dll

A device's private signing identity.

public sealed class DeviceIdentity : IDisposable

Inheritance

object

DeviceIdentity

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using var device = new DeviceIdentity(seed);
byte[] signature = device.Sign("21.5");
DeviceIdentity.Verify(device.PublicKey, "21.5", signature); // true

Remarks

A reading that drives a health or billing decision has to be provably from the device that claims to have sent it, and provably unaltered on the way. Sign it here, and any holder of PublicKey can check it with Verify(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>).

Constructors

DeviceIdentity(ReadOnlySpan<byte>)

Creates an identity from a provisioned 32-byte secret seed.

public DeviceIdentity(ReadOnlySpan<byte> seed)

Parameters

seed ReadOnlySpan<byte>

The device's secret, held on the device only.

Exceptions

ArgumentException

seed is not 32 bytes.

PamojaException

The native identity could not be created.

Fields

KeyLength

The length in bytes of an identity seed and of a public key.

public const int KeyLength = 32

Field Value

int

SignatureLength

The length in bytes of a signature.

public const int SignatureLength = 64

Field Value

int

Properties

Fingerprint

Gets the short hex fingerprint of this identity, for logs and displays.

public string Fingerprint { get; }

Property Value

string

Exceptions

PamojaException

The native call failed.

PublicKey

Gets the public key matching this identity, which is safe to share.

public byte[] PublicKey { get; }

Property Value

byte[]

Exceptions

PamojaException

The native call failed.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

FingerprintOf(ReadOnlySpan<byte>)

Returns the short hex fingerprint of a public key.

public static string FingerprintOf(ReadOnlySpan<byte> publicKey)

Parameters

publicKey ReadOnlySpan<byte>

The 32-byte public key to label.

Returns

string

A 16-character lowercase hex label.

Exceptions

PamojaException

The key is not a valid public key.

Sign(ReadOnlySpan<byte>)

Signs a payload.

public byte[] Sign(ReadOnlySpan<byte> payload)

Parameters

payload ReadOnlySpan<byte>

The bytes to cover.

Returns

byte[]

The 64-byte detached signature.

Exceptions

PamojaException

The native call failed.

Sign(string)

Signs text, encoded as UTF-8.

public byte[] Sign(string payload)

Parameters

payload string

The text to cover.

Returns

byte[]

The 64-byte detached signature.

Exceptions

ArgumentNullException

payload is null.

PamojaException

The native call failed.

SignMessage(ReadOnlySpan<byte>)

Signs a payload and returns one message carrying both.

public byte[] SignMessage(ReadOnlySpan<byte> payload)

Parameters

payload ReadOnlySpan<byte>

The bytes to cover.

Returns

byte[]

The signature followed by the payload.

Remarks

The message is the signature followed by the payload, which is usually what goes on a link: one blob to send, rather than a payload and a detached signature to keep together and split correctly at the far end. VerifyMessage(ReadOnlySpan<byte>, ReadOnlySpan<byte>) reverses it.

Exceptions

PamojaException

The native call failed.

SignMessage(string)

Signs text and returns one message carrying both.

public byte[] SignMessage(string payload)

Parameters

payload string

The text to cover.

Returns

byte[]

The signature followed by the payload.

Exceptions

ArgumentNullException

payload is null.

PamojaException

The native call failed.

Use<TResult>(Func<nint, TResult>)

Runs a native call that needs this identity handle.

public TResult Use<TResult>(Func<nint, TResult> call)

Parameters

call Func<nint, TResult>

The native call to make.

Returns

TResult

Whatever the native call returned.

Type Parameters

TResult

What the native call returns.

Remarks

The audit and update capabilities sign with an identity this class holds, and the native calls take its handle. This is how the two meet without a caller ever seeing it.

Verify(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Verifies that a signature covers a payload and was made by a key.

public static bool Verify(ReadOnlySpan<byte> publicKey, ReadOnlySpan<byte> payload, ReadOnlySpan<byte> signature)

Parameters

publicKey ReadOnlySpan<byte>

The 32-byte public key of the claimed signer.

payload ReadOnlySpan<byte>

The bytes the signature should cover.

signature ReadOnlySpan<byte>

The 64-byte detached signature.

Returns

bool

true if the signature is authentic, and false if the payload was altered or was signed by a different device.

Exceptions

PamojaException

An argument was not the expected length.

Verify(ReadOnlySpan<byte>, string, ReadOnlySpan<byte>)

Verifies a signature over text, encoded as UTF-8.

public static bool Verify(ReadOnlySpan<byte> publicKey, string payload, ReadOnlySpan<byte> signature)

Parameters

publicKey ReadOnlySpan<byte>

The 32-byte public key of the claimed signer.

payload string

The text the signature should cover.

signature ReadOnlySpan<byte>

The 64-byte detached signature.

Returns

bool

true if the signature is authentic.

Exceptions

ArgumentNullException

payload is null.

PamojaException

An argument was not the expected length.

VerifyMessage(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Verifies a signed message and returns the payload it carries.

public static byte[]? VerifyMessage(ReadOnlySpan<byte> publicKey, ReadOnlySpan<byte> message)

Parameters

publicKey ReadOnlySpan<byte>

The 32-byte public key of the claimed signer.

message ReadOnlySpan<byte>

The signature followed by the payload.

Returns

byte[]

The payload if the message is authentic, and null if it is too short to hold a signature, was altered, or was signed by a different device.