1 /*
2 * Copyright 2014 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.netty5.handler.ssl;
17
18 import io.netty5.buffer.api.BufferAllocator;
19 import io.netty5.buffer.api.DefaultBufferAllocators;
20
21 import javax.net.ssl.SSLEngine;
22 import java.util.List;
23 import java.util.Set;
24
25 /**
26 * JDK extension methods to support {@link ApplicationProtocolNegotiator}
27 *
28 * @deprecated use {@link ApplicationProtocolConfig}
29 */
30 @Deprecated
31 public interface JdkApplicationProtocolNegotiator extends ApplicationProtocolNegotiator {
32 /**
33 * Abstract factory pattern for wrapping an {@link SSLEngine} object. This is useful for NPN/APLN JDK support.
34 */
35 interface SslEngineWrapperFactory {
36 /**
37 * Abstract factory pattern for wrapping an {@link SSLEngine} object. This is useful for NPN/APLN support.
38 *
39 * @param engine The engine to wrap.
40 * @param applicationNegotiator The application level protocol negotiator
41 * @param isServer <ul>
42 * <li>{@code true} if the engine is for server side of connections</li>
43 * <li>{@code false} if the engine is for client side of connections</li>
44 * </ul>
45 * @return The resulting wrapped engine. This may just be {@code engine}.
46 */
47 SSLEngine wrapSslEngine(
48 SSLEngine engine, JdkApplicationProtocolNegotiator applicationNegotiator, boolean isServer);
49 }
50
51 abstract class AllocatorAwareSslEngineWrapperFactory implements SslEngineWrapperFactory {
52
53 @Override
54 public final SSLEngine wrapSslEngine(SSLEngine engine,
55 JdkApplicationProtocolNegotiator applicationNegotiator, boolean isServer) {
56 // Allocator is only used by Conscrypt engine, which require off-heap buffers.
57 BufferAllocator alloc = DefaultBufferAllocators.offHeapAllocator();
58 return wrapSslEngine(engine, alloc, applicationNegotiator, isServer);
59 }
60
61 /**
62 * Abstract factory pattern for wrapping an {@link SSLEngine} object. This is useful for NPN/APLN support.
63 *
64 * @param engine The engine to wrap.
65 * @param alloc the buffer allocator.
66 * @param applicationNegotiator The application level protocol negotiator
67 * @param isServer <ul>
68 * <li>{@code true} if the engine is for server side of connections</li>
69 * <li>{@code false} if the engine is for client side of connections</li>
70 * </ul>
71 * @return The resulting wrapped engine. This may just be {@code engine}.
72 */
73 abstract SSLEngine wrapSslEngine(SSLEngine engine, BufferAllocator alloc,
74 JdkApplicationProtocolNegotiator applicationNegotiator, boolean isServer);
75 }
76
77 /**
78 * Interface to define the role of an application protocol selector in the SSL handshake process. Either
79 * {@link ProtocolSelector#unsupported()} OR {@link ProtocolSelector#select(List)} will be called for each SSL
80 * handshake.
81 */
82 interface ProtocolSelector {
83 /**
84 * Callback invoked to let the application know that the peer does not support this
85 * {@link ApplicationProtocolNegotiator}.
86 */
87 void unsupported();
88
89 /**
90 * Callback invoked to select the application level protocol from the {@code protocols} provided.
91 *
92 * @param protocols the protocols sent by the protocol advertiser
93 * @return the protocol selected by this {@link ProtocolSelector}. A {@code null} value will indicate the no
94 * protocols were selected but the handshake should not fail. The decision to fail the handshake is left to the
95 * other end negotiating the SSL handshake.
96 * @throws Exception If the {@code protocols} provide warrant failing the SSL handshake with a fatal alert.
97 */
98 String select(List<String> protocols) throws Exception;
99 }
100
101 /**
102 * A listener to be notified by which protocol was select by its peer. Either the
103 * {@link ProtocolSelectionListener#unsupported()} OR the {@link ProtocolSelectionListener#selected(String)} method
104 * will be called for each SSL handshake.
105 */
106 interface ProtocolSelectionListener {
107 /**
108 * Callback invoked to let the application know that the peer does not support this
109 * {@link ApplicationProtocolNegotiator}.
110 */
111 void unsupported();
112
113 /**
114 * Callback invoked to let this application know the protocol chosen by the peer.
115 *
116 * @param protocol the protocol selected by the peer. May be {@code null} or empty as supported by the
117 * application negotiation protocol.
118 * @throws Exception This may be thrown if the selected protocol is not acceptable and the desired behavior is
119 * to fail the handshake with a fatal alert.
120 */
121 void selected(String protocol) throws Exception;
122 }
123
124 /**
125 * Factory interface for {@link ProtocolSelector} objects.
126 */
127 interface ProtocolSelectorFactory {
128 /**
129 * Generate a new instance of {@link ProtocolSelector}.
130 * @param engine The {@link SSLEngine} that the returned {@link ProtocolSelector} will be used to create an
131 * instance for.
132 * @param supportedProtocols The protocols that are supported.
133 * @return A new instance of {@link ProtocolSelector}.
134 */
135 ProtocolSelector newSelector(SSLEngine engine, Set<String> supportedProtocols);
136 }
137
138 /**
139 * Factory interface for {@link ProtocolSelectionListener} objects.
140 */
141 interface ProtocolSelectionListenerFactory {
142 /**
143 * Generate a new instance of {@link ProtocolSelectionListener}.
144 * @param engine The {@link SSLEngine} that the returned {@link ProtocolSelectionListener} will be used to
145 * create an instance for.
146 * @param supportedProtocols The protocols that are supported in preference order.
147 * @return A new instance of {@link ProtocolSelectionListener}.
148 */
149 ProtocolSelectionListener newListener(SSLEngine engine, List<String> supportedProtocols);
150 }
151
152 /**
153 * Get the {@link SslEngineWrapperFactory}.
154 */
155 SslEngineWrapperFactory wrapperFactory();
156
157 /**
158 * Get the {@link ProtocolSelectorFactory}.
159 */
160 ProtocolSelectorFactory protocolSelectorFactory();
161
162 /**
163 * Get the {@link ProtocolSelectionListenerFactory}.
164 */
165 ProtocolSelectionListenerFactory protocolListenerFactory();
166 }