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

ToHex

Returns the hexadecimal string that represents the data.

Encodings.ToHex(ReadOnlySpan<byte> data)

Exceptions

ArgumentOutOfRangeException

data has a length of 0.

FormatException

The data could not be converted to hex. This should never be thrown.

FromHex

Returns a byte array from a hexadecimal string. Common separator characters are ignored by default. ignoreChars can be null to disallow any non-hexadecimal characters.

Encodings.FromHex(string hex, string ignoreChars = ":- ")

Exceptions

ArgumentNullException

hex is null.

ArgumentOutOfRangeException

hex has a length of 0.

FormatException

Unable to parse the hex string.

ToBase64

Returns the Base64 string representing the data. Choose one variant (e.g. Base64URL for file names/URLs) and only ever use that variant.

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

Exceptions

ArgumentOutOfRangeException

data has a length of 0.

FormatException

The data could not be converted to Base64. This should never be thrown.

FromBase64

Returns a byte array from a Base64 string. The variant must match the one used for encoding. ignoreChars can be null to disallow any non-Base64 characters.

Encodings.FromBase64(string base64, Base64Variant variant = Base64Variant.Original, string ignoreChars = " ")

Exceptions

ArgumentNullException

base64 is null.

ArgumentOutOfRangeException

base64 has a length of 0.

FormatException

Unable to parse the Base64 string.

Constants

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.