ACCESS Developer Network | Connection Manager | Connection, Profile, Manager, Plugin, Vpn

The Connection Manager defines the interface between applications, other middleware components, and low-level Linux communication components. For example, the Connection Manager provides an API to search and connect an appropriate network profile at the application level, and is responsible for making up and configuring all relevant Linux networking components such as the network interface, the routing table, and the DNS resolver.

Connection Manager Architecture ^TOP^

The Connection Manager is composed of a set of sub-components:

A connection database that stores connection definitions and parameters.
A server that runs root-only operations (such as connection or database changes) and records the connections' state.
Plug-ins that implement small pieces of code to control, connect, and configure a connection step. For example, the IP plug-in is responsible for assigning IP address and creating default routes, while the PPP plug-in is responsible for running the PPP daemon.
A library that provides connection manager facilities to applications and services by way of an API written in C.
A Linux command cnc used by scripts to communicate with the Connection Manager server.
A Connection Hook which enables licensees to override connection and sharing mechanisms.

The Connection Manager also provides two application-level components:

A Network Preferences Panel which enables the user to create, change, and delete connection profiles.
A Signal Strength Status Gadget which provides the user with a shortcut to connection profiles.
A Notifier Application that displays connection progress information and asks for user choices (security, progress and fallback dialogs)

The Connection Manager runs as a server with root privileges.

The following diagram shows the relationships between the various Connection Manager components.

Figure 1.1 Connection Manager Framework

Connection Manager Server ^TOP^

The Connection Manager Server is responsible for:

Reading and writing the connection database
Connecting and disconnecting profiles
Controlling profiles
Ensuring the security of sensitive information

When connecting a profile, the Connection Manager server spawns a new thread and launches the connection notifier application to display progress in the user interface. (An application can also connect profiles silently—in this case, the notifier application is not run.) A specific pipe is created between the notifier and the server to transport user choices. If the pipe is broken—for example, if the notifier crashes—the Connection Manager server attempts to silently continue the connection. A connection can be cancelled at any time.

The connection manager server aborts a connecting process as soon as a plug-in has terminated its job. For example, if you cancel a connection over a PPP link while PPP is negotiating the user name and password, PPP will terminate its job. Subsequently, the Connection Manager will abort the connection. Note that it is also possible for a plug-in to detect the cancellation before terminating its job. The plug-in can then decide to abort the connection on its own.

The server runs as a privileged user (root) in order to configure network and other communication components. The server is run at Linux boot time by the init program, and first enumerates the plug-in modules before dynamically loading them.

Figure 1.2 Connection Manager Server Threads

When connecting, disconnecting, or controlling profiles, the server calls plug-in callbacks. Some plug-ins use standard Linux commands such as pppd or udhcpc, or directly call shell scripts. In all cases, the shell script called by the plug-in or Linux command sends the command's end status and results back to the Connection Manager Server. For example, the script associated with the udhcpc command sends back the locale IP address given by the DHCP server.

The Connection Manager provides a simple API and a shell command to exchange arguments and results between plug-ins and external jobs.

Figure 1.3 Connection Manager Server External Jobs

Connection Manager Plug-Ins ^TOP^

At startup, the Connection Manager loads Connection Manager plug-ins. These plug-ins define how to connect or configure communications components. For example, there is a plug-in to set up IP addresses on network interfaces and to configure routes, gateways, and DNS servers. There is also a plug-in that interacts with the ACCESS Linux Platform Telephony Manager to connect to a network via the phone module.

Connection Manager plug-ins are described in detail in Chapter 2, "Connection Manager Plug-Ins,".

Connection Manager Library ^TOP^

An application can link with the Connection Manager library to access its database or to connect to a network. The Connection Manager library implements a lightweight RPC mechanism between the application and the Connection Manager server.

Connection Manager Profiles ^TOP^

Connection Manager profiles define how to connect to a specific network. The selection of profiles depends upon the technologies that are available on the device. For example, a connection profile can define how to connect to a specific GSM network using a given phone number, login name, and password. Most devices also define Wi-Fi, Bluetooth, and/or USB profiles.

Connection Manager Database ^TOP^

