This class creates server sockets.  It may be subclassed by other
factories, which create particular types of server sockets.  This
provides a general framework for the addition of public socket-level
functionality.  It is the server side analogue of a socket factory,
and similarly provides a way to capture a variety of policies related
to the sockets being constructed.

 Like socket factories, server Socket factory instances have
methods used to create sockets. There is also an environment
specific default server socket factory; frameworks will often use
their own customized factory.

  Due to polymorphism of both factories and sockets, different
 kinds of sockets can be used by the same application code just
 by passing it different kinds of factories.

  Factories can themselves be customized with parameters used
 in socket construction.  So for example, factories could be
 customized to return sockets with different networking timeouts
 or security parameters already configured.

  The sockets returned to the application can be subclasses
 of java.net.Socket, so that they can directly expose new APIs
 for features such as compression, security, record marking,
 statistics collection, or firewall tunneling.

This class creates sockets.  It may be subclassed by other factories,
which create particular subclasses of sockets and thus provide a general
framework for the addition of public socket-level functionality.

 Socket factories are a simple way to capture a variety of policies
related to the sockets being constructed, producing such sockets in
a way which does not require special configuration of the code which
asks for the sockets:

      Due to polymorphism of both factories and sockets, different
     kinds of sockets can be used by the same application code just
     by passing it different kinds of factories.

      Factories can themselves be customized with parameters used
     in socket construction.  So for example, factories could be
     customized to return sockets with different networking timeouts
     or security parameters already configured.

      The sockets returned to the application can be subclasses
     of java.net.Socket, so that they can directly expose new APIs
     for features such as compression, security, record marking,
     statistics collection, or firewall tunneling.



 Factory classes are specified by environment-specific configuration
mechanisms.  For example, the getDefault method could return
a factory that was appropriate for a particular user or applet, and a
framework could use a factory customized to its own purposes.

A wrapper for CertPathParameters. This class is used to pass validation
settings to CertPath based TrustManagers using the
TrustManagerFactory.init() method.

Instances of this class are immutable.

Extends the SSLSession interface to support additional
session attributes.

This event indicates that an SSL handshake completed on a given
SSL connection.  All of the core information about that handshake's
result is captured through an "SSLSession" object.  As a convenience,
this event class provides direct access to some important session
attributes.

 The source of this event is the SSLSocket on which handshaking
just completed.

This interface is implemented by any class which wants to receive
notifications about the completion of an SSL protocol handshake
on a given SSL connection.

 When an SSL handshake completes, new security parameters will
have been established.  Those parameters always include the security
keys used to protect messages.  They may also include parameters
associated with a new session such as authenticated
peer identity and a new SSL cipher suite.

This class is the base interface for hostname verification.

During handshaking, if the URL's hostname and
the server's identification hostname mismatch, the
verification mechanism can call back to implementers of this
interface to determine if this connection should be allowed.

The policies can be certificate-based
or may depend on other authentication schemes.

These callbacks are used when the default rules for URL hostname
verification fail.

HttpsURLConnection extends HttpURLConnection
with support for https-specific features.

See
http://www.w3.org/pub/WWW/Protocols/ and
 RFC 2818
for more details on the
https specification.

This class uses HostnameVerifier and
SSLSocketFactory.
There are default implementations defined for both classes.
However, the implementations can be replaced on a per-class (static) or
per-instance basis.  All new HttpsURLConnections instances
will be assigned
the "default" static values at instance creation, but they can be overriden
by calling the appropriate per-instance set method(s) before
connecting.

This is the base interface for JSSE key managers.

KeyManagers are responsible for managing the
key material which is used to authenticate the local SSLSocket
to its peer.  If no key material is available, the socket will
be unable to present authentication credentials.

KeyManagers are created by either
using a KeyManagerFactory,
or by implementing one of the KeyManager subclasses.

This class acts as a factory for key managers based on a
source of key material. Each key manager manages a specific
type of key material for use by secure sockets. The key
material is based on a KeyStore and/or provider specific sources.

This class defines the Service Provider Interface (SPI)
for the KeyManagerFactory class.

 All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a particular key manager factory.

A parameters object for X509KeyManagers that encapsulates a List
of KeyStore.Builders.

This class is the base interface for providing
algorithm-specific information to a KeyManagerFactory or
TrustManagerFactory.

In some cases, initialization parameters other than keystores
may be needed by a provider.  Users of that particular provider
are expected to pass an implementation of the appropriate
sub-interface of this class as defined by the
provider.  The provider can then call the specified methods in
the ManagerFactoryParameters implementation to obtain the
needed information.

