Interface sun.security.ssl.SSLOptions

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface sun.security.ssl.SSLOptions

public interface SSLOptions
extends Object

SSLOptions exposes the Secure Sockets Layer (SSL) specific functionality of an SSL socket. An SSL socket supports both this interface (used to access security functionality) and the Socket interface (used to access network features).

SSL is a secure channel communications protocol. You may think of it as being like TCP, with these security features added:

Integrity Protection. SSL protects against modification of messages by an active wiretapper.
Authentication. In most modes, SSL provides peer authentication. Servers are usually authenticated, and clients may be authenticated if the server requests.
Confidentiality (Privacy Protection). In most modes, SSL will encrypt 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.

The SSLOptions API provides access to authentication data (where available), and provides some control over the kinds of protection being used on a given connection.

These kinds of protection are specified by a "cipher suite", which is a combination of cryptographic algorithms used by a given SSL connection. For example, how is integrity protection provided (what kind of message digest is used), how and whether the traffic is privacy-protected, and how authentication keys are exchanged.

When SSL connections are first set up, no security is provided. However, security is always provided by the time that application data is sent on the connection. Before sending such data, application programs may then express preferences for what cipher suites may be used in communication. SSL code performs a negotiation as part of preparing to send data. Some session suite that is supported by both sides of the SSL connection will be used; if there is no such suite, application data will not flow across the connection.

Notes:

This API is still a "work in progress". Comments are solicited! It is not intended to be a complete (or final) API at this time.
Since no form of data compression is standardized for use in SSL, this capability of the protocol is not exposed.

getActiveCipherSuite(): Returns the name of the SSL cipher suite which is currently active on this connection.
getEnabledCipherSuites(): Returns the names of the SSL cipher suites which are currently enabled for use on this connection.
getPeerCertificateChain(): Returns a certificate chain from the peer to a root CA.
getSupportedCipherSuites(): Returns the names of the SSL cipher suites which could be enabled for use on this connection.
setEnabledCipherSuites(String[]): Controls which particular SSL cipher suites are enabled for use on this connection.

getActiveCipherSuite

  public abstract String getActiveCipherSuite()

Returns the name of the SSL cipher suite which is currently active on this connection. This defines the level of protection which is provided to the data sent on the connection, including the kind of encryption used and most aspects of how authentication is performed.

The cipher suite names are as defined in the SSL protocol definition, and include:

SSL_RSA_WITH_RC4_128_MD5 ... a non-exportable cipher suite supporting 128 bit RC4 encryption keys and full RSA key sizes.
SSL_RSA_WITH_RC4_128_SHA ... a non-exportable cipher suite supporing 128 bit RC4 encryption keys and full RSA key sizes.
SSL_RSA_EXPORT_WITH_RC4_40_MD5 ... an exportable cipher suite using weakened RC4 encryption and limited RSA key sizes.
SSL_RSA_WITH_NULL_MD5 ... an exportable cipher suite using no encryption and full RSA key sizes.
SSL_RSA_WITH_NULL_SHA ... an exportable cipher suite using no encryption and full RSA key sizes.
SSL_NULL_WITH_NULL_NULL ... indicates that the connection has not yet been used to send application data, so that no cipher suite is in effect.

Returns:: the name of the currently active cipher suite
See Also:: getEnabledCipherSuites, getSupportedCipherSuites, setEnabledCipherSuites

getEnabledCipherSuites

  public abstract String[] getEnabledCipherSuites()

Returns the names of the SSL cipher suites which are currently enabled for use on this connection. When an SSL socket is first created, all enabled cipher suites (a) protect data confidentiality, by traffic encryption, and (b) can mutually authenticate both clients and servers.

Returns:: an array of cipher suite names
See Also:: getActiveCipherSuite, getSupportedCipherSuites, setEnabledCipherSuites

getPeerCertificateChain

  public abstract CertChain getPeerCertificateChain() throws SSLPeerUnverified

Returns a certificate chain from the peer to a root CA.

Returns:: the chain of certificates
Throws: SSLPeerUnverified: the identity of the peer is not known.

getSupportedCipherSuites

  public abstract String[] getSupportedCipherSuites()

Returns the names of the SSL cipher suites which could be enabled for use on this connection. This list may include cipher suites which do not protect data confidentiality, or which do not support the mutual authentication of clients and servers.

Returns:: an array of cipher suite names; treat as readonly.
See Also:: getActiveCipherSuite, getEnabledCipherSuites, setEnabledCipherSuites

setEnabledCipherSuites

  public abstract void setEnabledCipherSuites(String suites[])

Controls which particular SSL cipher suites are enabled for use on this connection. The cipher suites must have been listed by getCipherSuites() as being supported.

NOTE: This routine should only be called before application data has been sent on the SSL connection. That is, getActiveCipherSuite must return SSL_NULL_WITH_NULL_NULL.

Parameters:: suites - Names of all the cipher suites to enable. These names should be sorted, since the first suite in the list is prioritized as the "best" one to use,
See Also:: getActiveCipherSuite, getEnabledCipherSuites, getSupportedCipherSuites

All Packages  Class Hierarchy  This Package  Previous  Next  Index