com.lacunasoftware.restpki

Class AlphaCode

java.lang.Object

com.lacunasoftware.restpki.AlphaCode

public class AlphaCode
extends java.lang.Object

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. 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.

Constructor Summary

Constructors

Constructor and Description
AlphaCode()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	format(java.lang.String code) Formats an alphanumeric code in groups of characters separated by hyphens, for instance a 16-character code is formatted as XXXX-XXXX-XXXX-XXXX.
static java.lang.String	format(java.lang.String code, int nGroups) Formats an alphanumeric code in groups, for instance a 16-character code into 4 groups is formatted as XXXX-XXXX-XXXX-XXXX.
static java.lang.String	generate() Generates an alphanumeric code with the default size (see property DefaultSize).
static java.lang.String	generate(int codeSize) Generates an alphanumeric code with the given size.
static int	getDefaultSize() Gets the default size for codes (used by the method generate()).
static java.lang.String	parse(java.lang.String formattedCode) Parses a given alphanumeric code, removing hyphens or other punctuations.
static void	setDefaultSize(int defaultSize) Sets the default size for codes (used by the method generate()).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AlphaCode

public AlphaCode()

Method Detail

generate

public static java.lang.String 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.

Returns:

The alphanumeric code with the default size (unformatted).

generate

public static java.lang.String generate(int codeSize)

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.

Parameters:

codeSize - Size of the code to be generated.

Returns:

The alphanumeric code with the given size (unformatted).

format

public static java.lang.String format(java.lang.String code)

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.

Parameters:

code - The unformatted alphanumeric code.

Returns:

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

public static java.lang.String format(java.lang.String code,
                                      int nGroups)

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-XXXX or nGroups = 5 for XXXX-XXXX-XXXX-XXXX-XXXX.

Parameters:

code - The unformatted alphanumeric code.

nGroups - The number of groups.

Returns:

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

parse

public static java.lang.String parse(java.lang.String formattedCode)

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.

Parameters:

formattedCode - The formatted alphanumeric code, e.g. XXXX-XXXX-XXXX-XXXX.

Returns:

The unformatted alphanumeric code, e.g.: XXXXXXXXXXXXXXXX.

getDefaultSize

public static int getDefaultSize()

Gets 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).

Returns:

the default size for codes (used by the method generate()).

setDefaultSize

public static void setDefaultSize(int defaultSize)

Sets 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).

Parameters:

defaultSize - the default size for codes (used by the method generate()).