12.4. Vouchers

Below is a quick howto from mwiget who added the Voucher feature to SmallWall.

12.4.1. Quick Howto

Below are the steps to quickly setup and use the voucher functionality of SmallWall's Captive Portal.

  1. To enable, create and manage voucher support via captive portal, there is a Tab under Services->Captive Portal: Voucher.

  2. Enable captive portal first, upload a landing page that contains an input field 'auth_voucher'.

  3. Then enable Voucher support on the Voucher tab. Initially you can leave all fields with its defaults. Every new install will create unique encryption keys.

  4. Now add at least one "Roll" by clicking '+' on the Vouchers page, right to 'Voucher rolls': Specify a Roll Number, e.g. 0, how many vouchers that roll shall contain, and how long each voucher allows network access.

  5. Then generate the new vouchers by clicking on the paper logo right to the newly added roll. This will generate a CSV file and download via your browser.

Each of these generated vouchers can now be used by users for the configured amount of minutes for that roll. Note that as soon as a voucher has been activated, its timer will run down to zero and then block access, no matter if the session is idle or got disconnected due to logout or session termination.

To test the vouchers in the SmallWall GUI, click on Status->Captive Portal. New tabs, dedicated to voucher handling, show up when voucher support is enabled. Click on status->captive portal-> Test Vouchers and enter one or more of the newly generated vouchers from the downloaded CSV file and click submit. A message will be shown with the validation and duration of each given voucher.

One can add multiple rolls, e.g. to have vouchers with different time credit. It is also possible, to enter multiple vouchers, separated by space, to gain the sum of time credit of all entered vouchers.

There is more to it, read the comments to each config parameter on the voucher page.

Note on the very short public/private RSA keys: I know, those can be cracked easy and in no time, if one of the keys is known. The idea here was to make it a little bit harder than simply adding a shared password into the SmallWall config file. Unfortunately I'm no expert on encryption but I assume with such short encrypted vouchers, there is no security difference between the used RSA keys and a symmetric encryption. Anyhow, all that encryption/decryption stuff is done in the binary C program voucher.c, that is compiled and added into the SmallWall image, and can be modified to increase the usability and security.

12.4.2. Voucher Parameters

Below are the following parameters that can be configured for voucher use in SmallWall). The Enable Vouchers checkbox must activated for these parameters to be used.


Changing any Voucher parameter (apart from managing the list of Rolls) on this page will render existing vouchers useless if they were generated with different settings.

Table 12.5. Voucher Parameters

Parameter Description
Voucher Rolls Create, generate and activate Rolls with Vouchers that allow access through the captive portal for the configured time. Once a voucher is activated, its clock is started and runs uninterrupted until it expires. 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.
Voucher public key Paste an RSA public key (64 Bit or smaller) in PEM format here. This key is used to decrypt vouchers.
Voucher private key Paste an RSA private key (64 Bit or smaller) in PEM format here. This key is only used to generate encrypted vouchers and doesn't need to be available if the vouchers have been generated offline.
Character set Tickets are generated with the specified character set. It should contain printable characters (numbers, lower case and upper case letters) that are hard to confuse with others. Avoid e.g. 0/O and l/1.
# of Roll Bits Reserves a range in each voucher to store the Roll# it belongs to. Allowed range: 1..31. Sum of Roll+Ticket+Checksum bits must be one Bit less than the RSA key size.
# of Ticket Bits Reserves a range in each voucher to store the Ticket# it belongs to. Allowed range: 1..16. Using 16 bits allows a roll to have up to 65535 vouchers. A bit array, stored in RAM and in the config, is used to mark if a voucher has been used. A bit array for 65535 vouchers requires 8 KB of storage.
# 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 Magic number stored in every voucher. 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.
Save Interval The list of active and used vouchers can be stored in the system's configuration file once every x minutes to survive power outages. No save is done if no new vouchers have been activated. Enter 0 to never write runtime state to XML config.
Invalid Voucher Message Error message displayed for invalid vouchers on captive portal error page ($PORTAL_MESSAGE$)
Expired Voucher Message Error message displayed for expired vouchers on captive portal error page ($PORTAL_MESSAGE$).

12.4.3. Voucher Rolls

Each voucher roll has the following parameters.

Table 12.6. Voucher Roll Parameters

Parameter Description
Roll# Enter the Roll# (0..65535) found on top of the generated/printed vouchers.
Minutes per Ticket Defines the time in minutes that a user is allowed access. The clock starts ticking the first time a voucher is used for authentication.
Count Enter the number of vouchers (1..1023) found on top of the generated/printed vouchers. WARNING: Changing this number for an existing Roll will mark all vouchers as unused again.
Comment Can be used to further identify this roll. Ignored by the system.