## org.beepcore.beep.profile.tls.ptls
Class TLSProfilePureTLS

    java.lang.Object
      org.beepcore.beep.core.TuningProfile
          org.beepcore.beep.profile.tls.ptls.TLSProfilePureTLS

All Implemented Interfaces:
  RequestHandler, StartChannelListener

public class TLSProfilePureTLS
extends TuningProfile
implements StartChannelListener, RequestHandler

TLS provides encrypted and authenticated communication over a session using the PureTLS library. 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, though TLSProfilePureTLS requires some

This profile uses the PureTLS library from www.rtfm.com/puretls by Claymore Systems and Eric Rescorla to implement the TLS protocol for a session.

For now, this profile for TLS will NOT use anonymous ciphers. All ciphers must have a private key and certificate chain.

See Also:
  `init(java.lang.String, java.util.Hashtable)`, `Profile`, `Channel`, `TLSProfilePureTLSHandshakeCompletedListener`, `List`

Field Summary
`static String` `PROCEED1`
`static String` `PROCEED2`
`static String` `PROPERTY_CERTIFICATES`
`static String` `PROPERTY_CIPHER_SUITE`
`static String` `PROPERTY_CLIENT_AUTH_REQUIRED`
`static String` `PROPERTY_PRIVATE_KEY`
`static String` `PROPERTY_PRIVATE_KEY_ALGORITHM`
`static String` `PROPERTY_TRUSTED_CERTS`
`static String` `READY1`
`static String` `READY2`
`static String` `URI` use this as the uri for the channel to open to encrypt a session using TLS.

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

Method Summary
`boolean` `advertiseProfile(Session session)` Default implementation of advertiseProfile.
`boolean` `advertiseProfile(Session session, SessionTuningProperties tuning)`
`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.
`int` `getMaxCiphersKnown()` return the maximum number of ciphers that can be set.
`StartChannelListener` `init(String uri, Hashtable config)` init sets the criteria for which an TLS connection is made when a TLS channel is started for a profile.
`void` `receiveMSG(MessageMSG msg)`
`void` `setHandshakeCompletedListener(TLSProfilePureTLSHandshakeCompletedListener x)` set 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.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

### URI

    public static final String URI

  use this as the uri for the channel to open to encrypt a session using TLS.

  See Also:
    Constant Field Values

### PROPERTY_CLIENT_AUTH_REQUIRED

    public static final String PROPERTY_CLIENT_AUTH_REQUIRED

See Also:
  Constant Field Values

### PROPERTY_CIPHER_SUITE

    public static final String PROPERTY_CIPHER_SUITE

See Also:
  Constant Field Values

### PROPERTY_CERTIFICATES

    public static final String PROPERTY_CERTIFICATES

See Also:
  Constant Field Values

### PROPERTY_PRIVATE_KEY

    public static final String PROPERTY_PRIVATE_KEY

See Also:
  Constant Field Values

### PROPERTY_TRUSTED_CERTS

    public static final String PROPERTY_TRUSTED_CERTS

See Also:
  Constant Field Values

### PROPERTY_PRIVATE_KEY_ALGORITHM

    public static final String PROPERTY_PRIVATE_KEY_ALGORITHM

See Also:
  Constant Field Values

Constructor Detail

### TLSProfilePureTLS

    public TLSProfilePureTLS()

  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

### advertiseProfile

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

  Throws:
    `BEEPException`

### init

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

  init sets the criteria for which an TLS 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.

  Parameters:
    `uri` - used to start a channel with TLS protection
    `config` - used to specify the parameters for sessions protected by this profile's version of TLS. In other words, if you want another set of paramters, you must either recall this method or create another `TLSProfilePureTLS` and call this method with a new configuration. The meaningful properties that can be set are:

    Cipher Suite | `short []` corresponding to the TLS spec ciphers (Appendix A). By default all the ciphers (except anonymous for now) are available. Use this to restrict to a certain strength of cipher if you desire to do so.
    Certificates | `List` that holds the X.509 format certificates that verify this peer, ordered from the users to the root.
    Private Key | `PrivateKey` that holds the private key that correspond to the certificates.
    Key Type | `String` that tells what algorithm generated the private key. "RSA" or "DSA" are the two accepted private key formats.
    Trusted Certificates | `List` that holds all trusted (or root) certificates that we can verify a peer against.

  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 (must be `<ready />`).
    `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.

  As of now, it is not possible to close a TLS channel. To cease using TLS, the entire session must be closed. This is done since opening a TLS channel resets the entire session, effectively closing all the previously open channels, including channel 0 (hence the greetings are exchanged again).

  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 authentication 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 `TCPSession` 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:
    `profile configuration`

### generateCredential

    public static SessionCredential generateCredential()

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

  Returns:
    default SessionCredential that can be added to

### setHandshakeCompletedListener

    public void setHandshakeCompletedListener(TLSProfilePureTLSHandshakeCompletedListener x)

  set a listener for completed handshakes.

  Parameters:
    `x` - is called when a TLS handshake completes.

### getMaxCiphersKnown

    public int getMaxCiphersKnown()

  return the maximum number of ciphers that can be set.

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