Connection Manager profiles, along with other Connection Manager core objects, are stored in the Connection Manager Database. This database is simply a file stored in the Linux file system at /var/opt/alp/data/lib/cnc/cnc.db. Only users with root privileges should be allowed to read or write to the database file. Sensitive profile information, such as passwords, should be stored in separate files - not in the Connection Manager Database - under the directory /var/opt/alp/data/lib/cnc/passwords/. At boot time, the Connection Manager script file /etc/cnc/$DEVICE.cnc is executed to define built-in default profiles. (See "Connection Manager Script File" for an example.)

The Connection Database contains several types of records. Each record has a unique ID and a unique name. The Connection Manager API uses IDs or names to manipulate records.

Types of records include:

Plug-ins: Each Connection Manager plug-in has an associated record in the Connection Database. Plug-ins define anchors where profiles can be attached. For example, all network profiles are attached under the NetOut plug-in.
Profiles: Profiles define how to connect a device or a network interface. A profile is a sequence of references to plug-ins and/or interfaces. Each reference can define parameters. A profile has a string representation. For example, the following is a profile using the NetOut, IPIF (TCP/IP), PPP and Serial plug-ins. It is a profile that mounts a PPP connection through ttyS0.
```
NetOut/IPIF/PPP:User='test',Pass='test'/Serial:DevN='ttyS0' 
```
Interfaces: Interfaces are anchors where profiles can be attached. They are also used to group several plug-ins or interfaces under a unique name. For example, if Serial, ircomm, and rfcomm plug-ins are grouped under the rs232 interface, searching for "rs232/*" finds all profiles attached with Serial, ircomm and rfcomm plug-ins.
Edges: Edges can be created between plug-ins and interfaces to create groups. In the previous example, there are edges from the rs232 interface to Serial, to ircomm, and to rfcomm.
Templates: Templates are guides for creating new profiles.
Links: Links are objects that reference other objects. They are used to define several names to a same object.

To accelerate searches, the server keeps in memory a cache of the system names and IDs of all profiles.

Connection Manager Script File ^TOP^

The Connection Manager script file in the following example defines built-in default properties.

Listing 1.1 Sample Script File /etc/cnc/simulator.cnc

#!/opt/alp/bin/cnc -f 
 
#Ethernet profile 
add "Ethernet Connection" "NetOut:link=256/IPIF/Ethernet:DDev='eth1'" 
#Ethernet template 
add template "Ethernet Link" "NetOut:link=256/IPIF/Ethernet:DDev='eth1'" 
 
#USB profile 
#add "USB Connection" "NetOut:link=128/
IPIF:LoIP='192.168.2.101',NetM='255.255.255.0',GWys='192.168.2.100',DNSs='192.1
68.101.11',Dom 
s='palmsource.com'/Ethernet:DDev='usb0'" 
#USB template 
add template "USB Link" "NetOut:link=128/
IPIF:LoIP='192.168.2.101',NetM='255.255.255.0',GWys='192.168.2.100',DNSs='192.1
68.101.11',D 
oms='palmsource.com'/Ethernet:DDev='usb0'" 
 
#Ethernet IPv6 profile 
add "Ethernet Connection IPv6" "NetOut:link=256/IPIF6/Ethernet:DDev='eth1'" 
#Ethernet IPv6 template 
add template "Ethernet Link IPv6" "NetOut:link=256/IPIF6/Ethernet:DDev='eth1'" 
 
#Tunnel IPv6-over-IPv4 profile 
add "Connection IPv6-over-IPv4" "NetOut/IPIF6/TunIP/NetAccess" 
#Tunnel IPv6-over-IPv4 template 
add template "IPv6-over-IPv4" "NetOut/IPIF6/TunIP/NetAccess"

Network Preferences Panel ^TOP^

The network preferences panel application links to Connection Manager plug-in user interface modules. These modules define user screens to configure some parameters and the logic to check the parameters validity. For example, the IPIF plug-in defines several screens to allow the user to define the IP address, the gateway, the DNS servers of a network connection. This application uses the connection manager to read/write to the connection manager database.

