lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

IpSecManager

public final class IpSecManager
extends Object

java.lang.Object
   ↳ android.net.IpSecManager


This class contains methods for managing IPsec sessions. Once configured, the kernel will apply confidentiality (encryption) and integrity (authentication) to IP traffic.

Note that not all aspects of IPsec are permitted by this API. Applications may create transport mode security associations and apply them to individual sockets. Applications looking to create a VPN should use VpnService.

Instances of this class must be obtained using Context.getSystemService(Class) with the argument IpSecManager.class or Context.getSystemService(String) with the argument Context.IPSEC_SERVICE.

Summary

Nested classes

class IpSecManager.ResourceUnavailableException

Thrown to indicate that an IPsec resource is unavailable. 

class IpSecManager.SecurityParameterIndex

This class represents a reserved SPI. 

class IpSecManager.SpiUnavailableException

Thrown to indicate that a requested SPI is in use. 

class IpSecManager.UdpEncapsulationSocket

This class provides access to a UDP encapsulation Socket. 

Constants

int DIRECTION_IN

Used when applying a transform to direct traffic through an IpSecTransform towards the host.

int DIRECTION_OUT

Used when applying a transform to direct traffic through an IpSecTransform away from the host.

Public methods

IpSecManager.SecurityParameterIndex allocateSecurityParameterIndex(InetAddress destinationAddress)

Reserve a random SPI for traffic bound to or from the specified destination address.

IpSecManager.SecurityParameterIndex allocateSecurityParameterIndex(InetAddress destinationAddress, int requestedSpi)

Reserve the requested SPI for traffic bound to or from the specified destination address.

void applyTransportModeTransform(DatagramSocket socket, int direction, IpSecTransform transform)

Apply an IPsec transform to a datagram socket.

void applyTransportModeTransform(FileDescriptor socket, int direction, IpSecTransform transform)

Apply an IPsec transform to a socket.

void applyTransportModeTransform(Socket socket, int direction, IpSecTransform transform)

Apply an IPsec transform to a stream socket.

IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket(int port)

Open a socket for UDP encapsulation and bind to the given port.

IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket()

Open a socket for UDP encapsulation.

void removeTransportModeTransforms(FileDescriptor socket)

Remove an IPsec transform from a socket.

void removeTransportModeTransforms(DatagramSocket socket)

Remove an IPsec transform from a datagram socket.

void removeTransportModeTransforms(Socket socket)

Remove an IPsec transform from a stream socket.

Inherited methods

Constants

DIRECTION_IN

added in API level 28
public static final int DIRECTION_IN

Used when applying a transform to direct traffic through an IpSecTransform towards the host.

See applyTransportModeTransform(Socket, int, IpSecTransform).

Constant Value: 0 (0x00000000)

DIRECTION_OUT

added in API level 28
public static final int DIRECTION_OUT

Used when applying a transform to direct traffic through an IpSecTransform away from the host.

See applyTransportModeTransform(Socket, int, IpSecTransform).

Constant Value: 1 (0x00000001)

Public methods

allocateSecurityParameterIndex

added in API level 28
public IpSecManager.SecurityParameterIndex allocateSecurityParameterIndex (InetAddress destinationAddress)

Reserve a random SPI for traffic bound to or from the specified destination address.

If successful, this SPI is guaranteed available until released by a call to IpSecManager.SecurityParameterIndex.close().

Parameters
destinationAddress InetAddress: the destination address for traffic bearing the requested SPI. For inbound traffic, the destination should be an address currently assigned on-device.

This value must never be null.

Returns
IpSecManager.SecurityParameterIndex the reserved SecurityParameterIndex

This value will never be null.

Throws
#ResourceUnavailableException} indicating that too many SPIs are currently allocated for this user
IpSecManager.ResourceUnavailableException

allocateSecurityParameterIndex

added in API level 28
public IpSecManager.SecurityParameterIndex allocateSecurityParameterIndex (InetAddress destinationAddress, 
                int requestedSpi)

Reserve the requested SPI for traffic bound to or from the specified destination address.

If successful, this SPI is guaranteed available until released by a call to IpSecManager.SecurityParameterIndex.close().

Parameters
destinationAddress InetAddress: the destination address for traffic bearing the requested SPI. For inbound traffic, the destination should be an address currently assigned on-device.

This value must never be null.

requestedSpi int: the requested SPI. The range 1-255 is reserved and may not be used. See RFC 4303 Section 2.1.

Returns
IpSecManager.SecurityParameterIndex the reserved SecurityParameterIndex

