WebSVN – web_pages – Diff – /trunk/totp_opnsense/opnsense.pm

 # TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 # BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 # ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 # DAMAGE.
+=head1 NAME
-#
-# Library to interface with the OPNsense API
+opnsense - Perl interface for OPNsense Router API
+=head1 SYNOPSIS
+   use opnsense;
+   # Create an OPNsense API client
+   my $opn = opnsense->new(
+      url       => 'https://192.168.1.1',
+      apiKey    => 'your-api-key',
+      apiSecret => 'your-api-secret',
+      ovpnIndex => '1',
+      template  => 'PlainOpenVPN',
+      hostname  => 'vpn.example.com',
+      localPort => '1194'
+   );
+   # Get VPN providers
+   my $providers = $opn->getVpnProviders();
+   # Get VPN user certificates
+   my $vpnUsers = $opn->getVpnUsers();
+   # Get all system users (including TOTP secrets)
+   my $allUsers = $opn->getAllUsers();
+   # Download VPN configuration for a certificate
+   my $vpnConfig = $opn->getVpnConfig($certId);
+=head1 DESCRIPTION
-# Provides methods to interact with OPNsense routers via their API.
+This module provides an object-oriented interface to the OPNsense router API.
+It supports both curl-based and LWP::UserAgent-based HTTP requests with SSL
+verification disabled for compatibility with self-signed certificates.
+The module is designed to retrieve VPN configurations, user credentials,
+TOTP secrets, and manage OpenVPN export functionality.
+=head1 CONFIGURATION
+   $opnsense::useCurl = 1;  # Use curl (default) or 0 for LWP::UserAgent
+   $opnsense::debug = 0;    # Enable debug output (1) or disable (0)
-#
-# Change History:
+=head1 CHANGE HISTORY
+=over 4
-#  v1.0.0 2025-10-01 - RWR
+=item v1.0.0 2025-10-01 - RWR
-#    Initial version
+Initial version
-#  v1.0.1 2025-10-07 - RWR
+=item v1.0.1 2025-10-07 - RWR
-#    Fixed bug where script was looking for localport, but was localPort
+Fixed bug where script was looking for localport, but was localPort.
-#    Fixed bug where not all users were returned because opnSense (v24.7)
+Fixed bug where not all users were returned because opnSense (v24.7)
-#       does not send the username, it sends the description. Possible
+does not send the username, it sends the description. Quick fix is to
-#       programming error, but quick fix is to use username, then description
+use username, then description.
+=back
+=cut
 package opnsense;
 use strict;
 use warnings;
 our $VERSION = "1.0.0";
 our $useCurl = 1; # set to 1 to use curl for API requests, 0 to use LWP
 our $debug = 0;    # set to 1 for debug output
+=head1 METHODS
+=head2 new
+   my $opn = opnsense->new(%args);
+Constructor. Creates a new OPNsense API client object.
+B<Parameters:>
+=over 4
+=item * url - Base URL of the OPNsense router (e.g., 'https://192.168.1.1')
+=item * apiKey - API key from OPNsense (System | Access | Users)
+=item * apiSecret - API secret from OPNsense
+=item * ovpnIndex - OpenVPN provider index (single digit or hash)
+=item * template - OpenVPN template type (typically 'PlainOpenVPN')
+=item * hostname - External hostname for VPN endpoint
+=item * localPort - Port number for VPN connections
+=back
+B<Returns:> opnsense object
+=cut
 #-----------------------------
 # new: Constructor
 #-----------------------------
 sub new {
    my ($class, %args) = @_;
    };
    bless $self, $class;
    return $self;
+}
+=head2 apiRequest
+   my $response = $opn->apiRequest($endpoint, $method, $data);
+Internal method that dispatches API requests to either curl or LWP handler
+based on the $opnsense::useCurl setting.
+B<Parameters:>
+=over 4
+=item * endpoint - API endpoint path (e.g., '/api/openvpn/export/providers')
+=item * method - HTTP method (GET, POST, PUT, DELETE). Default: GET
+=item * data - Optional hashref of data to send with POST/PUT requests
+=back
+B<Returns:> Decoded JSON response or XML string
+=cut
 #-----------------------------
 # apiRequest: API request dispatcher
 #-----------------------------
 sub apiRequest {
    } else {
        return apiRequestLwp(@_);
+   }
+}
+=head2 apiRequestCurl
+   my $response = $self->apiRequestCurl($endpoint, $method, $data);
+Internal method that performs API requests using system curl command.
+SSL verification is disabled (--insecure flag).
+B<Parameters:>
+=over 4
+=item * endpoint - API endpoint path
+=item * method - HTTP method (GET, POST, PUT, DELETE). Default: GET
+=item * data - Optional hashref of data to send
+=back
+B<Returns:> Decoded JSON response or raw XML string
+=cut
 #-----------------------------
 # apiRequestCurl: API request using curl
 #-----------------------------
 sub apiRequestCurl {
    my ($self, $endpoint, $method, $data) = @_;
       return $json_text;
+   }
    return decode_json($json_text);
