1 /*
2 * Copyright (c) 2010, 2017, 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.util.List;
29
30 /**
31 * Extends the {@code SSLSession} interface to support additional
32 * session attributes.
33 *
34 * @since 1.7
35 */
36 public abstract class ExtendedSSLSession implements SSLSession {
37 /**
38 * Obtains an array of supported signature algorithms that the local side
39 * is willing to use.
40 * <p>
41 * Note: this method is used to indicate to the peer which signature
42 * algorithms may be used for digital signatures in TLS/DTLS 1.2. It is
43 * not meaningful for TLS/DTLS versions prior to 1.2.
44 * <p>
45 * The signature algorithm name must be a standard Java Security
46 * name (such as "SHA1withRSA", "SHA256withECDSA", and so on).
47 * See the <a href=
48 * "{@docRoot}/../specs/security/standard-names.html">
49 * Java Security Standard Algorithm Names</a> document
50 * for information about standard algorithm names.
51 * <p>
52 * Note: the local supported signature algorithms should conform to
53 * the algorithm constraints specified by
54 * {@link SSLParameters#getAlgorithmConstraints getAlgorithmConstraints()}
55 * method in {@code SSLParameters}.
56 *
57 * @return An array of supported signature algorithms, in descending
58 * order of preference. The return value is an empty array if
59 * no signature algorithm is supported.
60 *
61 * @see SSLParameters#getAlgorithmConstraints
62 */
63 public abstract String[] getLocalSupportedSignatureAlgorithms();
64
65 /**
66 * Obtains an array of supported signature algorithms that the peer is
67 * able to use.
68 * <p>
69 * Note: this method is used to indicate to the local side which signature
70 * algorithms may be used for digital signatures in TLS/DTLS 1.2. It is
71 * not meaningful for TLS/DTLS versions prior to 1.2.
72 * <p>
73 * The signature algorithm name must be a standard Java Security
74 * name (such as "SHA1withRSA", "SHA256withECDSA", and so on).
75 * See the <a href=
76 * "{@docRoot}/../specs/security/standard-names.html">
77 * Java Security Standard Algorithm Names</a> document
78 * for information about standard algorithm names.
79 *
80 * @return An array of supported signature algorithms, in descending
81 * order of preference. The return value is an empty array if
82 * the peer has not sent the supported signature algorithms.
83 *
84 * @see X509KeyManager
85 * @see X509ExtendedKeyManager
86 */
87 public abstract String[] getPeerSupportedSignatureAlgorithms();
88
89 /**
90 * Obtains an array of {@link CertificateAuthority} objects
91 * representing certificate authority indications sent by either
92 * a Client or a Server within a TLS session.
93 * <p>
94 * A Client may optionally send this information as part of a
95 * {@code ClientHello} message, during the TLS handshake. A
96 * Server may optionally send this information as part of a
97 * {@code CertificateRequest} message, during the TLS handshake.
98 * <p>
99 * If certificate authorities indications are available on a TLS
100 * session, the Client or Server certificate selection is expected
101 * to be based on it.
102 * <p>
103 * This is part of Certificate Authorities TLS extension (TLS 1.3).
104 * See further information in
105 * <a href="https://tools.ietf.org/html/draft-ietf-tls-tls13-20#section-4.2.4">TLS 1.3</a>.
106 *
107 * @see CertificateAuthority
108 *
109 * @return an array of CertificateAuthority objects with certificate
110 * authorities indications for this TLS session.
111 * Returns {@code null} if no information regarding
112 * certificate authorities is available.
113 * @throws UnsupportedOperationException if the underlying provider
114 * does not implement the operation
115 */
116 public CertificateAuthority[] getCertificateAuthorities() {
117 throw new UnsupportedOperationException();
118 }
119
120 /**
121 * Obtains a {@link List} containing all {@link SNIServerName}s
122 * of the requested Server Name Indication (SNI) extension.
123 * <P>
124 * In server mode, unless the return {@link List} is empty,
125 * the server should use the requested server names to guide its
126 * selection of an appropriate authentication certificate, and/or
127 * other aspects of security policy.
128 * <P>
129 * In client mode, unless the return {@link List} is empty,
130 * the client should use the requested server names to guide its
131 * endpoint identification of the peer's identity, and/or
132 * other aspects of security policy.
133 *
134 * @return a non-null immutable list of {@link SNIServerName}s of the
135 * requested server name indications. The returned list may be
136 * empty if no server name indications were requested.
137 * @throws UnsupportedOperationException if the underlying provider
138 * does not implement the operation
139 *
140 * @see SNIServerName
141 * @see X509ExtendedTrustManager
142 * @see X509ExtendedKeyManager
143 *
144 * @since 1.8
145 */
146 public List<SNIServerName> getRequestedServerNames() {
147 throw new UnsupportedOperationException();
148 }
149
150 /**
151 * Returns a {@link List} containing DER-encoded OCSP responses
152 * (using the ASN.1 type OCSPResponse defined in RFC 6960) for
153 * the client to verify status of the server's certificate during
154 * handshaking.
155 *
156 * <P>
157 * This method only applies to certificate-based server
158 * authentication. An {@link X509ExtendedTrustManager} will use the
159 * returned value for server certificate validation.
160 *
161 * @implSpec This method throws UnsupportedOperationException by default.
162 * Classes derived from ExtendedSSLSession must implement
163 * this method.
164 *
165 * @return a non-null unmodifiable list of byte arrays, each entry
166 * containing a DER-encoded OCSP response (using the
167 * ASN.1 type OCSPResponse defined in RFC 6960). The order
168 * of the responses must match the order of the certificates
169 * presented by the server in its Certificate message (See
170 * {@link SSLSession#getLocalCertificates()} for server mode,
171 * and {@link SSLSession#getPeerCertificates()} for client mode).
172 * It is possible that fewer response entries may be returned than
173 * the number of presented certificates. If an entry in the list
174 * is a zero-length byte array, it should be treated by the
175 * caller as if the OCSP entry for the corresponding certificate
176 * is missing. The returned list may be empty if no OCSP responses
177 * were presented during handshaking or if OCSP stapling is not
178 * supported by either endpoint for this handshake.
179 *
180 * @throws UnsupportedOperationException if the underlying provider
181 * does not implement the operation
182 *
183 * @see X509ExtendedTrustManager
184 *
185 * @since 9
186 */
187 public List<byte[]> getStatusResponses() {
188 throw new UnsupportedOperationException();
189 }
190 }