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