1 /*
   2  * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.net.ssl;
  27 
  28 import java.security.AlgorithmConstraints;
  29 import java.util.Map;
  30 import java.util.List;
  31 import java.util.HashMap;
  32 import java.util.ArrayList;
  33 import java.util.Collection;
  34 import java.util.Collections;
  35 import java.util.LinkedHashMap;
  36 
  37 /**
  38  * Encapsulates parameters for an SSL/TLS/DTLS connection. The parameters
  39  * are the list of ciphersuites to be accepted in an SSL/TLS/DTLS handshake,
  40  * the list of protocols to be allowed, the endpoint identification
  41  * algorithm during SSL/TLS/DTLS handshaking, the Server Name Indication (SNI),
  42  * the maximum network packet size, the algorithm constraints and whether
  43  * SSL/TLS/DTLS servers should request or require client authentication, etc.
  44  * <p>
  45  * SSLParameters can be created via the constructors in this class.
  46  * Objects can also be obtained using the {@code getSSLParameters()}
  47  * methods in
  48  * {@link SSLSocket#getSSLParameters SSLSocket} and
  49  * {@link SSLServerSocket#getSSLParameters SSLServerSocket} and
  50  * {@link SSLEngine#getSSLParameters SSLEngine} or the
  51  * {@link SSLContext#getDefaultSSLParameters getDefaultSSLParameters()} and
  52  * {@link SSLContext#getSupportedSSLParameters getSupportedSSLParameters()}
  53  * methods in {@code SSLContext}.
  54  * <p>
  55  * SSLParameters can be applied to a connection via the methods
  56  * {@link SSLSocket#setSSLParameters SSLSocket.setSSLParameters()} and
  57  * {@link SSLServerSocket#setSSLParameters SSLServerSocket.setSSLParameters()}
  58  * and {@link SSLEngine#setSSLParameters SSLEngine.setSSLParameters()}.
  59  * <p>
  60  * For example:
  61  *
  62  * <blockquote><pre>
  63  *     SSLParameters p = sslSocket.getSSLParameters();
  64  *     p.setProtocols(new String[] { "TLSv1.2" });
  65  *     p.setCipherSuites(
  66  *         new String[] { "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", ... });
  67  *     p.setApplicationProtocols(new String[] {"h2", "http/1.1"});
  68  *     sslSocket.setSSLParameters(p);
  69  * </pre></blockquote>
  70  *
  71  * @see SSLSocket
  72  * @see SSLEngine
  73  * @see SSLContext
  74  *
  75  * @since 1.6
  76  */
  77 public class SSLParameters {
  78 
  79     private String[] cipherSuites;
  80     private String[] protocols;
  81     private boolean wantClientAuth;
  82     private boolean needClientAuth;
  83     private String identificationAlgorithm;
  84     private AlgorithmConstraints algorithmConstraints;
  85     private Map<Integer, SNIServerName> sniNames = null;
  86     private Map<Integer, SNIMatcher> sniMatchers = null;
  87     private boolean preferLocalCipherSuites;
  88     private boolean enableRetransmissions = true;
  89     private int maximumPacketSize = 0;
  90     private String[] applicationProtocols = new String[0];
  91     private boolean useCertificateAuthorities = false;
  92 
  93     /**
  94      * Constructs SSLParameters.
  95      * <p>
  96      * The values of cipherSuites, protocols, cryptographic algorithm
  97      * constraints, endpoint identification algorithm, server names and
  98      * server name matchers are set to {@code null}; useCipherSuitesOrder,
  99      * wantClientAuth and needClientAuth are set to {@code false};
 100      * enableRetransmissions is set to {@code true}; maximum network packet
 101      * size is set to {@code 0}.
 102      */
 103     public SSLParameters() {
 104         // empty
 105     }
 106 
 107     /**
 108      * Constructs SSLParameters from the specified array of ciphersuites.
 109      * <p>
 110      * Calling this constructor is equivalent to calling the no-args
 111      * constructor followed by
 112      * {@code setCipherSuites(cipherSuites);}.  Note that the
 113      * standard list of cipher suite names may be found in the <a href=
 114      * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
 115      * JSSE Cipher Suite Names</a> section of the Java Cryptography
 116      * Architecture Standard Algorithm Name Documentation.  Providers
 117      * may support cipher suite names not found in this list.
 118      *
 119      * @param cipherSuites the array of ciphersuites (or null)
 120      */
 121     public SSLParameters(String[] cipherSuites) {
 122         setCipherSuites(cipherSuites);
 123     }
 124 
 125     /**
 126      * Constructs SSLParameters from the specified array of ciphersuites
 127      * and protocols.
 128      * <p>
 129      * Calling this constructor is equivalent to calling the no-args
 130      * constructor followed by
 131      * {@code setCipherSuites(cipherSuites); setProtocols(protocols);}.
 132      * Note that the standard list of cipher suite names may be found in the
 133      * <a href=
 134      * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
 135      * JSSE Cipher Suite Names</a> section of the Java Cryptography
 136      * Architecture Standard Algorithm Name Documentation.  Providers
 137      * may support cipher suite names not found in this list.
 138      *
 139      * @param cipherSuites the array of ciphersuites (or null)
 140      * @param protocols the array of protocols (or null)
 141      */
 142     public SSLParameters(String[] cipherSuites, String[] protocols) {
 143         setCipherSuites(cipherSuites);
 144         setProtocols(protocols);
 145     }
 146 
 147     private static String[] clone(String[] s) {
 148         return (s == null) ? null : s.clone();
 149     }
 150 
 151     /**
 152      * Returns a copy of the array of ciphersuites or null if none
 153      * have been set.
 154      * <P>
 155      * The returned array includes cipher suites from the list of standard
 156      * cipher suite names in the <a href=
 157      * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
 158      * JSSE Cipher Suite Names</a> section of the Java Cryptography
 159      * Architecture Standard Algorithm Name Documentation, and may also
 160      * include other cipher suites that the provider supports.
 161      *
 162      * @return a copy of the array of ciphersuites or null if none
 163      * have been set.
 164      */
 165     public String[] getCipherSuites() {
 166         return clone(cipherSuites);
 167     }
 168 
 169     /**
 170      * Sets the array of ciphersuites.
 171      *
 172      * @param cipherSuites the array of ciphersuites (or null).  Note that the
 173      * standard list of cipher suite names may be found in the <a href=
 174      * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names">
 175      * JSSE Cipher Suite Names</a> section of the Java Cryptography
 176      * Architecture Standard Algorithm Name Documentation.  Providers
 177      * may support cipher suite names not found in this list or might not
 178      * use the recommended name for a certain cipher suite.
 179      */
 180     public void setCipherSuites(String[] cipherSuites) {
 181         this.cipherSuites = clone(cipherSuites);
 182     }
 183 
 184     /**
 185      * Returns a copy of the array of protocols or null if none
 186      * have been set.
 187      *
 188      * @return a copy of the array of protocols or null if none
 189      * have been set.
 190      */
 191     public String[] getProtocols() {
 192         return clone(protocols);
 193     }
 194 
 195     /**
 196      * Sets the array of protocols.
 197      *
 198      * @param protocols the array of protocols (or null)
 199      */
 200     public void setProtocols(String[] protocols) {
 201         this.protocols = clone(protocols);
 202     }
 203 
 204     /**
 205      * Returns whether client authentication should be requested.
 206      *
 207      * @return whether client authentication should be requested.
 208      */
 209     public boolean getWantClientAuth() {
 210         return wantClientAuth;
 211     }
 212 
 213     /**
 214      * Sets whether client authentication should be requested. Calling
 215      * this method clears the {@code needClientAuth} flag.
 216      *
 217      * @param wantClientAuth whether client authentication should be requested
 218      */
 219     public void setWantClientAuth(boolean wantClientAuth) {
 220         this.wantClientAuth = wantClientAuth;
 221         this.needClientAuth = false;
 222     }
 223 
 224     /**
 225      * Returns whether client authentication should be required.
 226      *
 227      * @return whether client authentication should be required.
 228      */
 229     public boolean getNeedClientAuth() {
 230         return needClientAuth;
 231     }
 232 
 233     /**
 234      * Sets whether client authentication should be required. Calling
 235      * this method clears the {@code wantClientAuth} flag.
 236      *
 237      * @param needClientAuth whether client authentication should be required
 238      */
 239     public void setNeedClientAuth(boolean needClientAuth) {
 240         this.wantClientAuth = false;
 241         this.needClientAuth = needClientAuth;
 242     }
 243 
 244     /**
 245      * Returns the cryptographic algorithm constraints.
 246      *
 247      * @return the cryptographic algorithm constraints, or null if the
 248      *     constraints have not been set
 249      *
 250      * @see #setAlgorithmConstraints(AlgorithmConstraints)
 251      *
 252      * @since 1.7
 253      */
 254     public AlgorithmConstraints getAlgorithmConstraints() {
 255         return algorithmConstraints;
 256     }
 257 
 258     /**
 259      * Sets the cryptographic algorithm constraints, which will be used
 260      * in addition to any configured by the runtime environment.
 261      * <p>
 262      * If the {@code constraints} parameter is non-null, every
 263      * cryptographic algorithm, key and algorithm parameters used in the
 264      * SSL/TLS/DTLS handshake must be permitted by the constraints.
 265      *
 266      * @param constraints the algorithm constraints (or null)
 267      *
 268      * @since 1.7
 269      */
 270     public void setAlgorithmConstraints(AlgorithmConstraints constraints) {
 271         // the constraints object is immutable
 272         this.algorithmConstraints = constraints;
 273     }
 274 
 275     /**
 276      * Gets the endpoint identification algorithm.
 277      *
 278      * @return the endpoint identification algorithm, or null if none
 279      * has been set.
 280      *
 281      * @see X509ExtendedTrustManager
 282      * @see #setEndpointIdentificationAlgorithm(String)
 283      *
 284      * @since 1.7
 285      */
 286     public String getEndpointIdentificationAlgorithm() {
 287         return identificationAlgorithm;
 288     }
 289 
 290     /**
 291      * Sets the endpoint identification algorithm.
 292      * <p>
 293      * If the {@code algorithm} parameter is non-null or non-empty, the
 294      * endpoint identification/verification procedures must be handled during
 295      * SSL/TLS/DTLS handshaking.  This is to prevent man-in-the-middle attacks.
 296      *
 297      * @param algorithm The standard string name of the endpoint
 298      *     identification algorithm (or null).
 299      *     See the <a href=
 300      *     "{@docRoot}/../specs/security/standard-names.html">
 301      *     Java Security Standard Algorithm Names</a> document
 302      *     for information about standard algorithm names.
 303      *
 304      * @see X509ExtendedTrustManager
 305      *
 306      * @since 1.7
 307      */
 308     public void setEndpointIdentificationAlgorithm(String algorithm) {
 309         this.identificationAlgorithm = algorithm;
 310     }
 311 
 312     /**
 313      * Sets the desired {@link SNIServerName}s of the Server Name
 314      * Indication (SNI) parameter.
 315      * <P>
 316      * This method is only useful to {@link SSLSocket}s or {@link SSLEngine}s
 317      * operating in client mode.
 318      * <P>
 319      * Note that the {@code serverNames} list is cloned
 320      * to protect against subsequent modification.
 321      *
 322      * @param  serverNames
 323      *         the list of desired {@link SNIServerName}s (or null)
 324      *
 325      * @throws NullPointerException if the {@code serverNames}
 326      *         contains {@code null} element
 327      * @throws IllegalArgumentException if the {@code serverNames}
 328      *         contains more than one name of the same name type
 329      *
 330      * @see SNIServerName
 331      * @see #getServerNames()
 332      *
 333      * @since 1.8
 334      */
 335     public final void setServerNames(List<SNIServerName> serverNames) {
 336         if (serverNames != null) {
 337             if (!serverNames.isEmpty()) {
 338                 sniNames = new LinkedHashMap<>(serverNames.size());
 339                 for (SNIServerName serverName : serverNames) {
 340                     if (sniNames.put(serverName.getType(),
 341                                                 serverName) != null) {
 342                         throw new IllegalArgumentException(
 343                                     "Duplicated server name of type " +
 344                                     serverName.getType());
 345                     }
 346                 }
 347             } else {
 348                 sniNames = Collections.<Integer, SNIServerName>emptyMap();
 349             }
 350         } else {
 351             sniNames = null;
 352         }
 353     }
 354 
 355     /**
 356      * Returns a {@link List} containing all {@link SNIServerName}s of the
 357      * Server Name Indication (SNI) parameter, or null if none has been set.
 358      * <P>
 359      * This method is only useful to {@link SSLSocket}s or {@link SSLEngine}s
 360      * operating in client mode.
 361      * <P>
 362      * For SSL/TLS/DTLS connections, the underlying SSL/TLS/DTLS provider
 363      * may specify a default value for a certain server name type.  In
 364      * client mode, it is recommended that, by default, providers should
 365      * include the server name indication whenever the server can be located
 366      * by a supported server name type.
 367      * <P>
 368      * It is recommended that providers initialize default Server Name
 369      * Indications when creating {@code SSLSocket}/{@code SSLEngine}s.
 370      * In the following examples, the server name could be represented by an
 371      * instance of {@link SNIHostName} which has been initialized with the
 372      * hostname "www.example.com" and type
 373      * {@link StandardConstants#SNI_HOST_NAME}.
 374      *
 375      * <pre>
 376      *     Socket socket =
 377      *         sslSocketFactory.createSocket("www.example.com", 443);
 378      * </pre>
 379      * or
 380      * <pre>
 381      *     SSLEngine engine =
 382      *         sslContext.createSSLEngine("www.example.com", 443);
 383      * </pre>
 384      *
 385      * @return null or an immutable list of non-null {@link SNIServerName}s
 386      *
 387      * @see List
 388      * @see #setServerNames(List)
 389      *
 390      * @since 1.8
 391      */
 392     public final List<SNIServerName> getServerNames() {
 393         if (sniNames != null) {
 394             if (!sniNames.isEmpty()) {
 395                 return Collections.<SNIServerName>unmodifiableList(
 396                                         new ArrayList<>(sniNames.values()));
 397             } else {
 398                 return Collections.<SNIServerName>emptyList();
 399             }
 400         }
 401 
 402         return null;
 403     }
 404 
 405     /**
 406      * Sets the {@link SNIMatcher}s of the Server Name Indication (SNI)
 407      * parameter.
 408      * <P>
 409      * This method is only useful to {@link SSLSocket}s or {@link SSLEngine}s
 410      * operating in server mode.
 411      * <P>
 412      * Note that the {@code matchers} collection is cloned to protect
 413      * against subsequent modification.
 414      *
 415      * @param  matchers
 416      *         the collection of {@link SNIMatcher}s (or null)
 417      *
 418      * @throws NullPointerException if the {@code matchers}
 419      *         contains {@code null} element
 420      * @throws IllegalArgumentException if the {@code matchers}
 421      *         contains more than one name of the same name type
 422      *
 423      * @see Collection
 424      * @see SNIMatcher
 425      * @see #getSNIMatchers()
 426      *
 427      * @since 1.8
 428      */
 429     public final void setSNIMatchers(Collection<SNIMatcher> matchers) {
 430         if (matchers != null) {
 431             if (!matchers.isEmpty()) {
 432                 sniMatchers = new HashMap<>(matchers.size());
 433                 for (SNIMatcher matcher : matchers) {
 434                     if (sniMatchers.put(matcher.getType(),
 435                                                 matcher) != null) {
 436                         throw new IllegalArgumentException(
 437                                     "Duplicated server name of type " +
 438                                     matcher.getType());
 439                     }
 440                 }
 441             } else {
 442                 sniMatchers = Collections.<Integer, SNIMatcher>emptyMap();
 443             }
 444         } else {
 445             sniMatchers = null;
 446         }
 447     }
 448 
 449     /**
 450      * Returns a {@link Collection} containing all {@link SNIMatcher}s of the
 451      * Server Name Indication (SNI) parameter, or null if none has been set.
 452      * <P>
 453      * This method is only useful to {@link SSLSocket}s or {@link SSLEngine}s
 454      * operating in server mode.
 455      * <P>
 456      * For better interoperability, providers generally will not define
 457      * default matchers so that by default servers will ignore the SNI
 458      * extension and continue the handshake.
 459      *
 460      * @return null or an immutable collection of non-null {@link SNIMatcher}s
 461      *
 462      * @see SNIMatcher
 463      * @see #setSNIMatchers(Collection)
 464      *
 465      * @since 1.8
 466      */
 467     public final Collection<SNIMatcher> getSNIMatchers() {
 468         if (sniMatchers != null) {
 469             if (!sniMatchers.isEmpty()) {
 470                 return Collections.<SNIMatcher>unmodifiableList(
 471                                         new ArrayList<>(sniMatchers.values()));
 472             } else {
 473                 return Collections.<SNIMatcher>emptyList();
 474             }
 475         }
 476 
 477         return null;
 478     }
 479 
 480     /**
 481      * Sets whether the local cipher suites preference should be honored.
 482      *
 483      * @param honorOrder whether local cipher suites order in
 484      *        {@code #getCipherSuites} should be honored during
 485      *        SSL/TLS/DTLS handshaking.
 486      *
 487      * @see #getUseCipherSuitesOrder()
 488      *
 489      * @since 1.8
 490      */
 491     public final void setUseCipherSuitesOrder(boolean honorOrder) {
 492         this.preferLocalCipherSuites = honorOrder;
 493     }
 494 
 495     /**
 496      * Returns whether the local cipher suites preference should be honored.
 497      *
 498      * @return whether local cipher suites order in {@code #getCipherSuites}
 499      *         should be honored during SSL/TLS/DTLS handshaking.
 500      *
 501      * @see #setUseCipherSuitesOrder(boolean)
 502      *
 503      * @since 1.8
 504      */
 505     public final boolean getUseCipherSuitesOrder() {
 506         return preferLocalCipherSuites;
 507     }
 508 
 509     /**
 510      * Sets whether DTLS handshake retransmissions should be enabled.
 511      *
 512      * This method only applies to DTLS.
 513      *
 514      * @param   enableRetransmissions
 515      *          {@code true} indicates that DTLS handshake retransmissions
 516      *          should be enabled; {@code false} indicates that DTLS handshake
 517      *          retransmissions should be disabled
 518      *
 519      * @see     #getEnableRetransmissions()
 520      *
 521      * @since 9
 522      */
 523     public void setEnableRetransmissions(boolean enableRetransmissions) {
 524         this.enableRetransmissions = enableRetransmissions;
 525     }
 526 
 527     /**
 528      * Returns whether DTLS handshake retransmissions should be enabled.
 529      *
 530      * This method only applies to DTLS.
 531      *
 532      * @return  true, if DTLS handshake retransmissions should be enabled
 533      *
 534      * @see     #setEnableRetransmissions(boolean)
 535      *
 536      * @since 9
 537      */
 538     public boolean getEnableRetransmissions() {
 539         return enableRetransmissions;
 540     }
 541 
 542     /**
 543      * Sets the maximum expected network packet size in bytes for
 544      * SSL/TLS/DTLS records.
 545      *
 546      * @apiNote  It is recommended that if possible, the maximum packet size
 547      *           should not be less than 256 bytes so that small handshake
 548      *           messages, such as HelloVerifyRequests, are not fragmented.
 549      *
 550      * @implNote If the maximum packet size is too small to hold a minimal
 551      *           record, an implementation may attempt to generate as minimal
 552      *           records as possible.  However, this may cause a generated
 553      *           packet to be larger than the maximum packet size.
 554      *
 555      * @param   maximumPacketSize
 556      *          the maximum expected network packet size in bytes, or
 557      *          {@code 0} to use the implicit size that is automatically
 558      *          specified by the underlying implementation.
 559      * @throws  IllegalArgumentException
 560      *          if {@code maximumPacketSize} is negative.
 561      *
 562      * @see     #getMaximumPacketSize()
 563      *
 564      * @since 9
 565      */
 566     public void setMaximumPacketSize(int maximumPacketSize) {
 567         if (maximumPacketSize < 0) {
 568             throw new IllegalArgumentException(
 569                 "The maximum packet size cannot be negative");
 570         }
 571 
 572         this.maximumPacketSize = maximumPacketSize;
 573     }
 574 
 575     /**
 576      * Returns the maximum expected network packet size in bytes for
 577      * SSL/TLS/DTLS records.
 578      *
 579      * @apiNote  The implicit size may not be a fixed value, especially
 580      *           for a DTLS protocols implementation.
 581      *
 582      * @implNote For SSL/TLS/DTLS connections, the underlying provider
 583      *           should calculate and specify the implicit value of the
 584      *           maximum expected network packet size if it is not
 585      *           configured explicitly.  For any connection populated
 586      *           object, this method should never return {@code 0} so
 587      *           that applications can retrieve the actual implicit size
 588      *           of the underlying implementation.
 589      *           <P>
 590      *           An implementation should attempt to comply with the maximum
 591      *           packet size configuration.  However, if the maximum packet
 592      *           size is too small to hold a minimal record, an implementation
 593      *           may try to generate as minimal records as possible.  This
 594      *           may cause a generated packet to be larger than the maximum
 595      *           packet size.
 596      *
 597      * @return   the maximum expected network packet size, or {@code 0} if
 598      *           use the implicit size that is automatically specified by
 599      *           the underlying implementation and this object has not been
 600      *           populated by any connection.
 601      *
 602      * @see      #setMaximumPacketSize(int)
 603      *
 604      * @since 9
 605      */
 606     public int getMaximumPacketSize() {
 607         return maximumPacketSize;
 608     }
 609 
 610     /**
 611      * Returns a prioritized array of application-layer protocol names that
 612      * can be negotiated over the SSL/TLS/DTLS protocols.
 613      * <p>
 614      * The array could be empty (zero-length), in which case protocol
 615      * indications will not be used.
 616      * <p>
 617      * This method will return a new array each time it is invoked.
 618      *
 619      * @return a non-null, possibly zero-length array of application protocol
 620      *         {@code String}s.  The array is ordered based on protocol
 621      *         preference, with {@code protocols[0]} being the most preferred.
 622      * @see #setApplicationProtocols
 623      * @since 9
 624      */
 625     public String[] getApplicationProtocols() {
 626         return applicationProtocols.clone();
 627     }
 628 
 629     /**
 630      * Sets the prioritized array of application-layer protocol names that
 631      * can be negotiated over the SSL/TLS/DTLS protocols.
 632      * <p>
 633      * If application-layer protocols are supported by the underlying
 634      * SSL/TLS implementation, this method configures which values can
 635      * be negotiated by protocols such as <a
 636      * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the
 637      * Application Layer Protocol Negotiation (ALPN).
 638      * <p>
 639      * If this end of the connection is expected to offer application protocol
 640      * values, all protocols configured by this method will be sent to the
 641      * peer.
 642      * <p>
 643      * If this end of the connection is expected to select the application
 644      * protocol value, the {@code protocols} configured by this method are
 645      * compared with those sent by the peer.  The first matched value becomes
 646      * the negotiated value.  If none of the {@code protocols} were actually
 647      * requested by the peer, the underlying protocol will determine what
 648      * action to take.  (For example, ALPN will send a
 649      * {@code "no_application_protocol"} alert and terminate the connection.)
 650      * <p>
 651      * @implSpec
 652      * This method will make a copy of the {@code protocols} array.
 653      *
 654      * @param protocols   an ordered array of application protocols,
 655      *                    with {@code protocols[0]} being the most preferred.
 656      *                    If the array is empty (zero-length), protocol
 657      *                    indications will not be used.
 658      * @throws IllegalArgumentException if protocols is null, or if
 659      *                    any element in a non-empty array is null or an
 660      *                    empty (zero-length) string
 661      * @see #getApplicationProtocols
 662      * @since 9
 663      */
 664     public void setApplicationProtocols(String[] protocols) {
 665         if (protocols == null) {
 666             throw new IllegalArgumentException("protocols was null");
 667         }
 668 
 669         String[] tempProtocols = protocols.clone();
 670 
 671         for (String p : tempProtocols) {
 672             if (p == null || p.equals("")) {
 673                 throw new IllegalArgumentException(
 674                     "An element of protocols was null/empty");
 675             }
 676         }
 677         applicationProtocols = tempProtocols;
 678     }
 679 
 680     /**
 681      * Returns whether or not the use of Certificate Authorities
 682      * TLS extension is enabled on either a Client or a Server.
 683      * <p>
 684      * When the extension is enabled on a Client, information
 685      * regarding its trusted certificate authorities is sent in
 686      * a {@code ClientHello} message, during the TLS handshake.
 687      * <p>
 688      * When the extension is enabled on a Server, information
 689      * regarding its trusted certificate authorities is sent in
 690      * a {@code CertificateRequest} message, during the TLS handshake
 691      * (assuming the Server requires client certificate authentication).
 692      * <p>
 693      * This is part of Certificate Authorities TLS extension (TLS 1.3).
 694      * See further information in
 695      * <a href="https://tools.ietf.org/html/draft-ietf-tls-tls13-20#section-4.2.4">TLS 1.3</a>.
 696      * 
 697      * @return a boolean value indicating whether or not the use of
 698      *         Certificate Authorities TLS extension is enabled.
 699      */
 700     public boolean getUseCertificateAuthorities() {
 701         return useCertificateAuthorities;
 702     }
 703 
 704     /**
 705      * Sets whether or not the use of Certificate Authorities
 706      * TLS extension should be enabled on either a Client or a Server.
 707      * <p>
 708      * When the extension is enabled on a Client, information
 709      * regarding its trusted certificate authorities is sent in
 710      * a {@code ClientHello} message, during the TLS handshake.
 711      * <p>
 712      * When the extension is enabled on a Server, information
 713      * regarding its trusted certificate authorities is sent in
 714      * a {@code CertificateRequest} message, during the TLS handshake
 715      * (assuming the Server requires Client certificate authentication).
 716      * <p>
 717      * This is part of Certificate Authorities TLS extension (TLS 1.3).
 718      * See further information in
 719      * <a href="https://tools.ietf.org/html/draft-ietf-tls-tls13-20#section-4.2.4">TLS 1.3</a>.
 720      * 
 721      * @param useCertificateAuthorities whether or not the use of Certificate
 722      *        Authorities TLS extension should be enabled.
 723      * @throws UnsupportedOperationException if the underlying provider
 724      *         does not implement the operation.
 725      */
 726     public void setUseCertificateAuthorities(boolean useCertificateAuthorities) {
 727         this.useCertificateAuthorities = useCertificateAuthorities;
 728     }
 729 
 730 }