The following diagram shows the relationship between the network preferences panel and the Connection Manager components.

Figure 1.4 Network Preferences Panel Framework

Notifications ^TOP^

Connection Manager clients can register to receive Connection Manager notifications. Registering with the connection manager server opens a pipe between the client and the server. Each time a channel (or router) status changes, the server sends a message through these pipes. A client can poll() or select() on the fd pipe.

IPC and File Descriptors ^TOP^

This implementation of the ACCESS Linux Platform Connection Manager no longer relies on STREAMS or IOS. The Connection Manager uses native Linux IPC and communication components. This affects the implementation of the Connection Manager server and clients that use AF_UNIX sockets to communicate in place of IOS pipes. File descriptors are carried over process boundaries using CMSG_XXX macros. See man cmsg for a complete example.

Connecting Profiles ^TOP^

ACCESS Linux Platform defines two ways to connect profiles:

A high-level connection mechanism that ensures that an application uses the chosen profile for its communication, even if there are already other TCP/IP connections up. This method is reserved for TCP/IP profiles.
A simple connection/open mechanism that does not take into account TCP/IP-specific parameters. For example, this method can be used to open a serial port.

Working with Data Channels ^TOP^

An application must be able to:

Choose the right profile to connect
Route the network traffic to this profile, even if another connection is active.
Use the DNS servers associated with this profile, even if another connection (with its proper DNS servers) is active.

An application that requires this level of service must use connection channels. Each thread in the system can open a data channel or "bind" to an already open data channel. At one time, a thread is bound to zero or only one data channel. A thread can bind to another channel at anytime.

NOTE: Some carriers mandate well-defined connections for some services (for example, MMS).

Profile Tags

All network profiles can be labeled with one or more tags specifying the kind of service(s) they support. For example, one network profile can be labeled with an MMS tag, while another profile is tagged "WAP," etc. Profiles with no tag are considered to be generic, and are potentially able to support all services.

An application or background service that creates a data channel specifies which kind of network profiles it wants to connect to. For example, an MMS application requests an MMS-capable profile. The application or service can also choose to fall back to a more global profile if no specific profile exists.

To tag network profiles with one or more services, the licensee or carrier must add the srv0 parameter to the NetOut plug-in of the profiles (the NetOut plug-in is the first plug-in of all network profiles). This can be done at the profile creation with alp_cnc_profile_decode(), or later with alp_cnc_profile_set_parameters(). The srv0 parameter value is a 32-bit integer where each bit represents a service. A profile with no tag or with a value of 0 is assumed to be a general profile.

A link tag is also supported at channel creation to specify the type of link (Wi-Fi, Bluetooth, USB, GPRS, etc.).

Services and Links Constants

ACCESS Linux Platform defines constants for some well-known services and links:

ALP_CNC_CHANNEL_SRV_WAP
ALP_CNC_CHANNEL_SRV_MMS
ALP_CNC_CHANNEL_SRV_WEB
ALP_CNC_CHANNEL_SRV_EMAIL
ALP_CNC_CHANNEL_SRV_SIP
ALP_CNC_CHANNEL_SRV_IM
ALP_CNC_CHANNEL_SRV_PTT
ALP_CNC_CHANNEL_SRV_SYNC
ALP_CNC_CHANNEL_SRV_SHAREABLE
ALP_CNC_CHALLEL_SRV_DM
ALP_CNC_CHANNEL_SRV_GENERIC
ALP_CNC_CHANNEL_SRV_BACKGROUND
ALP_CNC_CHANNEL_LINK_CS
ALP_CNC_CHANNEL_LINK_PS
ALP_CNC_CHANNEL_LINK_PS_IP
ALP_CNC_CHANNEL_LINK_WIFI
ALP_CNC_CHANNEL_LINK_BLUETOOTH
ALP_CNC_CHANNEL_LINK_USB
ALP_CNC_CHANNEL_LINK_ETHERNET

If more than 32 kinds of services are needed, this list can be extended by carriers and licensees by adding other srv1 and srv2 parameters.

When connecting a data channel, the connection algorithm tries possible network profiles (see "Working with Profiles"). The connection algorithm attempts to use specific profiles before trying general profiles.

