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

public class TLSProfilePureTLS
extends TuningProfile
implements StartChannelListener

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 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, 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
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 Suiteshort [] 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.
CertificatesList that holds the X.509 format certificates that verify this peer, ordered from the users to the root.
Private KeyPrivateKey that holds the private key that correspond to the certificates.
Key TypeString that tells what algorithm generated the private key. "RSA" or "DSA" are the two accepted private key formats.
Trusted CertificatesList that holds all trusted (or root) certificates that we can verify a peer against.
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.

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