Below is a quick howto from mwiget who added the Voucher feature to m0n0wall. Vouchers are only available in the upcoming 1.3 firmwar release and are currently part of the beta version of the firmware.
Below are the steps to quickly setup and use the voucher functionality of m0n0wall's Captive Portal.
To enable, create and manage voucher support via captive portal, there is a new Tab under Services->Captive Portal: Voucher.
Enable captive portal first, upload a landing page that contains an input field 'auth_voucher'. An example can be found on the the URL above.
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.
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.
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 m0n0wall 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 m0n0wall 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 a newly added binary C program voucher.c, that is compiled and added into the m0n0wall image, and can be modified to increase the usability and security.
Below are the following parameters that can be configured for voucher use in the upcoming 1.3 m0n0wall). 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$). |
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. |