Routing Traffic

When a data channel is connected, the IPIF plug-in uses iproute2 to create a routing sub-table for the newly connected network interface. This two external devices sub-table defines the classic subnet rule through the interface and the default gateway for this interface. The thread that opened the channel is automatically bound to this channel.

The following example shows the routing sub-table after connecting the profile:

~ # ip route show table cnc_31 
10.128.20.0/22 dev eth1  scope link 
default via 10.128.20.1 dev eth1

The IPIF plug-in also configures an iproute2 rule in the main routing table to associate traffic explicitly using this interface to use the sub-table associated with this interface. This allows applications to bind their sockets to this interface and to use the right default gateway. For example (rule 32765):

~ # ip rule show 
0:      from all lookup local 
32763:  from all to 10.128.12.21 lookup cnc_31 
32764:  from all to 10.128.12.20 lookup cnc_31 
32765:  from 10.128.20.109 lookup cnc_31 
32766:  from all lookup main 
32767:  from all lookup default

The functions alp_cnc_channel_open(), alp_cnc_channel_connect(), and alp_cnc_channel_select() function bind the calling thread to a data channel. These functions cause that all future alp_cnc_socket() or socket() calls in the thread automatically bind the socket to the network interface associated with the channel. All the traffic in the thread then use the right interface and gateway. Applications that run multiple threads can bind each thread to a different channel. If an application does not want to bind a socket() to a channel, it must use alp_cnc_unbound_socket().

Multi DNS

An application or service bound to a channel uses DNS servers associated with this channel. The application also searches the right search domains associated with the channel.

When a channel is connected, the IPIF plug-in creates rules in the main routing table to be sure that DNS requests on the DNS servers of the channel are routed by the right interface using the right gateway. For example (rules 32763 and 32764):

~ # ip rule show 
0:      from all lookup local 
32763:  from all to 10.128.12.21 lookup cnc_31 
32764:  from all to 10.128.12.20 lookup cnc_31 
32765:  from 10.128.20.109 lookup cnc_31 
32766:  from all lookup main 
32767:  from all lookup default

When a thread is bound to a channel, the libc resolver in this thread uses the DNS servers and domains associated with the channel. This is possible by changing, after initialization, the _res thread variable used by the standard libc resolver. The file
/etc/resolv.conf is not used.

In case the connection uses a tunnel (for example, VPN over an Internet connection), the DNS servers of the tunnel are queried first (the ones on the private network in the VPN example). If they fail, the DNS servers of the main connection (the ones associated with the Internet connection in the VPN example). This ensures that even if the VPN DNS servers do not serve the Internet, an application, typically a web browser, can resolve Internet domain names. This is achieved by overriding the standard gethostbyname() call.

Data Channel API

Networked applications must use alp_cnc_channel_* functions to create, connect, and manage network channels. A networked application first opens a data channel (if a network profile is connected), and then uses the data channel by creating AF_INET or AF_INET6 sockets. Finally, the application closes the data channel.

Channel creation: The Connection Manager determines which network profiles fit the need of the application. The list is ordered by profile priority.; Functions: alp_cnc_channel_create() uses tags to find compatibles profiles; alp_cnc_channel_create_id() uses an explicit profile ID
Channel connection: The Connection Manager applies the following connection algorithm when connecting a channel: if a profile is already connected, the Connection Manager uses the connected profile. If no profile is connected, the Connection Manager first attempts to use the highest priority profile, and then falls back to other possible profiles. If the connection is not silent, the user is asked to confirm or change the algorithm fallback choices. The fallback algorithm also tries to avoid profiles that are not available, if availability is implemented in plug-ins. For example, it can avoid connecting to a GPRS profile if there is no GPRS coverage.; Functions: alp_cnc_channel_connect()
Channel use: The Connection Manager has overridden the socket() and gethostbyname() functions to fit channel requirements.; Functions: socket(), gethostbyname(), alp_cnc_socket(), alp_cnc_unbound_socket()
Channel disconnection: The Connection Manager marks the connected profile to be disconnected. If no other application uses this profile, a time-out is set. The profile is effectively disconnected if no application is using the profile after the time-out.; Functions: alp_cnc_channel_disconnect()
Channel destruction: The Connection Manager destroys the channel and associated memory (which may include, for example, the list of compatible profiles).; Functions: alp_cnc_channel_destroy()

