Table of Contents

Class SymmetricCipher

Namespace
CryptoHives.Foundation.Security.Cryptography.Cipher
Assembly
CryptoHives.Foundation.Security.Cryptography.dll

Base class for CryptoHives symmetric cipher implementations.

public abstract class SymmetricCipher : SymmetricAlgorithm, IDisposable
Inheritance
SymmetricCipher
Implements
Derived
Inherited Members

Remarks

This class extends SymmetricAlgorithm to enable drop-in replacement: switching the using directive from System.Security.Cryptography to CryptoHives.Foundation.Security.Cryptography.Cipher provides a managed implementation while preserving API compatibility with CryptoStream and other .NET cryptographic infrastructure.

All derived classes implement cipher algorithms without OS or hardware dependencies, providing deterministic behavior across all platforms. However, implementations may optionally use hardware intrinsics (AES-NI, ARM Crypto) when available for performance.

Usage pattern: 

using var aes = Aes256.Create();
aes.Key = key;
aes.IV = iv;

using var encryptor = aes.CreateEncryptor();
byte[] ciphertext = encryptor.TransformFinalBlock(plaintext, 0, plaintext.Length);

Security warning - CBC + PKCS#7 is padding-oracle-prone: the default Mode/Padding combination (CBC with PKCS7) provides no authentication. Decrypting attacker-controlled ciphertext and revealing - through any observable channel, including response timing, error type, or response size - whether the padding was valid lets an attacker decrypt the ciphertext byte-by-byte (Vaudenay's padding-oracle attack; exploited in practice by POODLE and Lucky 13). The PKCS#7 check in this library is constant-time with respect to where the padding is invalid, but that alone does not make an application built on top of it padding-oracle-safe: a caller that returns a distinguishable error/status for padding failures reintroduces the oracle at the application layer. For new code, prefer an AEAD cipher (AesGcm, ChaCha20Poly1305) which authenticates the ciphertext before any padding or plaintext is exposed, or pair CBC with a MAC verified before decryption (encrypt-then-MAC).

Constructors

SymmetricCipher()

Initializes a new instance of the SymmetricCipher class.

protected SymmetricCipher()

Properties

AlgorithmName

Gets the name of the cipher algorithm.

public abstract string AlgorithmName { get; }

Property Value

string

Examples

"AES-256", "ChaCha20", "AES-256-GCM"

IV

Gets or sets the initialization vector (IV) or nonce for the cipher operation.

public override byte[] IV { get; set; }

Property Value

byte[]

Remarks

The IV/nonce size depends on the algorithm and mode:

  • AES-CBC: 16 bytes (block size)
  • AES-GCM: 12 bytes (recommended) or variable
  • ChaCha20: 12 bytes
  • XChaCha20: 24 bytes

Important: Never reuse an IV/nonce with the same key. For GCM/Poly1305, nonce reuse completely compromises security.

Exceptions

ArgumentNullException

Value is null.

CryptographicException

Value has an invalid size.

IVSize

Gets the required IV/nonce size in bytes for the current mode.

public abstract int IVSize { get; }

Property Value

int

InitialCounter

Gets or sets the initial block counter value for stream ciphers.

public virtual uint InitialCounter { get; set; }

Property Value

uint

Remarks

The default value is 0. Some protocols (like TLS) use 1 as the initial counter. Block ciphers ignore this property.

IsAuthenticated

Gets a value indicating whether this cipher provides authenticated encryption.

public virtual bool IsAuthenticated { get; }

Property Value

bool

Key

Gets or sets the secret key for the cipher operation.

public override byte[] Key { get; set; }

Property Value

byte[]

Exceptions

ArgumentNullException

Value is null.

CryptographicException

Value has an invalid size.

Mode

Gets or sets the cipher mode of operation.

public virtual CipherMode Mode { get; set; }

Property Value

CipherMode

Remarks

This property shadows Mode to use CipherMode, which includes additional modes such as CTR, GCM, CCM, and Stream.

Padding

Gets or sets the padding mode.

public virtual PaddingMode Padding { get; set; }

Property Value

PaddingMode

Remarks

This property shadows Padding to use PaddingMode, whose values are identical to PaddingMode.

TagSize

Gets the authentication tag size in bytes for AEAD modes.

public virtual int TagSize { get; }

Property Value

int

Remarks

