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    *   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 }