diff options
Diffstat (limited to 'docs/src/api/overview')
| -rw-r--r-- | docs/src/api/overview/README.md | 8 | ||||
| -rw-r--r-- | docs/src/api/overview/connecting.md | 14 | ||||
| -rw-r--r-- | docs/src/api/overview/deregistering.md | 11 | ||||
| -rw-r--r-- | docs/src/api/overview/discovery.md | 63 | ||||
| -rw-r--r-- | docs/src/api/overview/flow.md | 8 | ||||
| -rw-r--r-- | docs/src/api/overview/getconfig.md | 73 | ||||
| -rw-r--r-- | docs/src/api/overview/registering.md | 35 |
7 files changed, 212 insertions, 0 deletions
diff --git a/docs/src/api/overview/README.md b/docs/src/api/overview/README.md new file mode 100644 index 0000000..d233b0c --- /dev/null +++ b/docs/src/api/overview/README.md @@ -0,0 +1,8 @@ +# API Overview + +This section defines the API in high-level, we explain what functions there are, what their use is and what a typical flow is for creating an eduVPN client with this library. The language specific documentation will be given in separate sections. + +## Note on types and names +This section acts as an introduction to the API, as such this section will e.g. only give general typing information for the arguments and return values. Please read the language specific API documentation as well. To give an example, we will often say that an `Error` is returned. For Go this is the `error` type, whereas for Python this is simply a string with the error message. + +Additionally, the name of the function described will not be stated exactly as this has language specific differences. For example in Go we use the camel case construct, whereas for python snake case is used. E.g. compare `GetConnectConfig` (Go) and `get_connect_config` (Python) diff --git a/docs/src/api/overview/connecting.md b/docs/src/api/overview/connecting.md new file mode 100644 index 0000000..c2a82a0 --- /dev/null +++ b/docs/src/api/overview/connecting.md @@ -0,0 +1,14 @@ +# Connecting/Disconnecting +## Summary +Name: `Set Connected` and `Set Disconnected` + +Arguments: None + +Returns: `Error` + +Used to signal to the FSM that we're connected/disconnected to the VPN + +## Detailed information +This function is used to set the internal FSM state to connected. As the library does not actually connect to a VPN server, as this is platform specific, this must be called by the client to signal to the library that the user is connected to the VPN. If the FSM does not have a transition to the Connected state it will signal this with a returned error. + +The same function is used to signal the FSM that the VPN is disconnected. diff --git a/docs/src/api/overview/deregistering.md b/docs/src/api/overview/deregistering.md new file mode 100644 index 0000000..0503dbe --- /dev/null +++ b/docs/src/api/overview/deregistering.md @@ -0,0 +1,11 @@ +# Deregistering +## Summary +name: `Deregister` + +Arguments: None + +Returns: Nothing + +Used to cleanup the library by deregistering the client and saving the config files +## Detailed information +The deregister method is used to cleanup the library. It should be called when the client closes. This also saves the state to the directory that was passed in the [Register](./registering.html) method. diff --git a/docs/src/api/overview/discovery.md b/docs/src/api/overview/discovery.md new file mode 100644 index 0000000..0999912 --- /dev/null +++ b/docs/src/api/overview/discovery.md @@ -0,0 +1,63 @@ +# Discovery +## Summary +Name: `Get Disco Servers` and `Get Disco Organizations` + +Arguments: None + +Returns: `JSON string for servers/organizations` and `Error for servers/organizations` + +Note: Depending on the wrapper they may be combined into one function, the return value of this function is then the following: +`organizations, error for organizations, servers, errors for servers` + +Used to obtain the servers and organizations list from the discovery server. +## Detailed information +Discovery is the aspect of eduVPN that allows a client to gather all the servers and organizations it can connect to. For this a discovery server is used, which is registered as `https://disco.eduvpn.org` in the library. We refer to the [official eduVPN documentation](https://github.com/eduvpn/documentation/blob/v3/SERVER_DISCOVERY.md) to learn more about the exact way that these organizations and servers are structured. + +The JSON data that this returns must be used by the client to build an UI. It is common for clients that the discovery functions get called on startup of the client. Note that there can be an error in retrieving the newest version of the servers/organizations. However, this library's goal is to ensure that a version is always available. Thus, a local copy is distributed with this library in the future. + +This library also internally looks at the version of the servers and organizations such that rollbacks attacks are prevented. The client does not have to do any additional checks for this. + +The structure of the JSON data is the structure in the [official eduVPN documentation](https://github.com/eduvpn/documentation/blob/v3/SERVER_DISCOVERY.md) without the `v` (version) field. So, for example, the servers list has a possible JSON structure of this: + +```json +[ + { + "server_type": "institute_access", + "base_url": "https://hku.eduvpn.nl/", + "display_name": { + "en-US": "Utrecht School of the Arts", + "nl-NL": "Hogeschool voor de Kunsten Utrecht" + }, + "keyword_list": "hku" + }, + { + "server_type": "secure_internet", + "base_url": "https://eduvpn.rash.al/", + "country_code": "AL", + "support_contact": [ + "mailto:helpdesk@rash.al" + ] + } +] +``` + +And the organizations list has a possible JSON structure of the following: + +```json +[ + { + "display_name": { + "nl": "SURFnet bv", + "en": "SURFnet bv" + }, + "org_id": "https://idp.surfnet.nl", + "secure_internet_home": "https://nl.eduvpn.org/", + "keyword_list": { + "en": "SURFnet bv SURF konijn surf surfnet powered by", + "nl": "SURFnet bv SURF konijn powered by" + } + } +] +``` + + diff --git a/docs/src/api/overview/flow.md b/docs/src/api/overview/flow.md new file mode 100644 index 0000000..14b5a72 --- /dev/null +++ b/docs/src/api/overview/flow.md @@ -0,0 +1,8 @@ +# Typical flow +A typical flow of creating a client is calling the methods that we talked about in order that we introduced them: + +- The client starts, it registers with the library +- A list of discovery servers/organizations is obtained using the library +- The client selects an URL to connect to and calls the function to get an OpenVPN/Wireguard config from the library +- The client uses the OS specific libraries and programs to use the OpenVPN/Wireguard config to establish a tunnel and calls the function to connect or disconnect +- When the client is done it calls the deregister method to save all configuration and clean up diff --git a/docs/src/api/overview/getconfig.md b/docs/src/api/overview/getconfig.md new file mode 100644 index 0000000..70bcb39 --- /dev/null +++ b/docs/src/api/overview/getconfig.md @@ -0,0 +1,73 @@ +# Getting an OpenVPN/Wireguard config +## Summary +name: `Get Connect Config` + +| Arguments | Description | type | +| --------- | -------------------------------------- | -------- | +| URL | The url of the VPN server to connect to | string | +| Force TCP | Whether or not to force the use of TCP | string | + +Returns: `OpenVPN/Wireguard config (string)` `wireguard/openvpn type (string)`, `Error` + +Used to obtain the OpenVPN/Wireguard config + +## Detailed information + +To get a configuration that is used to actually establish a tunnel with the VPN server, we have the Get Connect Config (the exact name depends on the language you're using) function in the library. This function has two parameters *URL* and *Force TCP*. + +*URL* is the base url of the server to connect to e.g. `nl.eduvpn.org`. Note that this function does not need any further input whether or not we want to connect for institute access or secure internet. This is handled in the library by checking the discovery list. If it does not find the server in the discovery list, it assumes it wants to connect as an institute server. + +The *Force TCP* flag is a boolean that indicates whether or not we want to use TCP to connect over the VPN. This flag is useful if the user has enabled e.g. a setting that forces the use of TCP, which is only supported by OpenVPN. If the Force TCP flag is set to true but the server only supports Wireguard then an error is returned and the config will be empty. + +This function takes care of OAuth which has certain callbacks with data. Additionally, there are also callbacks that need to be registered for selecting the right profile to connect to. These callbacks will be explained now. + +The data that this function returns is the OpenVPN/Wireguard config as a string, the type of config (a string: "wireguard" or "openvpn") and an error if present. + +### Callback: OAuth started + +OAuth has an important callback which is used to obtain the authorization URL by the client. This client needs to open this authorization URL in a web browser such that the user can authenticate with the VPN portal and then authorize the client to obtain OpenVPN/Wireguard configs. + +The callback for this is triggered whenever the OAuth Started state is triggered. The data which this callback has is the authorization url that needs to be opened in the web browser. + +The format of the authorization URL is e.g. this: + +`https://eduvpn.example.com/vpn-user-portal/oauth/authorize?client_id=org.eduvpn.app.linux&code_challenge=DsmGyWFBkvDXiIO33Fs40Z0fn4pxtzDCW2jKvAMptBg&code_challenge_method=S256&redirect_uri=http%3A%2F%2F127.0.0.1%3A8000%2Fcallback&response_type=code&scope=config&state=vha2Krx-HpOyvFkWsWYmey0jrHQ6bnb06PQ6zBXX_bg` + +### Callback: Selecting a profile + +Another aspect that needs to be taken into account is the fact that there can be multiple profiles that a client can connect to. When the function gets called for obtaining an OpenVPN/Wireguard configuration, it asks the client which profile it wants to connect to using the callback that gets triggered on the Ask Profile state. The data is the list of profiles in JSON format, e.g. + +```json +{ + "info": { + "profile_list": [ + { + "profile_id": "internet", + "default_gateway": true, + "display_name": "IPv4 (NAT) IPv6 (GUA) Access", + "vpn_proto_list": [ + "openvpn" + ] + }, + { + "profile_id": "adblock", + "default_gateway": true, + "display_name": "Malware/Tracking-Blocker IPv4 (NAT) IPv6 (GUA)", + "vpn_proto_list": [ + "openvpn" + ] + }, + { + "profile_id": "dnsonly", + "default_gateway": false, + "display_name": "DNS-Only & Malware/Tracking-Blocker (experimental)", + "vpn_proto_list": [ + "openvpn" + ] + } + ] + } +} +``` + +For actually selecting the profile, there is a separate function which takes care of this. This function takes as only argument the profile ID as a string. diff --git a/docs/src/api/overview/registering.md b/docs/src/api/overview/registering.md new file mode 100644 index 0000000..5c40614 --- /dev/null +++ b/docs/src/api/overview/registering.md @@ -0,0 +1,35 @@ +# Registering a client +## Summary +Name: `Register` + +| Arguments | Description | type | +| --------- | -------------------------------------- | -------- | +| Name | Name of the client | string | +| Directory | Path to save logging and state | string | +| Callback | Function to be used as the FSM callback | function | +| Debug | Indicates whether or not to configure debugging capabilities. See [this section](../../../gettingstarted/debugging/index.html) for more information on debugging. | boolean | + +Returns: `Error` + +Used as initialization function of the library +## Detailed information +This library is made to build eduVPN clients. To create such a client, the register method is used. This method takes a *name*, *directory* and *callback*. This method needs to be called whenever a client wants to use this library. If this method is not called then the remaining methods will not be available to use. + +The *name* is the name of the client, also used as a client ID for OAuth. In general the name is the following for each official eduVPN client (documented [here](https://git.sr.ht/~fkooman/vpn-user-portal/tree/v3/item/src/OAuth/ClientDb.php)): + + +| Platform | Client ID | +| -------- | ------------------------ | +| Linux | `org.eduvpn.app.linux` | +| Windows | `org.eduvpn.app.windows` | +| MacOS | `org.eduvpn.app.macos` | +| Android | `org.eduvpn.app.android` | +| iOS | `org.eduvpn.app.ios` | + +The *directory* is the file path where logging and config files are stored. The library creates this directory if it doesn't exist. This can be an absolute or relative path. We recommend to use an absolute path to ensure that the right directory is chosen. + +The *callback* is the function that gets called when the internal Finite State Machine switches state. This callback function must consist of three arguments + +- Old state: The old state as a string, which is the current FSM state before the transition. See [FSM states](../../gettingstarted/debugging/fsm.html#state-explanation) for a list of states. +- New state: The current state for the FSM after the transition, also a string. See [FSM states](../../gettingstarted/debugging/fsm.html#state-explanation) for a list of states. +- Data: The data that gets sent by the library as a string. Most common this is JSON data to build the UI or in case of OAuth it is the authorization URL that needs to be opened by the browser. When there is no data this is an empty string. |