Netgate is offering COVID-19 aid for pfSense software users, learn more.
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:
Use the pfSense® WebGUI to navigate to Services > Captive Portal
Click on the line for the Zone to edit
Click the Vouchers tab
Fill in the form as needed. In most cases, the remaining options on this screen can be left at their default values.
- Voucher Rolls
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.
- Voucher Keys
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.
- Voucher Public Key
This key is used to decrypt vouchers. The pre-generated key may be used, or click Generate new keys to make a new public and private key pair. A key may also be generated elsewhere and then used by pasting the RSA public key (64 Bit or smaller) in PEM format here.
- Voucher Private Key
This key is used to generate voucher codes and does not need to be available if the vouchers have been generated offline. The pre- generated key may be used, or paste in an RSA private key (64 Bit or smaller) in PEM format here if the key was generated elsewhere.
- Character Set
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
l(Lowercase L), and
1(Digit One). It cannot contain a space, double quote, or comma. Using a smaller character set will generally cause longer vouchers to ensure randomness.
- Voucher Bits
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
5. The sum of these is 31, which is one less than the default RSA key size of 32.
- # of Roll Bits
Number of bits used to store the Roll ID. Set this larger to have a lot of rolls active at the same time. Can be from 1-31, the default value is
- # 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, the default value is
- # of Checksum Bits
Reserves a range in each voucher to store a simple checksum over Roll bits and Ticket bits. Allowed range is 0-31, the default value is
- Magic Number
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.
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.
- Roll #
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.
1440minutes is 24 hours.
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
2 hour vouchers for coffee purchases.
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 (Typically
- 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