The Connection Manager also defines some "shortcut" functions:

alp_cnc_channel_open()	`alp_cnc_channel_create() + alp_cnc_channel_connect()`
`alp_cnc_channel_open_id()`	`alp_cnc_channel_create_id() + alp_cnc_channel_connect()`
`alp_cnc_channel_close()`	`alp_cnc_channel_disconnect() + alp_cnc_channel_destroy()`

The alp_cnc_channel_select() allows a thread to select or re-open an existing channel. After this call, thread sockets are bound to the selected channel. The thread that selected the channel should close it (i.e., disconnect or destroy it) when it no longer needs the channel.

When a thread terminates (if it faults, for example), its session with the Connection Manager server is automatically closed and opened. Alternatively, selected channels in the session are automatically disconnected or destroyed. Disconnecting a channel does not mean the associated connected profile has been disconnected.

Working with Profiles ^TOP^

The functions described in this section should not be used by networked applications that require data channels. Rather, the functions can be used to connect a non-network profile (for example, to open a serial port or a connection with the telephony sever).

Connect profile: Connect a given profile by its ID. Returns a file descriptor to the connection.; Function: alp_cnc_profile_connect()
Disconnect profile: Disconnect a given profile by its ID.; Function: alp_cnc_profile_disconnect()

A client can check whether a profile is connected by calling alp_cnc_object_get_info() with a profile ID, and then testing the ALP_CNC_IS_CONNECTED_OPTION flag.

The client can also register to receive server notifications. The Connection Manager server raises a notification every time a profile is connected, disconnected, or if profile availability changes.

The Connection Manager can raise the following types of notifications:

ALP_NOTIFY_APP_ID_CNC_SERVER: Notification application ID of connection manager server.
"cncd"
ALP_NOTIFY_EVENT_CNC_CONNECTION: Notification sent by cncd when a profile is connected or disconnected.
/alp/cnc/connection
ALP_NOTIFY_EVENT_CNC_AVAILABILITY: Notification eventually sent by a transport when it becomes available or unavailable.
/alp/cnc/availability

Connection Sharing ^TOP^

The Connection Manager allows connection sharing between an ACCESS Linux Platform device and one or more external devices.

The Connection Manager defines a type of network profiles called Netin ("Network IN") profiles. Netin profiles help launch Linux services to allow external devices (such as Bluetooth devices) to connect to the ACCESS Linux Platform device, and to share its network connections.

These special profiles begin with the Netin plug-in. The Connection Manager provides the IPIFIN plug-in. IPIFIN defines the process by which NAT, DHCP server, and ZCIP (zero conf) are configured, as well as the static address of the new local interface. IPIFIN is jointly used with the BluetoothIn profile to enable Bluetooth external devices to connect to an ACCESS Linux Platform device, allowing the devices to share an Internet connection.

The following example shows a BluetoothIn NAP Server profile:

NetIn/IPIFIN:DHCP=0x00000001/BluetoothIn:Topo=0x00000007

A Netin profile must first be turned ON by sending the profile an ON control. The plug-ins of the profile are called to perform initial configuration, such as running a DHCP server. A Netin profile can be turned OFF by sending it an OFF control.

Netin profiles also support UP and DOWN controls, which make plug-ins perform tasks when an external device connects or disconnects from an ACCESS Linux Platform device.

The following example from alp_init.sh shows how to start the BluetoothIn NAP Server for incoming connections:

if [ "$BLUETOOTH_ENABLED" = 1 ] ; then 
        /etc/cnc/bluetooth.cnc 2>&1 >/dev/null 
        /bin/sh -c "/opt/alp/bin/cnc in \"BluetoothIn NAP 
Server\" on" & 
        PrintStatus "Started bluetooth NAP server" 
fi

The Connection Hook ^TOP^

The Connection Manager makes the built-in connection algorithm hook-able in order to implement new mechanisms, such as automatic connection switching, or to implement customized algorithms, such as a custom carrier/licensee fallback mechanism.

