VPN Service

---

The Virtual Private Network (VPN) API provides functions for managing VPN.

Required Header

#include <vpn_service.h>

Overview

The VPN Service functions for managing VPN. There can be only one VPN connection running at the same time. The existing interface is deactivated when a new one is created. Using the VPN Service, you can implement features that allow the users of your application to:

• Initialize / Deinitialize the VPN device
• Routing management
• DNS management
• Firewall management To enable or disable VPN interface, you should launch VPN popup by using app-control.

Related Features

This API is related with the following features:

• http://tizen.org/feature/network.vpn
  It is recommended to design feature related codes in your application for reliability.
  You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
  To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
  More details on featuring your application can be found from Feature Element.

Functions
int	vpnsvc_init (const char *iface_name, vpnsvc_h *handle)
	Initializes VPN interface.
int	vpnsvc_deinit (vpnsvc_h handle)
	De-Initializes VPN interface.
int	vpnsvc_protect (vpnsvc_h handle, int socket_fd, const char *iface_name)
	Protect a socket from VPN connections.
int	vpnsvc_read (vpnsvc_h handle, int timeout_ms)
	Waits for the read event on VPN interface descriptor, but no more than the indicated timeout in milliseconds.
int	vpnsvc_write (vpnsvc_h handle, const char *data, size_t size)
	Writes the data supplied into the VPN interface.
int	vpnsvc_block_networks (vpnsvc_h handle, char *routes_dest_vpn_addr[], int routes_vpn_prefix[], size_t num_allow_routes_vpn, char *routes_dest_orig_addr[], int routes_orig_prefix[], size_t num_allow_routes_orig)
	Blocks all traffics except specified allowing networks.
int	vpnsvc_unblock_networks (vpnsvc_h handle)
	Removes any restrictions imposed by vpnsvc_block_networks().
int	vpnsvc_update_settings (vpnsvc_h handle)
	Updates settings (Local IP / Remote IP / MTU).
int	vpnsvc_get_iface_fd (vpnsvc_h handle, int *iface_fd)
	Gets the fd of the VPN interface.
int	vpnsvc_get_iface_index (vpnsvc_h handle, int *iface_index)
	Gets the index of VPN interface.
int	vpnsvc_get_iface_name (vpnsvc_h handle, char **iface_name)
	Gets the name of VPN interface.
int	vpnsvc_set_mtu (vpnsvc_h handle, int mtu)
	Sets the MTU of the VPN interface.
int	vpnsvc_set_blocking (vpnsvc_h handle, bool blocking)
	Sets blocking mode of the file descriptor of VPN interface.
int	vpnsvc_set_session (vpnsvc_h handle, const char *session)
	Sets the session name for the VPN. (It will be displayed in system-managed dialogs and notifications.)
int	vpnsvc_get_session (vpnsvc_h handle, char **session)
	Gets the session name for the VPN.
int	vpnsvc_set_local_ip_address (vpnsvc_h handle, const char *local_ip)
	Sets the VPN client IP address.
int	vpnsvc_set_remote_ip_address (vpnsvc_h handle, const char *remote_ip)
	Sets the VPN server IP address.
int	vpnsvc_add_route (vpnsvc_h handle, const char *route_address, int prefix)
	Adds the route address.
int	vpnsvc_remove_route (vpnsvc_h handle, const char *route_address, int prefix)
	Removes the route address.
int	vpnsvc_add_dns_server (vpnsvc_h handle, const char *dns_server)
	Adds the DNS server name.
int	vpnsvc_remove_dns_server (vpnsvc_h handle, const char *dns_server)
	Removes the DNS server name.
Typedefs
typedef void *	vpnsvc_h
	The VPN interface handle.

---

Typedef Documentation

typedef void* vpnsvc_h

The VPN interface handle.

This handle can be obtained by calling vpnsvc_init() and destroyed by calling vpnsvc_deinit().

Since :

3.0

See also:

vpnsvc_init()

vpnsvc_deinit()

---

Enumeration Type Documentation

enum vpnsvc_error_e

Enumeration for VPN service error types.

Indicate formats of error type field

Enumerator:

VPNSVC_ERROR_NONE	Successful
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_OUT_OF_MEMORY	Out of memory
VPNSVC_ERROR_PERMISSION_DENIED	Permission denied
VPNSVC_ERROR_NO_SUCH_FILE	No such file or directory
VPNSVC_ERROR_IO_ERROR	IO error
VPNSVC_ERROR_TIMEOUT	Time out error or no answer
VPNSVC_ERROR_IPC_FAILED	Failed to communicate with server
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

---

Function Documentation

int vpnsvc_add_dns_server	(	vpnsvc_h	handle,
		const char *	dns_server
	)

