src.javax.net.ssl.SSLEngine Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.net.ssl;
import java.nio.ByteBuffer;
import java.nio.ReadOnlyBufferException;
import java.util.List;
import java.util.function.BiFunction;
/**
* A class which enables secure communications using protocols such as
* the Secure Sockets Layer (SSL) or
* IETF RFC 2246 "Transport
* Layer Security" (TLS) protocols, but is transport independent.
*
* The secure communications modes include:
*
* - Integrity Protection. SSL/TLS protects against
* modification of messages by an active wiretapper.
*
*
- Authentication. In most modes, SSL/TLS provides
* peer authentication. Servers are usually authenticated, and
* clients may be authenticated as requested by servers.
*
*
- Confidentiality (Privacy Protection). In most
* modes, SSL/TLS encrypts data being sent between client and
* server. This protects the confidentiality of data, so that
* passive wiretappers won't see sensitive data such as financial
* information or personal information of many kinds.
*
*
*
* These kinds of protection are specified by a "cipher suite", which
* is a combination of cryptographic algorithms used by a given SSL
* connection. During the negotiation process, the two endpoints must
* agree on a cipher suite that is available in both environments. If
* there is no such suite in common, no SSL connection can be
* established, and no data can be exchanged.
*
* The cipher suite used is established by a negotiation process called
* "handshaking". The goal of this process is to create or rejoin a
* "session", which may protect many connections over time. After
* handshaking has completed, you can access session attributes by
* using the {@link #getSession()} method.
*
* The SSLSocket
class provides much of the same security
* functionality, but all of the inbound and outbound data is
* automatically transported using the underlying {@link
* java.net.Socket Socket}, which by design uses a blocking model.
* While this is appropriate for many applications, this model does not
* provide the scalability required by large servers.
*
* The primary distinction of an SSLEngine
is that it
* operates on inbound and outbound byte streams, independent of the
* transport mechanism. It is the responsibility of the
* SSLEngine
user to arrange for reliable I/O transport to
* the peer. By separating the SSL/TLS abstraction from the I/O
* transport mechanism, the SSLEngine
can be used for a
* wide variety of I/O types, such as {@link
* java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean)
* non-blocking I/O (polling)}, {@link java.nio.channels.Selector
* selectable non-blocking I/O}, {@link java.net.Socket Socket} and the
* traditional Input/OutputStreams, local {@link java.nio.ByteBuffer
* ByteBuffers} or byte arrays, future asynchronous
* I/O models , and so on.
*
* At a high level, the SSLEngine
appears thus:
*
*
* app data
*
* | ^
* | | |
* v | |
* +----+-----|-----+----+
* | | |
* | SSL|Engine |
* wrap() | | | unwrap()
* | OUTBOUND | INBOUND |
* | | |
* +----+-----|-----+----+
* | | ^
* | | |
* v |
*
* net data
*
* Application data (also known as plaintext or cleartext) is data which
* is produced or consumed by an application. Its counterpart is
* network data, which consists of either handshaking and/or ciphertext
* (encrypted) data, and destined to be transported via an I/O
* mechanism. Inbound data is data which has been received from the
* peer, and outbound data is destined for the peer.
*
* (In the context of an SSLEngine
, the term "handshake
* data" is taken to mean any data exchanged to establish and control a
* secure connection. Handshake data includes the SSL/TLS messages
* "alert", "change_cipher_spec," and "handshake.")
*
* There are five distinct phases to an SSLEngine
.
*
*
* - Creation - The
SSLEngine
has been created and
* initialized, but has not yet been used. During this phase, an
* application may set any SSLEngine
-specific settings
* (enabled cipher suites, whether the SSLEngine
should
* handshake in client or server mode, and so on). Once
* handshaking has begun, though, any new settings (except
* client/server mode, see below) will be used for
* the next handshake.
*
* - Initial Handshake - The initial handshake is a procedure by
* which the two peers exchange communication parameters until an
* SSLSession is established. Application data can not be sent during
* this phase.
*
*
- Application Data - Once the communication parameters have
* been established and the handshake is complete, application data
* may flow through the
SSLEngine
. Outbound
* application messages are encrypted and integrity protected,
* and inbound messages reverse the process.
*
* - Rehandshaking - Either side may request a renegotiation of
* the session at any time during the Application Data phase. New
* handshaking data can be intermixed among the application data.
* Before starting the rehandshake phase, the application may
* reset the SSL/TLS communication parameters such as the list of
* enabled ciphersuites and whether to use client authentication,
* but can not change between client/server modes. As before, once
* handshaking has begun, any new
SSLEngine
* configuration settings will not be used until the next
* handshake.
*
* - Closure - When the connection is no longer needed, the
* application should close the
SSLEngine
and should
* send/receive any remaining messages to the peer before
* closing the underlying transport mechanism. Once an engine is
* closed, it is not reusable: a new SSLEngine
must
* be created.
*
* An SSLEngine
is created by calling {@link
* SSLContext#createSSLEngine()} from an initialized
* SSLContext
. Any configuration
* parameters should be set before making the first call to
* wrap()
, unwrap()
, or
* beginHandshake()
. These methods all trigger the
* initial handshake.
*
* Data moves through the engine by calling {@link #wrap(ByteBuffer,
* ByteBuffer) wrap()} or {@link #unwrap(ByteBuffer, ByteBuffer)
* unwrap()} on outbound or inbound data, respectively. Depending on
* the state of the SSLEngine
, a wrap()
call
* may consume application data from the source buffer and may produce
* network data in the destination buffer. The outbound data
* may contain application and/or handshake data. A call to
* unwrap()
will examine the source buffer and may
* advance the handshake if the data is handshaking information, or
* may place application data in the destination buffer if the data
* is application. The state of the underlying SSL/TLS algorithm
* will determine when data is consumed and produced.
*
* Calls to wrap()
and unwrap()
return an
* SSLEngineResult
which indicates the status of the
* operation, and (optionally) how to interact with the engine to make
* progress.
*
* The SSLEngine
produces/consumes complete SSL/TLS
* packets only, and does not store application data internally between
* calls to wrap()/unwrap()
. Thus input and output
* ByteBuffer
s must be sized appropriately to hold the
* maximum record that can be produced. Calls to {@link
* SSLSession#getPacketBufferSize()} and {@link
* SSLSession#getApplicationBufferSize()} should be used to determine
* the appropriate buffer sizes. The size of the outbound application
* data buffer generally does not matter. If buffer conditions do not
* allow for the proper consumption/production of data, the application
* must determine (via {@link SSLEngineResult}) and correct the
* problem, and then try the call again.
*
* For example, unwrap()
will return a {@link
* SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine
* determines that there is not enough destination buffer space available.
* Applications should call {@link SSLSession#getApplicationBufferSize()}
* and compare that value with the space available in the destination buffer,
* enlarging the buffer if necessary. Similarly, if unwrap()
* were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the
* application should call {@link SSLSession#getPacketBufferSize()} to ensure
* that the source buffer has enough room to hold a record (enlarging if
* necessary), and then obtain more inbound data.
*
*
{@code
* SSLEngineResult r = engine.unwrap(src, dst);
* switch (r.getStatus()) {
* BUFFER_OVERFLOW:
* // Could attempt to drain the dst buffer of any already obtained
* // data, but we'll just increase it to the size needed.
* int appSize = engine.getSession().getApplicationBufferSize();
* ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
* dst.flip();
* b.put(dst);
* dst = b;
* // retry the operation.
* break;
* BUFFER_UNDERFLOW:
* int netSize = engine.getSession().getPacketBufferSize();
* // Resize buffer if needed.
* if (netSize > dst.capacity()) {
* ByteBuffer b = ByteBuffer.allocate(netSize);
* src.flip();
* b.put(src);
* src = b;
* }
* // Obtain more inbound network data for src,
* // then retry the operation.
* break;
* // other cases: CLOSED, OK.
* }
* }
*
*
* Unlike SSLSocket
, all methods of SSLEngine are
* non-blocking. SSLEngine
implementations may
* require the results of tasks that may take an extended period of
* time to complete, or may even block. For example, a TrustManager
* may need to connect to a remote certificate validation service,
* or a KeyManager might need to prompt a user to determine which
* certificate to use as part of client authentication. Additionally,
* creating cryptographic signatures and verifying them can be slow,
* seemingly blocking.
*
* For any operation which may potentially block, the
* SSLEngine
will create a {@link java.lang.Runnable}
* delegated task. When SSLEngineResult
indicates that a
* delegated task result is needed, the application must call {@link
* #getDelegatedTask()} to obtain an outstanding delegated task and
* call its {@link java.lang.Runnable#run() run()} method (possibly using
* a different thread depending on the compute strategy). The
* application should continue obtaining delegated tasks until no more
* exist, and try the original operation again.
*
* At the end of a communication session, applications should properly
* close the SSL/TLS link. The SSL/TLS protocols have closure handshake
* messages, and these messages should be communicated to the peer
* before releasing the SSLEngine
and closing the
* underlying transport mechanism. A close can be initiated by one of:
* an SSLException, an inbound closure handshake message, or one of the
* close methods. In all cases, closure handshake messages are
* generated by the engine, and wrap()
should be repeatedly
* called until the resulting SSLEngineResult
's status
* returns "CLOSED", or {@link #isOutboundDone()} returns true. All
* data obtained from the wrap()
method should be sent to the
* peer.
*
* {@link #closeOutbound()} is used to signal the engine that the
* application will not be sending any more data.
*
* A peer will signal its intent to close by sending its own closure
* handshake message. After this message has been received and
* processed by the local SSLEngine
's unwrap()
* call, the application can detect the close by calling
* unwrap()
and looking for a SSLEngineResult
* with status "CLOSED", or if {@link #isInboundDone()} returns true.
* If for some reason the peer closes the communication link without
* sending the proper SSL/TLS closure message, the application can
* detect the end-of-stream and can signal the engine via {@link
* #closeInbound()} that there will no more inbound messages to
* process. Some applications might choose to require orderly shutdown
* messages from a peer, in which case they can check that the closure
* was generated by a handshake message and not by an end-of-stream
* condition.
*
* There are two groups of cipher suites which you will need to know
* about when managing cipher suites:
*
*
* - Supported cipher suites: all the suites which are
* supported by the SSL implementation. This list is reported
* using {@link #getSupportedCipherSuites()}.
*
*
- Enabled cipher suites, which may be fewer than
* the full set of supported suites. This group is set using the
* {@link #setEnabledCipherSuites(String [])} method, and
* queried using the {@link #getEnabledCipherSuites()} method.
* Initially, a default set of cipher suites will be enabled on a
* new engine that represents the minimum suggested
* configuration.
*
*
* Implementation defaults require that only cipher suites which
* authenticate servers and provide confidentiality be enabled by
* default. Only if both sides explicitly agree to unauthenticated
* and/or non-private (unencrypted) communications will such a
* cipher suite be selected.
*
* Each SSL/TLS connection must have one client and one server, thus
* each endpoint must decide which role to assume. This choice determines
* who begins the handshaking process as well as which type of messages
* should be sent by each party. The method {@link
* #setUseClientMode(boolean)} configures the mode. Once the initial
* handshaking has started, an SSLEngine
can not switch
* between client and server modes, even when performing renegotiations.
*
* Applications might choose to process delegated tasks in different
* threads. When an SSLEngine
* is created, the current {@link java.security.AccessControlContext}
* is saved. All future delegated tasks will be processed using this
* context: that is, all access control decisions will be made using the
* context captured at engine creation.
*
*
*
* Concurrency Notes:
* There are two concurrency issues to be aware of:
*
*
* - The
wrap()
and unwrap()
methods
* may execute concurrently of each other.
*
* - The SSL/TLS protocols employ ordered packets.
* Applications must take care to ensure that generated packets
* are delivered in sequence. If packets arrive
* out-of-order, unexpected or fatal results may occur.
*
* For example:
*
*
* synchronized (outboundLock) {
* sslEngine.wrap(src, dst);
* outboundQueue.put(dst);
* }
*
*
* As a corollary, two threads must not attempt to call the same method
* (either wrap()
or unwrap()
) concurrently,
* because there is no way to guarantee the eventual packet ordering.
*
*
* Default configuration for different Android versions
* {@code SSLEngine} instances obtained from the default {@link SSLContext} are configured as
* follows:
*
*
*
*
Protocols
*
*
*
* Protocol
* Supported (API Levels)
* Enabled by default (API Levels)
*
*
*
*
* SSLv3
* 1–25
* 1–22
*
*
* TLSv1
* 1+
* 1+
*
*
* TLSv1.1
* 20+
* 20+
*
*
* TLSv1.2
* 20+
* 20+
*
*
* TLSv1.3
* 29+
* 29+
*
*
*
*
* Cipher suites
*
*
*
* Cipher suite
* Supported (API Levels)
* Enabled by default (API Levels)
*
*
*
*
* SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_DHE_DSS_WITH_DES_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_DHE_RSA_WITH_DES_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
* 9-22
*
*
*
* SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
* 9-22
*
*
*
* SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
* 9-22
*
*
*
* SSL_DH_anon_WITH_DES_CBC_SHA
* 9-22
*
*
*
* SSL_DH_anon_WITH_RC4_128_MD5
* 9-22
*
*
*
* SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_RSA_EXPORT_WITH_RC4_40_MD5
* 9-22
* 9-19
*
*
* SSL_RSA_WITH_3DES_EDE_CBC_SHA
* 9+
* 9-19
*
*
* SSL_RSA_WITH_DES_CBC_SHA
* 9-22
* 9-19
*
*
* SSL_RSA_WITH_NULL_MD5
* 9-22
*
*
*
* SSL_RSA_WITH_NULL_SHA
* 9-22
*
*
*
* SSL_RSA_WITH_RC4_128_MD5
* 9-25
* 9-19
*
*
* SSL_RSA_WITH_RC4_128_SHA
* 9-25
* 9-23
*
*
* TLS_AES_128_GCM_SHA256
* 29+
* 29+
*
*
* TLS_AES_256_GCM_SHA384
* 29+
* 29+
*
*
* TLS_CHACHA20_POLY1305_SHA256
* 29+
* 29+
*
*
* TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_DHE_DSS_WITH_AES_128_CBC_SHA
* 9-22
* 9-22
*
*
* TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
* 20-22
*
*
*
* TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
* 20-22
*
*
*
* TLS_DHE_DSS_WITH_AES_256_CBC_SHA
* 9-22
* 20-22
*
*
* TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
* 20-22
*
*
*
* TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
* 20-22
*
*
*
* TLS_DHE_DSS_WITH_DES_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_DHE_RSA_WITH_AES_128_CBC_SHA
* 9-25
* 9-25
*
*
* TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
* 20-25
*
*
*
* TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
* 20-25
* 20-25
*
*
* TLS_DHE_RSA_WITH_AES_256_CBC_SHA
* 9-25
* 20-25
*
*
* TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
* 20-25
*
*
*
* TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
* 20-25
* 20-25
*
*
* TLS_DHE_RSA_WITH_DES_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA
* 1-8
*
*
*
* TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
* 1-8
*
*
*
* TLS_DH_DSS_WITH_DES_CBC_SHA
* 1-8
*
*
*
* TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA
* 1-8
*
*
*
* TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
* 1-8
*
*
*
* TLS_DH_RSA_WITH_DES_CBC_SHA
* 1-8
*
*
*
* TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
* 1-8
*
*
*
* TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
* 1-8
*
*
*
* TLS_DH_anon_WITH_AES_128_CBC_SHA
* 9-22
*
*
*
* TLS_DH_anon_WITH_AES_128_CBC_SHA256
* 20-22
*
*
*
* TLS_DH_anon_WITH_AES_128_GCM_SHA256
* 20-22
*
*
*
* TLS_DH_anon_WITH_AES_256_CBC_SHA
* 9-22
*
*
*
* TLS_DH_anon_WITH_AES_256_CBC_SHA256
* 20-22
*
*
*
* TLS_DH_anon_WITH_AES_256_GCM_SHA384
* 20-22
*
*
*
* TLS_DH_anon_WITH_DES_CBC_SHA
* 1-8
*
*
*
* TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
* 20-22
*
*
*
* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
* 20+
* 20+
*
*
* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
* 20-28
*
*
*
* TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
* 20+
* 20+
*
*
* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
* 20+
* 20+
*
*
* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
* 20-28
*
*
*
* TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
* 20+
* 20+
*
*
* TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
* 24+
* 24+
*
*
* TLS_ECDHE_ECDSA_WITH_NULL_SHA
* 20-22
*
*
*
* TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
* 20-25
* 20-23
*
*
* TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA
* 21+
* 21+
*
*
* TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA
* 21+
* 21+
*
*
* TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256
* 24+
* 24+
*
*
* TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
* 20-22
*
*
*
* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
* 20+
* 20+
*
*
* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* 20-28
*
*
*
* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* 20+
* 20+
*
*
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
* 20+
* 20+
*
*
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
* 20-28
*
*
*
* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* 20+
* 20+
*
*
* TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
* 24+
* 24+
*
*
* TLS_ECDHE_RSA_WITH_NULL_SHA
* 20-22
*
*
*
* TLS_ECDHE_RSA_WITH_RC4_128_SHA
* 20-25
* 20-23
*
*
* TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_NULL_SHA
* 20-22
*
*
*
* TLS_ECDH_ECDSA_WITH_RC4_128_SHA
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_NULL_SHA
* 20-22
*
*
*
* TLS_ECDH_RSA_WITH_RC4_128_SHA
* 20-22
*
*
*
* TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_anon_WITH_AES_128_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_anon_WITH_AES_256_CBC_SHA
* 20-22
*
*
*
* TLS_ECDH_anon_WITH_NULL_SHA
* 20-22
*
*
*
* TLS_ECDH_anon_WITH_RC4_128_SHA
* 20-22
*
*
*
* TLS_EMPTY_RENEGOTIATION_INFO_SCSV
* 20+
* 20+
*
*
* TLS_FALLBACK_SCSV
* 21+
*
*
*
* TLS_NULL_WITH_NULL_NULL
* 1-8
*
*
*
* TLS_PSK_WITH_3DES_EDE_CBC_SHA
* 21-22
*
*
*
* TLS_PSK_WITH_AES_128_CBC_SHA
* 21+
* 21+
*
*
* TLS_PSK_WITH_AES_256_CBC_SHA
* 21+
* 21+
*
*
* TLS_PSK_WITH_RC4_128_SHA
* 21-25
*
*
*
* TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_RSA_WITH_3DES_EDE_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_RSA_WITH_AES_128_CBC_SHA
* 9+
* 9+
*
*
* TLS_RSA_WITH_AES_128_CBC_SHA256
* 20-28
*
*
*
* TLS_RSA_WITH_AES_128_GCM_SHA256
* 20+
* 20+
*
*
* TLS_RSA_WITH_AES_256_CBC_SHA
* 9+
* 20+
*
*
* TLS_RSA_WITH_AES_256_CBC_SHA256
* 20-28
*
*
*
* TLS_RSA_WITH_AES_256_GCM_SHA384
* 20+
* 20+
*
*
* TLS_RSA_WITH_DES_CBC_SHA
* 1-8
* 1-8
*
*
* TLS_RSA_WITH_NULL_MD5
* 1-8
*
*
*
* TLS_RSA_WITH_NULL_SHA
* 1-8
*
*
*
* TLS_RSA_WITH_NULL_SHA256
* 20-22
*
*
*
*
*
* NOTE: PSK cipher suites are enabled by default only if the {@code SSLContext} through
* which the engine was created has been initialized with a {@code PSKKeyManager}.
*
* @see SSLContext
* @see SSLSocket
* @see SSLServerSocket
* @see SSLSession
* @see java.net.Socket
*
* @since 1.5
* @author Brad R. Wetmore
*/
public abstract class SSLEngine {
private String peerHost = null;
private int peerPort = -1;
/**
* Constructor for an SSLEngine
providing no hints
* for an internal session reuse strategy.
*
* @see SSLContext#createSSLEngine()
* @see SSLSessionContext
*/
protected SSLEngine() {
}
/**
* Constructor for an SSLEngine
.
*
* SSLEngine
implementations may use the
* peerHost
and peerPort
parameters as hints
* for their internal session reuse strategy.
*
* Some cipher suites (such as Kerberos) require remote hostname
* information. Implementations of this class should use this
* constructor to use Kerberos.
*
* The parameters are not authenticated by the
* SSLEngine
.
*
* @param peerHost the name of the peer host
* @param peerPort the port number of the peer
* @see SSLContext#createSSLEngine(String, int)
* @see SSLSessionContext
*/
protected SSLEngine(String peerHost, int peerPort) {
this.peerHost = peerHost;
this.peerPort = peerPort;
}
/**
* Returns the host name of the peer.
*
* Note that the value is not authenticated, and should not be
* relied upon.
*
* @return the host name of the peer, or null if nothing is
* available.
*/
public String getPeerHost() {
return peerHost;
}
/**
* Returns the port number of the peer.
*
* Note that the value is not authenticated, and should not be
* relied upon.
*
* @return the port number of the peer, or -1 if nothing is
* available.
*/
public int getPeerPort() {
return peerPort;
}
/**
* Attempts to encode a buffer of plaintext application data into
* SSL/TLS network data.
*
* An invocation of this method behaves in exactly the same manner
* as the invocation:
*
* {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
* engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);}
*
*
* @param src
* a ByteBuffer
containing outbound application data
* @param dst
* a ByteBuffer
to hold outbound network data
* @return an SSLEngineResult
describing the result
* of this operation.
* @throws SSLException
* A problem was encountered while processing the
* data that caused the SSLEngine
to abort.
* See the class description for more information on
* engine closure.
* @throws ReadOnlyBufferException
* if the dst
buffer is read-only.
* @throws IllegalArgumentException
* if either src
or dst
* is null.
* @throws IllegalStateException if the client/server mode
* has not yet been set.
* @see #wrap(ByteBuffer [], int, int, ByteBuffer)
*/
public SSLEngineResult wrap(ByteBuffer src,
ByteBuffer dst) throws SSLException {
return wrap(new ByteBuffer [] { src }, 0, 1, dst);
}
/**
* Attempts to encode plaintext bytes from a sequence of data
* buffers into SSL/TLS network data.
*
* An invocation of this method behaves in exactly the same manner
* as the invocation:
*
* {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
* engine.wrap(srcs, 0, srcs.length, dst);}
*
*
* @param srcs
* an array of ByteBuffers
containing the
* outbound application data
* @param dst
* a ByteBuffer
to hold outbound network data
* @return an SSLEngineResult
describing the result
* of this operation.
* @throws SSLException
* A problem was encountered while processing the
* data that caused the SSLEngine
to abort.
* See the class description for more information on
* engine closure.
* @throws ReadOnlyBufferException
* if the dst
buffer is read-only.
* @throws IllegalArgumentException
* if either srcs
or dst
* is null, or if any element in srcs
is null.
* @throws IllegalStateException if the client/server mode
* has not yet been set.
* @see #wrap(ByteBuffer [], int, int, ByteBuffer)
*/
public SSLEngineResult wrap(ByteBuffer [] srcs,
ByteBuffer dst) throws SSLException {
if (srcs == null) {
throw new IllegalArgumentException("src == null");
}
return wrap(srcs, 0, srcs.length, dst);
}
/**
* Attempts to encode plaintext bytes from a subsequence of data
* buffers into SSL/TLS network data. This "gathering"
* operation encodes, in a single invocation, a sequence of bytes
* from one or more of a given sequence of buffers. Gathering
* wraps are often useful when implementing network protocols or
* file formats that, for example, group data into segments
* consisting of one or more fixed-length headers followed by a
* variable-length body. See
* {@link java.nio.channels.GatheringByteChannel} for more
* information on gathering, and {@link
* java.nio.channels.GatheringByteChannel#write(ByteBuffer[],
* int, int)} for more information on the subsequence
* behavior.
*
* Depending on the state of the SSLEngine, this method may produce
* network data without consuming any application data (for example,
* it may generate handshake data.)
*
* The application is responsible for reliably transporting the
* network data to the peer, and for ensuring that data created by
* multiple calls to wrap() is transported in the same order in which
* it was generated. The application must properly synchronize
* multiple calls to this method.
*
* If this SSLEngine
has not yet started its initial
* handshake, this method will automatically start the handshake.
*
* This method will attempt to produce SSL/TLS records, and will
* consume as much source data as possible, but will never consume
* more than the sum of the bytes remaining in each buffer. Each
* ByteBuffer
's position is updated to reflect the
* amount of data consumed or produced. The limits remain the
* same.
*
* The underlying memory used by the srcs
and
* dst ByteBuffer
s must not be the same.
*
* See the class description for more information on engine closure.
*
* @param srcs
* an array of ByteBuffers
containing the
* outbound application data
* @param offset
* The offset within the buffer array of the first buffer from
* which bytes are to be retrieved; it must be non-negative
* and no larger than srcs.length
* @param length
* The maximum number of buffers to be accessed; it must be
* non-negative and no larger than
* srcs.length
- offset
* @param dst
* a ByteBuffer
to hold outbound network data
* @return an SSLEngineResult
describing the result
* of this operation.
* @throws SSLException
* A problem was encountered while processing the
* data that caused the SSLEngine
to abort.
* See the class description for more information on
* engine closure.
* @throws IndexOutOfBoundsException
* if the preconditions on the offset
and
* length
parameters do not hold.
* @throws ReadOnlyBufferException
* if the dst
buffer is read-only.
* @throws IllegalArgumentException
* if either srcs
or dst
* is null, or if any element in the srcs
* subsequence specified is null.
* @throws IllegalStateException if the client/server mode
* has not yet been set.
* @see java.nio.channels.GatheringByteChannel
* @see java.nio.channels.GatheringByteChannel#write(
* ByteBuffer[], int, int)
*/
public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset,
int length, ByteBuffer dst) throws SSLException;
/**
* Attempts to decode SSL/TLS network data into a plaintext
* application data buffer.
*
* An invocation of this method behaves in exactly the same manner
* as the invocation:
*
* {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
* engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);}
*
*
* @param src
* a ByteBuffer
containing inbound network data.
* @param dst
* a ByteBuffer
to hold inbound application data.
* @return an SSLEngineResult
describing the result
* of this operation.
* @throws SSLException
* A problem was encountered while processing the
* data that caused the SSLEngine
to abort.
* See the class description for more information on
* engine closure.
* @throws ReadOnlyBufferException
* if the dst
buffer is read-only.
* @throws IllegalArgumentException
* if either src
or dst
* is null.
* @throws IllegalStateException if the client/server mode
* has not yet been set.
* @see #unwrap(ByteBuffer, ByteBuffer [], int, int)
*/
public SSLEngineResult unwrap(ByteBuffer src,
ByteBuffer dst) throws SSLException {
return unwrap(src, new ByteBuffer [] { dst }, 0, 1);
}
/**
* Attempts to decode SSL/TLS network data into a sequence of plaintext
* application data buffers.
*
* An invocation of this method behaves in exactly the same manner
* as the invocation:
*
* {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
* engine.unwrap(src, dsts, 0, dsts.length);}
*
*
* @param src
* a ByteBuffer
containing inbound network data.
* @param dsts
* an array of ByteBuffer
s to hold inbound
* application data.
* @return an SSLEngineResult
describing the result
* of this operation.
* @throws SSLException
* A problem was encountered while processing the
* data that caused the SSLEngine
to abort.
* See the class description for more information on
* engine closure.
* @throws ReadOnlyBufferException
* if any of the dst
buffers are read-only.
* @throws IllegalArgumentException
* if either src
or dsts
* is null, or if any element in dsts
is null.
* @throws IllegalStateException if the client/server mode
* has not yet been set.
* @see #unwrap(ByteBuffer, ByteBuffer [], int, int)
*/
public SSLEngineResult unwrap(ByteBuffer src,
ByteBuffer [] dsts) throws SSLException {
if (dsts == null) {
throw new IllegalArgumentException("dsts == null");
}
return unwrap(src, dsts, 0, dsts.length);
}
/**
* Attempts to decode SSL/TLS network data into a subsequence of
* plaintext application data buffers. This "scattering"
* operation decodes, in a single invocation, a sequence of bytes
* into one or more of a given sequence of buffers. Scattering
* unwraps are often useful when implementing network protocols or
* file formats that, for example, group data into segments
* consisting of one or more fixed-length headers followed by a
* variable-length body. See
* {@link java.nio.channels.ScatteringByteChannel} for more
* information on scattering, and {@link
* java.nio.channels.ScatteringByteChannel#read(ByteBuffer[],
* int, int)} for more information on the subsequence
* behavior.
*
* Depending on the state of the SSLEngine, this method may consume
* network data without producing any application data (for example,
* it may consume handshake data.)
*
* The application is responsible for reliably obtaining the network
* data from the peer, and for invoking unwrap() on the data in the
* order it was received. The application must properly synchronize
* multiple calls to this method.
*
* If this SSLEngine
has not yet started its initial
* handshake, this method will automatically start the handshake.
*
* This method will attempt to consume one complete SSL/TLS network
* packet, but will never consume more than the sum of the bytes
* remaining in the buffers. Each ByteBuffer
's
* position is updated to reflect the amount of data consumed or
* produced. The limits remain the same.
*
* The underlying memory used by the src
and
* dsts ByteBuffer
s must not be the same.
*
* The inbound network buffer may be modified as a result of this
* call: therefore if the network data packet is required for some
* secondary purpose, the data should be duplicated before calling this
* method. Note: the network data will not be useful to a second
* SSLEngine, as each SSLEngine contains unique random state which
* influences the SSL/TLS messages.
*
* See the class description for more information on engine closure.
*
* @param src
* a ByteBuffer
containing inbound network data.
* @param dsts
* an array of ByteBuffer
s to hold inbound
* application data.
* @param offset
* The offset within the buffer array of the first buffer from
* which bytes are to be transferred; it must be non-negative
* and no larger than dsts.length
.
* @param length
* The maximum number of buffers to be accessed; it must be
* non-negative and no larger than
* dsts.length
- offset
.
* @return an SSLEngineResult
describing the result
* of this operation.
* @throws SSLException
* A problem was encountered while processing the
* data that caused the SSLEngine
to abort.
* See the class description for more information on
* engine closure.
* @throws IndexOutOfBoundsException
* If the preconditions on the offset
and
* length
parameters do not hold.
* @throws ReadOnlyBufferException
* if any of the dst
buffers are read-only.
* @throws IllegalArgumentException
* if either src
or dsts
* is null, or if any element in the dsts
* subsequence specified is null.
* @throws IllegalStateException if the client/server mode
* has not yet been set.
* @see java.nio.channels.ScatteringByteChannel
* @see java.nio.channels.ScatteringByteChannel#read(
* ByteBuffer[], int, int)
*/
public abstract SSLEngineResult unwrap(ByteBuffer src,
ByteBuffer [] dsts, int offset, int length) throws SSLException;
/**
* Returns a delegated Runnable
task for
* this SSLEngine
.
*
* SSLEngine
operations may require the results of
* operations that block, or may take an extended period of time to
* complete. This method is used to obtain an outstanding {@link
* java.lang.Runnable} operation (task). Each task must be assigned
* a thread (possibly the current) to perform the {@link
* java.lang.Runnable#run() run} operation. Once the
* run
method returns, the Runnable
object
* is no longer needed and may be discarded.
*
* Delegated tasks run in the AccessControlContext
* in place when this object was created.
*
* A call to this method will return each outstanding task
* exactly once.
*
* Multiple delegated tasks can be run in parallel.
*
* @return a delegated Runnable
task, or null
* if none are available.
*/
public abstract Runnable getDelegatedTask();
/**
* Signals that no more inbound network data will be sent
* to this SSLEngine
.
*
* If the application initiated the closing process by calling
* {@link #closeOutbound()}, under some circumstances it is not
* required that the initiator wait for the peer's corresponding
* close message. (See section 7.2.1 of the TLS specification (RFC 2246) for more
* information on waiting for closure alerts.) In such cases, this
* method need not be called.
*
* But if the application did not initiate the closure process, or
* if the circumstances above do not apply, this method should be
* called whenever the end of the SSL/TLS data stream is reached.
* This ensures closure of the inbound side, and checks that the
* peer followed the SSL/TLS close procedure properly, thus
* detecting possible truncation attacks.
*
* This method is idempotent: if the inbound side has already
* been closed, this method does not do anything.
*
* {@link #wrap(ByteBuffer, ByteBuffer) wrap()} should be
* called to flush any remaining handshake data.
*
* @throws SSLException
* if this engine has not received the proper SSL/TLS close
* notification message from the peer.
*
* @see #isInboundDone()
* @see #isOutboundDone()
*/
public abstract void closeInbound() throws SSLException;
/**
* Returns whether {@link #unwrap(ByteBuffer, ByteBuffer)} will
* accept any more inbound data messages.
*
* @return true if the SSLEngine
will not
* consume anymore network data (and by implication,
* will not produce any more application data.)
* @see #closeInbound()
*/
public abstract boolean isInboundDone();
/**
* Signals that no more outbound application data will be sent
* on this SSLEngine
.
*
* This method is idempotent: if the outbound side has already
* been closed, this method does not do anything.
*
* {@link #wrap(ByteBuffer, ByteBuffer)} should be
* called to flush any remaining handshake data.
*
* @see #isOutboundDone()
*/
public abstract void closeOutbound();
/**
* Returns whether {@link #wrap(ByteBuffer, ByteBuffer)} will
* produce any more outbound data messages.
*
* Note that during the closure phase, a SSLEngine
may
* generate handshake closure data that must be sent to the peer.
* wrap()
must be called to generate this data. When
* this method returns true, no more outbound data will be created.
*
* @return true if the SSLEngine
will not produce
* any more network data
*
* @see #closeOutbound()
* @see #closeInbound()
*/
public abstract boolean isOutboundDone();
// Android-changed: Added warnings about misuse
/**
* Returns the names of the cipher suites which could be enabled for use
* on this engine. Normally, only a subset of these will actually
* be enabled by default, since this list may include cipher suites which
* do not meet quality of service requirements for those defaults. Such
* cipher suites might be useful in specialized applications.
*
*
Applications should not blindly enable all supported
* cipher suites. The supported cipher suites can include signaling cipher suite
* values that can cause connection problems if enabled inappropriately.
*
*
The proper way to use this method is to either check if a specific cipher
* suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)}
* or to filter a desired list of cipher suites to only the supported ones via
* {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}.
*
* @return an array of cipher suite names
* @see #getEnabledCipherSuites()
* @see #setEnabledCipherSuites(String [])
*/
public abstract String [] getSupportedCipherSuites();
/**
* Returns the names of the SSL cipher suites which are currently
* enabled for use on this engine. When an SSLEngine is first
* created, all enabled cipher suites support a minimum quality of
* service. Thus, in some environments this value might be empty.
*
* Even if a suite has been enabled, it might never be used. (For
* example, the peer does not support it, the requisite
* certificates/private keys for the suite are not available, or an
* anonymous suite is enabled but authentication is required.)
*
* @return an array of cipher suite names
* @see #getSupportedCipherSuites()
* @see #setEnabledCipherSuites(String [])
*/
public abstract String [] getEnabledCipherSuites();
/**
* Sets the cipher suites enabled for use on this engine.
*
* Each cipher suite in the suites
parameter must have
* been listed by getSupportedCipherSuites(), or the method will
* fail. Following a successful call to this method, only suites
* listed in the suites
parameter are enabled for use.
*
* See {@link #getEnabledCipherSuites()} for more information
* on why a specific cipher suite may never be used on a engine.
*
* @param suites Names of all the cipher suites to enable
* @throws IllegalArgumentException when one or more of the ciphers
* named by the parameter is not supported, or when the
* parameter is null.
* @see #getSupportedCipherSuites()
* @see #getEnabledCipherSuites()
*/
public abstract void setEnabledCipherSuites(String suites []);
/**
* Returns the names of the protocols which could be enabled for use
* with this SSLEngine
.
*
* @return an array of protocols supported
*/
public abstract String [] getSupportedProtocols();
/**
* Returns the names of the protocol versions which are currently
* enabled for use with this SSLEngine
.
*
* @return an array of protocols
* @see #setEnabledProtocols(String [])
*/
public abstract String [] getEnabledProtocols();
// Android-added: Added paragraph about contiguous protocols.
/**
* Set the protocol versions enabled for use on this engine.
*
* The protocols must have been listed by getSupportedProtocols()
* as being supported. Following a successful call to this method,
* only protocols listed in the protocols
parameter
* are enabled for use.
*
* Because of the way the protocol version is negotiated, connections
* will only be able to use a member of the lowest set of contiguous
* enabled protocol versions. For example, enabling TLSv1.2 and TLSv1
* will result in connections only being able to use TLSv1.
*
* @param protocols Names of all the protocols to enable.
* @throws IllegalArgumentException when one or more of
* the protocols named by the parameter is not supported or
* when the protocols parameter is null.
* @see #getEnabledProtocols()
*/
public abstract void setEnabledProtocols(String protocols[]);
/**
* Returns the SSLSession
in use in this
* SSLEngine
.
*
* These can be long lived, and frequently correspond to an entire
* login session for some user. The session specifies a particular
* cipher suite which is being actively used by all connections in
* that session, as well as the identities of the session's client
* and server.
*
* Unlike {@link SSLSocket#getSession()}
* this method does not block until handshaking is complete.
*
* Until the initial handshake has completed, this method returns
* a session object which reports an invalid cipher suite of
* "SSL_NULL_WITH_NULL_NULL".
*
* @return the SSLSession
for this SSLEngine
* @see SSLSession
*/
public abstract SSLSession getSession();
/**
* Returns the {@code SSLSession} being constructed during a SSL/TLS
* handshake.
*
* TLS protocols may negotiate parameters that are needed when using
* an instance of this class, but before the {@code SSLSession} has
* been completely initialized and made available via {@code getSession}.
* For example, the list of valid signature algorithms may restrict
* the type of certificates that can used during TrustManager
* decisions, or the maximum TLS fragment packet sizes can be
* resized to better support the network environment.
*
* This method provides early access to the {@code SSLSession} being
* constructed. Depending on how far the handshake has progressed,
* some data may not yet be available for use. For example, if a
* remote server will be sending a Certificate chain, but that chain
* has yet not been processed, the {@code getPeerCertificates}
* method of {@code SSLSession} will throw a
* SSLPeerUnverifiedException. Once that chain has been processed,
* {@code getPeerCertificates} will return the proper value.
*
* @see SSLSocket
* @see SSLSession
* @see ExtendedSSLSession
* @see X509ExtendedKeyManager
* @see X509ExtendedTrustManager
*
* @return null if this instance is not currently handshaking, or
* if the current handshake has not progressed far enough to
* create a basic SSLSession. Otherwise, this method returns the
* {@code SSLSession} currently being negotiated.
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
*
* @since 1.7
*/
public SSLSession getHandshakeSession() {
throw new UnsupportedOperationException();
}
/**
* Initiates handshaking (initial or renegotiation) on this SSLEngine.
*
* This method is not needed for the initial handshake, as the
* wrap()
and unwrap()
methods will
* implicitly call this method if handshaking has not already begun.
*
* Note that the peer may also request a session renegotiation with
* this SSLEngine
by sending the appropriate
* session renegotiate handshake message.
*
* Unlike the {@link SSLSocket#startHandshake()
* SSLSocket#startHandshake()} method, this method does not block
* until handshaking is completed.
*
* To force a complete SSL/TLS session renegotiation, the current
* session should be invalidated prior to calling this method.
*
* Some protocols may not support multiple handshakes on an existing
* engine and may throw an SSLException
.
*
* @throws SSLException
* if a problem was encountered while signaling the
* SSLEngine
to begin a new handshake.
* See the class description for more information on
* engine closure.
* @throws IllegalStateException if the client/server mode
* has not yet been set.
* @see SSLSession#invalidate()
*/
public abstract void beginHandshake() throws SSLException;
/**
* Returns the current handshake status for this SSLEngine
.
*
* @return the current SSLEngineResult.HandshakeStatus
.
*/
public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus();
/**
* Configures the engine to use client (or server) mode when
* handshaking.
*
* This method must be called before any handshaking occurs.
* Once handshaking has begun, the mode can not be reset for the
* life of this engine.
*
* Servers normally authenticate themselves, and clients
* are not required to do so.
*
* @param mode true if the engine should start its handshaking
* in "client" mode
* @throws IllegalArgumentException if a mode change is attempted
* after the initial handshake has begun.
* @see #getUseClientMode()
*/
public abstract void setUseClientMode(boolean mode);
/**
* Returns true if the engine is set to use client mode when
* handshaking.
*
* @return true if the engine should do handshaking
* in "client" mode
* @see #setUseClientMode(boolean)
*/
public abstract boolean getUseClientMode();
/**
* Configures the engine to require client authentication. This
* option is only useful for engines in the server mode.
*
* An engine's client authentication setting is one of the following:
*
* - client authentication required
*
- client authentication requested
*
- no client authentication desired
*
*
* Unlike {@link #setWantClientAuth(boolean)}, if this option is set and
* the client chooses not to provide authentication information
* about itself, the negotiations will stop and the engine will
* begin its closure procedure.
*
* Calling this method overrides any previous setting made by
* this method or {@link #setWantClientAuth(boolean)}.
*
* @param need set to true if client authentication is required,
* or false if no client authentication is desired.
* @see #getNeedClientAuth()
* @see #setWantClientAuth(boolean)
* @see #getWantClientAuth()
* @see #setUseClientMode(boolean)
*/
public abstract void setNeedClientAuth(boolean need);
/**
* Returns true if the engine will require client authentication.
* This option is only useful to engines in the server mode.
*
* @return true if client authentication is required,
* or false if no client authentication is desired.
* @see #setNeedClientAuth(boolean)
* @see #setWantClientAuth(boolean)
* @see #getWantClientAuth()
* @see #setUseClientMode(boolean)
*/
public abstract boolean getNeedClientAuth();
/**
* Configures the engine to request client authentication.
* This option is only useful for engines in the server mode.
*
* An engine's client authentication setting is one of the following:
*
* - client authentication required
*
- client authentication requested
*
- no client authentication desired
*
*
* Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and
* the client chooses not to provide authentication information
* about itself, the negotiations will continue.
*
* Calling this method overrides any previous setting made by
* this method or {@link #setNeedClientAuth(boolean)}.
*
* @param want set to true if client authentication is requested,
* or false if no client authentication is desired.
* @see #getWantClientAuth()
* @see #setNeedClientAuth(boolean)
* @see #getNeedClientAuth()
* @see #setUseClientMode(boolean)
*/
public abstract void setWantClientAuth(boolean want);
/**
* Returns true if the engine will request client authentication.
* This option is only useful for engines in the server mode.
*
* @return true if client authentication is requested,
* or false if no client authentication is desired.
* @see #setNeedClientAuth(boolean)
* @see #getNeedClientAuth()
* @see #setWantClientAuth(boolean)
* @see #setUseClientMode(boolean)
*/
public abstract boolean getWantClientAuth();
/**
* Controls whether new SSL sessions may be established by this engine.
* If session creations are not allowed, and there are no
* existing sessions to resume, there will be no successful
* handshaking.
*
* @param flag true indicates that sessions may be created; this
* is the default. false indicates that an existing session
* must be resumed
* @see #getEnableSessionCreation()
*/
public abstract void setEnableSessionCreation(boolean flag);
/**
* Returns true if new SSL sessions may be established by this engine.
*
* @return true indicates that sessions may be created; this
* is the default. false indicates that an existing session
* must be resumed
* @see #setEnableSessionCreation(boolean)
*/
public abstract boolean getEnableSessionCreation();
/**
* Returns the SSLParameters in effect for this SSLEngine.
* The ciphersuites and protocols of the returned SSLParameters
* are always non-null.
*
* @return the SSLParameters in effect for this SSLEngine.
* @since 1.6
*/
public SSLParameters getSSLParameters() {
SSLParameters params = new SSLParameters();
params.setCipherSuites(getEnabledCipherSuites());
params.setProtocols(getEnabledProtocols());
if (getNeedClientAuth()) {
params.setNeedClientAuth(true);
} else if (getWantClientAuth()) {
params.setWantClientAuth(true);
}
return params;
}
/**
* Applies SSLParameters to this engine.
*
*
This means:
*
* - If {@code params.getCipherSuites()} is non-null,
* {@code setEnabledCipherSuites()} is called with that value.
* - If {@code params.getProtocols()} is non-null,
* {@code setEnabledProtocols()} is called with that value.
* - If {@code params.getNeedClientAuth()} or
* {@code params.getWantClientAuth()} return {@code true},
* {@code setNeedClientAuth(true)} and
* {@code setWantClientAuth(true)} are called, respectively;
* otherwise {@code setWantClientAuth(false)} is called.
* - If {@code params.getServerNames()} is non-null, the engine will
* configure its server names with that value.
* - If {@code params.getSNIMatchers()} is non-null, the engine will
* configure its SNI matchers with that value.
*
*
* @param params the parameters
* @throws IllegalArgumentException if the setEnabledCipherSuites() or
* the setEnabledProtocols() call fails
* @since 1.6
*/
public void setSSLParameters(SSLParameters params) {
String[] s;
s = params.getCipherSuites();
if (s != null) {
setEnabledCipherSuites(s);
}
s = params.getProtocols();
if (s != null) {
setEnabledProtocols(s);
}
if (params.getNeedClientAuth()) {
setNeedClientAuth(true);
} else if (params.getWantClientAuth()) {
setWantClientAuth(true);
} else {
setWantClientAuth(false);
}
}
// BEGIN Android-added: Integrate ALPN-related methods from OpenJDK 9+181
// Also removed references to DTLS in documentation; Android doesn't support DTLS.
/**
* Returns the most recent application protocol value negotiated for this
* connection.
*
* If supported by the underlying SSL/TLS implementation,
* application name negotiation mechanisms such as RFC 7301 , the
* Application-Layer Protocol Negotiation (ALPN), can negotiate
* application-level values between peers.
*
* @implSpec
* The implementation in this class throws
* {@code UnsupportedOperationException} and performs no other action.
*
* @return null if it has not yet been determined if application
* protocols might be used for this connection, an empty
* {@code String} if application protocols values will not
* be used, or a non-empty application protocol {@code String}
* if a value was successfully negotiated.
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
* @since 9
*/
public String getApplicationProtocol() {
throw new UnsupportedOperationException();
}
/**
* Returns the application protocol value negotiated on a SSL/TLS
* handshake currently in progress.
*
* Like {@link #getHandshakeSession()},
* a connection may be in the middle of a handshake. The
* application protocol may or may not yet be available.
*
* @implSpec
* The implementation in this class throws
* {@code UnsupportedOperationException} and performs no other action.
*
* @return null if it has not yet been determined if application
* protocols might be used for this handshake, an empty
* {@code String} if application protocols values will not
* be used, or a non-empty application protocol {@code String}
* if a value was successfully negotiated.
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
* @since 9
*/
public String getHandshakeApplicationProtocol() {
throw new UnsupportedOperationException();
}
/**
* Registers a callback function that selects an application protocol
* value for a SSL/TLS handshake.
* The function overrides any values supplied using
* {@link SSLParameters#setApplicationProtocols
* SSLParameters.setApplicationProtocols} and it supports the following
* type parameters:
*
*
* - {@code SSLEngine}
*
- The function's first argument allows the current {@code SSLEngine}
* to be inspected, including the handshake session and configuration
* settings.
*
- {@code List
}
* - The function's second argument lists the application protocol names
* advertised by the TLS peer.
*
- {@code String}
*
- The function's result is an application protocol name, or null to
* indicate that none of the advertised names are acceptable.
* If the return value is an empty {@code String} then application
* protocol indications will not be used.
* If the return value is null (no value chosen) or is a value that
* was not advertised by the peer, the underlying protocol will
* determine what action to take. (For example, ALPN will send a
* "no_application_protocol" alert and terminate the connection.)
*
*
*
* For example, the following call registers a callback function that
* examines the TLS handshake parameters and selects an application protocol
* name:
* {@code
* serverEngine.setHandshakeApplicationProtocolSelector(
* (serverEngine, clientProtocols) -> {
* SSLSession session = serverEngine.getHandshakeSession();
* return chooseApplicationProtocol(
* serverEngine,
* clientProtocols,
* session.getProtocol(),
* session.getCipherSuite());
* });
* }
*
* @apiNote
* This method should be called by TLS server applications before the TLS
* handshake begins. Also, this {@code SSLEngine} should be configured with
* parameters that are compatible with the application protocol selected by
* the callback function. For example, enabling a poor choice of cipher
* suites could result in no suitable application protocol.
* See {@link SSLParameters}.
*
* @implSpec
* The implementation in this class throws
* {@code UnsupportedOperationException} and performs no other action.
*
* @param selector the callback function, or null to disable the callback
* functionality.
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
* @since 9
*/
public void setHandshakeApplicationProtocolSelector(
BiFunction, String> selector) {
throw new UnsupportedOperationException();
}
/**
* Retrieves the callback function that selects an application protocol
* value during a SSL/TLS handshake.
* See {@link #setHandshakeApplicationProtocolSelector
* setHandshakeApplicationProtocolSelector}
* for the function's type parameters.
*
* @implSpec
* The implementation in this class throws
* {@code UnsupportedOperationException} and performs no other action.
*
* @return the callback function, or null if none has been set.
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
* @since 9
*/
public BiFunction, String>
getHandshakeApplicationProtocolSelector() {
throw new UnsupportedOperationException();
}
// END Android-added: Integrate ALPN-related methods from OpenJDK 9+181
}