This value will never be null.

Throws
#ResourceUnavailableException} indicating that too many SPIs are currently allocated for this user
#SpiUnavailableException} indicating that the requested SPI could not be reserved
IpSecManager.SpiUnavailableException
IpSecManager.ResourceUnavailableException

applyTransportModeTransform

added in API level 28
public void applyTransportModeTransform (DatagramSocket socket, 
                int direction, 
                IpSecTransform transform)

Apply an IPsec transform to a datagram socket.

This applies transport mode encapsulation to the given socket. Once applied, I/O on the socket will be encapsulated according to the parameters of the IpSecTransform. When the transform is removed from the socket by calling removeTransportModeTransforms(FileDescriptor), unprotected traffic can resume on that socket.

For security reasons, the destination address of any traffic on the socket must match the remote InetAddress of the IpSecTransform. Attempts to send traffic to any other IP address will result in an IOException. In addition, reads and writes on the socket will throw IOException if the user deactivates the transform (by calling IpSecTransform.close()) without calling removeTransportModeTransforms(FileDescriptor).

Rekey Procedure

When applying a new tranform to a socket in the outbound direction, the previous transform will be removed and the new transform will take effect immediately, sending all traffic on the new transform; however, when applying a transform in the inbound direction, traffic on the old transform will continue to be decrypted and delivered until that transform is deallocated by calling IpSecTransform.close(). This overlap allows lossless rekey procedures where both transforms are valid until both endpoints are using the new transform and all in-flight packets have been received.

Parameters
socket DatagramSocket: a datagram socket

This value must never be null.

direction int: the direction in which the transform should be applied

transform IpSecTransform: a transport mode IpSecTransform

This value must never be null.

Throws
IOException indicating that the transform could not be applied

applyTransportModeTransform

added in API level 28
public void applyTransportModeTransform (FileDescriptor socket, 
                int direction, 
                IpSecTransform transform)

Apply an IPsec transform to a socket.

This applies transport mode encapsulation to the given socket. Once applied, I/O on the socket will be encapsulated according to the parameters of the IpSecTransform. When the transform is removed from the socket by calling removeTransportModeTransforms(FileDescriptor), unprotected traffic can resume on that socket.

For security reasons, the destination address of any traffic on the socket must match the remote InetAddress of the IpSecTransform. Attempts to send traffic to any other IP address will result in an IOException. In addition, reads and writes on the socket will throw IOException if the user deactivates the transform (by calling IpSecTransform.close()) without calling removeTransportModeTransforms(FileDescriptor).

Note that when applied to TCP sockets, calling IpSecTransform.close() on an applied transform before completion of graceful shutdown may result in the shutdown sequence failing to complete. As such, applications requiring graceful shutdown MUST close the socket prior to deactivating the applied transform. Socket closure may be performed asynchronously (in batches), so the returning of a close function does not guarantee shutdown of a socket. Setting an SO_LINGER timeout results in socket closure being performed synchronously, and is sufficient to ensure shutdown. Specifically, if the transform is deactivated (by calling IpSecTransform.close()), prior to the socket being closed, the standard [FIN - FIN/ACK - ACK], or the reset [RST] packets are dropped due to the lack of a valid Transform. Similarly, if a socket without the SO_LINGER option set is closed, the delayed/batched FIN packets may be dropped.

Rekey Procedure

When applying a new tranform to a socket in the outbound direction, the previous transform will be removed and the new transform will take effect immediately, sending all traffic on the new transform; however, when applying a transform in the inbound direction, traffic on the old transform will continue to be decrypted and delivered until that transform is deallocated by calling IpSecTransform.close(). This overlap allows lossless rekey procedures where both transforms are valid until both endpoints are using the new transform and all in-flight packets have been received.

Parameters
socket FileDescriptor: a socket file descriptor

This value must never be null.

direction int: the direction in which the transform should be applied

transform IpSecTransform: a transport mode IpSecTransform

This value must never be null.

Throws
IOException indicating that the transform could not be applied

applyTransportModeTransform

added in API level 28
public void applyTransportModeTransform (Socket socket, 
                int direction, 
                IpSecTransform transform)

Apply an IPsec transform to a stream socket.

This applies transport mode encapsulation to the given socket. Once applied, I/O on the socket will be encapsulated according to the parameters of the IpSecTransform. When the transform is removed from the socket by calling removeTransportModeTransforms(FileDescriptor), unprotected traffic can resume on that socket.