Adds the DNS server name.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice

Remarks:

The dns address should be set after enabling VPN interface.

Parameters:

[in]	handle	The VPN interface handle
[in]	dns_server	The DNS server address (IPv4 only)

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_add_route	(	vpnsvc_h	handle,
		const char *	route_address,
		int	prefix
	)

Adds the route address.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice

Remarks:

The route address should be set after enabling VPN interface.

Parameters:

[in]	handle	The VPN interface handle
[in]	route_address	Destination address of the routes (IPv4 only)
[in]	prefix	The prefix of routes, netmask length (also called a prefix, e.g. 8, 16, 24, 32)

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_block_networks	(	vpnsvc_h	handle,
		char *	routes_dest_vpn_addr[],
		int	routes_vpn_prefix[],
		size_t	num_allow_routes_vpn,
		char *	routes_dest_orig_addr[],
		int	routes_orig_prefix[],
		size_t	num_allow_routes_orig
	)

Blocks all traffics except specified allowing networks.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet

Parameters:

[in]	handle	The VPN interface handle
[in]	routes_dest_vpn_addr	Destination address of the routes, the list of allowing networks over VPN interface (e.g., VPN interface such as tun0, etc).
[in]	routes_vpn_prefix	The prefix of VPN interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32).
[in]	num_allow_routes_vpn	The number of allowing networks over VPN interface
[in]	routes_dest_orig_addr	Destination address of the routes, the list of allowing networks over the original interface (e.g., original interface such as eth0, wlan0, etc).
[in]	routes_orig_prefix	The prefix of Original interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32).
[in]	num_allow_routes_orig	The number of allowing networks over the original interface

Returns:

0 on success. otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IPC_FAILED	Cannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIED	Permission Denied
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Postcondition:

Please call vpnsvc_unblock_networks() if you want to allow all traffics.

See also:

vpnsvc_unblock_networks()

int vpnsvc_deinit

(

vpnsvc_h

handle

)

De-Initializes VPN interface.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet

Parameters:

[in]

handle

The VPN interface handle

Returns:

0 on success. otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IPC_FAILED	Cannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIED	Permission Denied
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

Before calling this function, VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_get_iface_fd	(	vpnsvc_h	handle,
		int *	iface_fd
	)

Gets the fd of the VPN interface.

Since :

3.0

Parameters:

[in]	handle	The VPN interface handle
[out]	iface_fd	The vpn interface fd

Returns:

The fd value of VPN interface. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

int vpnsvc_get_iface_index	(	vpnsvc_h	handle,
		int *	iface_index
	)

Gets the index of VPN interface.

Since :

3.0

Parameters:

[in]	handle	The VPN interface handle
[out]	iface_index	The VPN interface index

Returns:

The index of the VPN interface. otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

Before calling this function, VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_get_iface_name	(	vpnsvc_h	handle,
		char **	iface_name
	)

Gets the name of VPN interface.

Since :

3.0

Remarks:

The iface_name should be released using free()

Parameters:

[in]	handle	The VPN interface handle
[out]	iface_name	The name of VPN interface name

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

Before calling this function, VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_get_session	(	vpnsvc_h	handle,
		char **	session
	)

Gets the session name for the VPN.

Since :

3.0

Remarks:

The session should be released using free()

Parameters:

[in]	handle	The VPN interface handle
[out]	session	The Session Name returned

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

Before calling this function, VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_init	(	const char *	iface_name,
		vpnsvc_h *	handle
	)

Initializes VPN interface.

You should call vpnsvc_get_iface_name() for checking the actual initialized VPN interface name. (In case of duplicated interface name)

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet

Remarks:

The handle should be released using vpnsvc_deinit().

Parameters:

[in]	iface_name	The VPN interface name
[out]	handle	The VPN interface handle

Returns:

0 on success. otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_IPC_FAILED	Cannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIED	Permission Denied
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Postcondition:

Please call vpnsvc_deinit() if you want to de-initialize VPN interface.

Please call vpnsvc_get_iface_fd() if you want to know the fd(file descriptor) of VPN interface.

Please call vpnsvc_get_iface_index() if you want to know the index of VPN interface.

Please call vpnsvc_get_iface_name() if you want to know the name of VPN interface.

See also:

vpnsvc_deinit()

vpnsvc_get_iface_fd()

vpnsvc_get_iface_index()

vpnsvc_get_iface_name()

int vpnsvc_protect	(	vpnsvc_h	handle,
		int	socket_fd,
		const char *	iface_name
	)

Protect a socket from VPN connections.

After protecting, data sent through this socket will go directly to the underlying network.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet

