Table of Contents

Poly1305AeadTransform Class

Definition

Namespace
Bodu.Security.Cryptography
Assembly
Bodu.Security.Cryptography.dll
Package
Bodu.Security.Cryptography 1.2.0
Source
Poly1305AeadTransform.KeyAndNonceBuffer.cs

Provides the common IStreamAeadTransform implementation shared by the extended-nonce Poly1305 AEAD constructions - argument validation, buffer-overlap rules, single-use lifecycle, and secure clearing of retained key material. Derived types supply the keystream engine and, when required, an alternative framing.

public abstract class Poly1305AeadTransform : IStreamAeadTransform, IAeadTransform, IDisposable
Inheritance
Poly1305AeadTransform
Implements
Derived
Inherited Members
Extension Methods

Remarks

All constructions in this family bind a 256-bit key and a 192-bit nonce and emit a 128-bit tag, with the wire format ciphertext ‖ tag. Associated data is passed directly to Encrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) / Decrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) and defaults to empty; there is no separate associated-data step. By default the transform applies the RFC 8439 framing (Bodu.Security.Cryptography.Poly1305AeadCore.SealRfc8439(Bodu.Security.Cryptography.IStreamCipher,System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.Span{System.Byte}) / Bodu.Security.Cryptography.Poly1305AeadCore.OpenRfc8439(Bodu.Security.Cryptography.IStreamCipher,System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.Span{System.Byte})); a derived type may override SealCore(IStreamCipher, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>) and OpenCore(IStreamCipher, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>) to substitute a different framing, as the NaCl crypto_secretbox construction does.

Instances are stateful, not thread-safe, and single-use per message. A second call to Encrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) or Decrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) - including after a tag-mismatch failure - throws InvalidOperationException.

Allocation. The instance holds the key and nonce inline, and the constructions in this library draw each message's keystream from a value on the stack, so Encrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) and Decrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>) allocate nothing. A type derived outside this library is served through the engine its CreateEngine() override returns.

Buffer overlap. Exact in-place operation is supported: the plaintext (or ciphertext) may begin at the same location as the output. Any other (partial) overlap is rejected with ArgumentException.

Constructors

Poly1305AeadTransform(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Initializes a new instance of the Poly1305AeadTransform class with the specified key and nonce.

protected Poly1305AeadTransform(ReadOnlySpan<byte> key, ReadOnlySpan<byte> nonce)

Parameters

key ReadOnlySpan<byte>

The 256-bit (32-byte) secret key.

nonce ReadOnlySpan<byte>

The 192-bit (24-byte) nonce. Must be unique for every message encrypted under the same key.

Exceptions

ArgumentException

key is not exactly Bodu.Security.Cryptography.Poly1305AeadTransform.KeyBytes bytes, or nonce is not exactly Bodu.Security.Cryptography.Poly1305AeadTransform.NonceBytes bytes.

Properties

Key

Gets the retained secret key.

protected ReadOnlySpan<byte> Key { get; }

Property Value

ReadOnlySpan<byte>

A read-only view over the 32-byte key.

Nonce

Gets the retained nonce.

protected ReadOnlySpan<byte> Nonce { get; }

Property Value

ReadOnlySpan<byte>

A read-only view over the 24-byte nonce.

SupportsAssociatedData

Gets a value indicating whether this construction authenticates associated data.

protected virtual bool SupportsAssociatedData { get; }

Property Value

bool

true for the RFC 8439-framed constructions; false for the secretbox construction, which has no associated-data input.

TagSize

Gets the authentication-tag size, in bits.

public int TagSize { get; }

Property Value

int

The authentication-tag size, in bits.

Methods

CreateEngine()

Creates the keystream engine for a single message, positioned at block counter 0.

protected abstract IStreamCipher CreateEngine()

Returns

IStreamCipher

A freshly constructed IStreamCipher bound to Key and Nonce.

Remarks

The caller owns the returned engine and disposes it after the message completes.

Decrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>)

Verifies the authentication tag of ciphertextWithTag against associatedData and writes the recovered plaintext to output.

public int Decrypt(ReadOnlySpan<byte> ciphertextWithTag, Span<byte> output, ReadOnlySpan<byte> associatedData = default)

Parameters

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext followed by its TagSize / 8 byte tag.

output Span<byte>

Receives the recovered plaintext. Must be at least ciphertextWithTag.Length - (TagSize / 8) bytes long.

associatedData ReadOnlySpan<byte>

The data that must match what was supplied at encryption time. Defaults to empty.

Returns

int

Bytes written: ciphertextWithTag.Length - (TagSize / 8).

Exceptions

CryptographicException

The authentication tag did not match.

ArgumentException

ciphertextWithTag is shorter than the tag, output is too small, or the buffers partially overlap.

InvalidOperationException

The instance has already processed a message.

Dispose()

Releases the resources used by this instance and clears the retained key and nonce from memory.

public void Dispose()

Encrypt(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>)

Encrypts plaintext, authenticates it together with associatedData, and writes the ciphertext followed by the authentication tag to output.

public int Encrypt(ReadOnlySpan<byte> plaintext, Span<byte> output, ReadOnlySpan<byte> associatedData = default)

Parameters

plaintext ReadOnlySpan<byte>

The data to encrypt.

output Span<byte>

Receives the ciphertext followed by the TagSize / 8 byte tag. Must be at least plaintext.Length + (TagSize / 8) bytes long.

associatedData ReadOnlySpan<byte>

The data authenticated but not encrypted. Defaults to empty.

Returns

int

Total bytes written: plaintext.Length + (TagSize / 8).

Exceptions

ArgumentException

output is too small, or the buffers partially overlap.

InvalidOperationException

The instance has already processed a message.

OpenCore(IStreamCipher, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>)

Verifies and decrypts a message. The default implementation applies the RFC 8439 framing.

protected virtual int OpenCore(IStreamCipher engine, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> ciphertextWithTag, Span<byte> output)

Parameters

engine IStreamCipher

The keystream engine, positioned at block counter 0.

associatedData ReadOnlySpan<byte>

The associated data that must match the value used at encryption time.

ciphertextWithTag ReadOnlySpan<byte>

The ciphertext followed by its authentication tag.

output Span<byte>

Receives the recovered plaintext.

Returns

int

The number of plaintext bytes written.

Exceptions

CryptographicException

The authentication tag did not match.

SealCore(IStreamCipher, ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>)

Encrypts and authenticates a message. The default implementation applies the RFC 8439 framing.

protected virtual int SealCore(IStreamCipher engine, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> plaintext, Span<byte> output)

Parameters

engine IStreamCipher

The keystream engine, positioned at block counter 0.

associatedData ReadOnlySpan<byte>

The associated data to authenticate.

plaintext ReadOnlySpan<byte>

The data to encrypt.

output Span<byte>

Receives the ciphertext followed by the authentication tag.

Returns

int

The number of bytes written.

ThrowIfDisposed()

Throws an ObjectDisposedException if this instance has been disposed.

protected void ThrowIfDisposed()

Exceptions

ObjectDisposedException

The instance has been disposed.

Applies to

ProductVersions
.NET8, 10