1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * 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, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.conscrypt; 18 19 import java.nio.ByteBuffer; 20 import java.security.PrivateKey; 21 import javax.net.ssl.SSLEngine; 22 import javax.net.ssl.SSLEngineResult; 23 import javax.net.ssl.SSLException; 24 import javax.net.ssl.SSLSession; 25 26 /** 27 * Abstract base class for all Conscrypt {@link SSLEngine} classes. 28 */ 29 abstract class AbstractConscryptEngine extends SSLEngine { setBufferAllocator(BufferAllocator bufferAllocator)30 abstract void setBufferAllocator(BufferAllocator bufferAllocator); 31 32 /** 33 * Returns the maximum overhead, in bytes, of sealing a record with SSL. 34 */ maxSealOverhead()35 abstract int maxSealOverhead(); 36 37 /** 38 * Enables/disables TLS Channel ID for this server engine. 39 * 40 * <p>This method needs to be invoked before the handshake starts. 41 * 42 * @throws IllegalStateException if this is a client engine or if the handshake has already 43 * started. 44 */ setChannelIdEnabled(boolean enabled)45 abstract void setChannelIdEnabled(boolean enabled); 46 47 /** 48 * Gets the TLS Channel ID for this server engine. Channel ID is only available once the 49 * handshake completes. 50 * 51 * @return channel ID or {@code null} if not available. 52 * 53 * @throws IllegalStateException if this is a client engine or if the handshake has not yet 54 * completed. 55 * @throws SSLException if channel ID is available but could not be obtained. 56 */ getChannelId()57 abstract byte[] getChannelId() throws SSLException; 58 59 /** 60 * Sets the {@link PrivateKey} to be used for TLS Channel ID by this client engine. 61 * 62 * <p>This method needs to be invoked before the handshake starts. 63 * 64 * @param privateKey private key (enables TLS Channel ID) or {@code null} for no key (disables 65 * TLS Channel ID). The private key must be an Elliptic Curve (EC) key based on the NIST 66 * P-256 curve (aka SECG secp256r1 or ANSI X9.62 prime256v1). 67 * 68 * @throws IllegalStateException if this is a server engine or if the handshake has already 69 * started. 70 */ setChannelIdPrivateKey(PrivateKey privateKey)71 abstract void setChannelIdPrivateKey(PrivateKey privateKey); 72 73 /** 74 * Sets the listener for the completion of the TLS handshake. 75 */ setHandshakeListener(HandshakeListener handshakeListener)76 abstract void setHandshakeListener(HandshakeListener handshakeListener); 77 78 /** 79 * This method enables Server Name Indication (SNI) and overrides the {@link PeerInfoProvider} 80 * supplied during engine creation. 81 */ setHostname(String hostname)82 abstract void setHostname(String hostname); 83 84 /** 85 * Returns the hostname from {@link #setHostname(String)} or supplied by the 86 * {@link PeerInfoProvider} upon creation. No DNS resolution is attempted before 87 * returning the hostname. 88 */ getHostname()89 abstract String getHostname(); 90 getPeerHost()91 @Override public abstract String getPeerHost(); 92 getPeerPort()93 @Override public abstract int getPeerPort(); 94 95 /* @Override */ 96 @SuppressWarnings("MissingOverride") // For compilation with Java 6. getHandshakeSession()97 public final SSLSession getHandshakeSession() { 98 return handshakeSession(); 99 } 100 101 /** 102 * Work-around to allow this method to be called on older versions of Android. 103 */ handshakeSession()104 abstract SSLSession handshakeSession(); 105 106 @Override unwrap(ByteBuffer src, ByteBuffer dst)107 public abstract SSLEngineResult unwrap(ByteBuffer src, ByteBuffer dst) throws SSLException; 108 109 @Override unwrap(ByteBuffer src, ByteBuffer[] dsts)110 public abstract SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts) throws SSLException; 111 112 @Override unwrap(final ByteBuffer src, final ByteBuffer[] dsts, final int offset, final int length)113 public abstract SSLEngineResult unwrap(final ByteBuffer src, final ByteBuffer[] dsts, 114 final int offset, final int length) throws SSLException; 115 unwrap(final ByteBuffer[] srcs, final ByteBuffer[] dsts)116 abstract SSLEngineResult unwrap(final ByteBuffer[] srcs, final ByteBuffer[] dsts) 117 throws SSLException; 118 unwrap(final ByteBuffer[] srcs, int srcsOffset, final int srcsLength, final ByteBuffer[] dsts, final int dstsOffset, final int dstsLength)119 abstract SSLEngineResult unwrap(final ByteBuffer[] srcs, int srcsOffset, final int srcsLength, 120 final ByteBuffer[] dsts, final int dstsOffset, final int dstsLength) 121 throws SSLException; 122 123 @Override wrap(ByteBuffer src, ByteBuffer dst)124 public abstract SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst) throws SSLException; 125 126 @Override wrap( ByteBuffer[] srcs, int srcsOffset, int srcsLength, ByteBuffer dst)127 public abstract SSLEngineResult wrap( 128 ByteBuffer[] srcs, int srcsOffset, int srcsLength, ByteBuffer dst) throws SSLException; 129 130 /** 131 * This method enables session ticket support. 132 * 133 * @param useSessionTickets True to enable session tickets 134 */ setUseSessionTickets(boolean useSessionTickets)135 abstract void setUseSessionTickets(boolean useSessionTickets); 136 137 /** 138 * Sets the list of ALPN protocols. 139 * 140 * @param protocols the list of ALPN protocols 141 */ setApplicationProtocols(String[] protocols)142 abstract void setApplicationProtocols(String[] protocols); 143 144 /** 145 * Returns the list of supported ALPN protocols. 146 */ getApplicationProtocols()147 abstract String[] getApplicationProtocols(); 148 149 @SuppressWarnings("MissingOverride") // For compiling pre Java 9. getApplicationProtocol()150 public abstract String getApplicationProtocol(); 151 152 @SuppressWarnings("MissingOverride") // For compiling pre Java 9. getHandshakeApplicationProtocol()153 public abstract String getHandshakeApplicationProtocol(); 154 155 /** 156 * Sets an application-provided ALPN protocol selector. If provided, this will override 157 * the list of protocols set by {@link #setApplicationProtocols(String[])}. 158 */ setApplicationProtocolSelector(ApplicationProtocolSelector selector)159 abstract void setApplicationProtocolSelector(ApplicationProtocolSelector selector); 160 161 /** 162 * Returns the tls-unique channel binding value for this connection, per RFC 5929. This 163 * will return {@code null} if there is no such value available, such as if the handshake 164 * has not yet completed or this connection is closed. 165 */ getTlsUnique()166 abstract byte[] getTlsUnique(); 167 168 /** 169 * Exports a value derived from the TLS master secret as described in RFC 5705. 170 * 171 * @param label the label to use in calculating the exported value. This must be 172 * an ASCII-only string. 173 * @param context the application-specific context value to use in calculating the 174 * exported value. This may be {@code null} to use no application context, which is 175 * treated differently than an empty byte array. 176 * @param length the number of bytes of keying material to return. 177 * @return a value of the specified length, or {@code null} if the handshake has not yet 178 * completed or the connection has been closed. 179 * @throws SSLException if the value could not be exported. 180 */ exportKeyingMaterial(String label, byte[] context, int length)181 abstract byte[] exportKeyingMaterial(String label, byte[] context, int length) 182 throws SSLException; 183 } 184