SymmetricStreamAlgorithm Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

SymmetricStreamAlgorithm.cs

Provides the common base for the library's additive (symmetric, shared-key) stream ciphers, sharing key and nonce storage, validation, generation, transform creation, and disposal.

public abstract class SymmetricStreamAlgorithm : IDisposable

Inheritance

object

SymmetricStreamAlgorithm

Implements

IDisposable

Derived

ChaCha20

Hc128

Rabbit

Salsa20

XChaCha20

XSalsa20

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

SymmetricStreamAlgorithmExtensions.Decrypt(SymmetricStreamAlgorithm, byte[])

SymmetricStreamAlgorithmExtensions.Decrypt(SymmetricStreamAlgorithm, byte[], int)

SymmetricStreamAlgorithmExtensions.Decrypt(SymmetricStreamAlgorithm, byte[], int, int)

SymmetricStreamAlgorithmExtensions.Decrypt(SymmetricStreamAlgorithm, Stream, Stream)

SymmetricStreamAlgorithmExtensions.Decrypt(SymmetricStreamAlgorithm, Stream, Stream, int)

SymmetricStreamAlgorithmExtensions.Decrypt(SymmetricStreamAlgorithm, ReadOnlyMemory<byte>)

SymmetricStreamAlgorithmExtensions.Decrypt(SymmetricStreamAlgorithm, ReadOnlySpan<byte>)

SymmetricStreamAlgorithmExtensions.Encrypt(SymmetricStreamAlgorithm, byte[])

SymmetricStreamAlgorithmExtensions.Encrypt(SymmetricStreamAlgorithm, byte[], int)

SymmetricStreamAlgorithmExtensions.Encrypt(SymmetricStreamAlgorithm, byte[], int, int)

SymmetricStreamAlgorithmExtensions.Encrypt(SymmetricStreamAlgorithm, Stream, Stream)

SymmetricStreamAlgorithmExtensions.Encrypt(SymmetricStreamAlgorithm, Stream, Stream, int)

SymmetricStreamAlgorithmExtensions.Encrypt(SymmetricStreamAlgorithm, ReadOnlyMemory<byte>)

SymmetricStreamAlgorithmExtensions.Encrypt(SymmetricStreamAlgorithm, ReadOnlySpan<byte>)

Remarks

A stream cipher has no cipher block and applies neither a block-cipher mode nor padding. Unlike a block cipher it is not modelled on SymmetricAlgorithm: there is no Mode, Padding, BlockSize, or IV. Instead the cipher is parameterized by a Key and a Nonce, and produces an ICryptoTransform that XORs data with a key- and nonce-dependent keystream. The transform processes data one byte at a time and imposes no alignment requirement on callers, so it composes naturally with CryptoStream and any other consumer of the ICryptoTransform contract.

Because additive stream ciphers are self-inverse, CreateEncryptor() and CreateDecryptor() are interchangeable; both delegate to CreateTransform(), which in turn calls CreateStreamCipher(byte[], byte[]) - implemented by a derived class to build a configured IStreamCipher engine from the validated key and nonce.

Nonce reuse is catastrophic. A given (key, nonce) pair must encrypt at most one message; reusing a pair XORs two plaintexts under the same keystream and destroys confidentiality. Generate a fresh nonce per message with GenerateNonce() (or supply one explicitly) and never repeat it under the same key.

Constructors

SymmetricStreamAlgorithm(int, int)

Initializes a new instance of the SymmetricStreamAlgorithm class with a single fixed key size and a fixed nonce size.

protected SymmetricStreamAlgorithm(int keySizeBits, int nonceSizeBits)

Parameters

keySizeBits int

The required key size, in bits.

nonceSizeBits int

The required nonce size, in bits.

Remarks

Use this overload for ciphers that accept exactly one key length. The legal key sizes are fixed to the single supplied size.

SymmetricStreamAlgorithm(int, KeySizes[], int)

Initializes a new instance of the SymmetricStreamAlgorithm class with a default key size, an explicit set of legal key sizes, and a fixed nonce size.

