Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/android/net/IpSecManager#nestedclasses) \| [Constants](https://developer.android.com/reference/android/net/IpSecManager#constants) \| [Methods](https://developer.android.com/reference/android/net/IpSecManager#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/net/IpSecManager#inhmethods)
# IpSecManager
*** ** * ** ***
` public class IpSecManager `
` extends https://developer.android.com/reference/java/lang/Object ` ` `
|---|---|
| [java.lang.Object](https://developer.android.com/reference/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 an IPsec VPN should use `https://developer.android.com/reference/android/net/VpnManager` and `https://developer.android.com/reference/android/net/Ikev2VpnProfile`.
**See also:**
- [RFC 4301, Security Architecture for the Internet Protocol](https://tools.ietf.org/html/rfc4301)
## Summary
| ### Nested classes ||
|---|---|
| ` class` | `https://developer.android.com/reference/android/net/IpSecManager.ResourceUnavailableException` Thrown to indicate that an IPsec resource is unavailable. |
| ` class` | `https://developer.android.com/reference/android/net/IpSecManager.SecurityParameterIndex` This class represents a reserved SPI. |
| ` class` | `https://developer.android.com/reference/android/net/IpSecManager.SpiUnavailableException` Thrown to indicate that a requested SPI is in use. |
| ` class` | `https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket` This class provides access to a UDP encapsulation Socket. |
| ### Constants ||
|---|---|
| `int` | `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_IN` Used when applying a transform to direct traffic through an `https://developer.android.com/reference/android/net/IpSecTransform` towards the host. |
| `int` | `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_OUT` Used when applying a transform to direct traffic through an `https://developer.android.com/reference/android/net/IpSecTransform` away from the host. |
| ### Public methods ||
|---|---|
| ` https://developer.android.com/reference/android/net/IpSecManager.SecurityParameterIndex` | ` https://developer.android.com/reference/android/net/IpSecManager#allocateSecurityParameterIndex(java.net.InetAddress)(https://developer.android.com/reference/java/net/InetAddress destinationAddress) ` Reserve a random SPI for traffic bound to or from the specified destination address. |
| ` https://developer.android.com/reference/android/net/IpSecManager.SecurityParameterIndex` | ` https://developer.android.com/reference/android/net/IpSecManager#allocateSecurityParameterIndex(java.net.InetAddress,%20int)(https://developer.android.com/reference/java/net/InetAddress destinationAddress, int requestedSpi) ` Reserve the requested SPI for traffic bound to or from the specified destination address. |
| ` void` | ` https://developer.android.com/reference/android/net/IpSecManager#applyTransportModeTransform(java.io.FileDescriptor,%20int,%20android.net.IpSecTransform)(https://developer.android.com/reference/java/io/FileDescriptor socket, int direction, https://developer.android.com/reference/android/net/IpSecTransform transform) ` Apply an IPsec transform to a socket. |
| ` void` | ` https://developer.android.com/reference/android/net/IpSecManager#applyTransportModeTransform(java.net.DatagramSocket,%20int,%20android.net.IpSecTransform)(https://developer.android.com/reference/java/net/DatagramSocket socket, int direction, https://developer.android.com/reference/android/net/IpSecTransform transform) ` Apply an IPsec transform to a datagram socket. |
| ` void` | ` https://developer.android.com/reference/android/net/IpSecManager#applyTransportModeTransform(java.net.Socket,%20int,%20android.net.IpSecTransform)(https://developer.android.com/reference/java/net/Socket socket, int direction, https://developer.android.com/reference/android/net/IpSecTransform transform) ` Apply an IPsec transform to a stream socket. |
| ` https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket` | ` https://developer.android.com/reference/android/net/IpSecManager#openUdpEncapsulationSocket(int)(int port) ` Open a socket for UDP encapsulation and bind to the given port. |
| ` https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket` | ` https://developer.android.com/reference/android/net/IpSecManager#openUdpEncapsulationSocket()() ` Open a socket for UDP encapsulation. |
| ` void` | ` https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.io.FileDescriptor)(https://developer.android.com/reference/java/io/FileDescriptor socket) ` Remove an IPsec transform from a socket. |
| ` void` | ` https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.net.DatagramSocket)(https://developer.android.com/reference/java/net/DatagramSocket socket) ` Remove an IPsec transform from a datagram socket. |
| ` void` | ` https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.net.Socket)(https://developer.android.com/reference/java/net/Socket socket) ` Remove an IPsec transform from a stream socket. |
### Inherited methods
From class ` https://developer.android.com/reference/java/lang/Object ` ` https://developer.android.com/reference/java/lang/Object` ` https://developer.android.com/reference/java/lang/Object#clone()() `
Creates and returns a copy of this object.
` boolean` ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) `
Indicates whether some other object is "equal to" this one.
` void` ` https://developer.android.com/reference/java/lang/Object#finalize()() `
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
` final https://developer.android.com/reference/java/lang/Class` ` https://developer.android.com/reference/java/lang/Object#getClass()() `
Returns the runtime class of this `Object`.
` int` ` https://developer.android.com/reference/java/lang/Object#hashCode()() `
Returns a hash code value for the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#notify()() `
Wakes up a single thread that is waiting on this object's monitor.
` final void` ` https://developer.android.com/reference/java/lang/Object#notifyAll()() `
Wakes up all threads that are waiting on this object's monitor.
` https://developer.android.com/reference/java/lang/String` ` https://developer.android.com/reference/java/lang/Object#toString()() `
Returns a string representation of the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait()() `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*.
## Constants
### DIRECTION_IN
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static final int DIRECTION_IN
```
Used when applying a transform to direct traffic through an `https://developer.android.com/reference/android/net/IpSecTransform` towards the host.
See `https://developer.android.com/reference/android/net/IpSecManager#applyTransportModeTransform(java.net.Socket,%20int,%20android.net.IpSecTransform)`.
Constant Value: 0 (0x00000000)
### DIRECTION_OUT
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static final int DIRECTION_OUT
```
Used when applying a transform to direct traffic through an `https://developer.android.com/reference/android/net/IpSecTransform` away from the host.
See `https://developer.android.com/reference/android/net/IpSecManager#applyTransportModeTransform(java.net.Socket,%20int,%20android.net.IpSecTransform)`.
Constant Value: 1 (0x00000001)
## Public methods
### allocateSecurityParameterIndex
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/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 cannot be `null`.
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.SecurityParameterIndex` | the reserved SecurityParameterIndex. This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.ResourceUnavailableException` | indicating that too many SPIs are currently allocated for this user |
### allocateSecurityParameterIndex
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/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 cannot 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 ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.SecurityParameterIndex` | the reserved SecurityParameterIndex. This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.ResourceUnavailableException` | indicating that too many SPIs are currently allocated for this user |
| `https://developer.android.com/reference/android/net/IpSecManager.SpiUnavailableException` | indicating that the requested SPI could not be reserved |
### applyTransportModeTransform
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.io.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 `https://developer.android.com/reference/android/net/IpSecTransform#close()`) without calling `https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.io.FileDescriptor)`.
Note that when applied to TCP sockets, calling `https://developer.android.com/reference/android/net/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 `https://developer.android.com/reference/android/net/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 `https://developer.android.com/reference/android/net/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 cannot be `null`.
|
| `direction` | `int`: the direction in which the transform should be applied. Value is one of the following: - `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_IN` - `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_OUT` |
| `transform` | `IpSecTransform`: a transport mode `IpSecTransform` This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/io/IOException` | indicating that the transform could not be applied |
### applyTransportModeTransform
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.io.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 `https://developer.android.com/reference/android/net/IpSecTransform#close()`) without calling `https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.io.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 `https://developer.android.com/reference/android/net/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 cannot be `null`.
|
| `direction` | `int`: the direction in which the transform should be applied. Value is one of the following: - `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_IN` - `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_OUT` |
| `transform` | `IpSecTransform`: a transport mode `IpSecTransform` This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/io/IOException` | indicating that the transform could not be applied |
### applyTransportModeTransform
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.io.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 `https://developer.android.com/reference/android/net/IpSecTransform#close()`) without calling `https://developer.android.com/reference/android/net/IpSecManager#removeTransportModeTransforms(java.io.FileDescriptor)`.
Note that when applied to TCP sockets, calling `https://developer.android.com/reference/android/net/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 `https://developer.android.com/reference/android/net/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 `https://developer.android.com/reference/android/net/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 cannot be `null`.
|
| `direction` | `int`: the direction in which the transform should be applied. Value is one of the following: - `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_IN` - `https://developer.android.com/reference/android/net/IpSecManager#DIRECTION_OUT` |
| `transform` | `IpSecTransform`: a transport mode `IpSecTransform` This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/io/IOException` | indicating that the transform could not be applied |
### openUdpEncapsulationSocket
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket (int port)
```
Open a socket for UDP encapsulation and bind to the given port.
See `https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket` for the proper way to close the returned socket.
| Parameters ||
|---|---|
| `port` | `int`: a local UDP port
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket` | a socket that is bound to the given port. This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.ResourceUnavailableException` | indicating that too many encapsulation sockets are open |
| `https://developer.android.com/reference/java/io/IOException` | indicating that the socket could not be opened or bound |
### openUdpEncapsulationSocket
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket ()
```
Open a socket for UDP encapsulation.
See `https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket` for the proper way to close the returned socket.
The local port of the returned socket can be obtained by calling `https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket#getPort()`.
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.UdpEncapsulationSocket` | a socket that is bound to a local port. This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/android/net/IpSecManager.ResourceUnavailableException` | indicating that too many encapsulation sockets are open |
| `https://developer.android.com/reference/java/io/IOException` | indicating that the socket could not be opened or bound |
### removeTransportModeTransforms
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/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 cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/io/IOException` | indicating that the transform could not be removed from the socket |
### removeTransportModeTransforms
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/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 cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/io/IOException` | indicating that the transform could not be removed from the socket |
### removeTransportModeTransforms
Added in [API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 `https://developer.android.com/reference/android/net/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 cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/io/IOException` | indicating that the transform could not be removed from the socket |