Instances of this class represent a server name of type
host_name in a Server Name
Indication (SNI) extension.

As described in section 3, "Server Name Indication", of
TLS Extensions (RFC 6066),
"HostName" contains the fully qualified DNS hostname of the server, as
understood by the client.  The encoded server name value of a hostname is
represented as a byte string using ASCII encoding without a trailing dot.
This allows the support of Internationalized Domain Names (IDN) through
the use of A-labels (the ASCII-Compatible Encoding (ACE) form of a valid
string of Internationalized Domain Names for Applications (IDNA)) defined
in RFC 5890.

Note that SNIHostName objects are immutable.

Instances of this class represent a matcher that performs match
operations on an SNIServerName instance.

Servers can use Server Name Indication (SNI) information to decide if
specific SSLSocket or SSLEngine instances should accept
a connection.  For example, when multiple "virtual" or "name-based"
servers are hosted on a single underlying network address, the server
application can use SNI information to determine whether this server is
the exact server that the client wants to access.  Instances of this
class can be used by a server to verify the acceptable server names of
a particular type, such as host names.

SNIMatcher objects are immutable.  Subclasses should not provide
methods that can change the state of an instance once it has been created.

Instances of this class represent a server name in a Server Name
Indication (SNI) extension.

The SNI extension is a feature that extends the SSL/TLS protocols to
indicate what server name the client is attempting to connect to during
handshaking.  See section 3, "Server Name Indication", of TLS Extensions (RFC 6066).

SNIServerName objects are immutable.  Subclasses should not provide
methods that can change the state of an instance once it has been created.

Instances of this class represent a secure socket protocol
implementation which acts as a factory for secure socket
factories or SSLEngines. This class is initialized
with an optional set of key and trust managers and source of
secure random bytes.

 Every implementation of the Java platform is required to support the
following standard SSLContext protocol:

TLSv1

This protocol is described in the
SSLContext section of the
Java Cryptography Architecture Standard Algorithm Name Documentation.
Consult the release documentation for your implementation to see if any
other algorithms are supported.

This class defines the Service Provider Interface (SPI)
for the SSLContext class.

 All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a particular SSL context.

  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.

              app data

           |           ^
           |     |     |
           v     |     |
      ----+-----|-----+----+
      |          |          |
      |       SSL|Engine    |

              net data

 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.

  Supported cipher suites:  all the suites which are
 supported by the SSL implementation.  This list is reported
 using getSupportedCipherSuites().

  Enabled 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.

 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.

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 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 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 non-blocking I/O (polling), selectable non-blocking I/O, Socket and the
traditional Input/OutputStreams, local 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 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() or 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.



  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 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 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:


      Supported cipher suites:  all the suites which are
     supported by the SSL implementation.  This list is reported
     using getSupportedCipherSuites().

      Enabled 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.


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 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.

An encapsulation of the result state produced by
SSLEngine I/O calls.

 A SSLEngine provides a means for establishing
secure communication sessions between two peers.  SSLEngine
operations typically consume bytes from an input buffer and produce
bytes in an output buffer.  This class provides operational result
values describing the state of the SSLEngine, including
indications of what operations are needed to finish an
ongoing handshake.  Lastly, it reports the number of bytes consumed
and produced as a result of this operation.

Indicates some kind of error detected by an SSL subsystem.
This class is the general class of exceptions produced
by failed SSL-related operations.

Indicates that the client and server could not negotiate the
desired level of security.  The connection is no longer usable.

Reports a bad SSL key.  Normally, this indicates misconfiguration
of the server or client SSL certificate and private key.

Encapsulates parameters for an SSL/TLS connection. The parameters
are the list of ciphersuites to be accepted in an SSL/TLS handshake,
the list of protocols to be allowed, the endpoint identification
algorithm during SSL/TLS handshaking, the Server Name Indication (SNI),
the algorithm constraints and whether SSL/TLS servers should request
or require client authentication, etc.

SSLParameters can be created via the constructors in this class.
Objects can also be obtained using the getSSLParameters()
methods in
SSLSocket and
SSLServerSocket and
SSLEngine or the
getDefaultSSLParameters() and
getSupportedSSLParameters()
methods in SSLContext.

SSLParameters can be applied to a connection via the methods
SSLSocket.setSSLParameters() and
SSLServerSocket.setSSLParameters()
and SSLEngine.setSSLParameters().

Indicates that the peer's identity has not been verified.

When the peer was not able to
identify itself (for example; no certificate, the particular
cipher suite being used does not support authentication, or no
peer authentication was established during SSL handshaking) this
exception is thrown.

