From: Benedict Wong <benedictwong@google.com>
Date: Tue, 27 Mar 2018 22:19:37 +0000 (+0000)
Subject: Merge "Add documentation for TCP interactions with transforms"
X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=b454937f06;p=android-x86%2Fframeworks-base.git

Merge "Add documentation for TCP interactions with transforms"
---

b454937f068d285dc9e7c50a30df99024d300fa3
diff --cc core/java/android/net/IpSecManager.java
index 4157845d611b,246d1e1860a5..dc3c7655e8f9
--- a/core/java/android/net/IpSecManager.java
+++ b/core/java/android/net/IpSecManager.java
@@@ -305,18 -299,29 +305,31 @@@ public final class IpSecManager 
       * will throw IOException if the user deactivates the transform (by calling {@link
       * IpSecTransform#close()}) without calling {@link #removeTransportModeTransforms}.
       *
+      * <p>Note that when applied to TCP sockets, calling {@link 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 {@link 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.
+      *
       * <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
       */
@@@ -373,18 -377,29 +386,31 @@@
       * will throw IOException if the user deactivates the transform (by calling {@link
       * IpSecTransform#close()}) without calling {@link #removeTransportModeTransforms}.
       *
+      * <p>Note that when applied to TCP sockets, calling {@link 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 {@link 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.
+      *
       * <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
       */