Merge "Use consistent naming for allocating SPI." am: 816f0ebaab

am: 4753ed4b1b

Change-Id: Ib5d89044313341790b1ee9271642072ddce181af

core/java/android/net/IIpSecService.aidl

@@ -30,7 +30,7 @@ import android.os.ParcelFileDescriptor;
  */
 interface IIpSecService
 {
-    IpSecSpiResponse reserveSecurityParameterIndex(
+    IpSecSpiResponse allocateSecurityParameterIndex(
             int direction, in String remoteAddress, int requestedSpi, in IBinder binder);
 
     void releaseSecurityParameterIndex(int resourceId);

core/java/android/net/IpSecManager.java

@@ -46,7 +46,7 @@ import java.net.Socket;
  * to create a VPN should use {@link VpnService}.
  *
  * @see <a href="https://tools.ietf.org/html/rfc4301">RFC 4301, Security Architecture for the
- * Internet Protocol</a>
+ *     Internet Protocol</a>
  */
 @SystemService(Context.IPSEC_SERVICE)
 public final class IpSecManager {
@@ -59,8 +59,7 @@ public final class IpSecManager {
      *
      * @hide
      */
-    @TestApi
+    @TestApi public static final int INVALID_SECURITY_PARAMETER_INDEX = 0;
-    public static final int INVALID_SECURITY_PARAMETER_INDEX = 0;
 
     /** @hide */
     public interface Status {
@@ -78,7 +77,7 @@ public final class IpSecManager {
      * <p>The combination of remote {@code InetAddress} and SPI must be unique across all apps on
      * one device. If this error is encountered, a new SPI is required before a transform may be
      * created. This error can be avoided by calling {@link
-     * IpSecManager#reserveSecurityParameterIndex}.
+     * IpSecManager#allocateSecurityParameterIndex}.
      */
     public static final class SpiUnavailableException extends AndroidException {
         private final int mSpi;
@@ -121,7 +120,7 @@ public final class IpSecManager {
      * This class represents a reserved SPI.
      *
      * <p>Objects of this type are used to track reserved security parameter indices. They can be
-     * obtained by calling {@link IpSecManager#reserveSecurityParameterIndex} and must be released
+     * obtained by calling {@link IpSecManager#allocateSecurityParameterIndex} and must be released
      * by calling {@link #close()} when they are no longer needed.
      */
     public static final class SecurityParameterIndex implements AutoCloseable {
@@ -170,7 +169,7 @@ public final class IpSecManager {
             mRemoteAddress = remoteAddress;
             try {
                 IpSecSpiResponse result =
-                        mService.reserveSecurityParameterIndex(
+                        mService.allocateSecurityParameterIndex(
                                 direction, remoteAddress.getHostAddress(), spi, new Binder());
 
                 if (result == null) {
@@ -228,7 +227,7 @@ public final class IpSecManager {
      *     for this user
      * @throws SpiUnavailableException indicating that a particular SPI cannot be reserved
      */
-    public SecurityParameterIndex reserveSecurityParameterIndex(
+    public SecurityParameterIndex allocateSecurityParameterIndex(
             int direction, InetAddress remoteAddress) throws ResourceUnavailableException {
         try {
             return new SecurityParameterIndex(
@@ -255,7 +254,7 @@ public final class IpSecManager {
      *     for this user
      * @throws SpiUnavailableException indicating that the requested SPI could not be reserved
      */
-    public SecurityParameterIndex reserveSecurityParameterIndex(
+    public SecurityParameterIndex allocateSecurityParameterIndex(
             int direction, InetAddress remoteAddress, int requestedSpi)
             throws SpiUnavailableException, ResourceUnavailableException {
         if (requestedSpi == IpSecManager.INVALID_SECURITY_PARAMETER_INDEX) {
@@ -273,16 +272,18 @@ public final class IpSecManager {
      * unprotected traffic can resume on that socket.
      *
      * <p>For security reasons, the destination address of any traffic on the socket must match the
-     * remote {@code  InetAddress} of the {@code IpSecTransform}. Attempts to send traffic to any
+     * remote {@code InetAddress} of the {@code 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 {@link
      * IpSecTransform#close()}) without calling {@link #removeTransportModeTransform}.
      *
-     * <h4>Rekey Procedure</h4> <p>When applying a new tranform to a socket, the previous transform
+     * <h4>Rekey Procedure</h4>
-     * 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
+     * <p>When applying a new tranform to a socket, the previous transform will be removed. However,
-     * allows rekey procedures where both transforms are valid until both endpoints are using the
+     * inbound traffic on the old transform will continue to be decrypted until that transform is
-     * new transform and all in-flight packets have been received.
+     * 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.
      *
      * @param socket a stream socket
      * @param transform a transport mode {@code IpSecTransform}
@@ -310,11 +311,13 @@ public final class IpSecManager {
      * will throw IOException if the user deactivates the transform (by calling {@link
      * IpSecTransform#close()}) without calling {@link #removeTransportModeTransform}.
      *
-     * <h4>Rekey Procedure</h4> <p>When applying a new tranform to a socket, the previous transform
+     * <h4>Rekey Procedure</h4>
-     * 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
+     * <p>When applying a new tranform to a socket, the previous transform will be removed. However,
-     * allows rekey procedures where both transforms are valid until both endpoints are using the
+     * inbound traffic on the old transform will continue to be decrypted until that transform is
-     * new transform and all in-flight packets have been received.
+     * 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.
      *
      * @param socket a datagram socket
      * @param transform a transport mode {@code IpSecTransform}
@@ -342,11 +345,13 @@ public final class IpSecManager {
      * will throw IOException if the user deactivates the transform (by calling {@link
      * IpSecTransform#close()}) without calling {@link #removeTransportModeTransform}.
      *
-     * <h4>Rekey Procedure</h4> <p>When applying a new tranform to a socket, the previous transform
+     * <h4>Rekey Procedure</h4>
-     * 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
+     * <p>When applying a new tranform to a socket, the previous transform will be removed. However,
-     * allows rekey procedures where both transforms are valid until both endpoints are using the
+     * inbound traffic on the old transform will continue to be decrypted until that transform is
-     * new transform and all in-flight packets have been received.
+     * 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.
      *
      * @param socket a socket file descriptor
      * @param transform a transport mode {@code IpSecTransform}
@@ -379,7 +384,8 @@ public final class IpSecManager {
      * Applications should probably not use this API directly. Instead, they should use {@link
      * VpnService} to provide VPN capability in a more generic fashion.
      *
-     * TODO: Update javadoc for tunnel mode APIs at the same time the APIs are re-worked.
+     * <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
@@ -469,7 +475,8 @@ public final class IpSecManager {
      * all traffic that cannot be routed to the Tunnel's outbound interface. If that interface is
      * lost, all traffic will drop.
      *
-     * TODO: Update javadoc for tunnel mode APIs at the same time the APIs are re-worked.
+     * <p>TODO: Update javadoc for tunnel mode APIs at the same time the APIs are re-worked.
+     *
      * @param net a network that currently has transform applied to it.
      * @param transform a Tunnel Mode IPsec Transform that has been previously applied to the given
      *     network

core/java/android/net/IpSecTransform.java

@@ -47,7 +47,7 @@ import java.net.InetAddress;
  * system resources.
  *
  * @see <a href="https://tools.ietf.org/html/rfc4301">RFC 4301, Security Architecture for the
- * Internet Protocol</a>
+ *     Internet Protocol</a>
  */
 public final class IpSecTransform implements AutoCloseable {
     private static final String TAG = "IpSecTransform";
@@ -116,8 +116,7 @@ public final class IpSecTransform implements AutoCloseable {
     }
 
     /**
-     * Checks the result status and throws an appropriate exception if
+     * Checks the result status and throws an appropriate exception if the status is not Status.OK.
-     * the status is not Status.OK.
      */
     private void checkResultStatus(int status)
             throws IOException, IpSecManager.ResourceUnavailableException,
@@ -267,9 +266,7 @@ public final class IpSecTransform implements AutoCloseable {
         return;
     }
 
-    /**
+    /** This class is used to build {@link IpSecTransform} objects. */
-     * This class is used to build {@link IpSecTransform} objects.
-     */
     public static class Builder {
         private Context mContext;
         private IpSecConfig mConfig;
@@ -339,7 +336,7 @@ public final class IpSecTransform implements AutoCloseable {
          *
          * <p>Because IPsec operates at the IP layer, this 32-bit identifier uniquely identifies
          * packets to a given destination address. To prevent SPI collisions, values should be
-         * reserved by calling {@link IpSecManager#reserveSecurityParameterIndex}.
+         * reserved by calling {@link IpSecManager#allocateSecurityParameterIndex}.
          *
          * <p>If the SPI and algorithms are omitted for one direction, traffic in that direction
          * will not be encrypted or authenticated.
@@ -374,10 +371,9 @@ public final class IpSecTransform implements AutoCloseable {
          * <p>This allows IPsec traffic to pass through a NAT.
          *
          * @see <a href="https://tools.ietf.org/html/rfc3948">RFC 3948, UDP Encapsulation of IPsec
-         * ESP Packets</a>
+         *     ESP Packets</a>
          * @see <a href="https://tools.ietf.org/html/rfc7296#section-2.23">RFC 7296 section 2.23,
-         * NAT Traversal of IKEv2</a>
+         *     NAT Traversal of IKEv2</a>
-         *
          * @param localSocket a socket for sending and receiving encapsulated traffic
          * @param remotePort the UDP port number of the remote host that will send and receive
          *     encapsulated traffic. In the case of IKEv2, this should be port 4500.
@@ -402,7 +398,6 @@ public final class IpSecTransform implements AutoCloseable {
          *
          * @param intervalSeconds the maximum number of seconds between keepalive packets. Must be
          *     between 20s and 3600s.
-         *
          * @hide
          */
         @SystemApi
@@ -418,7 +413,6 @@ public final class IpSecTransform implements AutoCloseable {
          * will not affect any network traffic until it has been applied to one or more sockets.
          *
          * @see IpSecManager#applyTransportModeTransform
-         *
          * @param remoteAddress the remote {@code InetAddress} of traffic on sockets that will use
          *     this transform
          * @throws IllegalArgumentException indicating that a particular combination of transform
@@ -453,8 +447,8 @@ public final class IpSecTransform implements AutoCloseable {
          */
         public IpSecTransform buildTunnelModeTransform(
                 InetAddress localAddress, InetAddress remoteAddress) {
-            //FIXME: argument validation here
+            // FIXME: argument validation here
-            //throw new IllegalArgumentException("Natt Keepalive requires UDP Encapsulation");
+            // throw new IllegalArgumentException("Natt Keepalive requires UDP Encapsulation");
             mConfig.setLocalAddress(localAddress.getHostAddress());
             mConfig.setRemoteAddress(remoteAddress.getHostAddress());
             mConfig.setMode(MODE_TUNNEL);

services/core/java/com/android/server/IpSecService.java

@@ -827,15 +827,15 @@ public class IpSecService extends IIpSecService.Stub {
         throw new IllegalArgumentException("Invalid Direction: " + direction);
     }
 
-    @Override
     /** Get a new SPI and maintain the reservation in the system server */
-    public synchronized IpSecSpiResponse reserveSecurityParameterIndex(
+    @Override
+    public synchronized IpSecSpiResponse allocateSecurityParameterIndex(
             int direction, String remoteAddress, int requestedSpi, IBinder binder)
             throws RemoteException {
         checkDirection(direction);
         checkInetAddress(remoteAddress);
         /* requestedSpi can be anything in the int range, so no check is needed. */
-        checkNotNull(binder, "Null Binder passed to reserveSecurityParameterIndex");
+        checkNotNull(binder, "Null Binder passed to allocateSecurityParameterIndex");
 
         UserRecord userRecord = mUserResourceTracker.getUserRecord(Binder.getCallingUid());
         int resourceId = mNextResourceId.getAndIncrement();