protected SymmetricStreamAlgorithm(int defaultKeySizeBits, KeySizes[] legalKeySizes, int nonceSizeBits)

Parameters

defaultKeySizeBits int

The default key size, in bits, used by GenerateKey().

legalKeySizes KeySizes[]

The legal key sizes the cipher accepts. Must not be null.

nonceSizeBits int

The required nonce size, in bits.

Remarks

Use this overload for ciphers that accept more than one key length (for example Salsa20, which accepts 128-bit and 256-bit keys).

Exceptions

ArgumentNullException

legalKeySizes is null.

Properties

Key

Gets or sets the secret key.

public byte[] Key { get; set; }

Property Value

byte[]

A copy of the secret key bytes.

Remarks

Reading this property generates a random key of KeySize bits on first access if none has been set. Both the getter and setter copy the array so callers cannot mutate the cipher's key through an alias.

Exceptions

ObjectDisposedException

This instance has been disposed.

ArgumentNullException

The assigned value is null.

CryptographicException

The length of the assigned value is not one of the LegalKeySizes.

KeySize

Gets or sets the key size, in bits.

public int KeySize { get; set; }

Property Value

int

The key size, in bits. The default is the cipher's default key size.

Remarks

Assigning a new key size discards any key material previously held by Key; the next read of Key generates a fresh key of the new size.

Exceptions

ObjectDisposedException

This instance has been disposed.

CryptographicException

The assigned value is not one of the LegalKeySizes.

LegalKeySizes

Gets the key sizes, in bits, that this cipher accepts.

public KeySizes[] LegalKeySizes { get; }

Property Value

KeySizes[]

A copy of the legal key-size descriptors.

Exceptions

ObjectDisposedException

This instance has been disposed.

Nonce

Gets or sets the nonce.

public byte[] Nonce { get; set; }

Property Value

byte[]

A copy of the nonce bytes.

Remarks

Reading this property generates a random nonce of NonceSize bits on first access if none has been set. A nonce must never be reused under the same key; see the type remarks.

Exceptions

ObjectDisposedException

This instance has been disposed.

ArgumentNullException

The assigned value is null.

CryptographicException

The length of the assigned value is not NonceSize bits.

NonceLengthInBytes

Gets the required nonce length, in bytes.

protected int NonceLengthInBytes { get; }

Property Value

int

The nonce length, in bytes.

NonceSize

Gets the required nonce size, in bits.

public int NonceSize { get; }

Property Value

int

The nonce size, in bits.

Exceptions

ObjectDisposedException

This instance has been disposed.

Methods

CreateDecryptor()

Creates a self-inverse ICryptoTransform using the current Key and Nonce.

public ICryptoTransform CreateDecryptor()

Returns

ICryptoTransform

An ICryptoTransform that XORs data with the cipher keystream.

Remarks

Because an additive stream cipher is self-inverse, this method is identical to CreateEncryptor(). A given nonce may back only one transform created through the parameterless overloads; assign a fresh Nonce (or call GenerateNonce()) before creating another, or use CreateDecryptor(byte[], byte[]) to supply an explicit nonce.

Exceptions

ObjectDisposedException

This instance has been disposed.

CryptographicException

A transform has already been created for the current nonce; see the remarks.

CreateDecryptor(byte[], byte[])

Creates a self-inverse ICryptoTransform from the supplied key and nonce.

public ICryptoTransform CreateDecryptor(byte[] key, byte[] nonce)

Parameters

key byte[]

The secret key. Must not be null.

nonce byte[]

The nonce. Must not be null.

Returns

ICryptoTransform

An ICryptoTransform that XORs data with the cipher keystream.

Remarks

The supplied values are used as-is for this transform and do not alter the cipher's Key or Nonce properties. Because an additive stream cipher is self-inverse, this method is identical to CreateEncryptor(byte[], byte[]).

Exceptions

ObjectDisposedException

This instance has been disposed.

ArgumentNullException

key or nonce is null.

CryptographicException

The key or nonce length is invalid.

CreateEncryptor()