The connection algorithm calls the hook function in the following cases:

Upon receipt of a connection request, the hook function can choose the profile to connect. The hook function can also perform additional tasks, such as disconnecting an already-active connection. This may occur if a carrier does not support multiple connections at the same time.
When a fallback occurs, the hook function can choose the next profile to try, overriding the default fallback mechanism.
When the connection state of a profile changes, the hook function is called. When a profile is finally connected or an error condition is reached, the hook code has the opportunity to free hook connection variables.
When a connection is shared
When a connection is unshared

The hook function is implemented in a special plug-in called cnc_hook.so. The entry point of the hook module is called with a command number and parameters that correspond to the particular situation. The function returns a hook condition (hooked or not hooked) and additional parameters. If the condition is "not hooked," then the default built-in code is executed.

Configuration scripts use the cnc command to notify the Connection Manager server of changes or progress in the connection state. For example, the /etc/ppp/ip-up script executes cnc to send the negotiated parameters of the PPP connection, such as the local IP address, to the Connection Manager server.

Serial Communication ^TOP^

The Serial plug-in configures serial devices using POSIX termios.

VPN Framework ^TOP^

The VPN Framework extends the Connection Manager and provides VPN support for some protocols (IPSEC, L2TP). Thus, a VPN connection is similar to other types of connections (for example, Wi-Fi or GPRS), and the VPN Framework inherits all features of the Connection Manager. These features include profiles and existing plug-ins.

The VPN Framework consists of a VPN plug-in, VPN open-source products, and additional sample plug-ins for each product.

VPN Plug-in for Connection Manager ^TOP^

The VPN Plug-in manages interactions with the Connection Manager and its plug-ins, such as profiles and connections. The user interface of the plug-in offers the possibility to configure the following attributes:

VPN server IP address
Authentication and encryption data (user name/password, PSK, X. 509)

The configuration of the shared network by VPN (e.g., the corporate network) is done with the IPIF plug-in, so all VPN profiles must use the IPIF plug-in. Moreover, VPN profiles must use an existing connection via the NetAccess plug-in. Finally, a VPN profile must follow this format:

"VPN/IPIF/.../NetAccess"

In this example, the ellipses (...) can be any set of plug-ins for VPN (IPSEC, L2TP, PPP, etc.). The VPN Framework only supports IPv4 private networks and tunneling over IPv4 connections.

Framework for VPN Protocol Plug-ins ^TOP^

The VPN Framework is a part of the VPN plug-in. All VPN classic parameters are already managed by the VPN plug-in and its user interface. A VPN protocol plug-in deals only with its specific parameters. VPN plug-in function calls by sample plug-ins use the Connection Manager API mechanism.

The framework assumes that there is a maximum of three pieces of "secret" information to make a secure VPN connection: a X.509 certificate, a pre-shared key, and a login/password couple. In addition, the framework considers that a VPN connection has two security aspects: encryption and authentication.

The same protocol can gather the two aspects, but sometimes - for example, with L2TP/IPSEC - there may be a protocol for authentication (L2TP) and another for encryption (IPSEC). Therefore, in theory, there can be a maximum of six pieces of secret information (two login/password pairs, two pre-shared keys, and two X.509 certificates). However, according to practical uses of VPN, the VPN Framework only supports a maximum of three pieces of secret information for two protocols. Each piece of secret information cannot be used by more than one protocol. For example, a VPN L2TP/IPSEC connection can use the login/password and X.509 certificates for L2TP, and a pre-shared key for IPSEC.

Plug-in Samples ^TOP^

Samples are Connection Manager plug-ins. All VPN plug-ins must write scripts to catch route table operations and retransmit them by the cnc command. All VPN network information must then be exported in the profile. For more information, see "IPIF Plug-in [IPIF]".

IPSEC

The IPSEC plug-in sample is based on Openswan and vpnc (for CISCO interoperability). An "up-down" script catches route table operations. A very simple user interface permits configuration of one of the parameters.

See "IPSEC plug-in [IPSEC]" for parameters of the IPSEC plug-in and profile samples.

