Client
airvpn.client
An interface for interacting with the bootstrap API.
AirClient
Client for interacting with AirVPN's encrypted bootstrap API.
The client downloads and caches the bootstrap configuration, encrypts requests using the public RSA key advertised by the bootstrap server, decrypts responses with AES, and exposes low-level operations such as authentication and manifest retrieval.
login(username: str, password: str) -> User | None
Authenticate with the AirVPN API using the provided username and password.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
username
|
str
|
The username to use for authentication. |
required |
password
|
str
|
The password to use for authentication. |
required |
Returns:
| Type | Description |
|---|---|
User | None
|
User | None: A class built off the XML response, or None if no bootstrap server could be reached (see |
Raises:
| Type | Description |
|---|---|
LoginError
|
If the login's |
manifest() -> Manifest | None
Retrieve the manifest information from the AirVPN API.
Returns:
| Type | Description |
|---|---|
Manifest | None
|
Manifest | None: A class built off the XML response, or None if no bootstrap server could be reached (see |
request(action: str, **kwargs) -> str | None
Make a request to the AirVPN API with the specified action and parameters.
Bootstrap servers are tried one at a time, in random order. A server that can't be connected to is skipped in favor of the next one; a server that responds with a non-200 status or an empty body is also skipped.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
action
|
str
|
The API action to perform. |
required |
**kwargs
|
Additional keyword arguments representing the parameters for the API call. |
{}
|
Returns:
| Type | Description |
|---|---|
str | None
|
str | None: The decrypted response body as a raw XML string, or None if every bootstrap server failed to connect or respond successfully. |
Raises:
| Type | Description |
|---|---|
RCParseError
|
If an error occurs while parsing the RC file. |
RSAError or AESEncryptionError
|
If an error occurs during encryption. |
AESDecryptionError
|
If an error occurs during decryption. |
Key
Represents a device's certificates/keys issued to a user's account.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
The device/key's name. |
|
crt |
The device's OpenVPN certificate. |
|
key |
The device's OpenVPN private key. |
|
wg_private_key |
The device's WireGuard private key. |
|
wg_preshared |
The device's WireGuard preshared key. |
|
wg_ipv4 |
The device's assigned WireGuard IPv4 address. |
|
wg_ipv6 |
The device's assigned WireGuard IPv6 address. |
|
wg_dns_ipv4 |
The IPv4 DNS server to use for this device's WireGuard connection. |
|
wg_dns_ipv6 |
The IPv6 DNS server to use for this device's WireGuard connection. |
from_element(element: ElementTree.Element) -> Key
classmethod
Parses a <key> XML element into a Key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element
|
Element
|
The |
required |
Returns:
| Type | Description |
|---|---|
Key
|
A populated |
Manifest
The AirVPN bootstrap manifest: server list, connection modes, and client configuration.
This is the parsed form of the response from AirClient.manifest().
Attributes:
| Name | Type | Description |
|---|---|---|
time |
Unix timestamp this manifest was generated. |
|
next |
Unix timestamp the next manifest update is expected. |
|
next_update |
Number of seconds until the next expected update. |
|
dnscheck_host |
Hostname used for DNS-based connectivity checks. |
|
dnscheck_res1 |
Expected DNS check response IP, primary. |
|
dnscheck_res2 |
Expected DNS check response IP, secondary. |
|
speed_factor |
Weight given to speed in server scoring. |
|
latency_factor |
Weight given to latency in server scoring. |
|
penality_factor |
Weight given to penalties in server scoring. |
|
users_factor |
Weight given to user count in server scoring. |
|
load_factor |
Weight given to load in server scoring. |
|
ping_factor |
Weight given to ping in server scoring. |
|
pinger_delay |
Delay in seconds between pinger runs. |
|
pinger_retry |
Number of pinger retries. |
|
check_domain |
Domain used for connectivity checks. |
|
check_dns_query |
DNS query template used for connectivity checks. |
|
check_protocol |
Protocol used for connectivity checks (e.g. "https"). |
|
force_reauth_ts |
Unix timestamp after which reauthentication is forced. |
|
openvpn_directives |
Default OpenVPN config directives applied across modes. |
|
mode_protocol |
Default transport protocol for connections. |
|
mode_port |
Default port for connections. |
|
mode_alt |
Alternate mode indicator. |
|
messages |
Operator messages/announcements included in the manifest. |
|
urls |
Bootstrap server URLs. |
|
modes |
Connection modes available (protocol/port/type combinations). |
|
rsa |
The RSA public key used to encrypt requests, if present. |
|
servers |
Every VPN server known to the manifest. |
|
servers_groups |
Shared connection capabilities, keyed by server group. |
from_element(element: ElementTree.Element) -> Manifest
classmethod
Parses a <manifest> XML element (as returned by AirClient.manifest()) into a Manifest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element
|
Element
|
The root |
required |
Returns:
| Type | Description |
|---|---|
Manifest
|
A populated |
from_string(xml: str) -> Manifest
staticmethod
Parses an XML string into a Manifest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xml
|
str
|
The decrypted XML response string, as returned by |
required |
Returns:
| Type | Description |
|---|---|
Manifest
|
A populated |
ManifestServer
A single VPN server entry from the manifest.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
The server's public name. |
|
country_code |
ISO country code of the server's location. |
|
location |
City/region of the server. |
|
bw_max |
Maximum bandwidth available, in Mbit/s. |
|
bw |
Bandwidth currently in use, in bytes. |
|
users |
Number of users currently connected. |
|
users_max |
Maximum number of users this server accepts. |
|
ips_entry |
Entry IP addresses (IPv4 and IPv6), indexed by a mode's |
|
ips_exit |
Exit IP addresses (IPv4 and IPv6) traffic appears to originate from. |
|
scorebase |
Base score used in server selection/ranking. |
|
set |
Server set identifier, if applicable. |
|
group |
Server group identifier, matches a |
|
openvpn_directives |
Extra server-specific OpenVPN config directives, if any. |
|
warning_open |
A warning shown for an otherwise-open server (e.g. elevated packet loss), if any. |
|
warning_closed |
Reason the server is closed/unavailable (e.g. maintenance), if any. |
is_closed: bool
property
Whether the server is currently marked unavailable (e.g. for maintenance).
ManifestUrl
A bootstrap server URL for AirClient's legacy protocol.
Attributes:
| Name | Type | Description |
|---|---|---|
address |
The bootstrap server's URL. |
Mode
A connection mode offered by a server (a protocol/port/type combination).
Attributes:
| Name | Type | Description |
|---|---|---|
title |
Human-readable description of the mode. |
|
protocol |
Transport protocol (e.g. "udp", "tcp", "ssh", "ssl"). |
|
port |
Port number to connect to. |
|
entry_index |
Index into a server's |
|
specs |
Extra TLS/connection specs (e.g. "tls-crypt, tls1.2"), if any. |
|
type |
VPN type for this mode (e.g. "wireguard", "openvpn"). |
|
openvpn_minversion |
Minimum required OpenVPN version, if applicable. |
|
openvpn_directives |
Extra OpenVPN config directives specific to this mode, if any. |
|
ssh_destination |
SSH tunnel destination port, or 0 if not applicable. |
RSAParameters
The RSA public key used to encrypt requests to the bootstrap servers.
Attributes:
| Name | Type | Description |
|---|---|---|
exponent |
Base64-encoded RSA public key exponent. |
|
modulus |
Base64-encoded RSA public key modulus. |
ServersGroup
Shared connection capabilities for a group of servers.
Attributes:
| Name | Type | Description |
|---|---|---|
support_ipv4 |
Whether servers in this group support IPv4. |
|
support_ipv6 |
Whether servers in this group support IPv6. |
|
support_check |
Whether servers in this group support connectivity checks. |
|
ciphers_tls |
Colon-separated list of supported TLS key-exchange ciphers. |
|
ciphers_tlssuites |
Colon-separated list of supported TLS 1.3 cipher suites. |
|
ciphers_data |
Colon-separated list of supported data-channel ciphers. |
|
group |
The server group identifier these settings apply to. |
User
Represents the authenticated account and its connection credentials.
This is the parsed form of the response from AirClient.login().
Attributes:
| Name | Type | Description |
|---|---|---|
ts |
Unix timestamp the response was generated. |
|
login |
The account's username. |
|
expiration_date |
The account's expiration date. |
|
ca |
The OpenVPN CA certificate. |
|
ta |
The OpenVPN TLS-auth key. |
|
tls_crypt |
The OpenVPN tls-crypt key. |
|
ssh_key |
The SSH tunnel private key. |
|
ssh_ppk |
The SSH tunnel private key in PPK format. |
|
ssl_crt |
The SSL/stunnel certificate. |
|
wg_public_key |
The server's WireGuard public key. |
|
keys |
The devices/keys registered to this account. |
|
message |
A message from the server, if any (e.g. describing a login failure). |
|
message_action |
The action associated with |
from_element(element: ElementTree.Element) -> User
classmethod
Parses a <user> XML element into a User.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element
|
Element
|
The |
required |
Returns:
| Type | Description |
|---|---|
User
|
A populated |
from_string(xml: str) -> User
classmethod
Parses an XML string into a User.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xml
|
str
|
The decrypted XML response string, as returned by |
required |
Returns:
| Type | Description |
|---|---|
User
|
A populated |