Creates a self-inverse ICryptoTransform using the current Key and Nonce.

public ICryptoTransform CreateEncryptor()

Returns

ICryptoTransform

An ICryptoTransform that XORs data with the cipher keystream.

Remarks

Because an additive stream cipher is self-inverse, this method is identical to CreateDecryptor(). A given nonce may back only one transform created through the parameterless overloads; assign a fresh Nonce (or call GenerateNonce()) before creating another, or use CreateEncryptor(byte[], byte[]) to supply an explicit nonce.

Exceptions

ObjectDisposedException

This instance has been disposed.

CryptographicException

A transform has already been created for the current nonce; see the remarks.

CreateEncryptor(byte[], byte[])

Creates a self-inverse ICryptoTransform from the supplied key and nonce.

public ICryptoTransform CreateEncryptor(byte[] key, byte[] nonce)

Parameters

key byte[]

The secret key. Must not be null.

nonce byte[]

The nonce. Must not be null.

Returns

ICryptoTransform

An ICryptoTransform that XORs data with the cipher keystream.

Remarks

The supplied values are used as-is for this transform and do not alter the cipher's Key or Nonce properties. Because an additive stream cipher is self-inverse, this method is identical to CreateDecryptor(byte[], byte[]).

Exceptions

ObjectDisposedException

This instance has been disposed.

ArgumentNullException

key or nonce is null.

CryptographicException

The key or nonce length is invalid.

CreateStreamCipher(byte[], byte[])

Builds a configured IStreamCipher engine from the validated key and nonce.

protected abstract IStreamCipher CreateStreamCipher(byte[] key, byte[] nonce)

Parameters

key byte[]

The key, already validated to the algorithm's key size.

nonce byte[]

The nonce, already validated to the algorithm's nonce size.

Returns

IStreamCipher

A new IStreamCipher engine positioned at the start of its keystream.

Remarks

Implementations receive a key and nonce whose lengths have already been checked by the base class, so they need only construct their engine. Ownership of the returned engine transfers to the caller.

CreateTransform()

Creates a self-inverse ICryptoTransform using the current Key and Nonce.

public ICryptoTransform CreateTransform()

Returns

ICryptoTransform

An ICryptoTransform that XORs data with the cipher keystream.

Exceptions

ObjectDisposedException

This instance has been disposed.

CryptographicException

A transform has already been created for the current nonce. Assign a fresh Nonce (or call GenerateNonce()) before creating another, or use CreateTransform(byte[], byte[]) to supply an explicit nonce.

CreateTransform(byte[], byte[])

Validates the supplied key and nonce, builds the engine, and wraps it in a self-inverse stream transform.

public ICryptoTransform CreateTransform(byte[] key, byte[] nonce)

Parameters

key byte[]

The secret key. Must not be null.

nonce byte[]

The nonce. Must not be null.

Returns

ICryptoTransform

An ICryptoTransform that XORs data with the cipher keystream.

Remarks

The supplied values are used as-is for this transform and do not alter the cipher's Key or Nonce properties.

Exceptions

ObjectDisposedException

This instance has been disposed.

ArgumentNullException

key or nonce is null.

CryptographicException

The key or nonce length is invalid.

Dispose()

Releases all resources used by the current instance and clears any sensitive key material.

public void Dispose()

Dispose(bool)

Releases the unmanaged resources used by the instance and, optionally, the managed resources.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

GenerateKey()

Generates a random secret key of KeySize bits, replacing any existing key.

public void GenerateKey()

Exceptions

ObjectDisposedException

This instance has been disposed.

GenerateNonce()

Generates a random nonce of NonceSize bits, replacing any existing nonce.

public void GenerateNonce()

Exceptions

ObjectDisposedException

This instance has been disposed.

ThrowIfDisposed()

Throws an ObjectDisposedException if this instance has been disposed.

protected void ThrowIfDisposed()

Exceptions

ObjectDisposedException

The instance has been disposed.

Applies to

Product	Versions
.NET	8, 10

See Also

IStreamCipher

StreamCipherTransform