1 /*
2 * Copyright (c) 1999, 2015, 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
30 /**
31 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
32 * for the {@code SSLContext} class.
33 *
34 * <p> All the abstract methods in this class must be implemented by each
35 * cryptographic service provider who wishes to supply the implementation
36 * of a particular SSL context.
37 *
38 * @since 1.4
39 * @see SSLContext
40 */
41 public abstract class SSLContextSpi {
42 /**
43 * Initializes this context.
44 *
45 * @param km the sources of authentication keys
46 * @param tm the sources of peer authentication trust decisions
47 * @param sr the source of randomness
48 * @throws KeyManagementException if this operation fails
49 * @see SSLContext#init(KeyManager [], TrustManager [], SecureRandom)
50 */
51 protected abstract void engineInit(KeyManager[] km, TrustManager[] tm,
52 SecureRandom sr) throws KeyManagementException;
53
54 /**
55 * Returns a {@code SocketFactory} object for this
56 * context.
57 *
58 * @return the {@code SocketFactory} object
59 * @throws UnsupportedOperationException if the underlying provider
60 * does not implement the operation.
61 * @throws IllegalStateException if the SSLContextImpl requires
62 * initialization and the {@code engineInit()}
63 * has not been called
64 * @see javax.net.ssl.SSLContext#getSocketFactory()
65 */
66 protected abstract SSLSocketFactory engineGetSocketFactory();
67
68 /**
69 * Returns a {@code ServerSocketFactory} object for
70 * this context.
71 *
72 * @return the {@code ServerSocketFactory} object
73 * @throws UnsupportedOperationException if the underlying provider
74 * does not implement the operation.
75 * @throws IllegalStateException if the SSLContextImpl requires
76 * initialization and the {@code engineInit()}
77 * has not been called
78 * @see javax.net.ssl.SSLContext#getServerSocketFactory()
79 */
80 protected abstract SSLServerSocketFactory engineGetServerSocketFactory();
81
82 /**
83 * Creates a new {@code SSLEngine} using this context.
84 * <P>
85 * Applications using this factory method are providing no hints
86 * for an internal session reuse strategy. If hints are desired,
87 * {@link #engineCreateSSLEngine(String, int)} should be used
88 * instead.
89 * <P>
90 * Some cipher suites (such as Kerberos) require remote hostname
91 * information, in which case this factory method should not be used.
92 *
93 * @return the {@code SSLEngine} Object
94 * @throws IllegalStateException if the SSLContextImpl requires
95 * initialization and the {@code engineInit()}
96 * has not been called
97 *
98 * @see SSLContext#createSSLEngine()
99 *
100 * @since 1.5
101 */
102 protected abstract SSLEngine engineCreateSSLEngine();
103
104 /**
105 * Creates a {@code SSLEngine} using this context.
106 * <P>
107 * Applications using this factory method are providing hints
108 * for an internal session reuse strategy.
109 * <P>
110 * Some cipher suites (such as Kerberos) require remote hostname
111 * information, in which case peerHost needs to be specified.
112 *
113 * @param host the non-authoritative name of the host
114 * @param port the non-authoritative port
115 * @return the {@code SSLEngine} Object
116 * @throws IllegalStateException if the SSLContextImpl requires
117 * initialization and the {@code engineInit()}
118 * has not been called
119 *
120 * @see SSLContext#createSSLEngine(String, int)
121 *
122 * @since 1.5
123 */
124 protected abstract SSLEngine engineCreateSSLEngine(String host, int port);
125
126 /**
127 * Returns a server {@code SSLSessionContext} object for
128 * this context.
129 *
130 * @return the {@code SSLSessionContext} object
131 * @see javax.net.ssl.SSLContext#getServerSessionContext()
132 */
133 protected abstract SSLSessionContext engineGetServerSessionContext();
134
135 /**
136 * Returns a client {@code SSLSessionContext} object for
137 * this context.
138 *
139 * @return the {@code SSLSessionContext} object
140 * @see javax.net.ssl.SSLContext#getClientSessionContext()
141 */
142 protected abstract SSLSessionContext engineGetClientSessionContext();
143
144 private SSLSocket getDefaultSocket() {
145 try {
146 SSLSocketFactory factory = engineGetSocketFactory();
147 return (SSLSocket)factory.createSocket();
148 } catch (java.io.IOException e) {
149 throw new UnsupportedOperationException("Could not obtain parameters", e);
150 }
151 }
152
153 /**
154 * Returns a copy of the SSLParameters indicating the default
155 * settings for this SSL context.
156 *
157 * <p>The parameters will always have the ciphersuite and protocols
158 * arrays set to non-null values.
159 *
160 * <p>The default implementation obtains the parameters from an
161 * SSLSocket created by calling the
162 * {@linkplain javax.net.SocketFactory#createSocket
163 * SocketFactory.createSocket()} method of this context's SocketFactory.
164 *
165 * @return a copy of the SSLParameters object with the default settings
166 * @throws UnsupportedOperationException if the default SSL parameters
167 * could not be obtained.
168 *
169 * @since 1.6
170 */
171 protected SSLParameters engineGetDefaultSSLParameters() {
172 SSLSocket socket = getDefaultSocket();
173 return socket.getSSLParameters();
174 }
175
176 /**
177 * Returns a copy of the SSLParameters indicating the maximum supported
178 * settings for this SSL context.
179 *
180 * <p>The parameters will always have the ciphersuite and protocols
181 * arrays set to non-null values.
182 *
183 * <p>The default implementation obtains the parameters from an
184 * SSLSocket created by calling the
185 * {@linkplain javax.net.SocketFactory#createSocket
186 * SocketFactory.createSocket()} method of this context's SocketFactory.
187 *
188 * @return a copy of the SSLParameters object with the maximum supported
189 * settings
190 * @throws UnsupportedOperationException if the supported SSL parameters
191 * could not be obtained.
192 *
193 * @since 1.6
194 */
195 protected SSLParameters engineGetSupportedSSLParameters() {
196 SSLSocket socket = getDefaultSocket();
197 SSLParameters params = new SSLParameters();
198 params.setCipherSuites(socket.getSupportedCipherSuites());
199 params.setProtocols(socket.getSupportedProtocols());
200 return params;
201 }
202
203 }