1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package javax.net.ssl;
19
20import java.io.IOException;
21import java.net.InetAddress;
22import java.net.ServerSocket;
23
24/**
25 * The extension of {@code ServerSocket} which provides secure server sockets
26 * based on protocols like SSL, TLS, or others.
27 */
28public abstract class SSLServerSocket extends ServerSocket {
29
30    /**
31     * Only to be used by subclasses.
32     * <p>
33     * Creates a TCP server socket with the default authentication context.
34     *
35     * @throws IOException
36     *             if creating the socket fails.
37     */
38    protected SSLServerSocket() throws IOException {
39    }
40
41    /**
42     * Only to be used by subclasses.
43     * <p>
44     * Creates a TCP server socket on the specified port with the default
45     * authentication context. The connection's default backlog size is 50
46     * connections.
47     * @param port
48     *            the port to listen on.
49     * @throws IOException
50     *             if creating the socket fails.
51     */
52    protected SSLServerSocket(int port) throws IOException {
53        super(port);
54    }
55
56    /**
57     * Only to be used by subclasses.
58     * <p>
59     * Creates a TCP server socket on the specified port using the specified
60     * backlog and the default authentication context.
61     *
62     * @param port
63     *            the port to listen on.
64     * @param backlog
65     *            the number of pending connections to queue.
66     * @throws IOException
67     *             if creating the socket fails.
68     */
69    protected SSLServerSocket(int port, int backlog) throws IOException {
70        super(port, backlog);
71    }
72
73    /**
74     * Only to be used by subclasses.
75     * <p>
76     * Creates a TCP server socket on the specified port, using the specified
77     * backlog, listening on the specified interface, and using the default
78     * authentication context.
79     *
80     * @param port
81     *            the port the listen on.
82     * @param backlog
83     *            the number of pending connections to queue.
84     * @param address
85     *            the address of the interface to accept connections on.
86     * @throws IOException
87     *             if creating the socket fails.
88     */
89    protected SSLServerSocket(int port, int backlog, InetAddress address) throws IOException {
90        super(port, backlog, address);
91    }
92
93    /**
94     * Returns the names of the enabled cipher suites to be used for new
95     * connections.
96     *
97     * @return the names of the enabled cipher suites to be used for new
98     *         connections.
99     */
100    public abstract String[] getEnabledCipherSuites();
101
102    /**
103     * Sets the names of the cipher suites to be enabled for new connections.
104     * Only cipher suites returned by {@link #getSupportedCipherSuites()} are
105     * allowed.
106     *
107     * @param suites
108     *            the names of the to be enabled cipher suites.
109     * @throws IllegalArgumentException
110     *             if one of the cipher suite names is not supported.
111     */
112    public abstract void setEnabledCipherSuites(String[] suites);
113
114    /**
115     * Returns the names of the supported cipher suites.
116     *
117     * @return the names of the supported cipher suites.
118     */
119    public abstract String[] getSupportedCipherSuites();
120
121    /**
122     * Returns the names of the supported protocols.
123     *
124     * @return the names of the supported protocols.
125     */
126    public abstract String[] getSupportedProtocols();
127
128    /**
129     * Returns the names of the enabled protocols to be used for new
130     * connections.
131     *
132     * @return the names of the enabled protocols to be used for new
133     *         connections.
134     */
135    public abstract String[] getEnabledProtocols();
136
137    /**
138     * Sets the names of the protocols to be enabled for new connections. Only
139     * protocols returned by {@link #getSupportedProtocols()} are allowed.
140     *
141     * @param protocols
142     *            the names of the to be enabled protocols.
143     * @throws IllegalArgumentException
144     *             if one of the protocols is not supported.
145     */
146    public abstract void setEnabledProtocols(String[] protocols);
147
148    /**
149     * Sets whether server-mode connections will be configured to require client
150     * authentication. The client authentication is one of the following:
151     * <ul>
152     * <li>authentication required</li>
153     * <li>authentication requested</li>
154     * <li>no authentication needed</li>
155     * </ul>
156     * This method overrides the setting of {@link #setWantClientAuth(boolean)}.
157     *
158     * @param need
159     *            {@code true} if client authentication is required,
160     *            {@code false} if no authentication is needed.
161     */
162    public abstract void setNeedClientAuth(boolean need);
163
164    /**
165     * Returns whether server-mode connections will be configured to require
166     * client authentication.
167     *
168     * @return {@code true} if client authentication is required, {@code false}
169     *         if no client authentication is needed.
170     */
171    public abstract boolean getNeedClientAuth();
172
173    /**
174     * Sets whether server-mode connections will be configured to request client
175     * authentication. The client authentication is one of the following:
176     * <ul>
177     * <li>authentication required</li>
178     * <li>authentication requested</li>
179     * <li>no authentication needed</li>
180     * </ul>
181     * This method overrides the setting of {@link #setNeedClientAuth(boolean)}.
182     *
183     * @param want
184     *            {@code true} if client authentication should be requested,
185     *            {@code false} if no authentication is needed.
186     */
187    public abstract void setWantClientAuth(boolean want);
188
189    /**
190     * Returns whether server-mode connections will be configured to request
191     * client authentication.
192     *
193     * @return {@code true} is client authentication will be requested,
194     *         {@code false} if no client authentication is needed.
195     */
196    public abstract boolean getWantClientAuth();
197
198    /**
199     * Sets whether new connections should act in client mode when handshaking.
200     *
201     * @param mode
202     *            {@code true} if new connections should act in client mode,
203     *            {@code false} if not.
204     */
205    public abstract void setUseClientMode(boolean mode);
206
207    /**
208     * Returns whether new connection will act in client mode when handshaking.
209     *
210     * @return {@code true} if new connections will act in client mode when
211     *         handshaking, {@code false} if not.
212     */
213    public abstract boolean getUseClientMode();
214
215    /**
216     * Sets whether new SSL sessions may be established for new connections.
217     *
218     * @param flag
219     *            {@code true} if new SSL sessions may be established,
220     *            {@code false} if existing SSL sessions must be reused.
221     */
222    public abstract void setEnableSessionCreation(boolean flag);
223
224    /**
225     * Returns whether new SSL sessions may be established for new connections.
226     *
227     * @return {@code true} if new SSL sessions may be established,
228     *         {@code false} if existing SSL sessions must be reused.
229     */
230    public abstract boolean getEnableSessionCreation();
231}
232