Class CryptoSecretStream

Namespace

LibSodium

Assembly

LibSodium.Net.dll

The CryptoSecretStream class provides methods for performing authenticated encryption and decryption of data streams, with optional additional authenticated data. It is based on the XChaCha20-Poly1305 algorithm.

public static class CryptoSecretStream

Inheritance

object

CryptoSecretStream

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

HeaderLen

The length of the header used in the secret stream.

public const int HeaderLen = 24

Field Value

int

KeyLen

The length of the key used for encryption and decryption.

public const int KeyLen = 32

Field Value

int

OverheadLen

The length of the overhead added to each ciphertext message. This includes the authentication tag and any necessary metadata for the stream.

public static int OverheadLen

Field Value

int

StateLen

The length of the state used in the secret stream.

public static int StateLen

Field Value

int

Methods

DecryptChunk(Span<byte>, Span<byte>, out CryptoSecretStreamTag, ReadOnlySpan<byte>)

Decrypts and verifies the authenticity of a block of data using the secret stream.

public static Span<byte> DecryptChunk(Span<byte> state, Span<byte> cleartext, out CryptoSecretStreamTag tag, ReadOnlySpan<byte> ciphertext)

Parameters

state Span<byte>

The current state of the secret stream. Must be StateLen bytes long.

cleartext Span<byte>

The span to write the decrypted data to. Must have a length of at least ciphertext.Length - OverheadLen.

tag CryptoSecretStreamTag

When this method returns, contains the tag associated with the decrypted message.

ciphertext ReadOnlySpan<byte>

The encrypted and authenticated data to decrypt.

Returns

Span<byte>

A Span<T> representing the decrypted data written to cleartext.

Exceptions

ArgumentException

If the length of the state or cleartext spans are incorrect.

LibSodiumException

If the decryption or authentication of the chunk fails, likely due to tampered ciphertext.

DecryptChunk(Span<byte>, Span<byte>, out CryptoSecretStreamTag, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Decrypts and verifies the authenticity of a block of data using the secret stream with additional authenticated data (AAD).

public static Span<byte> DecryptChunk(Span<byte> state, Span<byte> cleartext, out CryptoSecretStreamTag tag, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> additionalData)

Parameters

state Span<byte>

The current state of the secret stream. Must be StateLen bytes long.

cleartext Span<byte>

The span to write the decrypted data to. Must have a length of at least ciphertext.Length - OverheadLen.

tag CryptoSecretStreamTag

When this method returns, contains the tag associated with the decrypted message.

ciphertext ReadOnlySpan<byte>

The encrypted and authenticated data to decrypt.

additionalData ReadOnlySpan<byte>

Additional authenticated data that was cryptographically incorporated during the calculation of the authentication tag for the corresponding ciphertext. This value must be identical to the one used during the EncryptChunk(Span<byte>, Span<byte>, ReadOnlySpan<byte>, CryptoSecretStreamTag, ReadOnlySpan<byte>) call for authentication to succeed.

Returns

Span<byte>

A Span<T> representing the decrypted data written to cleartext.

Exceptions

ArgumentException

If the length of the state or cleartext spans are incorrect.

LibSodiumException

If the decryption or authentication of the chunk fails, likely due to tampered ciphertext or incorrect AAD.

EncryptChunk(Span<byte>, Span<byte>, ReadOnlySpan<byte>, CryptoSecretStreamTag)

Encrypts and authenticates a block of data using the secret stream.

public static Span<byte> EncryptChunk(Span<byte> state, Span<byte> ciphertext, ReadOnlySpan<byte> cleartext, CryptoSecretStreamTag tag)

Parameters

state Span<byte>

The current state of the secret stream. Must be StateLen bytes long.

ciphertext Span<byte>

The span to write the encrypted and authenticated data to. Must have a length of at least cleartext.Length + OverheadLen.

cleartext ReadOnlySpan<byte>

The data to encrypt.

tag CryptoSecretStreamTag

The tag to associate with this message.

Returns

Span<byte>

A Span<T> representing the encrypted and authenticated data written to ciphertext.

Exceptions

ArgumentException

If the length of the state or ciphertext spans are incorrect.

LibSodiumException

If the encryption of the block fails.

EncryptChunk(Span<byte>, Span<byte>, ReadOnlySpan<byte>, CryptoSecretStreamTag, ReadOnlySpan<byte>)

Encrypts and authenticates a block of data using the secret stream with additional authenticated data (AAD).

public static Span<byte> EncryptChunk(Span<byte> state, Span<byte> ciphertext, ReadOnlySpan<byte> cleartext, CryptoSecretStreamTag tag, ReadOnlySpan<byte> additionalData)

Parameters

state Span<byte>

The current state of the secret stream. Must be StateLen bytes long.

ciphertext Span<byte>

The span to write the encrypted and authenticated data to. Must have a length of at least cleartext.Length + OverheadLen.

cleartext ReadOnlySpan<byte>

The data to encrypt.

tag CryptoSecretStreamTag

The tag to associate with this message.

additionalData ReadOnlySpan<byte>

Additional data that is cryptographically incorporated during the calculation of the authentication tag for the ciphertext. This data is authenticated but not encrypted.

Returns

Span<byte>

A Span<T> representing the encrypted and authenticated data written to ciphertext.

Exceptions

ArgumentException

If the length of the state or ciphertext spans are incorrect.

LibSodiumException

If the encryption of the chunk fails.

GenerateKey(Span<byte>)

Generates a random key for use with the secret stream.

public static void GenerateKey(Span<byte> key)

Parameters

key Span<byte>

The span to write the generated key to.

Exceptions

ArgumentException

If the length of the key span is not equal to KeyLen.

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

Initializes the authenticated decryption process for a secret stream.

public static void InitializeDecryption(Span<byte> state, ReadOnlySpan<byte> header, ReadOnlySpan<byte> key)

Parameters

state Span<byte>

The span to write the initial state to. Must be StateLen bytes long.

header ReadOnlySpan<byte>

The stream header received from the sender. Must be HeaderLen bytes long.

key ReadOnlySpan<byte>

The secret key used for encryption. Must be KeyLen bytes long.

Exceptions

ArgumentException

If the length of the state, header, or key spans are incorrect.

LibSodiumException

If the initialization of decryption fails, likely due to an incorrect header or key.

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

Initializes the authenticated encryption process for a secret stream.

public static void InitializeEncryption(Span<byte> state, Span<byte> header, ReadOnlySpan<byte> key)

Parameters

state Span<byte>

The span to write the initial state to. Must be StateLen bytes long.

header Span<byte>

The span to write the stream header to. Must be HeaderLen bytes long.

key ReadOnlySpan<byte>

The secret key to use for encryption. Must be KeyLen bytes long.

Exceptions

ArgumentException

If the length of the state, header, or key spans are incorrect.

LibSodiumException

If the initialization of encryption fails.