Using OpenVPN for PocketPC

8/3/2019 Using OpenVPN for PocketPC

1/16

1

Using OpenVPN for PocketPC

Before Installing

This is an Alpha. I know there are bugs, and I want to find them. I also don't want folks to be afraidto help test, because that will allow us to reach an acceptable quality level as rapidly as possible. I

recommend performing a backup before you start to experiment; on PocketPC devices this only take acouple minutes so it shouldn't be a hassle.

I have never had to hard-reset the device during development (even in the early phases of the driverportion), but you'll have at least the peace-of mind knowing you have that fallback position should

you think you need it, and you should be only out a few minutes time in restoring back to the

machine's original state.

I have, however, had to soft-reset. Don't forget that the uninstall is code, too, and may have bugs as

well that preclude a full uninstall. I do try to test the uninstall well before publishing a build, but I

have seen different behaviour on different OS versions in some cases.

Installation

The binaries are pre-built as a CAB file. You can copy the CAB file to any spot on your device (like

\). You can use the ActiveSync Explore feature to do the copying. Then, with File Explorer on thedevice you can find the CAB file and click it. It will install and the device will delete the CAB when

done.

Upon installing the CAB file, some files are copied to the system. Most of it is copied into:

\Program Files\OpenVPN

And the TAP driver and help file (for technical reasons) are copied to:

\Windows

A default instance (TAP1) is created and started, and the 'connection manager' application is started

up. It is also set up to start automatically upon device reset via a shortcut in the startup folder.

Basic User Interface

The connection manager starts up as an icon in the lower right-hand corner:

This icon may be tapped to present the menu:


2/16

2

Exit quits the Connection Manager application, and Help lets you open the help file or the about box.

The item labeled (recent config) is a most-recently-used configuration menu and will get populated as

you start using configurations.

Start From Config opens a menu of OpenVPN configuration files found on the system. These are

standard openvpn configuration files. You can build them on a desktop machine and copy them over.

In fact, I recommend you do just that as diagnosis is much easier on a desktop machine.

When you select this item the sub-menu is presented, e.g.:

In this example I have three configuration files. Sample comes out of the install and is provided as apattern for testers. It is the config file I have been testing with though obviously you will need to

modify it to point to your server and keys and whatnot. The other two are ones I created but aren't in

the distribution package. Stuff you create and put on your device will show up in this list.

The contents of the Start From Config menu are dynamically built from configuration files found on

the device. The files are located in a 'config' directory. By default, this directory is located at:

\Program Files\OpenVPN\config

The files must have the extension .ovpn to be recognized. In this example there were three such fileslocated in the config directory named:

y sample.ovpny real.ovpny test.ovpn

As mentioned, I recommend creating your creating of config files on a desktop machine and testingthem there. It is so much easier to test configurations on a desktop than to try to do so on the

PocketPC -- largely due to the keyboard, a console, and a big screen. You can then copy the knwon-


3/16

3

to-be-working file to the PocketPC device using whatever means; e.g. I use the Explore feature of