Returns 0 for non-AEAD modes. For GCM, common values are 12, 13, 14, 15, or 16 bytes.

Methods

CalculateOutputSize(int, bool)

Calculates the output buffer size required for the given input size.

protected virtual int CalculateOutputSize(int inputLength, bool encrypting)

Parameters

inputLength int

The input data length in bytes.

encrypting bool

True if encrypting, false if decrypting.

Returns

int

The required output buffer size in bytes.

ClearSensitiveData(byte[]?)

Clears sensitive data from memory.

protected static void ClearSensitiveData(byte[]? data)

Parameters

data byte[]

The data to clear.

CreateCipherDecryptor(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Creates a decryptor transform using the specified key and IV.

protected abstract ICipherTransform CreateCipherDecryptor(ReadOnlySpan<byte> key, ReadOnlySpan<byte> iv)

Parameters

key ReadOnlySpan<byte>

The secret key.

iv ReadOnlySpan<byte>

The initialization vector or nonce.

Returns

ICipherTransform

A new cipher decryptor transform.

CreateCipherEncryptor(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Creates an encryptor transform using the specified key and IV.

protected abstract ICipherTransform CreateCipherEncryptor(ReadOnlySpan<byte> key, ReadOnlySpan<byte> iv)

Parameters

key ReadOnlySpan<byte>

The secret key.

iv ReadOnlySpan<byte>

The initialization vector or nonce.

Returns

ICipherTransform

A new cipher encryptor transform.

CreateDecryptor()

Creates a decryptor transform using the current key and IV.

public ICipherTransform CreateDecryptor()

Returns

ICipherTransform

A new decryptor transform.

Exceptions

CryptographicException

Key or IV is not set.

CreateDecryptor(byte[], byte[]?)

Creates a decryptor transform using the specified key and IV.

public override ICryptoTransform CreateDecryptor(byte[] rgbKey, byte[]? rgbIV)

Parameters

rgbKey byte[]

The secret key.

rgbIV byte[]

The initialization vector or nonce.

Returns

ICryptoTransform

A new decryptor transform.

CreateEncryptor()

Creates an encryptor transform using the current key and IV.

public ICipherTransform CreateEncryptor()

Returns

ICipherTransform

A new encryptor transform.

Exceptions

CryptographicException

Key or IV is not set.

CreateEncryptor(byte[], byte[]?)

Creates an encryptor transform using the specified key and IV.

public override ICryptoTransform CreateEncryptor(byte[] rgbKey, byte[]? rgbIV)

Parameters

rgbKey byte[]

The secret key.

rgbIV byte[]

The initialization vector or nonce.

Returns

ICryptoTransform

A new encryptor transform.

Decrypt(ReadOnlySpan<byte>)

Decrypts ciphertext in a single operation.

public virtual byte[] Decrypt(ReadOnlySpan<byte> ciphertext)

Parameters

ciphertext ReadOnlySpan<byte>

The data to decrypt.

Returns

byte[]

The decrypted plaintext.

Encrypt(ReadOnlySpan<byte>)

Encrypts plaintext in a single operation.

public virtual byte[] Encrypt(ReadOnlySpan<byte> plaintext)

Parameters

plaintext ReadOnlySpan<byte>

The data to encrypt.

Returns

byte[]

The encrypted ciphertext.

Remarks

This is a convenience method that creates an encryptor, transforms the data, and disposes the encryptor. For multiple operations, reuse CreateEncryptor().

GenerateIV()

Generates a random IV/nonce appropriate for this algorithm and mode.

public override void GenerateIV()

GenerateKey()

Generates a random key appropriate for this algorithm.

public override void GenerateKey()

GetIVOrThrow()

Gets the current IV or throws if not set.

protected byte[] GetIVOrThrow()

Returns

byte[]

GetKeyOrThrow()

Gets the current key or throws if not set.

protected byte[] GetKeyOrThrow()

Returns

byte[]

ValidateIVSize(int)

Validates that the specified IV size is valid for this algorithm and mode.

protected virtual void ValidateIVSize(int byteLength)

Parameters

byteLength int

The IV size in bytes.

Exceptions

CryptographicException

The IV size is invalid.

ValidateKeySize(int)

Validates that the specified key size is valid for this algorithm.

protected void ValidateKeySize(int bitLength)

Parameters

bitLength int

The key size in bits.

Exceptions

CryptographicException

The key size is invalid.

Edit this page