Class CryptoBox

Namespace

LibSodium

Assembly

LibSodium.Net.dll

Provides high-level access to the Curve25519-based public-key authenticated encryption (crypto_box) from Libsodium.

public static class CryptoBox

Inheritance

object

CryptoBox

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This class supports both combined and detached modes, auto nonce, as well as encryption using precomputed shared keys.

Properties

MacLen

MAC length in bytes (16).

public static int MacLen { get; }

Property Value

int

NonceLen

Nonce length in bytes (24).

public static int NonceLen { get; }

Property Value

int

PrivateKeyLen

Private key length in bytes (32).

public static int PrivateKeyLen { get; }

Property Value

int

PublicKeyLen

Public key length in bytes (32).

public static int PublicKeyLen { get; }

Property Value

int

SealOverheadLen

Length of the ciphertext overhead (48) when using EncryptWithPublicKey and DecryptWithPrivateKey.

public static int SealOverheadLen { get; }

Property Value

int

SeedLen

Seed length in bytes (32).

public static int SeedLen { get; }

Property Value

int

SharedKeyLen

Shared key length in bytes (32).

public static int SharedKeyLen { get; }

Property Value

int

Methods

CalculatePublicKey(Span<byte>, SecureMemory<byte>)

Calculates the Curve25519 public key from a given private key.

public static void CalculatePublicKey(Span<byte> publicKey, SecureMemory<byte> privateKey)

Parameters

publicKey Span<byte>

The buffer where the calculated public key (32 bytes) will be written.

privateKey SecureMemory<byte>

The private key to derive from (32 bytes).

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if public key calculation fails.

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

Calculates the Curve25519 public key from a given private key.

public static void CalculatePublicKey(Span<byte> publicKey, ReadOnlySpan<byte> privateKey)

Parameters

publicKey Span<byte>

The buffer where the calculated public key (32 bytes) will be written.

privateKey ReadOnlySpan<byte>

The private key to derive from (32 bytes).

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if public key calculation fails.

CalculateSharedKey(SecureMemory<byte>, ReadOnlySpan<byte>, SecureMemory<byte>)

Calculates a shared secret using a peer's public key and the local private key.

public static void CalculateSharedKey(SecureMemory<byte> sharedKey, ReadOnlySpan<byte> peerPublicKey, SecureMemory<byte> localPrivateKey)

Parameters

sharedKey SecureMemory<byte>

The buffer where the shared key (32 bytes) will be written.

peerPublicKey ReadOnlySpan<byte>

The peer's public key (32 bytes).

localPrivateKey SecureMemory<byte>

The local private key (32 bytes).

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if shared key calculation fails.

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

Calculates a shared secret using a peer's public key and the local private key.

public static void CalculateSharedKey(Span<byte> sharedKey, ReadOnlySpan<byte> peerPublicKey, ReadOnlySpan<byte> localPrivateKey)

Parameters

sharedKey Span<byte>

The buffer where the shared key (32 bytes) will be written.

peerPublicKey ReadOnlySpan<byte>

The peer's public key (32 bytes).

localPrivateKey ReadOnlySpan<byte>

The local private key (32 bytes).

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if shared key calculation fails.