+}
+=head2 apiRequestLwp
+   my $response = $self->apiRequestLwp($endpoint, $method, $data);
+Internal method that performs API requests using LWP::UserAgent.
+SSL verification is disabled for self-signed certificates.
+B<Parameters:>
+=over 4
+=item * endpoint - API endpoint path
+=item * method - HTTP method (GET, POST, PUT, DELETE). Default: GET
+=item * data - Optional hashref of data to send
+=back
+B<Returns:> Decoded JSON response
+B<Dies:> If the API request fails
+=cut
 #-----------------------------
 # apiRequestLwp: API request using LWP
 #-----------------------------
 sub apiRequestLwp {
     return decode_json($res->decoded_content) if $res->is_success;
     die "API request failed: " . $res->status_line;
+}
+=head2 getVpnUsers
+   my $vpnUsers = $opn->getVpnUsers();
+Retrieves VPN user certificates from the OPNsense router.
+B<Returns:> Hashref keyed by certificate ID, value is username
+Example:
+   {
+      '60cc1de5e6dfd' => 'john',
+      '6327c3d037f8e' => 'mary'
+   }
+B<Note:> Skips users with spaces in username. Uses 'users' field if available,
+falls back to 'description' field for compatibility with OPNsense v24.7.
+=cut
 #-----------------------------
 # getVpnUsers: get VPN users
 #-----------------------------
 sub getVpnUsers {
     my ($self) = @_;
+    }
 #    print "In get_vpn_users, return object:\n" . Dumper($return); die;
     return $return;
+}
+=head2 getAllUsers
+   my $allUsers = $opn->getAllUsers();
+Retrieves all system users from the OPNsense router, including TOTP secrets
+and authentication data.
+B<Returns:> Hashref keyed by username, value is user object
+User object structure:
+   {
+      'john' => {
+         'name' => 'john',
+         'password' => '<hashed password>',
+         'otp_seed' => '<TOTP secret in base32>',
+         'disabled' => 0,
+         'description' => 'John Doe',
+         ...
+      }
+   }
+B<Note:> This method downloads the entire router configuration via
+/api/core/backup/download/this and extracts user data, as the /api/system/user
+endpoint is not functional in some OPNsense versions.
+=cut
 #-----------------------------
 # getAllUsers: get all users on the system
 #-----------------------------
 # returns a hashref keyed by username, value is the user object
 # The api is seriously broken. It is supposed to be /api/system/user, but that returns an error
         $return = $config->{system}->{user};
+    }
     return $return;
+}
+=head2 getVpnProviders
+   my $providers = $opn->getVpnProviders();
+Retrieves list of OpenVPN providers (instances) configured on the router.
+B<Returns:> Hashref keyed by provider ID (ovpnIndex), value is provider name
+Example:
+   {
+      '1' => 'Main VPN Server',
+      '2c3f5a1b' => 'Secondary VPN'
+   }
+B<Used by:> configure script to allow selection of VPN provider
+=cut
 #-----------------------------
 # getVpnProviders: get VPN providers
 #-----------------------------
 sub getVpnProviders {
    my ($self) = @_;
        $return->{$providers->{$provider}->{'vpnid'}} = $providers->{$provider}->{'name'};
+    }
    return $return;
+}
+=head2 getVpnConfig
+   my $vpnConfig = $opn->getVpnConfig($certId);
+Downloads OpenVPN configuration file for a specific certificate.
+B<Parameters:>
+=over 4
+=item * certId - Certificate ID from getVpnUsers()
+=back
+B<Returns:> Hashref containing:
+   {
+      'content' => '<base64 encoded .ovpn file>',
+      ...
+   }
+B<Note:> The returned content is base64 encoded and must be decoded before use.
+See makeVPNConfigFile() in opnsense-totp-ovpn-export for decoding example.
+=cut
 #-----------------------------
 # getVpnConfig: get VPN configuration file
 #-----------------------------
 sub getVpnConfig {
    my ( $self, $cert ) = @_;
    $debug = 0;
    my $return = $self->apiRequest($endpoint, 'POST', $payload);
    return $return;
+}
+=head1 DEPENDENCIES
+=over 4
+=item * LWP::UserAgent - For LWP-based HTTP requests
+=item * JSON - For encoding/decoding JSON data
+=item * Data::Dumper - For debugging output
+=item * XML::Simple - For parsing router configuration XML
+=back
+=head1 SECURITY CONSIDERATIONS
+=over 4
+=item * SSL verification is disabled to support self-signed certificates
+=item * API credentials are passed in plain text (use HTTPS)
+=item * Store API keys securely with restrictive file permissions (0600)
+=back
+=head1 SEE ALSO
+=over 4
+=item * configure - Router configuration management tool
+=item * opnsense-totp-ovpn-export - Main export script
+=item * opnsense.pm.md - Developer's guide
+=back
+=head1 AUTHOR
+Daily Data, Inc.
+=head1 COPYRIGHT AND LICENSE
+Copyright (c) 2025, Daily Data, Inc.
+All rights reserved.
+This software is provided under the BSD 3-Clause License.
+See the LICENSE file for details.
+=cut
 ;

Subversion Repositories web_pages

(root)/trunk/totp_opnsense/opnsense.pm – Rev 17 → 20