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. Some companies have integrated the exported voucher lists into their point of sale applications to print a voucher on customer receipts.
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.
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 that is 32-bits in length, but 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.
Generate Larger Keys¶
To generate a valid RSA key pair using 64 Bits, run the following from the shell on console or ssh:
$ openssl genrsa 64 > key64.private $ openssl rsa -pubout < key64.private >key64.public
Then use the contents of the resulting files to paste into those fields.
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.
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.
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.
The following list contains sample voucher codes generated by pfSense:
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.
Active vouchers, roll statistics, testing, and expiration of vouchers may all be performed on the Captive Portal Status page for the zone.
The portal page must include the following field to accept the voucher code:
- User is online after voucher expires
- The session timeout must be enabled in order to allow the voucher session to expire and deactivate.