IpSecManager
public
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 an IPsec VPN should use VpnManager
and Ikev2VpnProfile
.
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 |
int |
DIRECTION_OUT
Used when applying a transform to direct traffic through an |
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
public static final int DIRECTION_IN
Used when applying a transform to direct traffic through an IpSecTransform
towards the host.
See applyTransportModeTransform(java.net.Socket, int, android.net.IpSecTransform)
.
Constant Value: 0 (0x00000000)
DIRECTION_OUT
public static final int DIRECTION_OUT
Used when applying a transform to direct traffic through an IpSecTransform
away from the host.
See applyTransportModeTransform(java.net.Socket, int, android.net.IpSecTransform)
.
Constant Value: 1 (0x00000001)
Public methods
allocateSecurityParameterIndex
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 cannot be null . |
Returns | |
---|---|
IpSecManager.SecurityParameterIndex |
the reserved SecurityParameterIndex
This value cannot be null . |
Throws | |
---|---|
IpSecManager.ResourceUnavailableException |
indicating that too many SPIs are currently allocated for this user |
allocateSecurityParameterIndex
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 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 | |
---|---|
IpSecManager.SecurityParameterIndex |
the reserved SecurityParameterIndex
This value cannot be null . |
Throws | |
---|---|
IpSecManager.ResourceUnavailableException |
indicating that too many SPIs are currently allocated for this user |
IpSecManager.SpiUnavailableException |
indicating that the requested SPI could not be reserved |
applyTransportModeTransform
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 cannot be null . |
direction |
int : the direction in which the transform should be applied
Value is DIRECTION_IN , or DIRECTION_OUT |
transform |
IpSecTransform : a transport mode IpSecTransform
This value cannot be null . |
Throws | |
---|---|
IOException |
indicating that the transform could not be applied |
applyTransportModeTransform
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 cannot be null . |
direction |
int : the direction in which the transform should be applied
Value is DIRECTION_IN , or DIRECTION_OUT |
transform |
IpSecTransform : a transport mode IpSecTransform
This value cannot be null . |
Throws | |
---|---|
IOException |
indicating that the transform could not be applied |
applyTransportModeTransform
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 cannot be null . |
direction |
int : the direction in which the transform should be applied
Value is DIRECTION_IN , or DIRECTION_OUT |
transform |
IpSecTransform : a transport mode IpSecTransform
This value cannot be null . |
Throws | |
---|---|
IOException |
indicating that the transform could not be applied |
openUdpEncapsulationSocket
public IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket (int port)
Open a socket for UDP encapsulation and bind to the given port.
See 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 cannot 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
public IpSecManager.UdpEncapsulationSocket openUdpEncapsulationSocket ()
Open a socket for UDP encapsulation.
See 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 cannot 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
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 cannot be null . |
Throws | |
---|---|
IOException |
indicating that the transform could not be removed from the socket |
removeTransportModeTransforms
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 cannot be null . |
Throws | |
---|---|
IOException |
indicating that the transform could not be removed from the socket |
removeTransportModeTransforms
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 cannot be null . |
Throws | |
---|---|
IOException |
indicating that the transform could not be removed from the socket |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-04 UTC.