Parameters:

[in]	handle	The VPN interface handle
[in]	socket_fd	The opened socket file descriptor
[in]	iface_name	The network interface name (e.g., interface name such as eth0, ppp0, etc) through which the VPN is working

Returns:

0 on success. otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_IPC_FAILED	Cannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIED	Permission Denied
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

int vpnsvc_read	(	vpnsvc_h	handle,
		int	timeout_ms
	)

Waits for the read event on VPN interface descriptor, but no more than the indicated timeout in milliseconds.

Since :

3.0

Parameters:

[in]	handle	The VPN interface handle
[in]	timeout_ms	The value of timeout (milliseconds)

Returns:

0 on success. otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_TIMEOUT	Timeout (no answer in timeout_ms)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_remove_dns_server	(	vpnsvc_h	handle,
		const char *	dns_server
	)

Removes the DNS server name.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice

Parameters:

[in]	handle	The VPN interface handle
[in]	dns_server	The DNS server address (IPv4 only)

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_remove_route	(	vpnsvc_h	handle,
		const char *	route_address,
		int	prefix
	)

Removes the route address.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice

Parameters:

[in]	handle	The VPN interface handle
[in]	route_address	Destination address of the routes (IPv4 only)
[in]	prefix	The prefix of routes, netmask length (also called a prefix, e.g. 8, 16, 24, 32)

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_set_blocking	(	vpnsvc_h	handle,
		bool	blocking
	)

Sets blocking mode of the file descriptor of VPN interface.

Since :

3.0

Parameters:

[in]	handle	The VPN interface handle
[in]	blocking	The blocking mode flag; True = BLOCKING, False = NON_BLOCKING (Default : BLOCKING)

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	Failed to set the blocking flags
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

Before calling this function, VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_set_local_ip_address	(	vpnsvc_h	handle,
		const char *	local_ip
	)

Sets the VPN client IP address.

Since :

3.0

Remarks:

The local address should be set before enabling VPN interface.
vpnsvc_update_settings() should be invoked after setting local IP address.

Parameters:

[in]	handle	The VPN interface handle
[in]	local_ip	The local (VPN client) IP address (IPv4 only)

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_set_mtu	(	vpnsvc_h	handle,
		int	mtu
	)

Sets the MTU of the VPN interface.

Since :

3.0

Remarks:

vpnsvc_update_settings() should be invoked after setting MTU.

Parameters:

[in]	handle	The VPN interface handle
[in]	mtu	The MTU (Maximum Transmission Unit) value to be set for VPN interface. Default MTU size is 1500.

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

Before calling this function, VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_set_remote_ip_address	(	vpnsvc_h	handle,
		const char *	remote_ip
	)

Sets the VPN server IP address.

Since :

3.0

Remarks:

The remote address should be set before enabling VPN interface.
vpnsvc_update_settings() should be invoked after setting remote IP address.

Parameters:

[in]	handle	The VPN interface handle
[in]	remote_ip	The remote (VPN server) IP address (IPv4 only)

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IO_ERROR	I/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_set_session	(	vpnsvc_h	handle,
		const char *	session
	)

Sets the session name for the VPN. (It will be displayed in system-managed dialogs and notifications.)

Since :

3.0

Parameters:

[in]	handle	The VPN interface handle
[in]	session	The Session Name

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

Before calling this function, VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_unblock_networks

(

vpnsvc_h

handle

)

Removes any restrictions imposed by vpnsvc_block_networks().

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet

Parameters:

[in]

handle

The VPN interface handle

Returns:

0 on success. otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IPC_FAILED	Cannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIED	Permission Denied
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

int vpnsvc_update_settings

(

vpnsvc_h

handle

)

Updates settings (Local IP / Remote IP / MTU).

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/vpnservice

Parameters:

[in]

handle

The VPN interface handle

Returns:

0 on success. Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_IPC_FAILED	Cannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIED	Permission Denied
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()

int vpnsvc_write	(	vpnsvc_h	handle,
		const char *	data,
		size_t	size
	)

Writes the data supplied into the VPN interface.

Since :

3.0

Parameters:

[in]	handle	The VPN interface handle
[in]	data	Data writing to VPN interface
[in]	size	The size of data

Returns:

On success, the number of bytes written is returned (zero indicates nothing was written). Otherwise, a negative error value.

Return values:

VPNSVC_ERROR_NONE	Success
VPNSVC_ERROR_INVALID_PARAMETER	Invalid parameter
VPNSVC_ERROR_NOT_SUPPORTED	Not Supported
In	case of negative error, please refer to standard posix write API's error code.

Precondition:

The VPN interface should be initialized already.

See also:

vpnsvc_init()