Class AlphaCode

This class generates alphanumeric codes that are easy for humans to read. The codes are intended to be used as "document recovery codes" on printer-friendly versions of signed files, with codes that are (1) easy to read (2) easy to type back with low risk of mistaking similar characters such as "O" and "0" and (3) have a relatively high entropy for the size of the code (high number of possible codes relative to the size of the code, allowing the developer to choose a relatively small code size).

Inheritance

Object

AlphaCode

Inherited Members

Object.ToString()

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: Lacuna.RestPki.Client

Assembly: Lacuna.RestPki.Client.dll

Syntax

public static class AlphaCode

Remarks

To improve readability, the codes contain only uppercase letters and do not include characters like "O", "0", "1" and "I", while still maintaining a relatively high entropy per character. There are 32 possible characters, so every character adds 5 bits to the overall entropy (25% better than using hexadecimal) which results in smaller codes for the same intended entropy. For instance, to generate a code with 80 bits of entropy (2^80 possible codes), an hexadecimal code have to be 20 characters, while a code generated by this class needs only 16 characters.

Properties

DefaultSize

The default size for codes (used by the method Generate()). Each character contributes 5 bits to the overall entropy of the generated codes. This value is initially set to 16, which means 80 bits of entropy (2^80 possible codes).

Declaration

public static int DefaultSize { get; set; }

Property Value

Type	Description
Int32

Methods

Format(String)

Formats an alphanumeric code in groups of characters separated by hyphens, for instance a 16-character code is formatted as XXXX-XXXX-XXXX-XXXX. A guess of the number of groups is made based on the code size. If you want to specify the number of groups, use the overload Format(string, int) instead.

Declaration

public static string Format(string code)

Parameters

Type	Name	Description
String	code	The unformatted alphanumeric code

Returns

Type	Description
String	The alphanumeric code formatted in groups, or the unformatted code if no good guess of the number of groups can be made based on the code size

Format(String, Int32)

Formats an alphanumeric code in groups, for instance a 16-character code into 4 groups is formatted as XXXX-XXXX-XXXX-XXXX. The number of groups should be an exact divisor of the code size, otherwise the code is returned unformatted. For instance, for a code of size 20, you might pass nGroups = 4 for XXXXX-XXXXX-XXXXX-XXXXX or nGroups = 5 for XXXX-XXXX-XXXX-XXXX-XXXX.

Declaration

public static string Format(string code, int nGroups)

Parameters

Type	Name	Description
String	code	The unformatted alphanumeric code
Int32	nGroups	The number of groups

Returns

Type	Description
String	The alphanumeric code formatted in blocks, or the unformatted code if the code size is not divisible by the number of groups

Generate()

Generates an alphanumeric code with the default size (see property DefaultSize). The returned code is unformatted, and is meant to be stored on your database indexing the document or related entity. To show the code to users, you should format the code with one of the Format() methods.

Declaration

public static string Generate()

Returns

Type	Description
String	The alphanumeric code with the default size (unformatted)

Generate(Int32)

Generates an alphanumeric code with the given size. Each character contributes 5 bits to the overall entropy of the generated codes, so for instance a code with size 16 has 80 bits of entropy (2^80 possible codes). The returned code is unformatted, and is meant to be stored on your database indexing the document or related entity. To show the code to users, you should format the code with one of the Format() methods.

Declaration

public static string Generate(int codeSize)

Parameters

Type	Name	Description
Int32	codeSize	Size of the code to be generated

Returns

Type	Description
String	The alphanumeric code with the given size (unformatted)

Parse(String)

Parses a given alphanumeric code, removing hyphens or other punctuations. This method is intended to be called to parse a code typed by the user, before using the code to perform a lookup on the database.

Declaration

public static string Parse(string formattedCode)

Parameters

Type	Name	Description
String	formattedCode	The formatted alphanumeric code, e.g. XXXX-XXXX-XXXX-XXXX

Returns

Type	Description
String	The unformatted alphanumeric code, e.g.: XXXXXXXXXXXXXXXX