Implements the javax.net.ssl
abstract classes using
native methods and SSLeay.
Package Specification
The ITISSL package is based on SSLeay. The most
important classes in the package have SSLeay structures as
peers, to which they delegate the calls. The package implements Sun
Microsystems abstract SSL specification. It adds some additional
features, which may ease the customization of the package.
SSL and ITISSL - definitions
The purpose of this section is to define some basic terms specific not
only to SSL but also to this package.
-
Communication partners: The communication partner are the entities
participating in a communication session. The communication partners
have a well defined identity, embodied in a certificate.
-
Connection: A connection is a communication channel between two
communication partners. In our particular case, a connection is a SSL channel,
which means the data transmitted through the communication channel is encrypted
and the communication partners have identified themselves.
-
Handshake: The (SSL) handshake sequence establishes a connection.
-
Socket: Sockets are the data structures on both ends of a connections
which provide the communication functionality. From the point of view of
a socket, the communication partner is often referred to as peer.
-
ServerSocket: A server socket which creates sockets for incoming
connections.
-
Session: The same two communication partners (A and B) may use several
connections to communicate (suppose one for a control information, the
other one for data). The two connections may share the cryptographic information
they use, the identities of the peers, and other related data. This shared
data is stored in a session. A session is modeled in this package by a
session object.
-
Client and Server roles: The two communication partners on both
ends of a connection may be associated roles. The client and the server
roles. A client may have different security requirements than the server.
Client behavior is usually expected from a participant using a Socket for
a connection. Server behavior is expected from a communication partner
accepting connections via a ServerSocket. During the handshake, client
and server behave differently.
-
Client-side-socket and server-side-socket: The term 'ServerSocket'
for the sockets which accept connections collides with the role of the
sockets is creates. A client-side-socket is a communication socket (i.e.
SSLeaySocket) which has a client role. Client side sockets are
typically created by a socket factory. Server-side-sockets are normal communication
sockets (i.e. SSLeaySockets) which are created by a server socket
(i.e. SSLeayServerSocket) during the accept call. Server-side-sockets
have server roles.
-
Cipher suites: A cipher suite is a name for the encryption algorithms
used in a connection.
Class Overview
The most important classes in the package are:
-
SSLeaySocket. The SSLeaySocket implements Sun's
SSLSocket abstract class and is the core of the SSL package. All
data sent or received through such an object will obey the SSL protocol
communication rules. Two other classes, namely SSLeaySession and
SSLeaySessionContext are closely related to SSLeaySocket.
The first one, SSLeaySession, maintains information specific to
several connections sharing the same participants. The other one, SSLeaySessionContext,
participates in the creation of the socket by defining the initial configuration
and options of a socket.
-
SSLeaySocketFactory SSLeaySocketFactory creates
SSLeaySockets. It is a singleton, so there is at most one instance
of SSLeaySocketFactory per JVM. In order to create sockets, SSLeaySocketFactories
needs a SSLeaySessionContext, which participates in the creation
of SSLeaySockets. Thus, it owns exactly one SSLeaySessionContext,
which it uses for every SSLeaySocket creation. When the application
specifies default properties for sockets created by a factory, the factory
actually delegates this call to its session context. On the other hand,
SSLeaySocketFactories the object controlling the policy (configuration)
of the sockets it create. Some applications which need other socket configuration
policies than the default may extend the SSLeaySocketFactory and
use the special template methods to specify a different initial configuration
for the sockets they create.
-
SSLeayServerSocket creates itself SSLeaySockets
through its accept method. Since they are not communication objects themselves,
one can specify through their methods the characteristics and configuration
of the sockets they create. Thus they have a complete 'clone' of those
SSLeaySocket methods which configure the behavior of sockets.
Note that SSLeayServerSockets should not be created as 'standalone'
objects, but rather through a SSLeayServerSocketFactory.
-
SSLeayServerSocketFactory is the object which creates SSleayServerSockets.
Like its counterpart used for creating SSLeaySockets, it is a
singleton and owns exactly one SSLeaySessionContext which participates
in the creation of the SSLeayServerSockets. The initial defaults
for the created sockets are obtained from the owned context. Specification
of these defaults is also delegated to the context, so the factory has
no default information in its state. Note that SSLeayServerSocketFactories
are intended to be the application's instrument for specifying the configuration
and characteristic of its SSLeayServerSocktes. A template method
(setSSLPolicy) should be used by subclasses to specify the configuration
of the SSLeayServerSockets the factory creates. Note that SSLeayServerSockets
are not communication objects themselves, so specifying their configuration
means specifying the configuration of the SSLeaySockets they create
in their accept method.
-
SSLeaySessionContext has two main tasks.
-
The first one is to store the identity of the user and participate in the
creation of SSLeaySockets. SInce SSLeaySessionContexts
are owned by socket factories, there are exactly two such objects in a
JVM. Usually they share the same identity information, but this may not
be the case if sockets are configured differently from server sockets
-
The other one is to store information about SSLeaySessions. Since
there are two socket context objects in the JVM (owned by the two factories)
the session information in of the SSLeaySockets and SSLeayServerSockets
are stored separately. This is no surprise, because SSLeaySockets
obtained directly from a factory usually act as client-side-sockets and
the ones obtained from a SSLeayServersocket act as server-side-sockets.
See above for client and server roles in SSL. Storing information session
information is done on two levels. The real information exists in the underlying
SSLeay level. The java object acts just like a proxy for this information,
exporting session objects at a given point in the past.
-
SSLeaySession stores information for several conections.
It is the session objects which contain information (certificates, identity)
of the communication partner.
The following diagram in OMT notation depicts the most important relations
between classes of this package. In addition to the OMT notation, the classes
having a strong black line below use Java native interface and delegate
their functionality to SSLeay structures.
Extending and Reusing ITISSL
The default configuration (as implemented by the existing SSLeaySocketFactory
or SSleayServerSocketFactory) enforces the following policy:
-
client-side-sockets require authentication of the server-side-sockets,
but they don't authenticate themselves against the server-side-sockets
-
conversely, server-side-sockets authenticate themselves against client-side-sockets,
but don't require authentication of the client
-
The default cipher suites are those used in the underlying SSLeay package.
-
SSLeaySockets behave like clients (they have a client role) whereas
SSLeaySockets created by SSLeayServerSockts have server
roles.
The default implementation of the package does not cover all type of policies
needed by different applications. For example, the default implementation
is not suited for using it together with RMI. In a RMI call, both
the caller and the callee should authenticate themselves, which is not
the case with the existing implementation. Such an application should extend
the SSLeaySocketFactory and SSLeayServerSocketFactory
to specify the desired behavior for the sockets it uses.
Extending the socket factories
The two socket factories are the means by which users can specify the default
behavior of their sockets. The default implementation of the factories
create SSLeaySocket or SSleayServerSocket objects.
Both factories use the createSocket / createServerSocket methods
to create new socket objects. Prior to returning the newly created socket
to the caller of createSocket, they invoke a template method
(setSSLPolicy) which configures the socket. Subclasses
of SSLeaySocketFactory or SSLeayServerSocketFactory can
thus specify the initial configuration of their sockets by overriding this
method.
This should be the standard way to change the default policy of the
sockets.
Extending the socket factories and the socket class
There are some cases in which the user may want to extend the SSLeaySocket
class itself. This happens if the functionality of the socket objects is
not sufficient for the user's purposes. In this case, both sockets and
the factories which create them have to be extended. Let's take a look
at what steps are necessary for new socket objects to be used:
-
create a subclass of SSLeaySocket, MySSLeaySocket, which defines
new methods, not currently supported by SSLeaySocket.
-
create a subclass of SSLeaySocketFactory (MySSLeaySocketFactory)
-
specify in the constructor what type of sockets the factory should create
(using setSocketType)
-
override the setSSLPolicy to define the initial configuration
of your sockets, possibly using the new methods present in the MySSLeaySocket
class.
Serializability
Both SSLeayServerSocketFactories and
SSLeaySocketFactories are serializable. This means they can
be transported over a network if the communication partner needs the
same socket type. This is actually what RMI does.
However, all the context information is lost in the
serialisation/deserialisation process, so that a deserialized factory
'sees' a 'fresh' session context.
ITISSL setup startup information
For the SSL package to work
correctly and use the security features of the SSL protocol, some
initial information such as user identity, location of the CA
certificate and default security level (in form of cipher suites) are
required.
Depending on the configuration of the package, some of these items
may not be present. For a SSL client which does not need to
authenticate itself against the server, the user identity is not
mandatory. If the factory creating the sockets is correspondingly
configured, this may not lead to socket factory initialization
problems.
If essential information is missing (e.g. the user's identity in a server
or the location of the CA certificates) both socket factories will fail
to be created.
The following information has to be specified prior to loading the SSL
package:
-
The environment variable CA_FILE or the iti.ssl.ca_file
system property. This denotes the location of the file containing certificates
for certification agencies.
-
The environment variable CERT_FILE or the iti.ssl.cert_file
system property. Their values denote the location for the user's certificate.
-
The environment variable KEY_FILE or the iti.ssl.key_file
system property. Their values denote the location for the file containing
the user's private key.
-
The environment variable SSL_CIPHERS or the iti.ssl.ssl_ciphers
system property. Their value controls the initial security level for all
connections started by this JVM. If neither of the two is specified, the
value will be the SSLeay default.
- The system properties iti.ssl.clientIdentityRequired and
iti.ssl.serverIdentityRequired which control whether the
instatiation of the client (server) socket factories should fail if
the identity information is not present. Possible values are
true and false.
In the first four cases, the value of the system property, if not
null, will override the value specified in the corresponding
environment variable.
Related Documentation
Bugs and Limitations
The ITISSL package is still in its
early development stages and has not yet been thoroughly tested. The
following list of bugs and imitations display our understanding of
what the package lacks at the present moment. Help and suggestions
would be greatly appreciated:
-
Certificates, CA files, and private key files have to be in pem
format
-
No callbacks for specifying the pass phrase of a private key are included
-
SSLeaySocket.startHandshake can be called only once (a reconnect
functionality, as specified in the SSL API, is not yet possible)
-
SSLeaySession.getLastAccessTime returns the creation time of the
session and not the last time it was accessed. We don't know how to get
this information from the SSLeay layer.