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