Edit on GitHub

Generating alphanumeric codes on Java

When generating a printer-friendly version of a signed file, a "document verification code" needs to be included in the document so that a third party receiving the printed document can access your website and provide the code to get back the digitally signed version:

Codigo de verificacao

In the past, we provided the source code to generate this verification code as part of the samples, for instance:

public static class Util {

   // ...

   public static string GenerateVerificationCode() {
      // String with exactly 32 letters and numbers to be used on the codes.
      const string Alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
      // Allocate a byte array large enough to receive the necessary entropy
      var bytes = new byte[(int)Math.Ceiling(VerificationCodeSize * 5 / 8.0)];
      // ...
      return sb.ToString();
   }

   // ...

}

However, since the verification code plays an important role in protecting the access to your documents, we now offer the AlphaCode class to perform the code generation.

Updating your app to use AlphaCode

Warning

The verification code generation has recently undergone a careful audit and has received important improvements. We highly recommend that you update your application to use AlphaCode instead of the old provided code.

You probably brought the (now obsolete) methods generateVerificationCode, formatVerificationCode and parseVerificationCode into your own code. To update your application:

  1. Update the Maven package com.lacunasoftware.pkiexpress to version 1.10.0 or greater

  2. Replace the implementation of these methods on your code with calls to methods of the AlphaCode class:

    public static String generateVerificationCode() {
   return AlphaCode.generate();
}

public static String formatVerificationCode(String code) {
   return AlphaCode.format(code);
}

public static String parseVerificationCode(String formattedCode) {
   return AlphaCode.parse(formattedCode);
}

Design principles

The class AlphaCode generates alphanumeric codes that are easy for humans to read, such that:

  1. Codes should be easy to read
  2. Codes should be easy to type back with low risk of mistaking similar characters such as O and 0
  3. Codes should 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):

  • A hexadecimal code would need 20 characters, e.g.: 90A0-F20F-5883-8D55-AD31
  • An AlphaCode code would only need 16 characters, e.g.: FFWC-RHC5-9NLF-VM42

See also