Encoding

Purpose

It can be useful to convert bytes to strings. For example, to represent hashes or to create shareable X25519 and Ed25519 public keys. Hex and Base64 encoding can be used to do this.

Usage

GetToHexBufferSize

Returns the output buffer size required for ToHex().

Encodings.GetToHexBufferSize(ReadOnlySpan<byte> data)

Exceptions

ArgumentOutOfRangeException

data has a length of 0.

OverflowException

data.Length * 2 has resulted in an overflow.

ToHex

Fills a span with the hexadecimal string that represents the provided data.

Encodings.ToHex(Span<char> hex, ReadOnlySpan<byte> data)

Exceptions

ArgumentOutOfRangeException

hex has a length not equal to GetToHexBufferSize().

ArgumentOutOfRangeException

data has a length of 0.

OverflowException

data.Length * 2 has resulted in an overflow.

CryptographicException

Error converting bytes to hex.

GetFromHexBufferSize

Returns the output buffer size required for FromHex().

Encodings.GetFromHexBufferSize(ReadOnlySpan<char> hex, ReadOnlySpan<char> ignoreChars = default)

Exceptions

ArgumentOutOfRangeException

hex has a length of 0 or is not a multiple of 2 (after discounting ignored chars).

ArgumentException

hex cannot contain non-ASCII characters.

ArgumentException

ignoreChars cannot contain hex characters or represent the only characters in hex.

FromHex

Fills a span with the data from decoding a hexadecimal string. Separator characters to ignore when parsing can optionally be provided.

Encodings.FromHex(Span<byte> data, ReadOnlySpan<char> hex, ReadOnlySpan<char> ignoreChars = default)

Exceptions

ArgumentOutOfRangeException

data has a length not equal to GetFromHexBufferSize().

ArgumentOutOfRangeException

hex has a length of 0 or is not a multiple of 2 (after discounting ignored chars).

ArgumentException

hex cannot contain non-ASCII characters.

ArgumentException

ignoreChars cannot contain hex characters or represent the only characters in hex.

FormatException

Invalid hex string.

GetToBase64BufferSize

Returns the output buffer size required for ToBase64().

Encodings.GetToBase64BufferSize(ReadOnlySpan<byte> data, Base64Variant variant = Base64Variant.Original)

Exceptions

ArgumentOutOfRangeException

data has a length of 0.

ArgumentOutOfRangeException

variant must be a value within the enum.

OverflowException

The encoded length is too large for an array.

ToBase64

Fills a span with the Base64 string that represents the provided data. Choose one variant (e.g., Base64URL for file names/URLs) and only ever use that variant.

Encodings.ToBase64(Span<char> base64, ReadOnlySpan<byte> data, Base64Variant variant = Base64Variant.Original)

Exceptions

ArgumentOutOfRangeException

base64 has a length not equal to GetToBase64BufferSize().

ArgumentOutOfRangeException

data has a length of 0.

ArgumentOutOfRangeException

variant must be a value within the enum.

CryptographicException

Error converting bytes to Base64.

GetFromBase64BufferSize

Returns the output buffer size required for FromBase64().

Encodings.GetFromBase64BufferSize(ReadOnlySpan<char> base64, Base64Variant variant = Base64Variant.Original, ReadOnlySpan<char> ignoreChars = default)

Exceptions

ArgumentOutOfRangeException

base64 has a length of 0 or is not a valid length based on variant.

ArgumentOutOfRangeException

variant must be a value within the enum.

ArgumentException

base64 cannot contain non-ASCII characters.

ArgumentException

ignoreChars cannot contain Base64 characters or represent the only characters in base64.

OverflowException

The buffer size computation has resulted in an overflow.

FromBase64

Fills a span with the data from decoding a Base64 string. The variant must match the one used for encoding. Separator characters to ignore when parsing can optionally be provided.

Encodings.FromBase64(Span<byte> data, ReadOnlySpan<char> base64, Base64Variant variant = Base64Variant.Original, ReadOnlySpan<char> ignoreChars = default)

Exceptions

ArgumentOutOfRangeException

data has a length not equal to GetFromBase64BufferSize().

ArgumentOutOfRangeException

base64 has a length of 0 or is not a valid length based on variant.

ArgumentOutOfRangeException

variant must be a value within the enum.

ArgumentException

base64 cannot contain non-ASCII characters.

ArgumentException

ignoreChars cannot contain Base64 characters or represent the only characters in base64.

OverflowException

The buffer size computation has resulted in an overflow.

FormatException

Invalid Base64 string.

Constants

public const string HexCharacterSet = "0123456789ABCDEFabcdef";
public const string Base64CharacterSet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";
public const string Base64UrlCharacterSet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_=";
public const string Base64FullCharacterSet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/-_=";
public const string HexIgnoreChars = ":- _./,%;";
public const string Base64IgnoreChars = " \r\n";

public enum Base64Variant
{
    Original = 1,
    OriginalNoPadding = 3,
    Url = 5,
    UrlNoPadding = 7
}

Notes

Do NOT support multiple variants of Base64 in your application (e.g., Base64 with and without padding). This can lead to vulnerabilities.

Unlike in the .NET library, these functions run in constant time to avoid potential side-channel attacks. Furthermore, the Base64 implementation should be more resistant to malleability attacks.

Base64 has a better compression rate than hex. However, they tend to be used for different purposes. For instance, hex is often used for test vectors and encoding hashes, whereas Base64 is more commonly used for encoding keys.