## org.beepcore.beep.profile.tls.jsse
Class TLSProfileJSSE

    java.lang.Object
      org.beepcore.beep.core.TuningProfile
          org.beepcore.beep.profile.tls.TLSProfile
              org.beepcore.beep.profile.tls.jsse.TLSProfileJSSE

All Implemented Interfaces:
  Profile, RequestHandler, StartChannelListener

public class TLSProfileJSSE
extends TLSProfile
implements Profile, StartChannelListener, RequestHandler

TLS provides encrypted, and optionally authenticated, communication over a session. TLS is a tuning profile, a special set of profiles that affect an entire session. As a result, only one channel with the profile of TLS may be open per session. As with all tuning profiles, TLS may be configured using properties passed into the init method.

See Also:
  `init(java.lang.String, org.beepcore.beep.profile.ProfileConfiguration)`, `Profile`, `Channel`, `TLSProfileJSSEHandshakeCompletedListener`

Field Summary
`static String` `PROCEED1`
`static String` `PROCEED2`
`static String` `READY1`
`static String` `READY2`

Fields inherited from class org.beepcore.beep.profile.tls.TLSProfile
`URI`

Constructor Summary
`TLSProfileJSSE()` TLS provides encryption and optionally authentication for a session by opening a channel with this profile.

Method Summary
`void` `addHandshakeCompletedListener(TLSProfileJSSEHandshakeCompletedListener x)` add a listener for completed handshakes.
`boolean` `advertiseProfile(Session session)` Default implementation of advertiseProfile.
`boolean` `advertiseProfile(Session session, SessionTuningProperties tuning)` advertiseProfile
`void` `closeChannel(Channel channel)` Called when the underlying BEEP framework receives a "close" element.
`static SessionCredential` `generateCredential()` return the default credentials for the new session to use after a TLS negotiation is complete.
`StartChannelListener` `init(String uri, ProfileConfiguration config)` init sets the criteria for which an SSL connection is made when a TLS channel is started for a profile.
`void` `receiveMSG(MessageMSG msg)`
`void` `removeHandshakeCompletedListener(TLSProfileJSSEHandshakeCompletedListener x)` remove a listener for completed handshakes.
`void` `startChannel(Channel channel, String encoding, String data)` Called when the underlying BEEP framework receives a "start" element for the TLS profile.
`TCPSession` `startTLS(TCPSession session)` start a channel for the TLS profile.

Methods inherited from class org.beepcore.beep.profile.tls.TLSProfile
`getDefaultInstance, getInstance`

Methods inherited from class org.beepcore.beep.core.TuningProfile
`abort, begin, begin, complete, disableIO, enableIO, reset, sendProfile, setLocalCredential, setPeerCredential, startChannel`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### PROCEED1

    public static final String PROCEED1

See Also:
  Constant Field Values

### PROCEED2

    public static final String PROCEED2

See Also:
  Constant Field Values

### READY1

    public static final String READY1

See Also:
  Constant Field Values

### READY2

    public static final String READY2

See Also:
  Constant Field Values

Constructor Detail

### TLSProfileJSSE

    public TLSProfileJSSE()

  TLS provides encryption and optionally authentication for a session by opening a channel with this profile. The default action is to set up for a channel with encryption only, no authentication. To mandate authentication, set the configuration via `init`.

See Also:
  `Profile`

Method Detail

