1 /* 2 * Copyright (C) 2018 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 android.net.ssl; 18 19 import com.android.org.conscrypt.Conscrypt; 20 import javax.net.ssl.SSLEngine; 21 import javax.net.ssl.SSLException; 22 import libcore.util.NonNull; 23 import libcore.util.Nullable; 24 25 /** 26 * Static utility methods for accessing additional functionality of supported instances of 27 * {@link SSLEngine}. Engines from the platform TLS provider will be compatible with all 28 * methods in this class. 29 */ 30 public class SSLEngines { SSLEngines()31 private SSLEngines() {} 32 33 /** 34 * Returns whether the given engine can be used with the methods in this class. In general, 35 * only engines from the platform TLS provider are supported. 36 */ isSupportedEngine(@onNull SSLEngine engine)37 public static boolean isSupportedEngine(@NonNull SSLEngine engine) { 38 return Conscrypt.isConscrypt(engine); 39 } 40 checkSupported(@onNull SSLEngine e)41 private static void checkSupported(@NonNull SSLEngine e) { 42 if (!isSupportedEngine(e)) { 43 throw new IllegalArgumentException("Engine is not a supported engine."); 44 } 45 } 46 47 /** 48 * Enables or disables the use of session tickets. 49 * 50 * <p>This function must be called before the handshake is started or it will have no effect. 51 * 52 * @param engine the engine 53 * @param useSessionTickets whether to enable or disable the use of session tickets 54 * @throws IllegalArgumentException if the given engine is not a platform engine 55 */ setUseSessionTickets(@onNull SSLEngine engine, boolean useSessionTickets)56 public static void setUseSessionTickets(@NonNull SSLEngine engine, boolean useSessionTickets) { 57 checkSupported(engine); 58 Conscrypt.setUseSessionTickets(engine, useSessionTickets); 59 } 60 61 /** 62 * Exports a value derived from the TLS master secret as described in RFC 5705. 63 * 64 * A number of protocols leverage Transport Layer Security (TLS) to perform key 65 * establishment but then use some of the keying material for their own purposes. 66 * 67 * This method allows an application to export keying material from a TLS connection. 68 * The exported material will be the same on the client and server if they pass in 69 * the same values for {@code label} and {@code context}. See RFC 5705 for further 70 * details. 71 * 72 * @param engine the engine to use for exporting keying material 73 * @param label the label to use in calculating the exported value. This must be 74 * an ASCII-only string. 75 * @param context the application-specific context value to use in calculating the 76 * exported value. This may be {@code null} to use no application context, which is 77 * treated differently than an empty byte array. 78 * @param length the number of bytes of keying material to return. 79 * @return a value of the specified length, or {@code null} if the handshake has not yet 80 * completed or the connection has been closed. 81 * @throws SSLException if the value could not be exported. 82 */ 83 @Nullable exportKeyingMaterial(@onNull SSLEngine engine, @NonNull String label, @Nullable byte[] context, int length)84 public static byte[] exportKeyingMaterial(@NonNull SSLEngine engine, @NonNull String label, 85 @Nullable byte[] context, int length) throws SSLException { 86 checkSupported(engine); 87 return Conscrypt.exportKeyingMaterial(engine, label, context, length); 88 } 89 } 90