DecryptWithKeypair(Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, SecureMemory<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Decrypts a message using the recipient's private key and the sender's public key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> DecryptWithKeypair(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> senderPublicKey, SecureMemory<byte> recipientPrivateKey, ReadOnlySpan<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written.

ciphertext ReadOnlySpan<byte>

The encrypted message. May include MAC and nonce (combined) or exclude them (detached).

senderPublicKey ReadOnlySpan<byte>

The sender's public key (32 bytes).

recipientPrivateKey SecureMemory<byte>

The recipient's private key (32 bytes).

mac ReadOnlySpan<byte>

Optional. If provided, decryption is done in detached mode. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided it is taken from the beginning of the ciphertext.

Returns

Span<byte>

The span representing the decrypted plaintext.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when MAC verification fails or decryption fails.

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

Decrypts a message using the recipient's private key and the sender's public key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> DecryptWithKeypair(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> senderPublicKey, ReadOnlySpan<byte> recipientPrivateKey, ReadOnlySpan<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written.

ciphertext ReadOnlySpan<byte>

The encrypted message. May include MAC and nonce (combined) or exclude them (detached).

senderPublicKey ReadOnlySpan<byte>

The sender's public key (32 bytes).

recipientPrivateKey ReadOnlySpan<byte>

The recipient's private key (32 bytes).

mac ReadOnlySpan<byte>

Optional. If provided, decryption is done in detached mode. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided it is taken from the beginning of the ciphertext.

Returns

Span<byte>

The span representing the decrypted plaintext.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when MAC verification fails or decryption fails.

DecryptWithPrivateKey(Span<byte>, ReadOnlySpan<byte>, SecureMemory<byte>)

Decrypts a sealed message using the recipient's private key. This method uses libsodium's crypto_box_seal_open internally and automatically derives the recipient's public key from the given private key. The ciphertext must have been produced using EncryptWithPublicKey(Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>).

public static Span<byte> DecryptWithPrivateKey(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, SecureMemory<byte> recipientPrivateKey)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written. Must be at least ciphertext.Length - SealOverheadLen bytes long.

ciphertext ReadOnlySpan<byte>

The sealed ciphertext, including a 32-byte ephemeral public key and a 16-byte MAC. Must be at least SealOverheadLen bytes long.

recipientPrivateKey SecureMemory<byte>

The recipient's private key (32 bytes).

Returns

Span<byte>

A slice of the plaintext buffer containing the decrypted message.

Exceptions

ArgumentException

Thrown when buffer sizes are invalid or the private key is not 32 bytes long.

LibSodiumException

Thrown when the ciphertext cannot be decrypted or the MAC verification fails.

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

Decrypts a sealed message using the recipient's private key. This method uses libsodium's crypto_box_seal_open internally and automatically derives the recipient's public key from the given private key. The ciphertext must have been produced using EncryptWithPublicKey(Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>).

public static Span<byte> DecryptWithPrivateKey(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> recipientPrivateKey)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written. Must be at least ciphertext.Length - SealOverheadLen bytes long.

ciphertext ReadOnlySpan<byte>

The sealed ciphertext, including a 32-byte ephemeral public key and a 16-byte MAC. Must be at least SealOverheadLen bytes long.

recipientPrivateKey ReadOnlySpan<byte>

The recipient's private key (32 bytes).

Returns

Span<byte>

A slice of the plaintext buffer containing the decrypted message.

Exceptions

ArgumentException

Thrown when buffer sizes are invalid or the private key is not 32 bytes long.

LibSodiumException

Thrown when the ciphertext cannot be decrypted or the MAC verification fails.

DecryptWithSharedKey(Span<byte>, ReadOnlySpan<byte>, SecureMemory<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Decrypts a message using a precomputed shared key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> DecryptWithSharedKey(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, SecureMemory<byte> sharedKey, ReadOnlySpan<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written.

ciphertext ReadOnlySpan<byte>

The encrypted message. May include MAC and nonce (combined) or exclude them (detached).

sharedKey SecureMemory<byte>

The shared key (32 bytes) previously computed using CalculateSharedKey.

mac ReadOnlySpan<byte>

Optional. If provided, decryption is done in detached mode. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, it is taken from the beginning of the ciphertext

Returns

Span<byte>

The span representing the decrypted plaintext.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when MAC verification fails or decryption fails.

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

Decrypts a message using a precomputed shared key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> DecryptWithSharedKey(Span<byte> plaintext, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> sharedKey, ReadOnlySpan<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

plaintext Span<byte>

The buffer where the decrypted message will be written.

ciphertext ReadOnlySpan<byte>

The encrypted message. May include MAC and nonce (combined) or exclude them (detached).

sharedKey ReadOnlySpan<byte>

The shared key (32 bytes) previously computed using CalculateSharedKey.

mac ReadOnlySpan<byte>

Optional. If provided, decryption is done in detached mode. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, it is taken from the beginning of the ciphertext

Returns

Span<byte>

The span representing the decrypted plaintext.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when MAC verification fails or decryption fails.

EncryptWithKeypair(Span<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, SecureMemory<byte>, Span<byte>, ReadOnlySpan<byte>)

Encrypts a message using the recipient's public key and the sender's private key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> EncryptWithKeypair(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> recipientPublicKey, SecureMemory<byte> senderPrivateKey, Span<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

ciphertext Span<byte>

The buffer where the ciphertext will be written. Must be large enough to hold the output (plaintext + 16 bytes MAC [+ 24 bytes nonce if auto-generated]).

plaintext ReadOnlySpan<byte>

The message to encrypt.

recipientPublicKey ReadOnlySpan<byte>

The recipient's public key (32 bytes).

senderPrivateKey SecureMemory<byte>

The sender's private key (32 bytes).

mac Span<byte>

Optional. If provided, encryption is done in detached mode and the MAC (16 bytes) is written here. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, a random nonce is generated and prepended.

Returns

Span<byte>

The span representing the full ciphertext, including MAC and possibly nonce.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when encryption fails.

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

Encrypts a message using the recipient's public key and the sender's private key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> EncryptWithKeypair(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> senderPrivateKey, Span<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

ciphertext Span<byte>

The buffer where the ciphertext will be written. Must be large enough to hold the output (plaintext + 16 bytes MAC [+ 24 bytes nonce if auto-generated]).

plaintext ReadOnlySpan<byte>

The message to encrypt.

recipientPublicKey ReadOnlySpan<byte>

The recipient's public key (32 bytes).

senderPrivateKey ReadOnlySpan<byte>

The sender's private key (32 bytes).

mac Span<byte>

Optional. If provided, encryption is done in detached mode and the MAC (16 bytes) is written here. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, a random nonce is generated and prepended.

Returns

Span<byte>

The span representing the full ciphertext, including MAC and possibly nonce.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when encryption fails.

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

Encrypts a message anonymously using the recipient's public key. This method uses Libsodium's crypto_box_seal function internally, and does not require a sender key. The resulting ciphertext includes an ephemeral public key and a MAC, adding a constant overhead of SealOverheadLen bytes.

public static Span<byte> EncryptWithPublicKey(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> recipientPublicKey)

Parameters

ciphertext Span<byte>

The buffer where the sealed ciphertext will be written. Must be at least plaintext.Length + SealOverheadLen bytes long.

plaintext ReadOnlySpan<byte>

The message to encrypt.

recipientPublicKey ReadOnlySpan<byte>

The recipient's public key (32 bytes).

Returns

Span<byte>

A slice of the ciphertext buffer containing the full sealed ciphertext.

Exceptions

ArgumentException

Thrown when the recipient's public key is not 32 bytes long, or when the ciphertext buffer is too small.

LibSodiumException

Thrown when the underlying Libsodium encryption operation fails.

EncryptWithSharedKey(Span<byte>, ReadOnlySpan<byte>, SecureMemory<byte>, Span<byte>, ReadOnlySpan<byte>)

Encrypts a message using a precomputed shared key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> EncryptWithSharedKey(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, SecureMemory<byte> sharedKey, Span<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

ciphertext Span<byte>

The buffer where the ciphertext will be written. Must be large enough to hold the output (plaintext + 16 bytes MAC [+ 24 bytes nonce if auto-generated]).

plaintext ReadOnlySpan<byte>

The message to encrypt.

sharedKey SecureMemory<byte>

The shared key (32 bytes) previously computed using CalculateSharedKey.

mac Span<byte>

Optional. If provided, encryption is done in detached mode and the MAC (16 bytes) is written here. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, a random nonce is generated and prepended.

Returns

Span<byte>

The span representing the full ciphertext, including MAC and possibly nonce.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when encryption fails.

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

Encrypts a message using a precomputed shared key. Supports both combined and detached modes, with optional nonce.

public static Span<byte> EncryptWithSharedKey(Span<byte> ciphertext, ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> sharedKey, Span<byte> mac = default, ReadOnlySpan<byte> nonce = default)

Parameters

ciphertext Span<byte>

The buffer where the ciphertext will be written. Must be large enough to hold the output (plaintext + 16 bytes MAC [+ 24 bytes nonce if auto-generated]).

plaintext ReadOnlySpan<byte>

The message to encrypt.

sharedKey ReadOnlySpan<byte>

The shared key (32 bytes) previously computed using CalculateSharedKey.

mac Span<byte>

Optional. If provided, encryption is done in detached mode and the MAC (16 bytes) is written here. Otherwise, combined mode is used.

nonce ReadOnlySpan<byte>

Optional nonce (24 bytes). If not provided, a random nonce is generated and prepended.

Returns

Span<byte>

The span representing the full ciphertext, including MAC and possibly nonce.

Exceptions

ArgumentException

Thrown when buffer sizes are incorrect or parameters are invalid.

LibSodiumException

Thrown when encryption fails.

GenerateKeypair(Span<byte>, SecureMemory<byte>)

Generates a new Curve25519 key pair for use with crypto_box.

public static void GenerateKeypair(Span<byte> publicKey, SecureMemory<byte> privateKey)

Parameters

publicKey Span<byte>

The buffer where the generated public key (32 bytes) will be written.

privateKey SecureMemory<byte>

The buffer where the generated private key (32 bytes) will be written.

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if key generation fails.

GenerateKeypair(Span<byte>, Span<byte>)

Generates a new Curve25519 key pair for use with crypto_box.

public static void GenerateKeypair(Span<byte> publicKey, Span<byte> privateKey)

Parameters

publicKey Span<byte>

The buffer where the generated public key (32 bytes) will be written.

privateKey Span<byte>

The buffer where the generated private key (32 bytes) will be written.

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if key generation fails.

GenerateKeypairDeterministically(Span<byte>, SecureMemory<byte>, ReadOnlySpan<byte>)

Generates a Curve25519 key pair deterministically from a seed.

public static void GenerateKeypairDeterministically(Span<byte> publicKey, SecureMemory<byte> privateKey, ReadOnlySpan<byte> seed)

Parameters

publicKey Span<byte>

The buffer where the generated public key (32 bytes) will be written.

privateKey SecureMemory<byte>

The buffer where the generated private key (32 bytes) will be written.

seed ReadOnlySpan<byte>

The seed to use for deterministic key generation (32 bytes).

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if key generation fails.

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

Generates a Curve25519 key pair deterministically from a seed.

public static void GenerateKeypairDeterministically(Span<byte> publicKey, Span<byte> privateKey, ReadOnlySpan<byte> seed)

Parameters

publicKey Span<byte>

The buffer where the generated public key (32 bytes) will be written.

privateKey Span<byte>

The buffer where the generated private key (32 bytes) will be written.

seed ReadOnlySpan<byte>

The seed to use for deterministic key generation (32 bytes).

Exceptions

ArgumentException

Thrown if the buffer sizes are incorrect.

LibSodiumException

Thrown if key generation fails.