Docstring Updates for applyTransportModeTransform
-Add anotations to usages of PolicyDirection for apply...() methods. -Update the comments on DIRECTION_IN and DIRECTION_OUT to better reflect their current usage. -Add a better explanation to the rekey procedure doc. -Remove disused createTunnelInterface() stub. Bug: 73751066 Test: make docs Merged-In: I9f2ec864466148a18899f1e952c74a525902ccbc Change-Id: I9f2ec864466148a18899f1e952c74a525902ccbc (cherry picked from commit f4cdf25a906d0f52ffd76508d660b843b13b3ff8)
This commit is contained in:
Nathan Harold
@@ -58,14 +58,18 @@ public final class IpSecManager {
|
||||
private static final String TAG = "IpSecManager";
|
||||
|
||||
/**
|
||||
* For direction-specific attributes of an {@link IpSecTransform}, indicates that an attribute
|
||||
* applies to traffic towards the host.
|
||||
* Used when applying a transform to direct traffic through an {@link IpSecTransform}
|
||||
* towards the host.
|
||||
*
|
||||
* <p>See {@link #applyTransportModeTransform(Socket, int, IpSecTransform)}.
|
||||
*/
|
||||
public static final int DIRECTION_IN = 0;
|
||||
|
||||
/**
|
||||
* For direction-specific attributes of an {@link IpSecTransform}, indicates that an attribute
|
||||
* applies to traffic from the host.
|
||||
* Used when applying a transform to direct traffic through an {@link IpSecTransform}
|
||||
* away from the host.
|
||||
*
|
||||
* <p>See {@link #applyTransportModeTransform(Socket, int, IpSecTransform)}.
|
||||
*/
|
||||
public static final int DIRECTION_OUT = 1;
|
||||
|
||||
@@ -301,19 +305,21 @@ public final class IpSecManager {
|
||||
*
|
||||
* <h4>Rekey Procedure</h4>
|
||||
*
|
||||
* <p>When applying a new tranform to a socket, the previous transform will be removed. However,
|
||||
* inbound traffic on the old transform will continue to be decrypted until that transform is
|
||||
* deallocated by calling {@link IpSecTransform#close()}. This overlap allows rekey procedures
|
||||
* where both transforms are valid until both endpoints are using the new transform and all
|
||||
* in-flight packets have been received.
|
||||
* <p>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 {@link 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.
|
||||
*
|
||||
* @param socket a stream socket
|
||||
* @param direction the policy direction either {@link #DIRECTION_IN} or {@link #DIRECTION_OUT}
|
||||
* @param direction the direction in which the transform should be applied
|
||||
* @param transform a transport mode {@code IpSecTransform}
|
||||
* @throws IOException indicating that the transform could not be applied
|
||||
*/
|
||||
public void applyTransportModeTransform(
|
||||
Socket socket, int direction, IpSecTransform transform)
|
||||
Socket socket, @PolicyDirection int direction, IpSecTransform transform)
|
||||
throws IOException {
|
||||
applyTransportModeTransform(socket.getFileDescriptor$(), direction, transform);
|
||||
}
|
||||
@@ -334,19 +340,22 @@ public final class IpSecManager {
|
||||
*
|
||||
* <h4>Rekey Procedure</h4>
|
||||
*
|
||||
* <p>When applying a new tranform to a socket, the previous transform will be removed. However,
|
||||
* inbound traffic on the old transform will continue to be decrypted until that transform is
|
||||
* deallocated by calling {@link IpSecTransform#close()}. This overlap allows rekey procedures
|
||||
* where both transforms are valid until both endpoints are using the new transform and all
|
||||
* in-flight packets have been received.
|
||||
* <p>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 {@link 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.
|
||||
*
|
||||
* @param socket a datagram socket
|
||||
* @param direction the policy direction either DIRECTION_IN or DIRECTION_OUT
|
||||
* @param direction the direction in which the transform should be applied
|
||||
* @param transform a transport mode {@code IpSecTransform}
|
||||
* @throws IOException indicating that the transform could not be applied
|
||||
*/
|
||||
public void applyTransportModeTransform(
|
||||
DatagramSocket socket, int direction, IpSecTransform transform) throws IOException {
|
||||
DatagramSocket socket, @PolicyDirection int direction, IpSecTransform transform)
|
||||
throws IOException {
|
||||
applyTransportModeTransform(socket.getFileDescriptor$(), direction, transform);
|
||||
}
|
||||
|
||||
@@ -366,19 +375,21 @@ public final class IpSecManager {
|
||||
*
|
||||
* <h4>Rekey Procedure</h4>
|
||||
*
|
||||
* <p>When applying a new tranform to a socket, the previous transform will be removed. However,
|
||||
* inbound traffic on the old transform will continue to be decrypted until that transform is
|
||||
* deallocated by calling {@link IpSecTransform#close()}. This overlap allows rekey procedures
|
||||
* where both transforms are valid until both endpoints are using the new transform and all
|
||||
* in-flight packets have been received.
|
||||
* <p>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 {@link 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.
|
||||
*
|
||||
* @param socket a socket file descriptor
|
||||
* @param direction the policy direction either DIRECTION_IN or DIRECTION_OUT
|
||||
* @param direction the direction in which the transform should be applied
|
||||
* @param transform a transport mode {@code IpSecTransform}
|
||||
* @throws IOException indicating that the transform could not be applied
|
||||
*/
|
||||
public void applyTransportModeTransform(
|
||||
FileDescriptor socket, int direction, IpSecTransform transform)
|
||||
FileDescriptor socket, @PolicyDirection int direction, IpSecTransform transform)
|
||||
throws IOException {
|
||||
// We dup() the FileDescriptor here because if we don't, then the ParcelFileDescriptor()
|
||||
// constructor takes control and closes the user's FD when we exit the method.
|
||||
@@ -389,21 +400,6 @@ public final class IpSecManager {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply an active Tunnel Mode IPsec Transform to a network, which will tunnel all traffic to
|
||||
* and from that network's interface with IPsec (applies an outer IP header and IPsec Header to
|
||||
* all traffic, and expects an additional IP header and IPsec Header on all inbound traffic).
|
||||
* Applications should probably not use this API directly. Instead, they should use {@link
|
||||
* VpnService} to provide VPN capability in a more generic fashion.
|
||||
*
|
||||
* <p>TODO: Update javadoc for tunnel mode APIs at the same time the APIs are re-worked.
|
||||
*
|
||||
* @param net a {@link Network} that will be tunneled via IP Sec.
|
||||
* @param transform an {@link IpSecTransform}, which must be an active Tunnel Mode transform.
|
||||
* @hide
|
||||
*/
|
||||
public void applyTunnelModeTransform(Network net, IpSecTransform transform) {}
|
||||
|
||||
/**
|
||||
* Remove an IPsec transform from a stream socket.
|
||||
*
|
||||
@@ -770,7 +766,12 @@ public final class IpSecManager {
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply a transform to the IpSecTunnelInterface
|
||||
* Apply an active Tunnel Mode IPsec Transform to a {@link IpSecTunnelInterface}, which will
|
||||
* tunnel all traffic for the given direction through the underlying network's interface with
|
||||
* IPsec (applies an outer IP header and IPsec Header to all traffic, and expects an additional
|
||||
* IP header and IPsec Header on all inbound traffic).
|
||||
* <p>Applications should probably not use this API directly.
|
||||
*
|
||||
*
|
||||
* @param tunnel The {@link IpSecManager#IpSecTunnelInterface} that will use the supplied
|
||||
* transform.
|
||||
@@ -783,8 +784,8 @@ public final class IpSecManager {
|
||||
*/
|
||||
@SystemApi
|
||||
@RequiresPermission(android.Manifest.permission.NETWORK_STACK)
|
||||
public void applyTunnelModeTransform(IpSecTunnelInterface tunnel, int direction,
|
||||
IpSecTransform transform) throws IOException {
|
||||
public void applyTunnelModeTransform(IpSecTunnelInterface tunnel,
|
||||
@PolicyDirection int direction, IpSecTransform transform) throws IOException {
|
||||
try {
|
||||
mService.applyTunnelModeTransform(
|
||||
tunnel.getResourceId(), direction, transform.getResourceId());
|
||||
@@ -792,6 +793,7 @@ public final class IpSecManager {
|
||||
throw e.rethrowFromSystemServer();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Construct an instance of IpSecManager within an application context.
|
||||
*
|
||||
|
||||
Reference in New Issue
Block a user