1 /*
2 * Copyright 2024 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.handler.ssl;
17
18 import java.security.cert.CertificateException;
19 import java.security.cert.PKIXBuilderParameters;
20 import java.security.cert.X509Certificate;
21 import java.util.Date;
22 import javax.net.ssl.SSLEngine;
23 import javax.net.ssl.SSLSession;
24 import javax.net.ssl.TrustManager;
25 import javax.net.ssl.X509TrustManager;
26
27 /**
28 * An interface that {@code TrustManager} instances can implement, to be notified of resumed SSL sessions.
29 * <p>
30 * A {@link TrustManager} is called during the TLS handshake, and make decisions about whether
31 * the connected peer can be trusted or not. TLS include a feature where previously established sessions can
32 * be resumed without going through the trust verification steps.
33 * <p>
34 * When an {@link SSLSession} is resumed, any values added to it in the prior session may be lost.
35 * This interface gives {@link TrustManager} implementations an opportunity to restore any
36 * values they would normally add during the TLS handshake, before the handshake completion is signalled
37 * to the application.
38 * <p>
39 * When a session is resumed, the {@link SslHandler} will call the relevant {@code resume*} method,
40 * before completing the handshake promise and sending the {@link SslHandshakeCompletionEvent#SUCCESS}
41 * event down the pipeline.
42 * <p>
43 * A trust manager that does not add values to the handshake session in its {@code check*} methods,
44 * will typically not have any need to implement this interface.
45 * <p>
46 * <strong>Note:</strong> The implementing trust manager class must extend {@code X509ExtendedTrustManager},
47 * otherwise this interface will be ignored by the {@link SslHandler}.
48 */
49 public interface ResumableX509ExtendedTrustManager extends X509TrustManager {
50 /**
51 * Given the partial or complete certificate chain recovered from the session ticket,
52 * and the {@link SSLEngine} being used, restore the application state of the associated
53 * SSL session.
54 * <p>
55 * This method should obtain the {@link SSLSession} from the {@link SSLEngine#getSession()}
56 * method.
57 * <p>
58 * <strong>Note:</strong> If this method throws {@link CertificateException}, the TLS handshake will not
59 * necessarily be rejected. The TLS handshake "Finished" message may have already been sent to the peer
60 * by the time this method is called.
61 * <p>
62 * Implementors should be aware, that peers may make multiple connection attempts using the same session
63 * ticket. So this method may be called more than once for the same client, even if prior calls have thrown
64 * exceptions or invalidated their sessions.
65 * <p>
66 * The given certificate chain is not guaranteed to be the authenticated chain. Implementations that need the
67 * authenticated certificate chain will have to re-authenticate the certificates. It is recommended to do so
68 * with a {@link PKIXBuilderParameters#setDate(Date)} set to the session creation date from
69 * {@link SSLSession#getCreationTime()}. Otherwise, the authentication may fail due to the certificate expiring
70 * before the session ticket.
71 * <p>
72 * This method is called on the server-side, restoring sessions for clients.
73 *
74 * @param chain The peer certificate chain.
75 * @param engine The begine used for this connection.
76 * @throws CertificateException If the session cannot be restored. Locally, the handshake will appear to have
77 * failed, but the peer may have observed a finished handshake.
78 */
79 void resumeClientTrusted(X509Certificate[] chain, SSLEngine engine) throws CertificateException;
80
81 /**
82 * Given the partial or complete certificate chain recovered of the peer, and the {@link SSLEngine}
83 * being used, restore the application state of the associated SSL session.
84 * <p>
85 * This method should obtain the {@link SSLSession} from the {@link SSLEngine#getSession()}
86 * method.
87 * <p>
88 * <strong>Note:</strong> If this method throws {@link CertificateException}, the TLS handshake will not
89 * necessarily be rejected. The TLS handshake "Finished" message may have already been sent to the peer
90 * by the time this method is called.
91 * <p>
92 * Implementors should be aware, that peers may make multiple connection attempts using the same session
93 * ticket. So this method may be called more than once for the same client, even if prior calls have thrown
94 * exceptions or invalidated their sessions.
95 * <p>
96 * The given certificate chain is not guaranteed to be the authenticated chain. Implementations that need the
97 * authenticated certificate chain will have to re-authenticate the certificates. It is recommended to do so
98 * with a {@link PKIXBuilderParameters#setDate(Date)} set to the session creation date from
99 * {@link SSLSession#getCreationTime()}. Otherwise, the authentication may fail due to the certificate expiring
100 * before the session ticket.
101 * <p>
102 * This method is called on the client-side, restoring sessions for servers.
103 *
104 * @param chain The peer certificate chain.
105 * @param engine The begine used for this connection.
106 * @throws CertificateException If the session cannot be restored. Locally, the handshake will appear to have
107 * failed, but the peer may have observed a finished handshake.
108 */
109 void resumeServerTrusted(X509Certificate[] chain, SSLEngine engine) throws CertificateException;
110 }