Active Sync to do so. It's completely feasible to create a file on the PocketPC and use it, though, ifyou're very config-saavy (which I'm not). Additionally in the future I plan to have a 'config wizard'that you can create typical configs by clicking through some options. For now, though, it's file-based

only.

When you click one of these file, an instance of openvpn.exe is started with the command-line of --config specifying the file. Additionally, two items are specified that will effectively override those inthe config file: the named termination event, and the management interface and port. The values for

these come from the settings page.

The currently running instances of openvpn.exe may be viewed on the VPN Instances page. Before I

get to that I will discuss some of the configuration options.

Utils

This opens a sub-menu with options for accessing the Settings, TAP Instances, and VPN Instances

pages.

Settings

This page contains various applications settings.


4/16

4

Run this app on startup

Creates a startup shortcut to start the connection manager upon soft-reset.

Check TAP loaded on startup

When the connection manager starts, it will enumerate all registered TAP devices and try and getthem started if they aren't already. This is particularly useful on WM5 devices because the TAP

driver will not be automatically loaded from NDIS for application trust reasons.

Try to ping servers on connect

Prior to starting a VPN instance, try to ping at least one of the servers listed in the configuration file.This is particularly useful on PocketPC because networking is usually provided via a wireless

connection that is typically off. Failure to ping usually means that you need to turn your wireless onfirst. Servers can be configured not to respond to ping requests, however, so this isn't proof positive

that a connection will fail.

Mgt:

the openvpn.exe has no user-interface and relies upon the connection manager to provide it.This is done through the management connection. Typically it is sufficient and secure to leave the

interface (the IP address) to be a localhost address. This prevents network connections to themanagement interface and only allows processes running on the device to use them. For testingpurposes it can be handy to open this up to network connections. Then you can connect with, say,

telnet from a desktop machine. You can provide an explicit IP address of a NIC on the device, or you

can specific 0.0.0.0 which means 'any NIC'.

The port is actually a base port address. The specific port used is the first available after that address

and is assigned on-the-fly at connection time.


5/16

5

Term Event:

It is possible to have openvpn.exe instances use a named event to signal application shutdown. The

connection manager uses this feature to provide a 'global shutdown' event for all running instances

(individual instances are shutdown via management connection).

Cfg:

This is the location where the configuration files are kept. Files in this location, with the .ovpnextension, are used to populate the Start From Config menu. The ellipses button (...) is used tobrowse for a new location. The default location is the 'config' subdirectory of the install location

(default is \Program Files\OpenVPN).

Log:

This is the location where the log files are kept. The ellipses button (...) is used to browse for a newlocation. The default location is the 'log' subdirectory of the install location (default is \Program

Files\OpenVPN).

Settings 2

Some more settings; pertinent to the Windows Connection Manager. This is experimental and may

change. Also, it's mostly of interest to those using phone (GPRS, GSM, EVDO, etc.) networks to

make data connections.

[WiFi users can probably ignore all of this]

The Windows Connection Manager is a mechanism created to simplify the process of connecting tonetwork resources. It attempts to automatically start and stop network connections based upon

perceived cost, and applications' requests. Since OpenVPN creates a virtual network adapter, it

appears as another networking resource that Windows Connection Manager considers in it's


6/16

6

connection planning decisions. Connection Manager can at times believe that it is safe to disconnect

the phone network when the virtual NIC provided by openvpn is present.

To help with this, this page has the following options:

Use Windows Connection Manager

When this is checked, the application will request a connection from Windows Connection Manager

prior to starting the vpn process, openvpn.exe. This will cause Windows Connection Manager toautomatically start a connection if one is not present.

By unchecking this option, nothing will be done with Windows Connection Manager.

[I put this in since this feature is experimental, and so by unchecking it there is a way to return to

previous behaviour. I expect no one will need or want to uncheck it.]

Use this provider

When using Windows Connection Manager, an application can request to use a specific connection

provider. The user can create these through the Settings interface, but usually there will be some thatship out-of-box, especially with phone-based devices that have pre-configured connection settings.

If you use a phone or dialup network to connect, you should select the provider that you want to use tomake the basic internet connection through which openvpn will be tunneling.

In the example shown above, my mobile operator is Sprint, and so I have selected 'Sprint'. Choose the

one appropriate to your device. WiFi users can ignore this setting and leave it at the default of .

[Pick the one that looks sensible to your device, depending on your mobile operator. This seems to be

important.]

Exclusive

An application can specify that a connection is to be made for it's exclusive use.

[Checking this, and selecting an appropriate item in 'Use this provider' seem to be the essential things

in not having the original phone network connection dropped when another application uses Windows

Connection Manager]

TAP Instances

This page shows TAP virtual NIC instances on the system in any of their various states.


7/16

7

Upon installation a single default instance is created. It is probably all you'll ever need unless you'redoing something terribly fancy. Due to a limitation in CE, you are restricted to 10 such instances (andpractically 9 in this application for no good reason). I provided the capability in the wildly offhanded

chance that someone else in the world has a device called TAP that needs to co-exist on the system.

You can have two distinct device drivers service the same base name so long as the distinguishing

digit is different. Then again maybe someone wants a couple simultaneous tunnels. Regardless of the

need the capability is there. I've only ever tested with one running tunnel, however.

The adapter can be in any of various states:

y not loadedThe adapter instance is registered with NDIS, but the OS hasn't loaded it and so it's not

available for use. This can happen if a new instance has been created, if the 'auto load driveron startup' option has not been checked (on WM5 devices), or if the device is so locked-down

that third-party code is disallowed from running at all (like maybe some Smartphone devices).y available

The adapter instance has been loaded by the OS and no-one is using it at the moment.y in-use

The adapter instance is being used; presumably by an openvpn.exe instance.

y orphanThe adapter has been loaded by the OS, but it's NDIS registration doesn't exist. Adapters in

this state will vanish from the system once a reboot (soft-reset) is performed. This can

happen when you use the 'Delete' button. This is not a normal state except when you'repreparing for an uninstall.

There are several buttons that operate on the currently selected TAP instance.

New

This will create a new TAP adapter registration for those who wish it. It is not expected to be

needed. This does not load the driver, and the driver will initially be in the 'not loaded' state.


8/16

8

Delete

The delete button will delete the NDIS registration for the selected TAP instance. This does not

unload the driver, but rather places it into the 'orphan' state. 'Orphaned' drivers are technically usable,but will evaporate when the system has been soft-reset. This is an unusual state for a TAP instance

except when preparing for an uninstall.

Start


9/16

9

This will cause the OS to load the selected adapter (if it's not already loaded). For example, selecting

the' TAP Device 2' created earlier, and selecting Start will cause the instance to become 'available'.

Ver

This button opens the TAP instance (if available) and issues and ioctl() to query for it's build version.

This can only be done if the instance is loaded and available. It doesn't serve much purpose other than

as a sanity check for testing.


10/16

10

VPN Instances

The VPN instance tab shows running (and presumably connected) instances of openvpn.exe. Initially

it looks like this:

The 'Signal Stop' button will ask the selected running instance (when there are some there) to exit.

The 'Signal Stop All' button will signal all running instances to exit. The 'Signal Stop All' does not

use the management interface, but rather uses the termination event.

When you start an instance for the 'Start From Config' menu, the wait cursor appears while theinstance is starting:


11/16

11

If the 'Try to ping servers on connect' setting is checked, then a ping will be issued before actually

connecting. If it fails the following will be shown:

This typically means that you don't have a route to access the server. PocketPC devices usually have

wireless network cards that you must manually turn on. If you haven't turned it on and connected toan access point, you will get this message. Check that first. That's why I put this in: because I

always forget. It can also happen if the server is configured not to respond to ping requests, so keep

that in mind.


12/16

12

If there is a password needed for server authentication, or for the private key, then a dialog is

presented prompting for such:

The text at the top of the dialog indicates the instance you just started (it is derived from the configfilename), and the type of password OpenVPN wants. I believe there are only two types: 'Private

Key' for the local client private key, and 'Auth' for the server-side user authentication.

If the instance runs, then its process id and state are shown:


13/16

13

If one were to switch to the TAP tab, you can see the TAP device that this VPN instance is currently

using.

While connected, a pane is added to this view dynamically which provides detailed information pulled

from the OpenVPN 'management interface':

The name on this tab is derived from the file name of the config file used to start the instance.


14/16

14

In this case the 'State' button was pressed. Details of this information can be found in the OpenVPN

documentation.

The 'End' button is provided as a convenience and works the same as the 'Signal Stop' button on the

VPN tab.

Whilst connected, the visible aspect of the icon on the Today screen changes to provide an obviousindication that at least one VPN instance is running:

At this point you should be ready to use the connection in some way.

Accessing a Resource Through the Tunnel

You should be able to access network resources through the tunnel with whatever client application isrelevant. For example, here is a web page served by a web server inside the private network being

displayed by PocketIE. This web server is known internally as 192.168.1.10, but is also the remote

VPN endpoint 10.8.0.1.

Exiting

The Exit menu option exits the OpenVPN Connection Manager application. It also checks to see ifthere are any VPN instances running and prompts the user to terminate them (it uses the global

termination event specified on the settings page).


15/16

15

It is wise to stop all the instances because, if not, the connection manager will forget the mappings ofassigned management ports to pids and not not be able to control pre-existing VPN instances uponrunning the connection manager again. I would recommend only choosing Yes or Cancel for this

warning. If for some reason you have a stray instance running when you re-start the Connection

Manager, you can use the 'Signal Stop All' button and that should cause pre-existing instances to exit.

The OpenVPN Connection Manager can be restarted from its icon in the Programs list. It's expected

that the connection manager would need to be exited explicitly only when doing an uninstall anyway.

Uninstalling

Uninstalling the application from the PocketPC device has a slight challenge. Principally, there arethree executable components: the openvpn.exe, the ovpncmgr.exe, and the tap-ce.dll. None of these

may be loaded during uninstall or the uninstaller will be unable to delete the files from the system.

The uninstaller will issue a warning if you try. The ovpncmgr.exe is easy: you just use the menu andselect Exit. This should also signal any openvpn.exe instances to exit as well. The TAP driver (tap-ce.dll) is a little trickier. The deal is that this is loaded by NDIS into device.exe. Furthermore, NDIS

will automatically load this driver upon bootup. Here's the way I prepare a device for uninstallation:

1. Use OpenVPN Connection Manager (ovpncmgr.exe) and go to Utils->TAP Instances.2. Delete the registration for all the TAP drivers. This doesn't unload them, but will prevent

them from being loaded on reboot, and they will show as being in the 'orphan' state.

3. Soft-reset the device. OpenVPN Connection Manager may have auto-started but can just exitit via the menu option.

Now you can uninstall in the normal fashion (Settings->Remove Programs).

If you don't do this, uninstall will delete all the stuff it can, and you won't have fully uninstalled

everything. In particular the TAP driver may be left behind.


16/16

16

Addendum for any device:

I added a 'stop' method in the TAP instances page. You can uninstall now with less trouble by taking

the following alternative steps:

1. Go to Utils->TAP Instances, and select Stop on each TAP device.2.

select 'Delete' for each device.3. select 'Exit' from the menu

Since all the binaries are now unloaded, you can uninstall in the normal fashion (Settings->Remove

Programs). Also, this way avoids the need to soft-reset.

Addendum for WM5-based devices:

It appears that Windows Mobile 2005 has improved the uninstaller such that it knows how to deal

with loaded files. In that case you can forget about having to do all the legerdemain mentioned aboveand just go straight to the uninstaller. The uninstaller will know that you have to reset the device and

will present a dialog asking if it is OK to do so. After resetting, there is a deferred action that will

delete the previously locked files. So there's a nice thing with WM5!

Documents

Using OpenVPN for PocketPC