### init

    public StartChannelListener init(String uri,
                                     ProfileConfiguration config)
                              throws BEEPException

  init sets the criteria for which an SSL connection is made when a TLS channel is started for a profile. It should only be called once. For the properties, the initiator is defined as the peer who starts the channel for the TLS profile, the listener is the peer that receives the the channel start request, irregardless of which actually started the session.

  Specified by:
    `init` in interface `Profile`
  Parameters:
    `config` - `ProfileConfiguration` object that contains key value pairs to initialize the TLS layer. None of these are mandatory, but if you wish communication to be anonymous with no authentication, (i.e., the listener to not send back a certificate), you must set "Listener Anonymous" to "true" and "Initiator Authentication Required" to "false". The meaningful properties that can be set are these:

    Listener Anonymous | (true|false) must be set to false if the listener will not authenticate itself
    Initiator Authentication Required | (true|false) set if the initiator should send a certificate and the listener expects a certificate.
    Cipher Suite | not yet implemented.the algorithms that can be used for encryption, authentication, and key exchange.
    Key Algorithm | key management algorithm. See `KeyManagerFactory.getInstance(java.lang.String)`
    Key Provider | provider of the key management algorithm. Defaults to `com.sun.net.ssl.internal.ssl.Provider` See `KeyManagerFactory.getInstance(java.lang.String)`
    Trust Algorithm | algorithm to be used by the trust manager. See `TrustManagerFactory.getInstance(java.lang.String)`
    Trust Provider | provider of the trust manager. Defaults to `com.sun.net.ssl.internal.ssl.Provider`. See `TrustManagerFactory.getInstance(java.lang.String)`
    Key Store Passphrase | pass phrase used to encrypt the key store. See `KeyStore.load(java.io.InputStream, char[])`
    Key Store Data Type | data type of the key store passed in. "file" is currently the only value accepted, meaning Key Store is the name of a file containing keys. See `KeyStore.load(java.io.InputStream, char[])`
    Key Store | value of the key store, dependent on the type in Key Store Data Type. See `KeyStore.load(java.io.InputStream, char[])`
    Key Store Format | format of the keys within the key store. Default is "JKS". See `KeyStore.getInstance(java.lang.String)`
    Key Store Provider | provider for the key stores. See `KeyStore.getInstance(java.lang.String)`
    Trust Store Passphrase | pass phrase used to encrypt the trust store. See `KeyStore.load(java.io.InputStream, char[])`
    Trust Store Data Type | data type of the certificates in the trust store. "file" is currently th only value accepted, meaning the trust store is a file on the local disk. See `KeyStore.load(java.io.InputStream, char[])`
    Trust Store | value of the trust store, dependent on the type in Trust Store Data Type See `KeyStore.load(java.io.InputStream, char[])`
    Trust Store Format | format of the certificates within the trust store. Default is "JKS". See `KeyStore.getInstance(java.lang.String)`
    Trust Store Provider | provider for the trust stores. See `KeyStore.getInstance(java.lang.String)`

  Throws:
    `BEEPException` - For any error in the profile configuration, a negative response in the form of a BEEP error will be sent back to the requesting peer. The session will continue to be open and usable, at least from the standpoint of this peer.
  See Also:
    `KeyManagerFactory`, `TrustManagerFactory`, `KeyStore`, `SSLContext`

### advertiseProfile

    public boolean advertiseProfile(Session session,
                                    SessionTuningProperties tuning)
                             throws BEEPException

  advertiseProfile

  Throws:
    `BEEPException`

### startChannel

    public void startChannel(Channel channel,
                             String encoding,
                             String data)
                      throws StartChannelException

  Called when the underlying BEEP framework receives a "start" element for the TLS profile.

  Specified by:
    `startChannel` in interface `StartChannelListener`
  Parameters:
    `channel` - A `Channel` object which represents a channel in this `Session`.
    `data` - The content of the "profile" element selected for this channel (may be `null`).
    `encoding` - specifies whether the content of the "profile" element selected for this channel is represented as a base64-encoded string. The `encoding` is only valid if `data` is not `null`.
  Throws:
    `StartChannelException` - Throwing this exception will cause an error to be returned to the BEEP peer requesting to start a channel. The channel is then discarded.

### receiveMSG

    public void receiveMSG(MessageMSG msg)

  Specified by:
    `receiveMSG` in interface `RequestHandler`

### closeChannel

    public void closeChannel(Channel channel)
                      throws CloseChannelException

  Called when the underlying BEEP framework receives a "close" element.

  Specified by:
    `closeChannel` in interface `StartChannelListener`
  Parameters:
    `channel` - `Channel` which received the close request.
  Throws:
    `CloseChannelException` - Throwing this exception will return an error to the BEEP peer requesting the close. The channel will remain open.

### advertiseProfile

    public boolean advertiseProfile(Session session)
                             throws BEEPException

  Default implementation of advertiseProfile. Just returns TRUE that the TLS profile should be advertised.

  Specified by:
    `advertiseProfile` in interface `StartChannelListener`
  Throws:
    `BEEPException`

### startTLS

    public TCPSession startTLS(TCPSession session)
                        throws BEEPException

  start a channel for the TLS profile. Besides issuing the channel start request, it also performs the initiator side chores necessary to begin encrypted communication using TLS over a session. Parameters regarding the type of encryption and whether or not authentication is required are specified using the profile configuration passed to the `init` method Upon returning, all traffic over the session will be entrusted as per these parameters.

  Parameters:
    `session` - The session to encrypt communcation for
  Returns:
    new `Session` with TLS negotiated.
  Throws:
    `BEEPException` - an error occurs during the channel start request or the TLS handshake (such as trying to negotiate an anonymous connection with a peer that doesn't support an anonymous cipher suite).
  See Also:
    `init - profile configuration`

### generateCredential

    public static SessionCredential generateCredential()

  return the default credentials for the new session to use after a TLS negotiation is complete.

### addHandshakeCompletedListener

    public void addHandshakeCompletedListener(TLSProfileJSSEHandshakeCompletedListener x)

  add a listener for completed handshakes.

  Parameters:
    `x` - receives handshake complete events

### removeHandshakeCompletedListener

    public void removeHandshakeCompletedListener(TLSProfileJSSEHandshakeCompletedListener x)

  remove a listener for completed handshakes.

  Parameters:
    `x` - receives handshake complete events

Copyright ? 2001 Invisible Worlds, Inc. All Rights Reserved.