Voucher Generators

Introduction

Voucher generators in the voucher server determine how each voucher’s Hidden Recharge Number (HRN) is generated, encrypted and stored in the database.

  1. The encryption algorithm used to encrypt each HRN (one per voucher) before storage in the database.
  2. The length of each HRN.

A deployed voucher server may define more than one generator if required - e.g. if multiple different voucher number lengths are required.

Hidden Recharge Number

The Hidden Recharge Number (HRN) is the numeric (or alphanumeric) voucher number which is used by the person who purchases (or otherwise receives) the voucher, submitting the voucher number for the voucher value.

The HRN may also be called the “voucher number”, or the “voucher PIN”, or “PIN digits”.

The voucher server will by default limit voucher numbers to numeric digits (as these are most easily submitted via voice IVR systems in telephony networks), however HRNs may be any combination of alphanumeric values. It is also possible to restrict certain alphabetic characters from use (e.g. i, I, 1, L and l), decreasing the likelihood of invalid input due to mistakes by users.

Encryption Methods

Vouchers often represent financial value and require strong security controls to ensure this financial value cannot be stolen or abused by users with access to the voucher system.

The expectation is for the voucher server to encrypt, using a one-way hash, each voucher HRN generated by the voucher server. This encryption is done immediately in memory during voucher generation, and the encrypted HRN is stored into the database.

The unencrypted HRN is not stored to the database, it is written to a print file, which is then stored securely on disk (or other target output source). The print file is generally the only location for the unencrypted HRNs and is generally deleted off of disk as soon as is practical.

The following encryption methods are available without custom extension:

  1. No Encryption
  2. HMAC SHA 1
  3. HMAC SHA 256
  4. HMAC MD5

The “No Encryption” option is recommended only for test use. For production use it is recommended that “HMAC SHA 256” is used.

Voucher Generator Details

The voucher generator details screen determines the key generator properties:

Voucher Generator Details

Fields

Class

The “Class” of encryption determines the mechanism by which the encryption is performed. Other than “No Encryption” which does not perform any encryption at all, each encryption method is a one-way hash function which, given the unencrypted HRN and the generator’s encryption key, will generate the encrypted HRN stored to the database.

The options available in the base installation of the voucher server are:

The Mac Encrypted Random Number option includes an encyrption method configuration option which is a required field to determine which HMAC encryption method is used.

Encryption Method

The encryption method determines the actual HMAC encryption method used. It is recommended that SHA 256 is selected.

Encryption Key

When defining a voucher generator using a HMAC encryption method, an encryption key must be provided. The length of the encryption key must be at least 256 bits (32 bytes) of data.

An encryption key is not required when the “No Encryption” class is selected.

Once configured, it is critical that the encryption key is not altered. Altering the encryption key would invalidate all vouchers generated with the voucher generator, as the one-way hash would be unable to re-generate the same encrypted HRN value from the unencrypted HRN value.

HRN Length

The HRN length is the number of digits that a user would type into an input field redeem a voucher. The HRN length should be long enough to ensure that voucher users cannot have a reasonable chance of guessing a voucher number (even when knowning many redeemed voucher numbers), yet short enough to minimise user frustration.

Active Flag

The active/inactive flag for the voucher generator determines whether the generator can be selected when new voucher batches are defined. It does not affect batches previously created.

HRN Uniqueness

It is important for the HRN to be unique within the scope of all active and redeemable vouchers in the voucher server.

Where an encrypted HRN conflicts with an existing stored record, the second voucher generated will not be able to be committed to the database, as there is a unique constraint on the encrypted HRN field to enforce uniqueness.

If the voucher generation system randomly generates two unencrypted HRNs that are the same value after encryption, then the system will not let the second generated voucher be stored - the voucher generation will throw the clashing HRN away and regenerate a new random HRN.

In the case where the same HRN generates to two different encrypted HRNs, then which voucher record is selected by the system during voucher redemption is determined by the order in which the generators are used.

It is feasible (but unlikely) that two HRNs, when encrypted, will have the same encryption string. The likelihood of this occurring depends on the encryption method - for example with HMAC SHA 256 the chance of a collision is approximately 10^38.