Authenticating Captive Portal Users with Vouchers

The Voucher functionality of Captive Portal generates codes that can be used to gain Internet access through the Captive Portal. Each roll of vouchers is generated with a specific time limit. This is commonly used where authenticated time-limited Internet access is desired, without needing to provide a username and password to users. Common uses for Vouchers include Coffee shops, Hotels, Airports, and other similar places.

Users enter their voucher code in the portal page and are granted access for as long as the voucher is valid. Voucher time does not stop counting down if a user logs out; the voucher is only valid from the start of the session for the duration of the voucher length.

To use vouchers, a custom portal page must be used that submits the voucher as auth_voucher.

Setting Up Vouchers

The voucher system creates and verifies vouchers based on public/private key and configuration settings.

RSA Keys

Before the program can be used, a public/private RSA key pair must be generated. A set is generated automatically the first time the page is visited. A new pair may be manually generated if desired. The maximum key length supported is 64 Bits. Using shorter keys will make the generated vouchers shorter but eventually less secure.

Character Set

The character set defines the valid characters for voucher text. The set is case sensitive and should contain printable characters (numbers, lower case and upper case letters) that are hard to confuse with others. For example, avoid 0 (Digit zero), O (Letter O), and l (Lowercase L), 1 (Digit One). It cannot contain a space, double quote, or comma.

Voucher Fields

The following fields control how the vouchers themselves are generated. Leaving these values at their defaults is recommended but they may be adjusted as needed. The total of all these fields must be less than the RSA key size. For example, the default values are 16, 10, and 5. The sum of these is 31, which is one less than 32.

• Number of Roll Bits: Number of Bits used to store the Roll Id. Set this larger if many rolls will be active at the same time. Can be from 1-31.

• Number of Ticket Bits: Number of Bits used to store the Ticket Id. Set this larger if each roll will have a large number of vouchers. Can be from 1-16.

• Number of Checksum Bits:Reserves a range in each voucher to store a simple checksum over Roll# and Ticket#. Allowed range is 0-31.

Magic Number

The Magic Number is stored in every voucher and verified during voucher check. Size depends on how many bits are left by Roll+Ticket+Checksum bits. If all bits are used, no magic number will be used and checked.

Output Example

The following list contains sample voucher codes generated by pfSense® software:

6UVeTS6II68
kGZ38iBgyx4
gWUhfyvWo43
kiViNq31p7b
jLzSQuZMPJa

The generated vouchers will be different due to the generated RSA key pair, even if the same config file is used.

Voucher Status/Management

Active vouchers, roll statistics, testing, and expiration of vouchers may all be performed on the Captive Portal Status page for the zone.

Testing

To test the vouchers, go to Status > Captive Portal, select the zone, and visit the Test Vouchers tab. See Captive Portal Status.