SSLEngine Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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.
[Android.Runtime.Register("javax/net/ssl/SSLEngine", DoNotGenerateAcw=true)]
public abstract class SSLEngine : Java.Lang.Object[<Android.Runtime.Register("javax/net/ssl/SSLEngine", DoNotGenerateAcw=true)>]
type SSLEngine = class
inherit Object- Inheritance
- Attributes
Remarks
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: <UL>
<LI> <em>Integrity Protection</em>. SSL/TLS protects against modification of messages by an active wiretapper.
<LI> <em>Authentication</em>. In most modes, SSL/TLS provides peer authentication. Servers are usually authenticated, and clients may be authenticated as requested by servers.
<LI> <em>Confidentiality (Privacy Protection)</em>. 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.
</UL>
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 #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 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 java.nio.channels.spi.AbstractSelectableChannel#configureBlocking(boolean) non-blocking I/O (polling), java.nio.channels.Selector selectable non-blocking I/O, java.net.Socket Socket and the traditional Input/OutputStreams, local 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.
<OL> <li> 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.
<li> 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.
<li> 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.
<li> 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.
<li> 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. </OL> An SSLEngine is created by calling 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 #wrap(ByteBuffer, ByteBuffer) wrap() or #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 ByteBuffers must be sized appropriately to hold the maximum record that can be produced. Calls to SSLSession#getPacketBufferSize() and 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 SSLEngineResult) and correct the problem, and then try the call again.
For example, unwrap() will return a SSLEngineResult.Status#BUFFER_OVERFLOW result if the engine determines that there is not enough destination buffer space available. Applications should call 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 SSLEngineResult.Status#BUFFER_UNDERFLOW, the application should call 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 java.lang.Runnable delegated task. When SSLEngineResult indicates that a delegated task result is needed, the application must call #getDelegatedTask() to obtain an outstanding delegated task and call its 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 #isOutboundDone() returns true. All data obtained from the wrap() method should be sent to the peer.
#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 #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 #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:
<UL> <LI> <em>Supported</em> cipher suites: all the suites which are supported by the SSL implementation. This list is reported using #getSupportedCipherSuites().
<LI> <em>Enabled</em> cipher suites, which may be fewer than the full set of supported suites. This group is set using the #setEnabledCipherSuites(String []) method, and queried using the #getEnabledCipherSuites() method. Initially, a default set of cipher suites will be enabled on a new engine that represents the minimum suggested configuration. </UL>
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 #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 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.
<HR>
<B>Concurrency Notes</B>: There are two concurrency issues to be aware of:
<OL> <li>The wrap() and unwrap() methods may execute concurrently of each other.
<li> 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. </OL>
<h3>Default configuration for different Android versions</h3>
SSLEngine instances obtained from the default SSLContext are configured as follows:
<style type="text/css"> tr.deprecated { background-color: #ccc; color: #999; font-style: italic; }</style>
<h4>Protocols</h4> <table> <thead> <tr> <th>Protocol</th> <th>Supported (API Levels)</th> <th>Enabled by default (API Levels)</th> </tr> </thead> <tbody> <tr class="deprecated"> <td>SSLv3</td> <td>1–25</td> <td>1–22</td> </tr> <tr> <td>TLSv1</td> <td>1+</td> <td>1+</td> </tr> <tr> <td>TLSv1.1</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLSv1.2</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLSv1.3</td> <td>29+</td> <td>29+</td> </tr> </tbody> </table>
<h4>Cipher suites</h4> <table> <thead> <tr> <th>Cipher suite</th> <th>Supported (API Levels)</th> <th>Enabled by default (API Levels)</th> </tr> </thead> <tbody> <tr class="deprecated"> <td>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_DHE_DSS_WITH_DES_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_DHE_RSA_WITH_DES_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>SSL_DH_anon_EXPORT_WITH_RC4_40_MD5</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>SSL_DH_anon_WITH_3DES_EDE_CBC_SHA</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>SSL_DH_anon_WITH_DES_CBC_SHA</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>SSL_DH_anon_WITH_RC4_128_MD5</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_RSA_EXPORT_WITH_RC4_40_MD5</td> <td>9-22</td> <td>9-19</td> </tr> <tr> <td>SSL_RSA_WITH_3DES_EDE_CBC_SHA</td> <td>9+</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_RSA_WITH_DES_CBC_SHA</td> <td>9-22</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_RSA_WITH_NULL_MD5</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>SSL_RSA_WITH_NULL_SHA</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>SSL_RSA_WITH_RC4_128_MD5</td> <td>9-25</td> <td>9-19</td> </tr> <tr class="deprecated"> <td>SSL_RSA_WITH_RC4_128_SHA</td> <td>9-25</td> <td>9-23</td> </tr> <tr> <td>TLS_AES_128_GCM_SHA256</td> <td>29+</td> <td>29+</td> </tr> <tr> <td>TLS_AES_256_GCM_SHA384</td> <td>29+</td> <td>29+</td> </tr> <tr> <td>TLS_CHACHA20_POLY1305_SHA256</td> <td>29+</td> <td>29+</td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</td> <td>9-22</td> <td>9-22</td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_AES_128_CBC_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</td> <td>9-22</td> <td>20-22</td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_AES_256_CBC_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_AES_256_GCM_SHA384</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DHE_DSS_WITH_DES_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</td> <td>9-25</td> <td>9-25</td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</td> <td>20-25</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256</td> <td>20-25</td> <td>20-25</td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</td> <td>9-25</td> <td>20-25</td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_AES_256_CBC_SHA256</td> <td>20-25</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_AES_256_GCM_SHA384</td> <td>20-25</td> <td>20-25</td> </tr> <tr class="deprecated"> <td>TLS_DHE_RSA_WITH_DES_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_DSS_WITH_DES_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_RSA_WITH_DES_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_3DES_EDE_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_AES_128_CBC_SHA</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_AES_128_CBC_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_AES_128_GCM_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_AES_256_CBC_SHA</td> <td>9-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_AES_256_CBC_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_AES_256_GCM_SHA384</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_DH_anon_WITH_DES_CBC_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr> <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</td> <td>20+</td> <td>20+</td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</td> <td>20-28</td> <td></td> </tr> <tr> <td>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</td> <td>20+</td> <td>20+</td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384</td> <td>20-28</td> <td></td> </tr> <tr> <td>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</td> <td>24+</td> <td>24+</td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_ECDSA_WITH_NULL_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_ECDSA_WITH_RC4_128_SHA</td> <td>20-25</td> <td>20-23</td> </tr> <tr> <td>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</td> <td>21+</td> <td>21+</td> </tr> <tr> <td>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</td> <td>21+</td> <td>21+</td> </tr> <tr> <td>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</td> <td>24+</td> <td>24+</td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr> <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</td> <td>20+</td> <td>20+</td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</td> <td>20-28</td> <td></td> </tr> <tr> <td>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</td> <td>20+</td> <td>20+</td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384</td> <td>20-28</td> <td></td> </tr> <tr> <td>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</td> <td>24+</td> <td>24+</td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_RSA_WITH_NULL_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDHE_RSA_WITH_RC4_128_SHA</td> <td>20-25</td> <td>20-23</td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_NULL_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_ECDSA_WITH_RC4_128_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_NULL_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_RSA_WITH_RC4_128_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_anon_WITH_NULL_SHA</td> <td>20-22</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_ECDH_anon_WITH_RC4_128_SHA</td> <td>20-22</td> <td></td> </tr> <tr> <td>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLS_FALLBACK_SCSV</td> <td>21+</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_NULL_WITH_NULL_NULL</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_PSK_WITH_3DES_EDE_CBC_SHA</td> <td>21-22</td> <td></td> </tr> <tr> <td>TLS_PSK_WITH_AES_128_CBC_SHA</td> <td>21+</td> <td>21+</td> </tr> <tr> <td>TLS_PSK_WITH_AES_256_CBC_SHA</td> <td>21+</td> <td>21+</td> </tr> <tr class="deprecated"> <td>TLS_PSK_WITH_RC4_128_SHA</td> <td>21-25</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_RSA_EXPORT_WITH_DES40_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_RSA_WITH_3DES_EDE_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr> <td>TLS_RSA_WITH_AES_128_CBC_SHA</td> <td>9+</td> <td>9+</td> </tr> <tr class="deprecated"> <td>TLS_RSA_WITH_AES_128_CBC_SHA256</td> <td>20-28</td> <td></td> </tr> <tr> <td>TLS_RSA_WITH_AES_128_GCM_SHA256</td> <td>20+</td> <td>20+</td> </tr> <tr> <td>TLS_RSA_WITH_AES_256_CBC_SHA</td> <td>9+</td> <td>20+</td> </tr> <tr class="deprecated"> <td>TLS_RSA_WITH_AES_256_CBC_SHA256</td> <td>20-28</td> <td></td> </tr> <tr> <td>TLS_RSA_WITH_AES_256_GCM_SHA384</td> <td>20+</td> <td>20+</td> </tr> <tr class="deprecated"> <td>TLS_RSA_WITH_DES_CBC_SHA</td> <td>1-8</td> <td>1-8</td> </tr> <tr class="deprecated"> <td>TLS_RSA_WITH_NULL_MD5</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_RSA_WITH_NULL_SHA</td> <td>1-8</td> <td></td> </tr> <tr class="deprecated"> <td>TLS_RSA_WITH_NULL_SHA256</td> <td>20-22</td> <td></td> </tr> </tbody> </table>
<em>NOTE</em>: PSK cipher suites are enabled by default only if the SSLContext through which the engine was created has been initialized with a PSKKeyManager.
Added in 1.5.
Java documentation for javax.net.ssl.SSLEngine.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Constructors
| SSLEngine() |
Constructor for an |
| SSLEngine(IntPtr, JniHandleOwnership) |
A constructor used when creating managed representations of JNI objects; called by the runtime. |
| SSLEngine(String, Int32) |
Constructor for an |
Properties
| ApplicationProtocol |
Returns the most recent application protocol value negotiated for this connection. |
| Class |
Returns the runtime class of this |
| DelegatedTask |
Returns a delegate task for this engine instance. |
| EnableSessionCreation |
Returns whether new SSL sessions may be established by this engine. |
| Handle |
The handle to the underlying Android instance. (Inherited from Object) |
| HandshakeApplicationProtocol |
Returns the application protocol value negotiated on a SSL/TLS handshake currently in progress. |
| HandshakeApplicationProtocolSelector |
Retrieves the callback function that selects an application protocol value during a SSL/TLS handshake. -or- Registers a callback function that selects an application protocol value for a SSL/TLS handshake. |
| HandshakeSession |
Returns the |
| HandshakeStatus |
Returns the status of the handshake of this engine instance. |
| IsInboundDone |
Returns whether no more inbound data will be accepted by this engine. |
| IsOutboundDone |
Returns whether no more outbound data will be produced by this engine. |
| JniIdentityHashCode | (Inherited from Object) |
| JniPeerMembers | |
| NeedClientAuth |
Returns whether this engine instance will require client authentication. |
| PeerHost |
Returns the host name of the peer. |
| PeerPort |
Returns the port number of the peer. |
| PeerReference | (Inherited from Object) |
| Session |
Returns the SSL session for this engine instance. |
| SSLParameters |
Returns the SSLParameters in effect for this SSLEngine. -or- Applies SSLParameters to this engine. |
| ThresholdClass |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
| ThresholdType |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
| UseClientMode |
Returns whether this engine is set to act in client mode when handshaking. |
| WantClientAuth |
Returns whether this engine will request client authentication. |
Methods
| BeginHandshake() |
Initiates handshaking (initial or renegotiation) on this SSLEngine. |
| Clone() |
Creates and returns a copy of this object. (Inherited from Object) |
| CloseInbound() |
Signals that no more inbound network data will be sent
to this |
| CloseOutbound() |
Signals that no more outbound application data will be sent
on this |
| Dispose() | (Inherited from Object) |
| Dispose(Boolean) | (Inherited from Object) |
| Equals(Object) |
Indicates whether some other object is "equal to" this one. (Inherited from Object) |
| GetEnabledCipherSuites() |
Returns the names of the SSL cipher suites which are currently enabled for use on this engine. |
| GetEnabledProtocols() |
Returns the names of the protocol versions which are currently
enabled for use with this |
| GetHashCode() |
Returns a hash code value for the object. (Inherited from Object) |
| GetSupportedCipherSuites() |
Returns the names of the cipher suites which could be enabled for use on this engine. |
| GetSupportedProtocols() |
Returns the names of the protocols which could be enabled for use
with this |
| JavaFinalize() |
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object) |
| Notify() |
Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object) |
| NotifyAll() |
Wakes up all threads that are waiting on this object's monitor. (Inherited from Object) |
| SetEnabledCipherSuites(String[]) |
Sets the cipher suites enabled for use on this engine. |
| SetEnabledProtocols(String[]) |
Set the protocol versions enabled for use on this engine. |
| SetHandle(IntPtr, JniHandleOwnership) |
Sets the Handle property. (Inherited from Object) |
| ToArray<T>() | (Inherited from Object) |
| ToString() |
Returns a string representation of the object. (Inherited from Object) |
| UnregisterFromRuntime() | (Inherited from Object) |
| Unwrap(ByteBuffer, ByteBuffer) |
Attempts to decode SSL/TLS network data into a plaintext application data buffer. |
| Unwrap(ByteBuffer, ByteBuffer[]) |
Attempts to decode SSL/TLS network data into a sequence of plaintext application data buffers. |
| Unwrap(ByteBuffer, ByteBuffer[], Int32, Int32) |
Attempts to decode SSL/TLS network data into a subsequence of plaintext application data buffers. |
| Wait() |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object) |
| Wait(Int64) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
| Wait(Int64, Int32) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
| Wrap(ByteBuffer, ByteBuffer) |
Attempts to encode a buffer of plaintext application data into SSL/TLS network data. |
| Wrap(ByteBuffer[], ByteBuffer) |
Attempts to encode plaintext bytes from a sequence of data buffers into SSL/TLS network data. |
| Wrap(ByteBuffer[], Int32, Int32, ByteBuffer) |
Attempts to encode plaintext bytes from a subsequence of data buffers into SSL/TLS network data. |
Explicit Interface Implementations
| IJavaPeerable.Disposed() | (Inherited from Object) |
| IJavaPeerable.DisposeUnlessReferenced() | (Inherited from Object) |
| IJavaPeerable.Finalized() | (Inherited from Object) |
| IJavaPeerable.JniManagedPeerState | (Inherited from Object) |
| IJavaPeerable.SetJniIdentityHashCode(Int32) | (Inherited from Object) |
| IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from Object) |
| IJavaPeerable.SetPeerReference(JniObjectReference) | (Inherited from Object) |
Extension Methods
| JavaCast<TResult>(IJavaObject) |
Performs an Android runtime-checked type conversion. |
| JavaCast<TResult>(IJavaObject) | |
| GetJniTypeName(IJavaPeerable) | |