Vouchers

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 common in places where an organization wants authenticated, but time-limited, Internet access without needing to provide a username and password to users.

This type of configuration is prevalent in travel and hospitality locations such as coffee shops, hotels, and airports. Users enter a voucher code in the portal login form and are the portal grants access for the amount of time allowed by the voucher roll. Voucher rolls can be exported by the GUI as a CSV file, and some companies have even integrated the exported voucher lists into point of sale applications to print voucher codes 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 by the same or a different computer. If the voucher is used again by another computer, the previous session is stopped.

Vouchers require a public/private RSA key pair to generate and verify. A 32-bit set of keys is generated automatically by the firewall the first time the page loads. A custom key pair may be generated manually by the GUI as well. The maximum key length is 64 Bits. Using shorter keys will make the voucher codes shorter but eventually less secure.

Voucher Options

Voucher options are unique per Captive Portal Zone. To configure vouchers, navigate to the Vouchers tab when editing a Captive Portal Zone.

Voucher Rolls:

Voucher rolls are managed by this section of the page. The page lists information about each roll along with a link to add new rolls. No options appear here until after the other settings are active. See Managing Voucher Rolls for details.

Enable:

When checked, this portal zone allows vouchers as a method of authentication, and the page changes to display the other voucher options.

Voucher Keys:

The keys which generate and verify vouchers. Before vouchers are active on a zone, the GUI randomly generates new values each time the page loads. After saving voucher settings, the keys are present in the configuration and remain static from that point on.

Warning

Do not change the keys or other bits after creating voucher rolls. If the values change, all current voucher rolls are invalid. Create new voucher rolls using the new settings after making changes.

Voucher Public Key:

This key is used by the portal to decrypt vouchers. Use the existing random key, or click Generate new keys to make a new public and private key pair. Users may generate keys elsewhere and paste the RSA public key (64 Bit or smaller) in PEM format here.

Voucher Private Key:

This key is used by the portal to generate voucher codes and does not need to be available if the vouchers are generated by another system. Use the existing random key or paste in an RSA private key (64 Bit or smaller) in PEM format here.

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 0 (Digit zero), O (Letter O), l (Lowercase L), and 1 (Digit One). It cannot contain a space, double quote, or comma. A smaller character set will result in longer vouchers to ensure sufficient randomness.

Voucher Bits:

The following “bit” fields control how the vouchers themselves are generated by the portal. The best practice is to leave these values at their defaults, but they may be adjusted if necessary. The total of all bit 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 the default RSA key size of 32.

# of Roll Bits:

Number of bits for 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 16.

# of Ticket Bits:

Number of bits for 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 10.

# 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 5.

Magic Number:

The magic number is present in every voucher, and is verified by the portal during voucher check. The size of the magic number depends on the number of bits remaining after adding together the number of bits for the roll, ticket, and checksum. If there are no bits remaining for use by the magic number, then the portal does not use magic numbers.

Invalid Voucher Message:

This message is displayed by the portal 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 by the portal if they enter a voucher that was valid, but has expired.

Enable Vouchers

• Use the pfSense® WebGUI to navigate to Services > Captive Portal

• Click on the line for the Zone to edit

• Ensure the Zone Authentication Method is set to Use an Authentication backend, change the value and save if necessary.

• Click the Vouchers tab

• Check Enable

• Fill in the form based on the options described in Voucher Options. In most cases, the options may remain at their default values.

• Click Save

With Vouchers enabled, the voucher management controls will be active in the GUI.

Managing Voucher Rolls

Vouchers are created by the portal 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 from which their code was picked.

Voucher Roll Options

Roll #:

The number of this roll. Each roll must have a unique number. This can be any number from 0 to 65535 with the default number of Roll Bits.

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. 1440 minutes is 24 hours.

Count:

Defines the number of vouchers in this roll. The value can be from 0 to 1023 with the default number of Ticket Bits.

Note

If the count on an existing roll is changed, it will invalidate all other vouchers on the roll.

Comment:

A description of the roll for reference, such as 2 hour vouchers for coffee purchases.

Creating Voucher Rolls

To create a voucher roll:

• Use the pfSense® WebGUI to navigate to Services > Captive Portal

• Click on the line for the Zone to edit

• Click the Vouchers tab

• Click Add under the roll list

• Fill in the options as described in Voucher Roll Options

• Click Save

The new roll is available for immediate use by clients.

Editing Existing Rolls

To edit an existing voucher roll, click at the end of its row, but be careful when making changes. Changing the Roll number or Count will invalidate the current vouchers on the roll.

Removing Voucher Rolls

To remove rolls of vouchers, click at the end of their row. When a roll is removed, all of the vouchers in that roll become invalid. Do not remove a roll unless it has been completely used, compromised, or otherwise unnecessary.

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.

Nearly any spreadsheet editor can open this file, such as LibreOffice Calc, Google Docs, or Excel. Programs such as those can print vouchers, feed them into a POS system, and so on.

Using Vouchers on A Portal Page

The portal page must submit voucher codes via the auth_voucher form field. See Portal page with Vouchers for an example.

Viewing Active Vouchers

To view the list of currently active vouchers and their timers, navigate to Status > Captive Portal, on the Active Vouchers tab for a zone, as seen in Figure Active Vouchers.

Active Vouchers

Viewing Voucher Roll Utilization

To view a list of voucher rolls and usage counts, navigate to Status > Captive Portal, on the Voucher Rolls tab for a zone, as in Figure Vouchers Roll Usage

Vouchers Roll Usage

Testing Vouchers

To test the validity of a voucher code, enter it at 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 by a client.

Testing Vouchers

Expiring Vouchers

To invalidate vouchers, during or before use, enter them at Status > Captive Portal, on the Expire Vouchers tab for a zone. After submitting, any voucher listed in the form will no longer be allowed by the portal. Active vouchers entered on this page are also immediately expired.

The page can expire any number of vouchers in a batch. Enter vouchers separated by newlines.

Synchronizing Vouchers

At the bottom of the Vouchers tab there are options to synchronize vouchers to another HA node. This works similarly to the XML-RPC configuration synchronization found in high availability setups (See pfSense Software XMLRPC Config Sync Overview). When active, this function copies the voucher rolls to the target node and also pushes information about active vouchers to the target node as vouchers are consumed by users.

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 443).

Voucher sync username:

The username for synchronization access (Must have appropriate privileges).

Voucher sync password:

The GUI password for the target node.

Unlike the configuration synchronization in a high availability cluster, this synchronization is configured on both the primary and secondary nodes. This ensures that vouchers used on the secondary node while it is active are also sent back to the primary when it returns to an active state. Unlike configuration synchronization, this does not create a loop.