1 /*
2 * Copyright (c) 1999, 2016, 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.*;
29 import java.util.Objects;
30
31 import sun.security.jca.GetInstance;
32
33 /**
34 * Instances of this class represent a secure socket protocol
35 * implementation which acts as a factory for secure socket
36 * factories or {@code SSLEngine}s. This class is initialized
37 * with an optional set of key and trust managers and source of
38 * secure random bytes.
39 *
40 * <p> Every implementation of the Java platform is required to support the
41 * following standard {@code SSLContext} protocols:
42 * <ul>
43 * <li>{@code TLSv1}</li>
44 * <li>{@code TLSv1.1}</li>
45 * <li>{@code TLSv1.2}</li>
46 * </ul>
47 * These protocols are described in the <a href=
48 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SSLContext">
49 * SSLContext section</a> of the
50 * Java Cryptography Architecture Standard Algorithm Name Documentation.
51 * Consult the release documentation for your implementation to see if any
52 * other algorithms are supported.
53 *
54 * @since 1.4
55 */
56 public class SSLContext {
57 private final Provider provider;
58
59 private final SSLContextSpi contextSpi;
60
61 private final String protocol;
62
63 /**
64 * Creates an SSLContext object.
65 *
66 * @param contextSpi the delegate
67 * @param provider the provider
68 * @param protocol the protocol
69 */
70 protected SSLContext(SSLContextSpi contextSpi, Provider provider,
71 String protocol) {
72 this.contextSpi = contextSpi;
73 this.provider = provider;
74 this.protocol = protocol;
75 }
76
77 private static SSLContext defaultContext;
78
79 /**
80 * Returns the default SSL context.
81 *
82 * <p>If a default context was set using the {@link #setDefault
83 * SSLContext.setDefault()} method, it is returned. Otherwise, the first
84 * call of this method triggers the call
85 * {@code SSLContext.getInstance("Default")}.
86 * If successful, that object is made the default SSL context and returned.
87 *
88 * <p>The default context is immediately
89 * usable and does not require {@linkplain #init initialization}.
90 *
91 * @return the default SSL context
92 * @throws NoSuchAlgorithmException if the
93 * {@link SSLContext#getInstance SSLContext.getInstance()} call fails
94 * @since 1.6
95 */
96 public static synchronized SSLContext getDefault()
97 throws NoSuchAlgorithmException {
98 if (defaultContext == null) {
99 defaultContext = SSLContext.getInstance("Default");
100 }
101 return defaultContext;
102 }
103
104 /**
105 * Sets the default SSL context. It will be returned by subsequent calls
106 * to {@link #getDefault}. The default context must be immediately usable
107 * and not require {@linkplain #init initialization}.
108 *
109 * @param context the SSLContext
110 * @throws NullPointerException if context is null
111 * @throws SecurityException if a security manager exists and its
112 * {@code checkPermission} method does not allow
113 * {@code SSLPermission("setDefaultSSLContext")}
114 * @since 1.6
115 */
116 public static synchronized void setDefault(SSLContext context) {
117 if (context == null) {
118 throw new NullPointerException();
119 }
120 SecurityManager sm = System.getSecurityManager();
121 if (sm != null) {
122 sm.checkPermission(new SSLPermission("setDefaultSSLContext"));
123 }
124 defaultContext = context;
125 }
126
127 /**
128 * Returns a {@code SSLContext} object that implements the
129 * specified secure socket protocol.
130 *
131 * <p> This method traverses the list of registered security Providers,
132 * starting with the most preferred Provider.
133 * A new SSLContext object encapsulating the
134 * SSLContextSpi implementation from the first
135 * Provider that supports the specified protocol is returned.
136 *
137 * <p> Note that the list of registered providers may be retrieved via
138 * the {@link Security#getProviders() Security.getProviders()} method.
139 *
140 * @implNote
141 * The JDK Reference Implementation additionally uses the
142 * {@code jdk.security.provider.preferred}
143 * {@link Security#getProperty(String) Security} property to determine
144 * the preferred provider order for the specified algorithm. This
145 * may be different than the order of providers returned by
146 * {@link Security#getProviders() Security.getProviders()}.
147 *
148 * @param protocol the standard name of the requested protocol.
149 * See the SSLContext section in the <a href=
150 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SSLContext">
151 * Java Cryptography Architecture Standard Algorithm Name
152 * Documentation</a>
153 * for information about standard protocol names.
154 *
155 * @return the new {@code SSLContext} object
156 *
157 * @throws NoSuchAlgorithmException if no {@code Provider} supports a
158 * {@code SSLContextSpi} implementation for the
159 * specified protocol
160 *
161 * @throws NullPointerException if {@code protocol} is {@code null}
162 *
163 * @see java.security.Provider
164 */
165 public static SSLContext getInstance(String protocol)
166 throws NoSuchAlgorithmException {
167 Objects.requireNonNull(protocol, "null protocol name");
168 GetInstance.Instance instance = GetInstance.getInstance
169 ("SSLContext", SSLContextSpi.class, protocol);
170 return new SSLContext((SSLContextSpi)instance.impl, instance.provider,
171 protocol);
172 }
173
174 /**
175 * Returns a {@code SSLContext} object that implements the
176 * specified secure socket protocol.
177 *
178 * <p> A new SSLContext object encapsulating the
179 * SSLContextSpi implementation from the specified provider
180 * is returned. The specified provider must be registered
181 * in the security provider list.
182 *
183 * <p> Note that the list of registered providers may be retrieved via
184 * the {@link Security#getProviders() Security.getProviders()} method.
185 *
186 * @param protocol the standard name of the requested protocol.
187 * See the SSLContext section in the <a href=
188 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SSLContext">
189 * Java Cryptography Architecture Standard Algorithm Name
190 * Documentation</a>
191 * for information about standard protocol names.
192 *
193 * @param provider the name of the provider.
194 *
195 * @return the new {@code SSLContext} object
196 *
197 * @throws IllegalArgumentException if the provider name is
198 * {@code null} or empty
199 *
200 * @throws NoSuchAlgorithmException if a {@code SSLContextSpi}
201 * implementation for the specified protocol is not
202 * available from the specified provider
203 *
204 * @throws NoSuchProviderException if the specified provider is not
205 * registered in the security provider list
206 *
207 * @throws NullPointerException if {@code protocol} is {@code null}
208 *
209 * @see java.security.Provider
210 */
211 public static SSLContext getInstance(String protocol, String provider)
212 throws NoSuchAlgorithmException, NoSuchProviderException {
213 Objects.requireNonNull(protocol, "null protocol name");
214 GetInstance.Instance instance = GetInstance.getInstance
215 ("SSLContext", SSLContextSpi.class, protocol, provider);
216 return new SSLContext((SSLContextSpi)instance.impl, instance.provider,
217 protocol);
218 }
219
220 /**
221 * Returns a {@code SSLContext} object that implements the
222 * specified secure socket protocol.
223 *
224 * <p> A new SSLContext object encapsulating the
225 * SSLContextSpi implementation from the specified Provider
226 * object is returned. Note that the specified Provider object
227 * does not have to be registered in the provider list.
228 *
229 * @param protocol the standard name of the requested protocol.
230 * See the SSLContext section in the <a href=
231 * "{@docRoot}/../technotes/guides/security/StandardNames.html#SSLContext">
232 * Java Cryptography Architecture Standard Algorithm Name
233 * Documentation</a>
234 * for information about standard protocol names.
235 *
236 * @param provider an instance of the provider.
237 *
238 * @return the new {@code SSLContext} object
239 *
240 * @throws IllegalArgumentException if the provider is {@code null}
241 *
242 * @throws NoSuchAlgorithmException if a {@code SSLContextSpi}
243 * implementation for the specified protocol is not available
244 * from the specified {@code Provider} object
245 *
246 * @throws NullPointerException if {@code protocol} is {@code null}
247 *
248 * @see java.security.Provider
249 */
250 public static SSLContext getInstance(String protocol, Provider provider)
251 throws NoSuchAlgorithmException {
252 Objects.requireNonNull(protocol, "null protocol name");
253 GetInstance.Instance instance = GetInstance.getInstance
254 ("SSLContext", SSLContextSpi.class, protocol, provider);
255 return new SSLContext((SSLContextSpi)instance.impl, instance.provider,
256 protocol);
257 }
258
259 /**
260 * Returns the protocol name of this {@code SSLContext} object.
261 *
262 * <p>This is the same name that was specified in one of the
263 * {@code getInstance} calls that created this
264 * {@code SSLContext} object.
265 *
266 * @return the protocol name of this {@code SSLContext} object.
267 */
268 public final String getProtocol() {
269 return this.protocol;
270 }
271
272 /**
273 * Returns the provider of this {@code SSLContext} object.
274 *
275 * @return the provider of this {@code SSLContext} object
276 */
277 public final Provider getProvider() {
278 return this.provider;
279 }
280
281 /**
282 * Initializes this context. Either of the first two parameters
283 * may be null in which case the installed security providers will
284 * be searched for the highest priority implementation of the
285 * appropriate factory. Likewise, the secure random parameter may
286 * be null in which case the default implementation will be used.
287 * <P>
288 * Only the first instance of a particular key and/or trust manager
289 * implementation type in the array is used. (For example, only
290 * the first javax.net.ssl.X509KeyManager in the array will be used.)
291 *
292 * @param km the sources of authentication keys or null
293 * @param tm the sources of peer authentication trust decisions or null
294 * @param random the source of randomness for this generator or null
295 * @throws KeyManagementException if this operation fails
296 */
297 public final void init(KeyManager[] km, TrustManager[] tm,
298 SecureRandom random)
299 throws KeyManagementException {
300 contextSpi.engineInit(km, tm, random);
301 }
302
303 /**
304 * Returns a {@code SocketFactory} object for this
305 * context.
306 *
307 * @return the {@code SocketFactory} object
308 * @throws UnsupportedOperationException if the underlying provider
309 * does not implement the operation.
310 * @throws IllegalStateException if the SSLContextImpl requires
311 * initialization and the {@code init()} has not been called
312 */
313 public final SSLSocketFactory getSocketFactory() {
314 return contextSpi.engineGetSocketFactory();
315 }
316
317 /**
318 * Returns a {@code ServerSocketFactory} object for
319 * this context.
320 *
321 * @return the {@code ServerSocketFactory} object
322 * @throws UnsupportedOperationException if the underlying provider
323 * does not implement the operation.
324 * @throws IllegalStateException if the SSLContextImpl requires
325 * initialization and the {@code init()} has not been called
326 */
327 public final SSLServerSocketFactory getServerSocketFactory() {
328 return contextSpi.engineGetServerSocketFactory();
329 }
330
331 /**
332 * Creates a new {@code SSLEngine} using this context.
333 * <P>
334 * Applications using this factory method are providing no hints
335 * for an internal session reuse strategy. If hints are desired,
336 * {@link #createSSLEngine(String, int)} should be used
337 * instead.
338 * <P>
339 * Some cipher suites (such as Kerberos) require remote hostname
340 * information, in which case this factory method should not be used.
341 *
342 * @return the {@code SSLEngine} object
343 * @throws UnsupportedOperationException if the underlying provider
344 * does not implement the operation.
345 * @throws IllegalStateException if the SSLContextImpl requires
346 * initialization and the {@code init()} has not been called
347 * @since 1.5
348 */
349 public final SSLEngine createSSLEngine() {
350 try {
351 return contextSpi.engineCreateSSLEngine();
352 } catch (AbstractMethodError e) {
353 UnsupportedOperationException unsup =
354 new UnsupportedOperationException(
355 "Provider: " + getProvider() +
356 " doesn't support this operation");
357 unsup.initCause(e);
358 throw unsup;
359 }
360 }
361
362 /**
363 * Creates a new {@code SSLEngine} using this context using
364 * advisory peer information.
365 * <P>
366 * Applications using this factory method are providing hints
367 * for an internal session reuse strategy.
368 * <P>
369 * Some cipher suites (such as Kerberos) require remote hostname
370 * information, in which case peerHost needs to be specified.
371 *
372 * @param peerHost the non-authoritative name of the host
373 * @param peerPort the non-authoritative port
374 * @return the new {@code SSLEngine} object
375 * @throws UnsupportedOperationException if the underlying provider
376 * does not implement the operation.
377 * @throws IllegalStateException if the SSLContextImpl requires
378 * initialization and the {@code init()} has not been called
379 * @since 1.5
380 */
381 public final SSLEngine createSSLEngine(String peerHost, int peerPort) {
382 try {
383 return contextSpi.engineCreateSSLEngine(peerHost, peerPort);
384 } catch (AbstractMethodError e) {
385 UnsupportedOperationException unsup =
386 new UnsupportedOperationException(
387 "Provider: " + getProvider() +
388 " does not support this operation");
389 unsup.initCause(e);
390 throw unsup;
391 }
392 }
393
394 /**
395 * Returns the server session context, which represents the set of
396 * SSL sessions available for use during the handshake phase of
397 * server-side SSL sockets.
398 * <P>
399 * This context may be unavailable in some environments, in which
400 * case this method returns null. For example, when the underlying
401 * SSL provider does not provide an implementation of SSLSessionContext
402 * interface, this method returns null. A non-null session context
403 * is returned otherwise.
404 *
405 * @return server session context bound to this SSL context
406 */
407 public final SSLSessionContext getServerSessionContext() {
408 return contextSpi.engineGetServerSessionContext();
409 }
410
411 /**
412 * Returns the client session context, which represents the set of
413 * SSL sessions available for use during the handshake phase of
414 * client-side SSL sockets.
415 * <P>
416 * This context may be unavailable in some environments, in which
417 * case this method returns null. For example, when the underlying
418 * SSL provider does not provide an implementation of SSLSessionContext
419 * interface, this method returns null. A non-null session context
420 * is returned otherwise.
421 *
422 * @return client session context bound to this SSL context
423 */
424 public final SSLSessionContext getClientSessionContext() {
425 return contextSpi.engineGetClientSessionContext();
426 }
427
428 /**
429 * Returns a copy of the SSLParameters indicating the default
430 * settings for this SSL context.
431 *
432 * <p>The parameters will always have the ciphersuites and protocols
433 * arrays set to non-null values.
434 *
435 * @return a copy of the SSLParameters object with the default settings
436 * @throws UnsupportedOperationException if the default SSL parameters
437 * could not be obtained.
438 * @since 1.6
439 */
440 public final SSLParameters getDefaultSSLParameters() {
441 return contextSpi.engineGetDefaultSSLParameters();
442 }
443
444 /**
445 * Returns a copy of the SSLParameters indicating the supported
446 * settings for this SSL context.
447 *
448 * <p>The parameters will always have the ciphersuites and protocols
449 * arrays set to non-null values.
450 *
451 * @return a copy of the SSLParameters object with the supported
452 * settings
453 * @throws UnsupportedOperationException if the supported SSL parameters
454 * could not be obtained.
455 * @since 1.6
456 */
457 public final SSLParameters getSupportedSSLParameters() {
458 return contextSpi.engineGetSupportedSSLParameters();
459 }
460
461 }