From 48bc306aba8b1cf07ab0b3f6e9d96fc11b9ddebb Mon Sep 17 00:00:00 2001 From: hwipl <33433250+hwipl@users.noreply.github.com> Date: Tue, 23 Apr 2024 14:45:46 +0200 Subject: [PATCH 1/2] Update user docs Signed-off-by: hwipl <33433250+hwipl@users.noreply.github.com> --- docs/user/debug.md | 28 +++++++++++++--------------- docs/user/usage.md | 27 ++++++++++++++++++++++++--- 2 files changed, 37 insertions(+), 18 deletions(-) diff --git a/docs/user/debug.md b/docs/user/debug.md index af62973..e1f9d82 100644 --- a/docs/user/debug.md +++ b/docs/user/debug.md @@ -10,8 +10,8 @@ OC-Client and OC-Daemon logs, and with other tools. Some Examples are: ### Connected Server -You can see the server you are currently connected to in the OC-Client and -OC-Daemon logs. +You can see the server you are currently connected to in the `Current Server` +line in `oc-client status`. ### Current Profile @@ -20,36 +20,34 @@ the profile name. ### Connection State -You can see the current connection state with `Connected` in `oc-client -status`. +You can see the current connection state in the `Connection State` line in +`oc-client status`. ### Local IP -There are two ways to see the current IP used inside the tunnel: - -- `IPv4` or `IPv6` in `Config` in `oc-client status` -- `ip address show dev $DEV`, where `$DEV` is the VPN device name found in - `Device -> Name` in `Config` in `oc-client status` +You can see the current IP used inside the tunnel in the `IP` line in +`oc-client status`. ### Server IP -The `Gateway` in `Config` in `oc-client status` is the IP address of the server -you are currently connected to. +The `Gateway` entry in the `VPN Config` line in `oc-client status -verbose` is +the IP address of the server you are currently connected to. ### Sent/Received Bytes You can view statistics about sent and received bytes on the tunnel device with -`ip -statistics a show dev $DEV`, where $DEV is the VPN device name. +`ip -statistics a show dev $DEV`, where $DEV is the VPN device name (default: +`oc-daemon-tun0`). ### Information about Encryption -You can find Information about the used encryption, e.g., cipher suite, in the +You can find information about the used encryption, e.g., cipher suite, in the OC-Client and OC-Daemon log output. ## Split Routing Details -You can view details about split routing with `oc-client status` and then in -`Config -> Split`. +You can view details about split routing with `oc-client status -verbose` in +the `VPN Config` line and then in the `Split` entry. `Split` contains the Split Routing configuration with IPv4 address ranges in `ExcludeIPv4`, IPv6 address ranges in `ExcludeIPv6` and DNS-based Excludes in diff --git a/docs/user/usage.md b/docs/user/usage.md index 7ef5a31..58beed4 100644 --- a/docs/user/usage.md +++ b/docs/user/usage.md @@ -21,14 +21,24 @@ Options: set additional CA certificate file -cert file set client certificate file or PKCS11 URI + -config file + set config file -key file set client key file or PKCS11 URI + -profile file + set XML profile file -server address set server address -system-settings use system settings instead of user configuration -user username set username + -user-cert file + set user certificate file or PKCS11 URI. + Note: requires OpenConnect v9.00 or higher + -user-key file + set user key file or PKCS11 URI. + Note: requires OpenConnect v9.00 or higher -version print version @@ -43,6 +53,8 @@ Commands: list VPN servers in XML Profile status show VPN status + monitor + monitor VPN status updates save save current settings to user configuration @@ -70,9 +82,8 @@ option `-system-settings` and load the system-wide configuration instead of the user-specific configuration. You can override settings in the configuration files with the `oc-client` -command line options `-ca`, `-cert`, `-key`, `-server` and `-user`. You can use -the `oc-client` command `save` to save the currently loaded settings into your -user-specific configuration. +command line options. You can use the `oc-client` command `save` to save the +currently loaded settings into your user-specific configuration. The JSON format of the system-wide and user-specific configuration is identical. Your system-wide or user-specific configuration file could, for @@ -128,6 +139,14 @@ You can show the current status with: $ oc-client status ``` +### Monitoring Status + +You can monitor the current status with: + +```console +$ oc-client monitor +``` + ### Listing Servers You can list VPN servers in your XML profile (`/var/lib/oc-daemon/profile.xml`) @@ -146,6 +165,8 @@ line arguments: ``` Usage of oc-daemon: + -config file + set config file (default "/var/lib/oc-daemon/oc-daemon.json") -verbose enable verbose output -version From bbb66d22b008d080024fa1a78a0fa4a197b745d4 Mon Sep 17 00:00:00 2001 From: hwipl <33433250+hwipl@users.noreply.github.com> Date: Tue, 23 Apr 2024 20:32:10 +0200 Subject: [PATCH 2/2] Update development docs Signed-off-by: hwipl <33433250+hwipl@users.noreply.github.com> --- docs/development/api.md | 157 +++++++++++++++------------ docs/development/dns-config.md | 2 +- docs/development/overview.md | 13 ++- docs/development/traffic-policing.md | 7 +- 4 files changed, 98 insertions(+), 81 deletions(-) diff --git a/docs/development/api.md b/docs/development/api.md index 5544ac9..7210ac1 100644 --- a/docs/development/api.md +++ b/docs/development/api.md @@ -1,8 +1,85 @@ # Daemon API -The daemon API is used by the oc-client and the oc-daemon-vpncscript to +The Daemon API is used to communicate with the oc-daemon. It actually consists +of two APIs: the D-Bus API for user interaction and the Unix Socket API for +communication with the oc-daemon-vpncscript. + +## D-Bus API + +The D-Bus API is used by oc-client or other client implementations to communicate with the oc-daemon. +```console +$ gdbus introspect --system --dest com.telekom_mms.oc_daemon.Daemon --object-path /com/telekom_mms/oc_daemon/Daemon + +node /com/telekom_mms/oc_daemon/Daemon { + interface com.telekom_mms.oc_daemon.Daemon { + methods: + Connect(in s server, + in s cookie, + in s host, + in s connectURL, + in s fingerprint, + in s resolve); + Disconnect(); + signals: + properties: + readonly u TrustedNetwork = 1; + readonly u OCRunning = 1; + readonly s VPNConfig = ''; + readonly s IP = ''; + readonly s Server = ''; + readonly x ConnectedAt = 0; + readonly u ConnectionState = 1; + readonly s Device = ''; + readonly as Servers = ['VPN Server 1', 'VPN Server 2']; + }; +}; +``` + +### Methods + +`Connect()` is used to connect to a VPN server. The parameter `server` is the +name of the VPN server. The remaining parameters are the login information +returned by `openconnect -authenticate`: `Cookie` is an access token containing +information for authentication and authorization on the VPN server. `Host` is +the VPN server address. `ConnectURL` is the VPN server URL. `Fingerprint` is +the fingerprint of the server's certificate. `Resolve` maps the server's host +name to its IP address to bypass DNS resolution. + +`Disconnect()` is used to disconnect from the current VPN server. + +### Properties + +All properties emit `org.freedesktop.DBus.Properties.PropertiesChanged` +signals. + +`TrustedNetwork` indicates whether a trusted network has been detected. + +`OCRunning` indicates whether the OpenConnect process is running. + +`VPNConfig` is the VPN network configuration. For the go-representation of the +configuration see [VPN Network Configuration](vpn-network-config.md). + +`IP` is the local client's IP address in the VPN. + +`Server` is the name of the current VPN server. + +`ConnectedAt` is the time when the VPN connection was established. + +`ConnectionState` indicates whether the VPN connection was established using +the OpenConnect process. + +`Device` is the name of the local client's VPN network device (default: +`oc-daemon-tun0`). + +`Servers` is the list of names of available VPN servers. + +## Unix Socket API + +The Unix Socket API is used by the oc-daemon-vpncscript to communicate with the +oc-daemon. + ``` Client OC-Daemon | | @@ -26,24 +103,21 @@ Client OC-Daemon ``` +---------------+-----------------+---------------------+ -| Type (16 bit) | Length (16 bit) | Value (Length byte) | +| Type (16 bit) | Length (32 bit) | Value (Length byte) | +---------------+-----------------+---------------------+ ``` Message format: * Type: 16 Bits - * Length: 16 Bits + * Length: 32 Bits * Value: Length Bytes Message Types: * 1: OK (Server Response - OK) * 2: Error (Server Response - Error) -* 3: VPN Connect (Client Request - Connect to VPN) -* 4: VPN Disconnect (Client Request - Disconnect from VPN) -* 5: VPN Query (Client Request - Query Status of Daemon/VPN) -* 6: VPN Config Update (Client Request - Update VPN Network Configuration) +* 3: VPN Config Update (Client Request - Update VPN Network Configuration) Value depends on message type: @@ -51,66 +125,7 @@ Value depends on message type: * empty, or * in case of Error: error message string -## VPN Connect - -* Request - * Type: VPN Connect - * Value: JSON with login information -* Response - * Type: OK - * Value: empty - -Go-representation of the login information: - -```go -type LoginInfo struct { - Cookie string - Host string - Fingerprint string -} -``` - -The login information represents the information returned by `openconnect --authenticate`: `Cookie` is an access token containing information for -authentication and authorization on the VPN server. `Host` is the VPN server. -`Fingerprint` is the fingerprint of the server's certificate. - -## VPN Disconnect - -* Request - * Type: VPN Disconnect - * Value: empty -* Response - * Type: OK - * Value: empty - -## VPN Query - -* Request - * Type: VPN Query - * Value: empty -* Response - * Type: OK - * Value: JSON with VPN/daemon status - -Go-representation of the status: - -```go -type Status struct { - TrustedNetwork bool - Running bool - Connected bool - Config *Config -} -``` - -`TrustedNetwork` indicates if a trusted network has been detected. `Running` -indicates if the openconnect process is running. `Connected` indicates if the -VPN connection was established using the openconnect process. `Config` is the -VPN network configuration. For the go-representation of the configuration see -[VPN Network Configuration](vpn-network-config.md). - -## VPN Config Update +### VPN Config Update * Request * Type: VPN Config Update @@ -125,16 +140,16 @@ Go-representation of the config update: type ConfigUpdate struct { Reason string Token string - Config *Config + Config *vpnconfig.Config } ``` -`Reason` is the reason of the update: `connect` or `disconnect`. `Token` is +`Reason` is the reason of the update: `connect` or `disconnect`. `Token` is a secret shared between the oc-daemon and the client. It is used to verify a legitimate request to change the VPN configuration. `Config` is the VPN network configuration. For the go-representation of the configuration see [VPN Network Configuration](vpn-network-config.md). -Note: the token is passed from the oc-daemon to openconnect via an environment -variable. This variable is also passed by openconnect to oc-daemon-vpncscript, +Note: the token is passed from the oc-daemon to OpenConnect via an environment +variable. This variable is also passed by OpenConnect to oc-daemon-vpncscript, that then uses it in its Config Update request. diff --git a/docs/development/dns-config.md b/docs/development/dns-config.md index dca7672..8c2e1b6 100644 --- a/docs/development/dns-config.md +++ b/docs/development/dns-config.md @@ -17,7 +17,7 @@ components inside the oc-daemon. It performs the following operations: * Check domain names in DNS queries using watch list * Report A records to oc-daemon * Report AAAA records to oc-daemon - * Store CNAMES in watch list (with a timeout) + * Store DNAME and CNAME records in watch list (with a timeout) ## Split-DNS diff --git a/docs/development/overview.md b/docs/development/overview.md index 8b75c82..c5780f5 100644 --- a/docs/development/overview.md +++ b/docs/development/overview.md @@ -67,6 +67,8 @@ User OC-Client OC-Daemon OpenConnect OC-Daemon-VPNCScript | | <-------- | | | | | ---------------------> Authenticate | | | <--------------------- | | + | | --------> Status | | + | | <-------- | | | | | --------> Connect -----> Connect ----------> Config Update | | Network <------------------------- | | | Config | | @@ -80,9 +82,10 @@ User OC-Client OC-Daemon OpenConnect OC-Daemon-VPNCScript 2. abort, if VPN is already running 2. runs `openconnect -authenticate` 3. parses login info from openconnect - 4. sends "connect" message with login info to oc-daemon + 4. retrieves and checks status again + 5. passes login info to oc-daemon with "connect" request 3. oc-daemon connects to VPN server - 1. receives login info in oc-client "connect" message + 1. receives login info in oc-client "connect" request 2. runs `openconnect -script oc-daemon-vpncscript` 4. openconnect starts running 1. establishes tunnel @@ -110,12 +113,12 @@ User OC-Client OC-Daemon OpenConnect OC-Daemon-VPNCScript ``` 1. user runs oc-client with "disconnect" command -2. oc-client sends "disconnect" request +2. oc-client requests "disconnect" 1. oc client retrieves status from oc-daemon 1. abort, if VPN is not running - 2. sends "disconnect" message to oc-daemon + 2. requests "disconnect" from oc-daemon 3. oc-daemon disconnects VPN - 1. receives "disconnect" message from oc-client + 1. receives "disconnect" request from oc-client 2. terminates running openconnect process 4. openconect stops running 1. disconnects tunnel diff --git a/docs/development/traffic-policing.md b/docs/development/traffic-policing.md index 045eb0f..d32db19 100644 --- a/docs/development/traffic-policing.md +++ b/docs/development/traffic-policing.md @@ -16,6 +16,7 @@ On startup, Traffic Policing performs the following configuration steps: * Allow traffic of related and established connections * Allow traffic on allowed devices * Allow incoming and outgoing ICMPv4 and ICMPv6 traffic + * Allow incoming and outgoing DHCPv4 and DHCPv6 traffic * Allow outgoing DNS traffic (port 53) * Allow outgoing traffic to allowed IPv4/6 hosts * Block all other traffic @@ -30,7 +31,7 @@ On startup, Traffic Policing performs the following configuration steps: * Start Captive Portal Detection (CPD) * If portal is detected: * Allow HTTP(S) traffic (ports 80 and 443) - * If no more portal is detected (after login): + * If portal is not detected anymore (after login): * Remove HTTP(S) traffic exception * Resolve/Update all IPs in sets of allowed IPv4/6 hosts @@ -42,9 +43,7 @@ firewall exceptions in Traffic Policing, so we can log onto the network. Captive Portal Detection uses Ubuntu's portal detection scheme. It sends an HTTP request to `connectivity-check.ubuntu.com` and expects the response `204 (No Content)`. If CPD receives a different response, it assumes, there is a -portal. If the response is a `302 (Redirect)`, CPD reports the host name of the -redirect location, so Traffic Policing can add the host name to the allowed -IPv4/6 hosts. +portal. In order to allow Ubuntu's and other portal detection schemes, the following CPD hosts are added to the allowed IPv4/6 hosts: