Tizen Native API  5.0
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

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]handleThe VPN interface handle
[in]dns_serverThe DNS server address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]route_addressDestination address of the routes (IPv4 only)
[in]prefixThe 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_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]routes_dest_vpn_addrDestination address of the routes, the list of allowing networks over VPN interface (e.g., VPN interface such as tun0, etc).
[in]routes_vpn_prefixThe prefix of VPN interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32).
[in]num_allow_routes_vpnThe number of allowing networks over VPN interface
[in]routes_dest_orig_addrDestination 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_prefixThe prefix of Original interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32).
[in]num_allow_routes_origThe number of allowing networks over the original interface
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[out]iface_fdThe vpn interface fd
Returns:
The fd value of VPN interface. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
int vpnsvc_get_iface_index ( vpnsvc_h  handle,
int *  iface_index 
)

Gets the index of VPN interface.

Since :
3.0
Parameters:
[in]handleThe VPN interface handle
[out]iface_indexThe VPN interface index
Returns:
The index of the VPN interface. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[out]iface_nameThe name of VPN interface name
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[out]sessionThe Session Name returned
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot 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_nameThe VPN interface name
[out]handleThe VPN interface handle
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]socket_fdThe opened socket file descriptor
[in]iface_nameThe 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_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]timeout_msThe value of timeout (milliseconds)
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_TIMEOUTTimeout (no answer in timeout_ms)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]dns_serverThe DNS server address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]route_addressDestination address of the routes (IPv4 only)
[in]prefixThe 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_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]blockingThe blocking mode flag; True = BLOCKING, False = NON_BLOCKING (Default : BLOCKING)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORFailed to set the blocking flags
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]local_ipThe local (VPN client) IP address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]mtuThe 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_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]remote_ipThe remote (VPN server) IP address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]sessionThe Session Name
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()

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]handleThe VPN interface handle
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported

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

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
Parameters:
[in]handleThe VPN interface handle
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot 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]handleThe VPN interface handle
[in]dataData writing to VPN interface
[in]sizeThe 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_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Incase 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()