Merge "Add documentation for TCP interactions with transforms"

diff --cc core/java/android/net/IpSecManager.java
index 4157845,246d1e1..dc3c765
--- 1/core/java/android/net/IpSecManager.java
--- 2/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
       */