Vouchers are single use codes used to gain Internet access through a Captive Portal. Each roll of vouchers is cryptographically generated and includes a set time limit. Vouchers are commonly implemented in places where authenticated, but time-limited, Internet access is desired without needing to provide a username and password to users.
This type of configuration is frequently found in places such as coffee shops, hotels, and airports. Users enter a voucher code in the portal login form and are granted access for the amount of time configured for the voucher roll. Voucher rolls can be exported as a CSV file, and some companies have even integrated the exported voucher lists into their point of sale applications to print a voucher on customer receipts.
Voucher time does not stop counting down if a user logs out; they allow access only from the start of the session until the duration of the voucher length has elapsed. During that time, the voucher can be re-used from the same or a different computer. If the voucher is used again from another computer, the previous session is stopped.
A public/private RSA key pair is required to generate and verify vouchers. A 32- bit set of keys is generated automatically by the firewall the first time the page is visited, and a custom key pair may be generated manually if desired. The maximum key length supported is 64 Bits. Using shorter keys will make the generated vouchers shorter but eventually less secure.
The voucher settings are unique per Captive Portal Zone. To configure vouchers:
- Navigate to Services > Captive Portal
- Click on the line for the Zone to edit
- Click the Vouchers tab
- Check Enable
- Fill in the form as needed. In most cases, the remaining options on this screen can be left at their default values.
Voucher rolls are managed in this section of the screen. Information about each roll is listed along with a link to Add new rolls. No options appear here until after the other settings have been configured and saved. See Managing Voucher Rolls for more.
The keys used to generate and verify vouchers. Before vouchers are enabled on a zone, these values are randomly generated each time the page loads. Once vouchers are enabled and saved, the keys are set.
Take care not to change the keys or other bits once they have been saved, or all current vouchers are rendered invalid and new voucher rolls must be created.
The character set defines which characters are valid for voucher
text. The character 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
The following “bit” fields control how the vouchers themselves
are generated. Leaving these values at their defaults is recommended but they
may be adjusted if required. The total of all bit fields must be less than
the RSA key size. For example, the default values are
The magic number is stored in every voucher, and is verified during voucher check. The size of the magic number depends on how many bits are left by adding together the number of bits for the roll, ticket, and checksum. If all bits are used, no magic number will be used or checked.
|Invalid Voucher Message:|
This message is displayed to the user if they attempt to enter a voucher that does not exist or is not valid in any way except for being expired.
|Expired Voucher Message:|
This message is displayed to the user if they enter a voucher that was valid, but has expired.
- Click Save
Once the settings have been saved, the voucher management controls will be active.
Managing Voucher Rolls¶
Vouchers are created in batches called Rolls. Each roll has specific settings that are unique to that roll. For example, a roll can have an 8-hour time limit and a separate roll can have a 12-hour time limit. Then users may be given voucher codes depending on which level of service they purchased and they will be limited to the amount of time corresponding to the voucher roll their code was picked from.
Creating Voucher Rolls¶
To create a roll, click Add under the roll list.
The number of this roll. Each roll must have a unique number. This can be any number from 0 to 65535.
|Minutes per Ticket:|
Defines how long the voucher lasts, in minutes. The voucher
time starts counting down the moment the voucher is used, and does not stop,
so plan the voucher length accordingly. Because this is defined in minutes,
ensure the correct length is used, e.g.
Defines how many vouchers will be made on this roll. The value can be from 0 to 1023.
If the count on an existing roll is changed, it will invalidate all other vouchers on the roll, so it is best not to change this once a roll has been created.
A description of the roll for reference, such as
Click Save and the new roll is ready to use.
Editing Existing Rolls¶
An existing voucher roll can be edited by clicking , but be careful when making changes. Changing the Roll number or Count will cause the current vouchers on the roll to be invalidated.
Removing Voucher Rolls¶
Rolls of vouchers can be removed by clicking at the end of their row. When a roll is removed, all of the vouchers in that roll become invalid, so do not remove a roll unless it has been completely used, compromised, or otherwise is no longer needed.
Exporting/Downloading Voucher Rolls¶
Click to download a file containing the vouchers in the
specified roll. This action downloads a
.csv (Comma Separated Value)
spreadsheet containing all voucher codes for this roll.
This file can be saved and opened in nearly any spreadsheet editor such as LibreOffice Calc, Google Docs, or Excel. From there they can be printed, fed into a POS system, and so on.
Using Vouchers on A Portal Page¶
Vouchers must be submitted via the
auth_voucher form field. See
Portal page with Vouchers for an example.
Viewing Active Vouchers¶
A list of currently active vouchers and their timers can be found at Status > Captive Portal, on the Active Vouchers tab for a zone, as seen in Figure Active Vouchers.
Viewing Voucher Roll Utilization¶
A list of voucher rolls and how many have been used can be found at Status > Captive Portal, on the Voucher Rolls tab for a zone, as in Figure Vouchers Roll Usage
A voucher code can be tested for validity by entering it on Status > Captive Portal, on the Test Vouchers tab for a zone. Upon submission, the page will display if a code is valid or not, and if it is valid, it will show the voucher time limit, as seen in Figure Testing Vouchers. Testing a voucher does not count it as used or expired, it is still free to be used at a later time.
Vouchers can be invalidated during or before use by entering them at Status > Captive Portal, on the Expire Vouchers tab for a zone. After submitting, any voucher listed in the form will no longer work. Active vouchers entered on this page are also immediately expired.
Any number of vouchers my be expired in a batch. Enter vouchers separated by newlines.
At the bottom of the Vouchers tab there are options to synchronize vouchers to another unit. This works similarly to the XML-RPC configuration synchronization found in high availability setups (See pfSense XML-RPC Config Sync Overview). When configured, this will copy the voucher rolls to the target unit and also push information about active vouchers to the target unit as the vouchers are used.
|Synchronize Voucher Database IP:|
|The target IP address or hostname of the other node for voucher synchronization.|
|Voucher sync port:|
|The port on the target node where the GUI is listening
|Voucher sync username:|
|The username for synchronization access (Must be
|Voucher sync password:|
|The GUI password for the target system.|
Unlike the configuration synchronization in a high availability cluster, this synchronization is configured on both the master and slave nodes. This is done to ensure that vouchers used on the slave node while it is active are also sent back to the master when it returns to an active state. Unlike the configuration synchronization, this does not create a loop.
Manually Generating RSA Keys for Vouchers¶
RSA public and private keys can be manually created on a separate system for use with vouchers. The commands to generate a 64-bit key for the vouchers are:
$ openssl genrsa 64 > key64.private $ openssl rsa -pubout < key64.private >key64.public