1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
|
OpenVPN 3 D-Bus API: Backend VPN client process
===============================================
The VPN backend client process (`openvpn-service-client`) is the core
VPN client in the OpenVPN 3 Linux implementation. This process
represents a single TUN/TAP adapter on the system and is the process
which implements the OpenVPN 3 Core library's VPN client object.
This process is started by the
[`net.openvpn.v3.backends`](dbus-service-net.openvpn.v3.backends.md)
service. The session manager
([`net.openvpn.v3.sessions`](77070442.html)) is the service which
calls the `net.openvpn.v3.backends.StartClient` method with a token
value, which results in a new VPN backend client process being started.
Upon initialisation, the VPN backend process asks for a well-known bus
name starting with `net.openvpn.v3.backends.be` and then appends its
own PID value. This is to ensure each VPN backend client process can
be reached by the session manager. For the session manager to know
which session object is related to which backend client process, the
VPN backend client issues the
`net.openvpn.v3.backends.RegistrationRequest` signal where it provides
its own well-known bus name in the signal. The session manager listens
for these signals and once received, the session manager responds back
by calling backend process'
`net.openvpn.v3.backends.RegistrationConfirmation` method where the
token value the backend process was started with is validated, to
ensure the proper session object is tied to the proper session object.
By design, it is only the `openvpn` user account which is allowed to
contact and call methods in the backend VPN client processes and it is
intended that only the session manager is the service which
establishes contact with this service. Any other process or user
should do all calls via the session manager. The session manager will
proxy those calls to the proper backend. And signals from the backend
will be proxied back via the session manager.
D-Bus destination: `net.openvpn.v3.backends.be${PID}` \- Object path: `/net/openvpn/v3/backends/session`
-------------------------------------------------------------------------------------------------------------
```
node /net/openvpn/v3/backends/session {
interface net.openvpn.v3.backends {
methods:
RegistrationConfirmation(in s token,
in o config_path,
out s config_name);
Ping(out b alive);
Ready();
Connect();
Pause(in s reason);
Resume();
Restart();
Disconnect();
ForceShutdown();
UserInputQueueGetTypeGroup(out a(uu) type_group_list);
UserInputQueueFetch(in u type,
in u group,
in u id,
out u type,
out u group,
out u id,
out s name,
out s description,
out b hidden_input);
UserInputQueueCheck(in u type,
in u group,
out au indexes);
UserInputProvide(in u type,
in u group,
in u id,
in s value);
signals:
StatusChange(u code_major,
u code_minor,
s message);
Log(u group,
u level,
s session_token,
s message);
AttentionRequired(u type,
u group,
s message);
RegistrationRequest(s busname,
s token);
properties:
readwrite u log_level;
readonly s session_name;
readonly (sssbusb) connection;
readonly a{sx} statistics;
readonly (uus) status;
readwrite b dco;
readonly o device_path;
readonly s device_name;
};
};
```
### Method: `net.openvpn.v3.backends.RegistrationConfirmation`
This method must be called by the session manager after the backend
VPN client process have issued the `RegistrationRequest` signal. The
backend client will verify the token value with the token value the
process was started with. If it matches, this call will return boolean
true.
#### Arguments
| Direction | Name | Type | Description |
|-----------|--------------|-------------|------------------------------------------------------------|
| In | token | string | This token is used to verify that the session manager have connected the proper backend client service with the correct session object |
| In | config_path | object path | Contains the VPN configuration profile path to use for this connection |
| Out | config_name | string | On success, contains the configuration profile name used in the configuration manager when fetching the profile |
### Method: `net.openvpn.v3.backends.Ping`
Used to check if the backend process is alive and responsive. This
Ping method is going a bit deeper than the
`org.freedesktop.DBus.Peer.Ping`, as it ensures the response comes
from within the OpenVPN 3 code base.
#### Arguments
| Direction | Name | Type | Description |
|-----------|--------------|-------------|---------------------------------|
| Out | alive | boolean | This should always return true. |
### Method: `net.openvpn.v3.backends.Ready`
Used to check if the backend process is ready to connect to the
server. This function does not return anything if it is ready. If it
is not ready, it will result in a D-Bus error response.
#### Arguments
(No arguments)
### Method: `net.openvpn.v3.backends.Connect`
This method starts the connect process to the remote server.
#### Arguments
(No arguments)
### Method: `net.openvpn.v3.backends.Pause`
Pauses an on-going VPN connection. If connection have not started or
it have already been paused, it will result in a D-Bus error response.
#### Arguments
| Direction | Name | Type | Description |
|-----------|--------|--------------|--------------------------------------------------------------------------------|
| In | reason | string | A string used for log purposes primarily, describing why the tunnel was paused |
### Method: `net.openvpn.v3.backends.Resume`
Resumes a paused VPN connection. If the connection have not been
paused already, it will result in a D-Bus error response.
#### Arguments
(No arguments)
### Method: `net.openvpn.v3.backends.Disconnect`
Disconnects from a server. If there is no active connection running,
it will result in a D-Bus error response. This will also do a
graceful shutdown of the VPN backend process.
#### Arguments
(No arguments)
### Method: `net.openvpn.v3.backends.ForceShutdown`
Forces the background VPN client process to stop running. It will
either shutdown properly or do a kill() by itself, depending on what
is possible. It can be expected that calling this method once will
result in the backend client process to be stopped.
#### Arguments
(No arguments)
### Method: `net.openvpn.v3.backends.UserInputQueueGetTypeGroup`
This will return information about various `ClientAttentionType`
and `ClientAttentionGroup` tuples which contains requests for the
front-end application. This information is used when checking
the request queue via `UserInputQueueCheck`.
Valid `ClientAttentionType` values are:
| Identifier | ID | Description |
|-------------------|:---:|--------------------------------------------------------------------|
| UNSET | 0 | This is an invalid value, used for initialization only |
| CREDENTIALS | 1 | User credentials are requested |
| PKCS11 | 2 | PKCS#11/Smart card operation |
Valid `ClientAttentionGroup` values are:
| Identifier | ID | Description |
|-------------------|:---:|--------------------------------------------------------------------|
| UNSET | 0 | This is an invalid value, used for initialization only |
| USER_PASSWORD | 1 | Classic username/password authentication |
| HTTP_PROXY_CREDS | 2 | Credentials for authenticating to the HTTP proxy |
| PK_PASSPHRASE | 3 | Passphrase for the user's private key |
| CHALLENGE_STATIC | 4 | Static challenge/response authentication, typically acquired before a connection starts |
| CHALLENGE_DYNAMIC | 5 | Dynamic challenge/response authentication, requested by the VPN server |
| PKCS11_SIGN | 6 | PKCS#11 signature operation |
| PKCS11_DECRYPT | 7 | PKCS#11 decrypt operation |
| OPEN_URL | 8 | URL for web authentication |
All of these references are declared in `src/dbus/constants.hpp`.
#### Arguments
| Direction | Name | Type | Description |
|-----------|-----------------|-------------------|-------------|
| Out | type_group_list | array(uint, uint) | An array of tuples of `(ClientAttentionType, ClientAttentionGroup)` |
### Method: `net.openvpn.v3.backends.UserInputQueueCheck`
This is used to get the proper index values of information requests
the backend has asked for and which is not yet satsified. The index
list is tied to a specific `(ClientAttentionType,
ClientAttentionGroup)` tuple.
#### Arguments
| Direction | Name | Type | Description |
|-----------|---------|-------------|------------------------------------------------|
| In | type | uint | `ClientAttentionType` reference to query for |
| In | group | uint | `ClientAttentionGroup` reference to query for |
| Out | indexes | array(uint) | An array of indexes which needs to be provided |
### Method: `net.openvpn.v3.backends.UserInputQueueFetch`
This method returns details about a specific information request from
the backend process.
#### Arguments
| Direction | Name | Type | Description |
|-----------|--------------|---------|------------------------------------------------------------|
| In | type | uint | `ClientAttentionType` reference to query for |
| In | group | uint | `ClientAttentionGroup` reference to query for |
| In | id | uint | Request ID to query for, provided by `UserInputQueueCheck` |
| Out | type | uint | `ClientAttentionType` reference |
| Out | group | uint | `ClientAttentionGroup` reference |
| Out | id | uint | Request ID |
| Out | name | string | An internal variable name |
| Out | description | string | A description to present to the front-end user |
| Out | hidden_input | boolean | If true, the user's input should be masked/hidden |
### Method: `net.openvpn.v3.backends.UserInputProvide`
This method is used to return information from the front-end
application to the backend serivce.
#### Arguments
| Direction | Name | Type | Description |
|-----------|--------------|---------|------------------------------------------------------------|
| In | type | uint | `ClientAttentionType` reference to query for |
| In | group | uint | `ClientAttentionGroup` reference to query for |
| In | id | uint | Request ID to query for, provided by `UserInputQueueCheck` |
| In | value | string | The front-end's response to the backend |
### Signal: `net.openvpn.v3.backends.StatusChange`
This signal is issued each time specific events occurs. They can both
be from the session object itself or StatusChange messages proxied
from the VPN client backend process.
#### Arguments
| Name | Type | Description |
|-------------|--------|------------------------------------------------------------------------|
| code_major | uint | Major status group classification. Maps to enum class StatusMajor |
| code_minor | uint | Minor status category classification within the status group. Maps to enum class StatusMinor |
| message | string | An optional string containing a more descriptive message of the signal |
See `src/dbus/constants.hpp` for more details on valid values.
### Signal: `net.openvpn.v3.backends.Log`
Whenever a specific session want to log something, it issues a Log
signal which carries a log group, log verbosity level and a string
with the log message itself. The D-Bus path provided in the signal
points at the issuing VPN session. See the separate [logging
documentation](dbus-logging.md) for details on this signal.
Beware that the back-end Log signalling differs slightly from the front-end
signalling, where the Log signal is extended to carry a session token as well.
This is due to the back-end client process cannot separate Log signals via the
D-Bus object path.
### Signal: `net.openvpn.v3.backends.AttentionRequired`
This signal is issued whenever the backend needs information, most
commonly from the front-end user interface. This can be used to get
user credentials or do PKCS#11/SmartCard operations, etc.
#### Arguments
| Name | Type | Description |
|-----------|--------|-------------------------------------------------|
| type | uint | `ClientAttentionType` reference of the request |
| group | uint | `ClientAttentionGroup` reference of the request |
| message | string | A string containing a description of what kind of information being requested |
### Signal: `net.openvpn.v3.backends.RegistrationRequest`
This signal is sent once during the start-up of the backend VPN client
process initialization phase. The backend requires its
`net.openvpn.v3.backends.RegistrationConfirmation` method to be called
by the session manager after this signal have been sent to complete
the initialization.
#### Arguments
| Name | Type | Description |
|-----------|--------|-------------------------------------------------|
| busname | string | This contains this backend VPN clients process well-known busname. This is formatted as `net.openvpn.v3.backends.be${PID}` where `${PID`} references its own process ID |
| token | string | Initial start-up token, used by the session manager to verify the VPN backend process relation to the session object |
### `Properties`
| Name | Type | Read/Write | Description |
|---------------|------------------|:----------:|----------------------------|
| log_level | uint | read-write | Controls the log verbosity of messages intended to be proxied to the user front-end. **Note:** Not currently implemented |
| connection | (string, string, string, uint) | Read-only | Details related to the currently on-going connection. Requires a connected status. |
| session_name | string | Read-only | Session name generated by the OpenVPN 3 Core library after a successful connection has been established |
| statistics | dictionary | Read-only | Contains tunnel statistics |
| status | (uint, uint, string) | Read-only | Last issued StatusChange signal, as a tuple list (StatusMinor, StatusMajor, StatusDescription) |
| dco | boolean | read-write | Kernel based Data Channel Offload flag. Must be modified before calling Connect() to override the current setting. |
| device_path | object path | Read-only | D-Bus object path to the net.openvpn.v3.netcfg device object related to this session |
| device_name | string | Read-only | Virtual network interface name used by this session |
#### Struct: connection
This is a fixed struct with the following fields:
| Field | Name | type | Description |
|-------|-------------|--------|----------------------------------------------------------------------------------------------------|
| 0 | proto | string | Protocol used for the connection: udp, tcp |
| 1 | server | string | Server hostname the client is connected to |
| 2 | server_ip | string | IP address of the server the client is connected to |
| 3 | server_port | uint | Server TCP/UDP port number used for the connection |
#### Dictionary: statistics
This is dictionary may have few or many fields, it depends on which
events have occurred by the OpenVPN 3 Core library for a specific
session. The list below is not exhaustive and may change.
| Name | Type | Description |
|--------------------|--------|-----------------------------------------------------|
| BYTES_IN | uint64 | Number of bytes received on the TCP/UDP socket |
| BYTES_OUT | uint64 | Number of bytes sent from the TCP/UDP socket |
| PACKETS_IN | uint64 | Number of packets received on the TCP/UDP socket |
| PACKETS_OUT | uint64 | Number of packets sent from the TCP/UDP socket |
| TUN_BYTES_IN | uint64 | Number of bytes received on the TUN/TAP interface |
| TUN_BYTES_OUT | uint64 | Number of bytes sent from the TUN/TAP interface |
| TUN_PACKETS_IN | uint64 | Number of packets received on the TUN/TAP interface |
| TUN_PACKETS_OUT | uint64 | Number of packets sent from the TUN/TAP interface |
| NETWORK_SEND_ERROR | uint64 | Number of times there where issues sending packets |
| KEEPALIVE_TIMEOUT | uint64 | Number of times the tunnel keepalive restart was triggered |
| N_PAUSE | uint64 | Number of times the tunnel was paused |
| N_RECONNECT | uint64 | Number of times the tunnel needed to do a reconnect |
|
