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