For security reasons, the destination address of any traffic on the socket must match the remote InetAddress of the IpSecTransform. Attempts to send traffic to any other IP address will result in an IOException. In addition, reads and writes on the socket will throw IOException if the user deactivates the transform (by calling IpSecTransform.close()) without calling removeTransportModeTransforms(FileDescriptor).

Note that when applied to TCP sockets, calling IpSecTransform.close() on an applied transform before completion of graceful shutdown may result in the shutdown sequence failing to complete. As such, applications requiring graceful shutdown MUST close the socket prior to deactivating the applied transform. Socket closure may be performed asynchronously (in batches), so the returning of a close function does not guarantee shutdown of a socket. Setting an SO_LINGER timeout results in socket closure being performed synchronously, and is sufficient to ensure shutdown. Specifically, if the transform is deactivated (by calling IpSecTransform.close()), prior to the socket being closed, the standard [FIN - FIN/ACK - ACK], or the reset [RST] packets are dropped due to the lack of a valid Transform. Similarly, if a socket without the SO_LINGER option set is closed, the delayed/batched FIN packets may be dropped.

Rekey Procedure

When applying a new tranform to a socket in the outbound direction, the previous transform will be removed and the new transform will take effect immediately, sending all traffic on the new transform; however, when applying a transform in the inbound direction, traffic on the old transform will continue to be decrypted and delivered until that transform is deallocated by calling IpSecTransform.close(). This overlap allows lossless rekey procedures where both transforms are valid until both endpoints are using the new transform and all in-flight packets have been received.

Parameters
socket Socket: a stream socket

This value must never be null.

direction int: the direction in which the transform should be applied

transform IpSecTransform: a transport mode IpSecTransform

This value must never be null.

Throws
IOException indicating that the transform could not be applied

openUdpEncapsulationSocket

added in API level 28
public IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket (int port)

Open a socket for UDP encapsulation and bind to the given port.

See IpSecManager.UdpEncapsulationSocket for the proper way to close the returned socket.

Parameters
port int: a local UDP port

Returns
IpSecManager.UdpEncapsulationSocket a socket that is bound to the given port

This value will never be null.

Throws
IOException indicating that the socket could not be opened or bound
IpSecManager.ResourceUnavailableException indicating that too many encapsulation sockets are open

openUdpEncapsulationSocket

added in API level 28
public IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket ()

Open a socket for UDP encapsulation.

See IpSecManager.UdpEncapsulationSocket for the proper way to close the returned socket.

The local port of the returned socket can be obtained by calling IpSecManager.UdpEncapsulationSocket.getPort().

Returns
IpSecManager.UdpEncapsulationSocket a socket that is bound to a local port

This value will never be null.

Throws
IOException indicating that the socket could not be opened or bound
IpSecManager.ResourceUnavailableException indicating that too many encapsulation sockets are open

removeTransportModeTransforms

added in API level 28
public void removeTransportModeTransforms (FileDescriptor socket)

Remove an IPsec transform from a socket.

Once removed, traffic on the socket will not be encrypted. Removing transforms from a socket allows the socket to be reused for communication in the clear.

If an IpSecTransform object applied to this socket was deallocated by calling IpSecTransform.close(), then communication on the socket will fail until this method is called.

Parameters
socket FileDescriptor: a socket that previously had a transform applied to it

This value must never be null.

Throws
IOException indicating that the transform could not be removed from the socket

removeTransportModeTransforms

added in API level 28
public void removeTransportModeTransforms (DatagramSocket socket)

Remove an IPsec transform from a datagram socket.

Once removed, traffic on the socket will not be encrypted. Removing transforms from a socket allows the socket to be reused for communication in the clear.

If an IpSecTransform object applied to this socket was deallocated by calling IpSecTransform.close(), then communication on the socket will fail until this method is called.

Parameters
socket DatagramSocket: a socket that previously had a transform applied to it

This value must never be null.

Throws
IOException indicating that the transform could not be removed from the socket

removeTransportModeTransforms

added in API level 28
public void removeTransportModeTransforms (Socket socket)

Remove an IPsec transform from a stream socket.

Once removed, traffic on the socket will not be encrypted. Removing transforms from a socket allows the socket to be reused for communication in the clear.

If an IpSecTransform object applied to this socket was deallocated by calling IpSecTransform.close(), then communication on the socket will fail until this method is called.

Parameters
socket Socket: a socket that previously had a transform applied to it

This value must never be null.

Throws
IOException indicating that the transform could not be removed from the socket