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