This class is for various network permissions.
An SSLPermission contains a name (also referred to as a "target name") but
no actions list; you either have the named permission
or you don't.

The target name is the name of the network permission (see below). The naming
convention follows the  hierarchical property naming convention.
Also, an asterisk
may appear at the end of the name, following a ".", or by itself, to
signify a wildcard match. For example: "foo.*" and "*" signify a wildcard
match, while "*foo" and "a*b" do not.

The following table lists all the possible SSLPermission target names,
and for each provides a description of what the permission allows
and a discussion of the risks of granting code the permission.



Permission Target Name
What the Permission Allows
Risks of Allowing this Permission



  setHostnameVerifier
  The ability to set a callback which can decide whether to
allow a mismatch between the host being connected to by
an HttpsURLConnection and the common name field in
server certificate.

  Malicious
code can set a verifier that monitors host names visited by
HttpsURLConnection requests or that allows server certificates
with invalid common names.




  getSSLSessionContext
  The ability to get the SSLSessionContext of an SSLSession.

  Malicious code may monitor sessions which have been established
with SSL peers or might invalidate sessions to slow down performance.




  setDefaultSSLContext
  The ability to set the default SSL context

  Malicious code can set a context that monitors the opening of
connections or the plaintext data that is transmitted.

Reports an error in the operation of the SSL protocol.  Normally
this indicates a flaw in one of the protocol implementations.

This class extends ServerSockets and
provides secure server sockets using protocols such as the Secure
Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.

Instances of this class are generally created using a
SSLServerSocketFactory.  The primary function
of SSLServerSockets
is to create SSLSockets by accepting
connections.

SSLServerSockets contain several pieces of state data
which are inherited by the SSLSocket at
socket creation.  These include the enabled cipher
suites and protocols, whether client
authentication is necessary, and whether created sockets should
begin handshaking in client or server mode.  The state
inherited by the created SSLSocket can be
overriden by calling the appropriate methods.

SSLServerSocketFactorys create
SSLServerSockets.

  Peer Identity.  Sessions are between a particular
 client and a particular server.  The identity of the peer may
 have been established as part of session setup.  Peers are
 generally identified by X.509 certificate chains.

  Cipher Suite Name.  Cipher suites describe the
 kind of cryptographic protection that's used by connections
 in a particular session.

  Peer Host.  All connections in a session are
 between the same two hosts.  The address of the host on the other
 side of the connection is available.

In SSL, sessions are used to describe an ongoing relationship between
two entities.  Each SSL connection involves one session at a time, but
that session may be used on many connections between those entities,
simultaneously or sequentially.  The session used on a connection may
also be replaced by a different session.  Sessions are created, or
rejoined, as part of the SSL handshaking protocol. Sessions may be
invalidated due to policies affecting security or resource usage,
or by an application explicitly calling invalidate.
Session management policies are typically used to tune performance.

 In addition to the standard session attributes, SSL sessions expose
these read-only attributes:

      Peer Identity.  Sessions are between a particular
     client and a particular server.  The identity of the peer may
     have been established as part of session setup.  Peers are
     generally identified by X.509 certificate chains.

      Cipher Suite Name.  Cipher suites describe the
     kind of cryptographic protection that's used by connections
     in a particular session.

      Peer Host.  All connections in a session are
     between the same two hosts.  The address of the host on the other
     side of the connection is available.



 Sessions may be explicitly invalidated.  Invalidation may also
be done implicitly, when faced with certain kinds of errors.

This event is propagated to a SSLSessionBindingListener.
When a listener object is bound or unbound to an SSLSession by
SSLSession.putValue(String, Object)
or SSLSession.removeValue(String), objects which
implement the SSLSessionBindingListener will be receive an
event of this type.  The event's name field is the
key in which the listener is being bound or unbound.

This interface is implemented by objects which want to know when
they are being bound or unbound from a SSLSession.  When either event
occurs via SSLSession.putValue(String, Object)
or SSLSession.removeValue(String), the event is communicated
through a SSLSessionBindingEvent identifying the session.

 Sessions can be set to expire after a specified
 time limit.
 The number of sessions that can be stored in context
 can be limited.

A SSLSessionContext represents a set of
SSLSessions associated with a single entity. For example,
it could be associated with a server or client who participates in many
sessions concurrently.

Not all environments will contain session contexts.

There are SSLSessionContext parameters that affect how
sessions are stored:

     Sessions can be set to expire after a specified
     time limit.
     The number of sessions that can be stored in context
     can be limited.