L2TP

The L2TP plug-in sample is based on rp-l2tpd and uses PPP plug-ins. The EAP-TLS authentication mode is tentative and used through the VPN plug-in, the PPP plug-in, and profiles. There is no user interface for L2TP.

The L2TP plug-in is also an rp-l2tp plug-in to handle pppd calls and redirect the UDP datagrams exchange to a master pseudo-terminal (/dev/ptmx). The L2TP plug-in can then open the slave pseudo-terminal (/dev/pts) for the PPP plug-in. Route table operations are caught by the PPP plug-in.

See "L2TP plug-in [L2TP]" for parameters of the L2TP plug-in and profile samples.

L2TP/IPSEC

It is possible to create a connection profile that uses the L2TP plug-in and the IPSEC plug-in to make a "L2TP over IPSEC" VPN. This is mostly used on Windows 2000/XP/2003 platforms. The following is a sample connection profile:

"VPN:Host='myoffice.com',User='foo',Pass=2589,PShK=7543,EMod='psk',Prot=17,Port
=1701/IPIF/PPP:Auth='CHAP'/L2TP/IPSEC/Net

VPN API ^TOP^

The Connection Manager library of APIs is used for VPN programming. A plug-in that can be used for VPN must add an edge with the "VpnPlugin" interface, and it must add an edge with each of the supported secret method interfaces (Auth, Psk, X509). An inline function is provided for making this process easier. To retrieve the configuration of the VPN connection, a plug-in must do a "control" on the VPN plug-in, which can be accomplished with the inline function included in the library.

VPN profiles define all the parameters needed to establish a VPN connection. A VPN connection needs an underlying generic NetOut connection.

The VPN profile is associated with the underlying NetOut profile in the following ways:

The VPN profile directly references a generic NetOut profile
The VPN connection uses a generic NetOut profile, if one is already connected, when connecting the VPN profile
The user is asked to choose a NetOut profile from a list if there is no connected NetOut profile. The chosen profile is connected to the VPN profile.

When a VPN profile is connected, the IPIF plug-in performs the following functions:

Adds routes to the virtual network via the virtual network interface. Applications can reach hosts on the VPN and hosts on the Internet.
Updates DNS information with the DNS servers of the virtual network. Applications can resolve names on the VPN, as well as names on the Internet because:
- Generally, VPN DNS servers also resolve Internet names
- The function gethostbyname() is overridden with alp_cnc_gethostbyname(). In case VPN DNS servers cannot resolve Internet names, alp_cnc_gethostbyname() will run another request on the underlying connection DNS servers.

The Figure 1.5 provides an example of a web client with two open pages: one on the Internet and one on a private network.

Figure 1.5 Web Client with Two Open Pages

The VPN framework (Connection Manager plug-in) API is as follows:

alp_cnc_vpn_get_configuration

Purpose

Give the configuration of the VPN connection

Parameters

← cfg: pointer on the configuration
→ cxP: pointer on the channel

Returns

ALP_STATUS_OK or an error if any

alp_cnc_vpn_register_plugin

Purpose

Parameters

→ pluginName: name of the plug-in
→ isAuthCapable: True if the plug-in supports user/pass authentication, false otherwise
→ isPskCapable: True if the plug-in supports pre-shared key, false otherwise
→ isCertCapable: True if the plug-in supports X.509 certificates, false otherwise

Returns

ALP_STATUS_OK or an error if any

Locale Changes ^TOP^

A profile can have a friendly name. This friendly name is localized. It is a string resource associated with the profile. An application that draws profile names should prefer the friendly name to the name of the profile. If a profile does not have a friendly name, the name is chosen.

The Connection Manager introduces a new parameter called fnam. If this parameter is present in a profile, an application that displays profile names to the user should use the fnam value to access a localized string resource called the friendly name of the profile.

The value format of fnam is a string:

fname='<plugin-id>:<string-id>'

An application uses alp_cnc_plugin_load() and the associated get_resource() callback to get the string.

The labl parameter used in connection templates also supports this syntax. The labl parameters are displayed in the "New Profile" form of the Connection Setup Application.