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