A session can be retrieved based on its session id, and all session id's
in a SSLSessionContext can be listed.

  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 as requested by servers.

  Confidentiality (Privacy Protection).  In most
 modes, SSL 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.

  calling startHandshake which explicitly
         begins handshakes, or
  any attempt to read or write application data on
         this socket causes an implicit handshake, or
  a call to getSession tries to set up a session
         if there is no currently valid session, and
         an implicit handshake is done.

  Supported cipher suites:  all the suites which are
 supported by the SSL implementation.  This list is reported
 using getSupportedCipherSuites.

  Enabled cipher suites, which may be fewer
 than the full set of supported suites.  This group is
 set using the setEnabledCipherSuites method, and
 queried using the getEnabledCipherSuites method.
 Initially, a default set of cipher suites will be enabled on
 a new socket that represents the minimum suggested configuration.

This class extends Sockets and provides secure
socket using protocols such as the "Secure
Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.

Such sockets are normal stream sockets, but they
add a layer of security protections over the underlying network transport
protocol, such as TCP.  Those protections include:

      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 as requested by servers.

      Confidentiality (Privacy Protection).  In most
     modes, SSL 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 ciphersuite 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 initial handshake on this connection can be initiated in
one of three ways:

      calling startHandshake which explicitly
             begins handshakes, or
      any attempt to read or write application data on
             this socket causes an implicit handshake, or
      a call to getSession tries to set up a session
             if there is no currently valid session, and
             an implicit handshake is done.


If handshaking fails for any reason, the SSLSocket
is closed, and no further communications can be done.

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 getSupportedCipherSuites.

      Enabled cipher suites, which may be fewer
     than the full set of supported suites.  This group is
     set using the setEnabledCipherSuites method, and
     queried using the getEnabledCipherSuites method.
     Initially, a default set of cipher suites will be enabled on
     a new socket 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 ciphersuite be
selected.

When SSLSockets are first created, no handshaking
is done so that applications may first set their communication
preferences:  what cipher suites to use, whether the socket should be
in client or server mode, etc.
However, security is always provided by the time that application data
is sent over the connection.

 You may register to receive event notification of handshake
completion.  This involves
the use of two additional classes.  HandshakeCompletedEvent
objects are passed to HandshakeCompletedListener instances,
which are registered by users of this API.

SSLSockets are created by SSLSocketFactorys,
or by accepting a connection from a
SSLServerSocket.

A SSL socket must choose to operate in the client or server mode.
This will determine who begins the handshaking process, as well
as which messages should be sent by each party.  Each
connection must have one client and one server, or handshaking
will not progress properly.  Once the initial handshaking has started, a
socket can not switch between client and server modes, even when
performing renegotiations.

SSLSocketFactorys create SSLSockets.

Standard constants definitions

This is the base interface for JSSE trust managers.

TrustManagers are responsible for managing the trust material
that is used when making trust decisions, and for deciding whether
credentials presented by a peer should be accepted.

TrustManagers are created by either
using a TrustManagerFactory,
or by implementing one of the TrustManager subclasses.

This class acts as a factory for trust managers based on a
source of trust material. Each trust manager manages a specific
type of trust material for use by secure sockets. The trust
material is based on a KeyStore and/or provider specific sources.

This class defines the Service Provider Interface (SPI)
for the TrustManagerFactory class.

 All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a particular trust manager factory.

Abstract class that provides for extension of the X509KeyManager
interface.

Methods in this class should be overriden to provide actual
implementations.

Extensions to the X509TrustManager interface to support
SSL/TLS connection sensitive trust management.

To prevent man-in-the-middle attacks, hostname checks can be done
to verify that the hostname in an end-entity certificate matches the
targeted hostname.  TLS does not require such checks, but some protocols
over TLS (such as HTTPS) do.  In earlier versions of the JDK, the
certificate chain checks were done at the SSL/TLS layer, and the hostname
verification checks were done at the layer over TLS.  This class allows
for the checking to be done during a single call to this class.

RFC 2830 defines the server identification specification for the "LDAPS"
algorithm. RFC 2818 defines both the server identification and the
client identification specification for the "HTTPS" algorithm.

Instances of this interface manage which X509 certificate-based
key pairs are used to authenticate the local side of a secure
socket.

During secure socket negotiations, implentations
call methods in this interface to:

 determine the set of aliases that are available for negotiations
     based on the criteria presented,
 select the  best alias based on
     the criteria presented, and
 obtain the corresponding key material for given aliases.


Note: the X509ExtendedKeyManager should be used in favor of this
class.

Instance of this interface manage which X509 certificates
may be used to authenticate the remote side of a secure
socket. Decisions may be based on trusted certificate
authorities, certificate revocation lists, online
status checking or other means.