View Javadoc
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 }