Table of Contents

Class Session

Namespace
Pamoja.Session
Assembly
Pamoja.Session.dll

A confidential, tamper-evident, replay-protected channel with one peer.

public sealed class Session : IDisposable
Inheritance
Session
Implements
Inherited Members

Remarks

Two devices that already know each other's public keys can agree on a session key without ever sending it, and then exchange messages that cannot be read, altered undetected, or replayed. That is the whole of what a small device usually needs from transport security, at a fraction of what a TLS stack costs it.

Constructors

Session(AgreementKey, ReadOnlySpan<byte>, ReadOnlySpan<byte>, SessionRole)

Establishes a session with a peer.

public Session(AgreementKey local, ReadOnlySpan<byte> peerPublicKey, ReadOnlySpan<byte> salt, SessionRole role)

Parameters

local AgreementKey

This device's key-agreement secret.

peerPublicKey ReadOnlySpan<byte>

The peer's 32-byte public key, already authenticated by pinning or by a signature.

salt ReadOnlySpan<byte>

A fresh per-session salt both sides share, exchanged in the clear. Reusing one with the same pair of keys reuses the session key, so it must change each session.

role SessionRole

Whether this device opens the session or answers.

Remarks

Both devices call this with the same salt and opposite roles, and arrive at the same key without either sending it.

Exceptions

PamojaException

The native session could not be created.

Fields

TagLength

The length in bytes of the tag on a sealed message.

public const int TagLength = 16

Field Value

int

Methods

Dispose()

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

public void Dispose()

HkdfSha256(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, int)

Expands input keying material into bytes bound to a purpose.

public static byte[] HkdfSha256(ReadOnlySpan<byte> salt, ReadOnlySpan<byte> ikm, ReadOnlySpan<byte> info, int length)

Parameters

salt ReadOnlySpan<byte>

The salt, which may be empty.

ikm ReadOnlySpan<byte>

The input keying material.

info ReadOnlySpan<byte>

Context binding the output to its purpose.

length int

How many bytes to derive.

Returns

byte[]

The derived bytes.

Exceptions

PamojaException

The native call failed.

HmacSha256(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Computes a keyed hash over a message.

public static byte[] HmacSha256(ReadOnlySpan<byte> key, ReadOnlySpan<byte> message)

Parameters

key ReadOnlySpan<byte>

The secret key.

message ReadOnlySpan<byte>

The message to authenticate.

Returns

byte[]

The 32-byte digest.

Remarks

This is the primitive a host uses to authenticate a pairing exchange or a single command, where a whole session would be more than the job needs.

Exceptions

PamojaException

The native call failed.

Open(SealedMessage, ReadOnlySpan<byte>)

Opens a message from the peer.

public byte[] Open(SealedMessage message, ReadOnlySpan<byte> aad = default)

Parameters

message SealedMessage

The ciphertext with the counter and tag that arrived with it.

aad ReadOnlySpan<byte>

The same associated data the sender authenticated.

Returns

byte[]

The plaintext.

Exceptions

PamojaException

The counter repeats or is older than the replay window still tracks, or the tag does not authenticate. Nothing readable is ever returned from a message that failed either check.

Seal(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Seals a message for the peer.

public SealedMessage Seal(ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> aad = default)

Parameters

plaintext ReadOnlySpan<byte>

The message to protect.

aad ReadOnlySpan<byte>

Data authenticated but not encrypted, so it stays readable on the wire yet cannot be altered: a device identifier or a routing header belongs here.

Returns

SealedMessage

The ciphertext, with the counter and tag to send beside it.

Exceptions

PamojaException

The native call failed.