/* * Copyright (c) 2010, 2025, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.net.ssl; import java.util.List; import javax.crypto.SecretKey; /** * Extends the {@code SSLSession} interface to support additional * session attributes. * * @since 1.7 */ public abstract class ExtendedSSLSession implements SSLSession { /** * Constructor for subclasses to call. */ public ExtendedSSLSession() {} /** * Obtains an array of supported signature algorithms that the local side * is willing to use. *

* Note: this method is used to indicate to the peer which signature * algorithms may be used for digital signatures in TLS/DTLS 1.2. It is * not meaningful for TLS/DTLS versions prior to 1.2. *

* The signature algorithm name must be a standard Java Security * name (such as "SHA1withRSA", "SHA256withECDSA", and so on). * See the * Java Security Standard Algorithm Names document * for information about standard algorithm names. *

* Note: the local supported signature algorithms should conform to * the algorithm constraints specified by * {@link SSLParameters#getAlgorithmConstraints getAlgorithmConstraints()} * method in {@code SSLParameters}. * * @return An array of supported signature algorithms, in descending * order of preference. The return value is an empty array if * no signature algorithm is supported. * * @spec security/standard-names.html Java Security Standard Algorithm Names * @see SSLParameters#getAlgorithmConstraints */ public abstract String[] getLocalSupportedSignatureAlgorithms(); /** * Obtains an array of supported signature algorithms that the peer is * able to use. *

* Note: this method is used to indicate to the local side which signature * algorithms may be used for digital signatures in TLS/DTLS 1.2. It is * not meaningful for TLS/DTLS versions prior to 1.2. *

* The signature algorithm name must be a standard Java Security * name (such as "SHA1withRSA", "SHA256withECDSA", and so on). * See the * Java Security Standard Algorithm Names document * for information about standard algorithm names. * * @return An array of supported signature algorithms, in descending * order of preference. The return value is an empty array if * the peer has not sent the supported signature algorithms. * * @spec security/standard-names.html Java Security Standard Algorithm Names * @see X509KeyManager * @see X509ExtendedKeyManager */ public abstract String[] getPeerSupportedSignatureAlgorithms(); /** * Obtains a {@link List} containing all {@link SNIServerName}s * of the requested Server Name Indication (SNI) extension. *

* In server mode, unless the return {@link List} is empty, * the server should use the requested server names to guide its * selection of an appropriate authentication certificate, and/or * other aspects of security policy. *

* In client mode, unless the return {@link List} is empty, * the client should use the requested server names to guide its * endpoint identification of the peer's identity, and/or * other aspects of security policy. * * @return a non-null immutable list of {@link SNIServerName}s of the * requested server name indications. The returned list may be * empty if no server name indications were requested. * @throws UnsupportedOperationException if the underlying provider * does not implement the operation * * @see SNIServerName * @see X509ExtendedTrustManager * @see X509ExtendedKeyManager * * @since 1.8 */ public List getRequestedServerNames() { throw new UnsupportedOperationException(); } /** * Returns a {@link List} containing DER-encoded OCSP responses * (using the ASN.1 type OCSPResponse defined in RFC 6960) for * the client to verify status of the server's certificate during * handshaking. * *

* This method only applies to certificate-based server * authentication. An {@link X509ExtendedTrustManager} will use the * returned value for server certificate validation. * * @implSpec This method throws UnsupportedOperationException by default. * Classes derived from ExtendedSSLSession must implement * this method. * * @return a non-null unmodifiable list of byte arrays, each entry * containing a DER-encoded OCSP response (using the * ASN.1 type OCSPResponse defined in RFC 6960). The order * of the responses must match the order of the certificates * presented by the server in its Certificate message (See * {@link SSLSession#getLocalCertificates()} for server mode, * and {@link SSLSession#getPeerCertificates()} for client mode). * It is possible that fewer response entries may be returned than * the number of presented certificates. If an entry in the list * is a zero-length byte array, it should be treated by the * caller as if the OCSP entry for the corresponding certificate * is missing. The returned list may be empty if no OCSP responses * were presented during handshaking or if OCSP stapling is not * supported by either endpoint for this handshake. * * @throws UnsupportedOperationException if the underlying provider * does not implement the operation * * @see X509ExtendedTrustManager * * @since 9 */ public List getStatusResponses() { throw new UnsupportedOperationException(); } /** * Generates Exported Keying Material (EKM) calculated according to the * algorithms defined in RFCs 5705/8446. *

* RFC 5705 (for (D)TLSv1.2 and earlier) calculates different EKM * values depending on whether {@code context} is null or non-null/empty. * RFC 8446 (TLSv1.3) treats a null context as non-null/empty. *

* {@code label} will be converted to bytes using * the {@link java.nio.charset.StandardCharsets#UTF_8} * character encoding. * * @spec https://www.rfc-editor.org/info/rfc5705 * RFC 5705: Keying Material Exporters for Transport Layer * Security (TLS) * @spec https://www.rfc-editor.org/info/rfc8446 * RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3 * * @implSpec The default implementation throws * {@code UnsupportedOperationException}. * * @param keyAlg the algorithm of the resultant {@code SecretKey} object. * See the SecretKey Algorithms section in the * * Java Security Standard Algorithm Names Specification * for information about standard secret key algorithm * names. * @param label the label bytes used in the EKM calculation. * {@code label} will be converted to a {@code byte[]} * before the operation begins. * @param context the context bytes used in the EKM calculation, or null * @param length the number of bytes of EKM material needed * * @throws SSLKeyException if the key cannot be generated * @throws IllegalArgumentException if {@code keyAlg} is empty, * {@code length} is non-positive, or if the {@code label} or * {@code context} length can not be accommodated * @throws NullPointerException if {@code keyAlg} or {@code label} is null * @throws IllegalStateException if this session does not have the * necessary key generation material (for example, a session * under construction during handshaking) * @throws UnsupportedOperationException if the underlying provider * does not implement the operation * * @return a {@code SecretKey} that contains {@code length} bytes of the * EKM material * * @since 25 */ public SecretKey exportKeyingMaterialKey(String keyAlg, String label, byte[] context, int length) throws SSLKeyException { throw new UnsupportedOperationException( "Underlying provider does not implement the method"); } /** * Generates Exported Keying Material (EKM) calculated according to the * algorithms defined in RFCs 5705/8446. *

* RFC 5705 (for (D)TLSv1.2 and earlier) calculates different EKM * values depending on whether {@code context} is null or non-null/empty. * RFC 8446 (TLSv1.3) treats a null context as non-null/empty. *

* {@code label} will be converted to bytes using * the {@link java.nio.charset.StandardCharsets#UTF_8} * character encoding. *

* Depending on the chosen underlying key derivation mechanism, the * raw bytes might not be extractable/exportable. In such cases, the * {@link #exportKeyingMaterialKey(String, String, byte[], int)} method * should be used instead to access the generated key material. * * @spec https://www.rfc-editor.org/info/rfc5705 * RFC 5705: Keying Material Exporters for Transport Layer * Security (TLS) * @spec https://www.rfc-editor.org/info/rfc8446 * RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3 * * @implSpec The default implementation throws * {@code UnsupportedOperationException}. * * @param label the label bytes used in the EKM calculation. * {@code label} will be converted to a {@code byte[]} * before the operation begins. * @param context the context bytes used in the EKM calculation, or null * @param length the number of bytes of EKM material needed * * @throws SSLKeyException if the key cannot be generated * @throws IllegalArgumentException if {@code length} is non-positive, * or if the {@code label} or {@code context} length can * not be accommodated * @throws NullPointerException if {@code label} is null * @throws IllegalStateException if this session does not have the * necessary key generation material (for example, a session * under construction during handshaking) * @throws UnsupportedOperationException if the underlying provider * does not implement the operation, or if the derived * keying material is not extractable * * @return a byte array of size {@code length} that contains the EKM * material * @since 25 */ public byte[] exportKeyingMaterialData( String label, byte[] context, int length) throws SSLKeyException { throw new UnsupportedOperationException( "Underlying provider does not implement the method"); } }