8230946: Clarify security manager behaviour of a connected DatagramSocket and DatagramChannel

Update to API, to clarify that packets are dropped in the receive method of non-connected sockets if they fail the security manager checks

Reviewed-by: alanb, chegar, dfuchs

src/java.base/share/classes/java/net/DatagramSocket.java

@@ -434,14 +434,15 @@ class DatagramSocket implements java.io.Closeable {
      * verify that datagrams are permitted to be sent and received
      * respectively.
      *
-     * <p> When a socket is connected, {@link #receive receive} and
-     * {@link #send send} <b>will not perform any security checks</b>
-     * on incoming and outgoing packets, other than matching the packet's
-     * and the socket's address and port. On a send operation, if the
-     * packet's address is set and the packet's address and the socket's
-     * address do not match, an {@code IllegalArgumentException} will be
-     * thrown. A socket connected to a multicast address may only be used
-     * to send packets.
+     * <p> Care should be taken to ensure that a connected datagram socket
+     * is not shared with untrusted code. When a socket is connected,
+     * {@link #receive receive} and {@link #send send} <b>will not perform
+     * any security checks</b> on incoming and outgoing packets, other than
+     * matching the packet's and the socket's address and port. On a send
+     * operation, if the packet's address is set and the packet's address
+     * and the socket's address do not match, an {@code IllegalArgumentException}
+     * will be thrown. A socket connected to a multicast address may only
+     * be used to send packets.
      *
      * @param address the remote address for the socket
      *
@@ -708,9 +709,11 @@ class DatagramSocket implements java.io.Closeable {
      * the length of the received message. If the message is longer than
      * the packet's length, the message is truncated.
      * <p>
-     * If there is a security manager, a packet cannot be received if the
-     * security manager's {@code checkAccept} method
-     * does not allow it.
+     * If there is a security manager, and the socket is not currently
+     * connected to a remote address, a packet cannot be received if the
+     * security manager's {@code checkAccept} method does not allow it.
+     * Datagrams that are not permitted by the security manager are silently
+     * discarded.
      *
      * @param      p   the {@code DatagramPacket} into which to place
      *                 the incoming data.

src/java.base/share/classes/java/nio/channels/DatagramChannel.java

@@ -265,7 +265,10 @@ public abstract class DatagramChannel
      * java.lang.SecurityManager#checkAccept checkAccept} and {@link
      * java.lang.SecurityManager#checkConnect checkConnect} methods permit
      * datagrams to be received from and sent to, respectively, the given
-     * remote address.
+     * remote address. Once connected, no further security checks are performed
+     * for datagrams received from, or sent to, the given remote address. Care
+     * should be taken to ensure that a connected datagram channel is not shared
+     * with untrusted code.
      *
      * <p> This method may be invoked at any time.  It will not have any effect
      * on read or write operations that are already in progress at the moment
@@ -369,9 +372,10 @@ public abstract class DatagramChannel
      * to a specific remote address and a security manager has been installed
      * then for each datagram received this method verifies that the source's
      * address and port number are permitted by the security manager's {@link
-     * java.lang.SecurityManager#checkAccept checkAccept} method.  The overhead
-     * of this security check can be avoided by first connecting the socket via
-     * the {@link #connect connect} method.
+     * java.lang.SecurityManager#checkAccept checkAccept} method. Datagrams
+     * that are not permitted by the security manager are silently discarded.
+     * The overhead of this security check can be avoided by first connecting
+     * the socket via the {@link #connect connect} method.
      *
      * <p> This method may be invoked at any time.  If another thread has
      * already initiated a read operation upon this channel, however, then an
@@ -401,11 +405,6 @@ public abstract class DatagramChannel
      *          closing the channel and setting the current thread's
      *          interrupt status
      *
-     * @throws  SecurityException
-     *          If a security manager has been installed
-     *          and it does not permit datagrams to be accepted
-     *          from the datagram's sender
-     *
      * @throws  IOException
      *          If some other I/O error occurs
      */