Table of Contents

Class Base16

Namespace
Yubico.Core.Buffers
Assembly
Yubico.Core.dll

Class for encoding and decoding bytes into base-16 encoded text, otherwise known as hexadecimal.

public class Base16 : ITextEncoding
Inheritance
object
Base16
Implements
Derived

Remarks

This base class is a fully functional encoder/decoder for base-16, also known as hexadecimal. The class Hex is an alias so that code using that class can continue unmodified. New code should use this class.

See RFC4648 for details (https://datatracker.ietf.org/doc/html/rfc4648) on base-16.

Properties

CharacterSet

The set of characters that correspond to numbers 0 - 16.

protected virtual Span<char> CharacterSet { get; }

Property Value

Span<char>

DefaultLowerCase

Indicates the default case of characters for this encoding.

protected virtual bool DefaultLowerCase { get; }

Property Value

bool

Remarks

This is used when decoding data to check for characters that are in an unexpected case. To match nibbles (4-bit values) to a character, we must change the case of the character to match what's expected. For example, the reference string for ModHex is cbdefghijklnrtuv. If we receive a 16-bit value in ModHex that looks like CCCB, then the matching algorithm needs to know to change each character as it is being evaluated to cccb.

Methods

Decode(ReadOnlySpan<char>, Span<byte>)

Decode the string into data.

public void Decode(ReadOnlySpan<char> encoded, Span<byte> data)

Parameters

encoded ReadOnlySpan<char>

Encoded text.

data Span<byte>

A System.Span<T> to decode the data to.

Remarks

When decoding sensitive data that should not be in an immutable object, this method gives you the ability to decode directly to a char System.Span<T>.

The point of this method is to allow you to decode data to a char collection that you own. Therefore, you must allocate this collection before calling this method.

For Base16 and ModHex, it is one character per four bits of information, so two characters per byte.

For Base32, it is more complicated. Each character hold five bits of data. Plus, you must account for padding at the end of the encoded data. There is a method to calculate the space needed called GetDecodedSize(ReadOnlySpan<char>) that will tell you how many bytes you need.

Decode(string)

Decode the string into a byte array.

public byte[] Decode(string encoded)

Parameters

encoded string

A string encoded with data to be decoded.

Returns

byte[]

A byte collection resulting from decoding encoded.

DecodeText(ReadOnlySpan<char>, Span<byte>)

Decode the string into data.

public static void DecodeText(ReadOnlySpan<char> encoded, Span<byte> data)

Parameters

encoded ReadOnlySpan<char>

Encoded text.

data Span<byte>

A System.Span<T> to decode the data to.

Remarks

When decoding sensitive data that should not be in an immutable object, this method gives you the ability to decode directly to a char System.Span<T>.

The point of this method is to allow you to decode data to a char collection that you own. Therefore, you must allocate this collection before calling this method.

For Base16 and ModHex, it is one character per four bits of information, so two characters per byte.

For Base32, it is more complicated. Each character hold five bits of data. Plus, you must account for padding at the end of the encoded data. There is a method to calculate the space needed called GetDecodedSize(ReadOnlySpan<char>) that will tell you how many bytes you need.

DecodeText(string)

Decode the string into a byte array.

public static byte[] DecodeText(string encoded)

Parameters

encoded string

A string encoded with data to be decoded.

Returns

byte[]

A byte collection resulting from decoding encoded.

Encode(ReadOnlySpan<byte>)

Encode the byte collection into a string representation.

public string Encode(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

The byte collection to encode.

Returns

string

A string representation of data.

Encode(ReadOnlySpan<byte>, Span<char>)

Encode the byte collection into encoded.

public void Encode(ReadOnlySpan<byte> data, Span<char> encoded)

Parameters

data ReadOnlySpan<byte>

The data to be encoded.

encoded Span<char>

A System.Span<T> to encode the data to.

Remarks

When encoding sensitive data that should not be in an immutable object, this method gives you the ability to encode directly to memory.

The point of this method is to allow you to encode data to memory that you own. Therefore, you must allocate this memory before calling this method. The amount of memory required varies depending on the encoding.

For Base16 and ModHex, it is one character per four bits of information, so two characters per byte.

For Base32, it is more complicated. Each character hold five bits of data. Plus, you must account for padding at the end of the encoded data. There is a method to calculate the space needed called GetEncodedSize(int) that will tell you how many bytes you need.

EncodeBytes(ReadOnlySpan<byte>)

Encode the byte collection into a string representation.

public static string EncodeBytes(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

The byte collection to encode.

Returns

string

A string representation of data.

EncodeBytes(ReadOnlySpan<byte>, Span<char>)

Encode the byte collection into encoded.

public static void EncodeBytes(ReadOnlySpan<byte> data, Span<char> encoded)

Parameters

data ReadOnlySpan<byte>

The data to be encoded.

encoded Span<char>

A System.Span<T> to encode the data to.

Remarks

When encoding sensitive data that should not be in an immutable object, this method gives you the ability to encode directly to memory.

The point of this method is to allow you to encode data to memory that you own. Therefore, you must allocate this memory before calling this method. The amount of memory required varies depending on the encoding.

For Base16 and ModHex, it is one character per four bits of information, so two characters per byte.

For Base32, it is more complicated. Each character hold five bits of data. Plus, you must account for padding at the end of the encoded data. There is a method to calculate the space needed called GetEncodedSize(int) that will tell you how many bytes you need.