src/java.base/share/classes/javax/net/ssl/ExtendedSSLSession.java - master - githubmirror/panama-vector

src/java.base/share/classes/javax/net/ssl/ExtendedSSLSession.java
276 строк12 KB
Bradford Wetmore
8341346: Add support for exporting TLS Keying Material
31 май 2025, 02:06
31 май 2025, 02:062926435
/*
 * 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.
     * <p>
     * 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.
     * <p>
     * The signature algorithm name must be a standard Java Security
     * name (such as "SHA1withRSA", "SHA256withECDSA", and so on).
     * See the <a href=
     * "{@docRoot}/../specs/security/standard-names.html">
     * Java Security Standard Algorithm Names</a> document
     * for information about standard algorithm names.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * The signature algorithm name must be a standard Java Security
     * name (such as "SHA1withRSA", "SHA256withECDSA", and so on).
     * See the <a href=
     * "{@docRoot}/../specs/security/standard-names.html">
     * Java Security Standard Algorithm Names</a> 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.
     * <P>
     * 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.
     * <P>
     * 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<SNIServerName> 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.
     *
     * <P>
     * 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<byte[]> getStatusResponses() {
        throw new UnsupportedOperationException();
    }

    /**
     * Generates Exported Keying Material (EKM) calculated according to the
     * algorithms defined in RFCs 5705/8446.
     * <P>
     * 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.
     * <P>
     * {@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
     *                <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
     *                Java Security Standard Algorithm Names Specification</a>
     *                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.
     * <P>
     * 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.
     * <P>
     * {@code label} will be converted to bytes using
     * the {@link java.nio.charset.StandardCharsets#UTF_8}
     * character encoding.
     * <P>
     * 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");
    }
}