1 /*
2 * Copyright (c) 2005, 2010, 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
30 /**
31 * Encapsulates parameters for an SSL/TLS connection. The parameters
32 * are the list of ciphersuites to be accepted in an SSL/TLS handshake,
33 * the list of protocols to be allowed, the endpoint identification
34 * algorithm during SSL/TLS handshaking, the algorithm constraints and
35 * whether SSL/TLS servers should request or require client authentication.
36 * <p>
37 * SSLParameters can be created via the constructors in this class.
38 * Objects can also be obtained using the <code>getSSLParameters()</code>
39 * methods in
40 * {@link SSLSocket#getSSLParameters SSLSocket} and
41 * {@link SSLServerSocket#getSSLParameters SSLServerSocket} and
42 * {@link SSLEngine#getSSLParameters SSLEngine} or the
43 * {@link SSLContext#getDefaultSSLParameters getDefaultSSLParameters()} and
44 * {@link SSLContext#getSupportedSSLParameters getSupportedSSLParameters()}
45 * methods in <code>SSLContext</code>.
46 * <p>
47 * SSLParameters can be applied to a connection via the methods
48 * {@link SSLSocket#setSSLParameters SSLSocket.setSSLParameters()} and
49 * {@link SSLServerSocket#setSSLParameters SSLServerSocket.setSSLParameters()}
50 * and {@link SSLEngine#setSSLParameters SSLEngine.getSSLParameters()}.
51 *
52 * @see SSLSocket
53 * @see SSLEngine
54 * @see SSLContext
55 *
56 * @since 1.6
57 */
58 public class SSLParameters {
59
60 private String[] cipherSuites;
61 private String[] protocols;
62 private boolean wantClientAuth;
63 private boolean needClientAuth;
64 private String identificationAlgorithm;
65 private AlgorithmConstraints algorithmConstraints;
66
67 /**
68 * Constructs SSLParameters.
69 * <p>
70 * The cipherSuites and protocols values are set to <code>null</code>,
71 * wantClientAuth and needClientAuth are set to <code>false</code>.
72 */
73 public SSLParameters() {
74 // empty
75 }
76
77 /**
78 * Constructs SSLParameters from the specified array of ciphersuites.
79 * <p>
80 * Calling this constructor is equivalent to calling the no-args
81 * constructor followed by
82 * <code>setCipherSuites(cipherSuites);</code>.
83 *
84 * @param cipherSuites the array of ciphersuites (or null)
85 */
86 public SSLParameters(String[] cipherSuites) {
87 setCipherSuites(cipherSuites);
88 }
89
90 /**
91 * Constructs SSLParameters from the specified array of ciphersuites
92 * and protocols.
93 * <p>
94 * Calling this constructor is equivalent to calling the no-args
95 * constructor followed by
96 * <code>setCipherSuites(cipherSuites); setProtocols(protocols);</code>.
97 *
98 * @param cipherSuites the array of ciphersuites (or null)
99 * @param protocols the array of protocols (or null)
100 */
101 public SSLParameters(String[] cipherSuites, String[] protocols) {
102 setCipherSuites(cipherSuites);
103 setProtocols(protocols);
104 }
105
106 private static String[] clone(String[] s) {
107 return (s == null) ? null : s.clone();
108 }
109
110 /**
111 * Returns a copy of the array of ciphersuites or null if none
112 * have been set.
113 *
114 * @return a copy of the array of ciphersuites or null if none
115 * have been set.
116 */
117 public String[] getCipherSuites() {
118 return clone(cipherSuites);
119 }
120
121 /**
122 * Sets the array of ciphersuites.
123 *
124 * @param cipherSuites the array of ciphersuites (or null)
125 */
126 public void setCipherSuites(String[] cipherSuites) {
127 this.cipherSuites = clone(cipherSuites);
128 }
129
130 /**
131 * Returns a copy of the array of protocols or null if none
132 * have been set.
133 *
134 * @return a copy of the array of protocols or null if none
135 * have been set.
136 */
137 public String[] getProtocols() {
138 return clone(protocols);
139 }
140
141 /**
142 * Sets the array of protocols.
143 *
144 * @param protocols the array of protocols (or null)
145 */
146 public void setProtocols(String[] protocols) {
147 this.protocols = clone(protocols);
148 }
149
150 /**
151 * Returns whether client authentication should be requested.
152 *
153 * @return whether client authentication should be requested.
154 */
155 public boolean getWantClientAuth() {
156 return wantClientAuth;
157 }
158
159 /**
160 * Sets whether client authentication should be requested. Calling
161 * this method clears the <code>needClientAuth</code> flag.
162 *
163 * @param wantClientAuth whether client authentication should be requested
164 */
165 public void setWantClientAuth(boolean wantClientAuth) {
166 this.wantClientAuth = wantClientAuth;
167 this.needClientAuth = false;
168 }
169
170 /**
171 * Returns whether client authentication should be required.
172 *
173 * @return whether client authentication should be required.
174 */
175 public boolean getNeedClientAuth() {
176 return needClientAuth;
177 }
178
179 /**
180 * Sets whether client authentication should be required. Calling
181 * this method clears the <code>wantClientAuth</code> flag.
182 *
183 * @param needClientAuth whether client authentication should be required
184 */
185 public void setNeedClientAuth(boolean needClientAuth) {
186 this.wantClientAuth = false;
187 this.needClientAuth = needClientAuth;
188 }
189
190 /**
191 * Returns the cryptographic algorithm constraints.
192 *
193 * @return the cryptographic algorithm constraints, or null if the
194 * constraints have not been set
195 *
196 * @see #setAlgorithmConstraints(AlgorithmConstraints)
197 *
198 * @since 1.7
199 */
200 public AlgorithmConstraints getAlgorithmConstraints() {
201 return algorithmConstraints;
202 }
203
204 /**
205 * Sets the cryptographic algorithm constraints, which will be used
206 * in addition to any configured by the runtime environment.
207 * <p>
208 * If the <code>constraints</code> parameter is non-null, every
209 * cryptographic algorithm, key and algorithm parameters used in the
210 * SSL/TLS handshake must be permitted by the constraints.
211 *
212 * @param constraints the algorithm constraints (or null)
213 *
214 * @since 1.7
215 */
216 public void setAlgorithmConstraints(AlgorithmConstraints constraints) {
217 // the constraints object is immutable
218 this.algorithmConstraints = constraints;
219 }
220
221 /**
222 * Gets the endpoint identification algorithm.
223 *
224 * @return the endpoint identification algorithm, or null if none
225 * has been set.
226 *
227 * @see X509ExtendedTrustManager
228 * @see #setEndpointIdentificationAlgorithm(String)
229 *
230 * @since 1.7
231 */
232 public String getEndpointIdentificationAlgorithm() {
233 return identificationAlgorithm;
234 }
235
236 /**
237 * Sets the endpoint identification algorithm.
238 * <p>
239 * If the <code>algorithm</code> parameter is non-null or non-empty, the
240 * endpoint identification/verification procedures must be handled during
241 * SSL/TLS handshaking. This is to prevent man-in-the-middle attacks.
242 *
243 * @param algorithm The standard string name of the endpoint
244 * identification algorithm (or null). See Appendix A in the <a href=
245 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
246 * Java Cryptography Architecture API Specification & Reference </a>
247 * for information about standard algorithm names.
248 *
249 * @see X509ExtendedTrustManager
250 *
251 * @since 1.7
252 */
253 public void setEndpointIdentificationAlgorithm(String algorithm) {
254 this.identificationAlgorithm = algorithm;
255 }
256
257 }