| 16 |
rodolico |
1 |
# Program Overview: totp_opnsense Suite (Updated)
|
|
|
2 |
|
|
|
3 |
This suite consists of four main programs/modules for managing TOTP and OpenVPN user access with OPNSense routers. Each has a distinct role in the workflow, from configuration parsing to user authentication and QR code delivery.
|
|
|
4 |
|
|
|
5 |
---
|
|
|
6 |
|
|
|
7 |
## 1. configure
|
|
|
8 |
|
|
|
9 |
**Purpose:**
|
|
|
10 |
- Reads and parses OPNSense configuration files.
|
|
|
11 |
- Loads settings and credentials for API access and OpenVPN configuration.
|
|
|
12 |
- Provides utility subs for configuration management.
|
|
|
13 |
|
|
|
14 |
**Key Features:**
|
|
|
15 |
- 3-space indentation and camelCase variable naming.
|
|
|
16 |
- Modular subroutines with headers for clarity.
|
|
|
17 |
- Loads the custom `Opnsense` Perl module for API interaction.
|
|
|
18 |
|
|
|
19 |
**Main Subroutines:**
|
|
|
20 |
- `usage`: Prints usage instructions.
|
|
|
21 |
- `readConfig`: Reads and parses the configuration file.
|
|
|
22 |
|
|
|
23 |
---
|
|
|
24 |
|
|
|
25 |
## 2. index.php
|
|
|
26 |
|
|
|
27 |
**Purpose:**
|
|
|
28 |
- Provides a web interface for users to log in and retrieve their TOTP QR code and OpenVPN configuration.
|
|
|
29 |
- Validates user credentials and displays relevant information.
|
|
|
30 |
|
|
|
31 |
**Key Features:**
|
|
|
32 |
- 3-space indentation and camelCase variable naming for PHP code.
|
|
|
33 |
- Function headers for all major operations.
|
|
|
34 |
- Reads configuration generated by `processOPNSense.pl`.
|
|
|
35 |
|
|
|
36 |
**Main Functions:**
|
|
|
37 |
- `validateUser`: Validates user credentials against stored data.
|
|
|
38 |
- `displayQRCode`: Shows the QR code for the user's OTP.
|
|
|
39 |
- `displayOTPSeed`: Displays the OTP seed for manual entry.
|
|
|
40 |
- `downloadOvpnFile`: Provides a download link for the user's OpenVPN configuration.
|
|
|
41 |
- Displays the last time users.json was updated and allows a request for that from the webui. If user requests an update, a file is placed in /tmp which can be managed by a cron job
|
|
|
42 |
- see `updaterouters.cron` for an example of allowing users to request a rescan of a router.
|
|
|
43 |
|
|
|
44 |
---
|
|
|
45 |
|
|
|
46 |
## 3. opnsense-totp-ovpn-export
|
|
|
47 |
|
|
|
48 |
**Purpose:**
|
|
|
49 |
- Creates a lock file and checks there is only one instance running to decrease chance of corruption
|
|
|
50 |
- Loads router and user configuration from JSON files.
|
|
|
51 |
- Uses the `opnsense` module to interact with the OPNSense API.
|
|
|
52 |
- Generates QR codes and OpenVPN configuration files for users.
|
|
|
53 |
|
|
|
54 |
**Key Features:**
|
|
|
55 |
- 3-space indentation and camelCase variable naming.
|
|
|
56 |
- Clearly marked subroutine headers for maintainability.
|
|
|
57 |
- Uses `GD::Barcode::QRcode` for QR code generation and `MIME::Base64` for decoding OpenVPN files.
|
|
|
58 |
|
|
|
59 |
**Main Subroutines:**
|
|
|
60 |
- `loadConfig`: Loads router configuration from a JSON file.
|
|
|
61 |
- `loadUsers`: Loads user data from a JSON file.
|
|
|
62 |
- Additional subs for QR code and OpenVPN file management.
|
|
|
63 |
|
|
|
64 |
---
|
|
|
65 |
|
|
|
66 |
## 4. opnsense.pm (Perl Module)
|
|
|
67 |
|
|
|
68 |
**Purpose:**
|
|
|
69 |
- Provides an object-oriented interface for interacting with the OPNSense API.
|
|
|
70 |
- Handles API requests using either curl or LWP::UserAgent, with SSL verification disabled for compatibility.
|
|
|
71 |
|
|
|
72 |
**Key Features:**
|
|
|
73 |
- 3-space indentation and camelCase variable naming.
|
|
|
74 |
- Clearly marked subroutine headers for maintainability.
|
|
|
75 |
- Flexible API request handling (curl or LWP).
|
|
|
76 |
|
|
|
77 |
**Main Subroutines:**
|
|
|
78 |
- `new`: Constructor for the Opnsense object.
|
|
|
79 |
- `apiRequest`: Dispatches API requests to curl or LWP handler.
|
|
|
80 |
- `apiRequestCurl`: Handles API requests using curl.
|
|
|
81 |
- `apiRequestLwp`: Handles API requests using LWP::UserAgent.
|
|
|
82 |
|
|
|
83 |
---
|
|
|
84 |
|
|
|
85 |
## Datafile Structures
|
|
|
86 |
|
|
|
87 |
**user configuration file**
|
|
|
88 |
- The users configuration file (users.json) contains sensitive information (totp codes and password hash)
|
|
|
89 |
- The users configuration file is used by both index.php and loadOpnSense.pl, so should be owned by root, but with read access to others
|
|
|
90 |
- The users configuration file is a json file with the following structure
|
|
|
91 |
```json
|
|
|
92 |
{
|
|
|
93 |
"router1" : {
|
|
|
94 |
"qrLocationFileystem": "/file/system/path/to/qrcode/directory",
|
|
|
95 |
"qrLocation": "./qrcodes", # relative path to qrcode directory
|
|
|
96 |
"ovpnLocationFileSystem": "/file/system/path/to/ovpn/directory",
|
|
|
97 |
"ovpnLocation": "./openvpn_configs", # relative path to ovpn file directory
|
|
|
98 |
"lastUpdate": 1759817343, # unix timestamp of last update
|
|
|
99 |
"users" : {
|
|
|
100 |
"user1" : {
|
|
|
101 |
"password" : "<hashed password>",
|
|
|
102 |
"otp_seed" : "<otp seed>",
|
|
|
103 |
"qrFile" : "<path to qr code image file (relative)>",
|
|
|
104 |
"ovpnFile" : "<path to openvpn config file (relative)>"
|
|
|
105 |
},
|
|
|
106 |
"user2" : {
|
|
|
107 |
...
|
|
|
108 |
}
|
|
|
109 |
}
|
|
|
110 |
},
|
|
|
111 |
"router2" : {
|
|
|
112 |
...
|
|
|
113 |
}
|
|
|
114 |
}
|
|
|
115 |
```
|
|
|
116 |
**router configuration file**
|
|
|
117 |
- The router configuration file contains the apiSecret and apiKey that could allow black hats to access and modify your router
|
|
|
118 |
- The router configuration file is owned by root and set with permissions 0600, allowing access only to the root user
|
|
|
119 |
- The router configuration file is a json file with the following structure
|
|
|
120 |
```json
|
|
|
121 |
{
|
|
|
122 |
"routername": {
|
|
|
123 |
"hostname": "router.example.org", # hostname written to ovpn files
|
|
|
124 |
"localPort": "1194", # port number written to ovpn files
|
|
|
125 |
"apiSecret": "secret API key from opnSense Router",
|
|
|
126 |
"apiKey": "public API key from openSense Router",
|
|
|
127 |
"url": "https://192.168.1.1", # how the scripts connect to router
|
|
|
128 |
"template": "PlainOpenVPN", # valid template from opnsense, PlainOpenVPN is used exclusively so far
|
|
|
129 |
"ovpnIndex": "1" # the index into the OVPN instance. In older systems, a single digit, in newer ones a long hash
|
|
|
130 |
}
|
|
|
131 |
}
|
|
|
132 |
```
|
|
|
133 |
|
|
|
134 |
|
|
|
135 |
# Workflow Summary
|
|
|
136 |
1. Get API Key from router and save
|
|
|
137 |
2. Run `configure` to set up router
|
|
|
138 |
3. run `opnsense-totp-ovpn-export` to export the .ovpn files and generate the totp QR code image
|
|
|
139 |
4. Users access `index.php` to log in, view their QR code, OTP seed, and download OpenVPN config.
|
|
|
140 |
|
|
|
141 |
# Security Note
|
|
|
142 |
All scripts treat OTP secrets and user data as sensitive. It is recommended to keep generated files and QR codes on a secure internal network.
|