net.jini.jeri.ssl
Class SslServerEndpoint

java.lang.Object
  extended by net.jini.jeri.ssl.SslServerEndpoint
All Implemented Interfaces:
ServerCapabilities, ServerEndpoint

public final class SslServerEndpoint
extends Object
implements ServerEndpoint

An implementation of ServerEndpoint that uses TLS/SSL to support invocation constraints for direct communication over TCP sockets.

Instances of this class are intended to be created for use with the BasicJeriExporter class. Calls to enumerateListenEndpoints return instances of SslEndpoint.

This class supports at least the following constraints, possibly limited by the available cipher suites:

This class authenticates as a single Principal if the following items are present in the server Subject:

In addition, this class will only dispatch remote calls that authenticate as a given principal if the caller of listen on the class's ServerEndpoint.ListenEndpoint has been granted AuthenticationPermission with that principal as the local principal, the principal representing the authenticated identity of the client for the call (if any) as the peer principal, and the accept action.

This class supports remote connections between authenticated servers and authenticated or anonymous clients, and between anonymous servers and anonymous clients. Connections between anonymous servers and authenticated clients are not supported. Because of the suites available in the TLS/SSL protocol, support for Confidentiality.NO requires the server to authenticate with an RSA public key.

If the server subject contains principals and credentials that would permit authentication of more than one X500Principal, the endpoint will make an arbitrary choice of the principal to use for authentication, and will continue to make the same choice so long as subject contents, validity of credentials, and security permissions do not change.

The host name specified when creating an SslServerEndpoint instance controls the host name that will be contained in SslEndpoint instances produced when enumerateListenEndpoints is invoked to listen on the server endpoint; the host name does not affect the behavior of the listen operation itself, which listens on all of the local system's network addresses. If the host name in the server endpoint is null, then the host name in the SslEndpoint instances that it produces will be the default server host name, which is the IP address string of the InetAddress returned by InetAddress.getLocalHost when enumerateListenEndpoints is invoked.

This class permits specifying a SocketFactory for creating the Socket instances that the associated SslEndpoint instances use to make remote connections back to the server, and a ServerSocketFactory for creating the ServerSocket instances that the server endpoint uses to accept remote connections. These socket factories and sockets should not implement the TLS/SSL protocol; it is the responsibility of the implementation to establish TLS/SSL connections over the sockets it obtains from the socket factories. In particular, instances of SSLSocketFactory and SSLServerSocketFactory should not be used, and the factories used should not return instances of SSLSocket or SSLServerSocket.

A SocketFactory used with instances of this class should be serializable, and must implement Object.equals to obey the guidelines that are specified for equals methods of Endpoint instances. A ServerSocketFactory used with instances of this class must implement Object.equals to obey the guidelines that are specified for equals methods of ListenEndpoint instances.

This class uses the Jini extensible remote invocation (Jini ERI) multiplexing protocol to map outgoing requests to socket connections.

Since:
2.0
Author:
Sun Microsystems, Inc.
See Also:
SslEndpoint, ConfidentialityStrength
Implementation Specifics:
This implementation uses the Java(TM) Secure Socket Extension (JSSE).

This implementation uses the ServerConnectionManager class to manage connections.

This implementation uses the following Logger instances in the net.jini.jeri.ssl namespace:

net.jini.jeri.ssl.init
Level Description
WARNING problems with initializing JSSE

net.jini.jeri.ssl.server
Level Description
INFO problems with accepting or handling server connections, or with handling inbound requests
FAILED problems with checking constraints or permissions, with enumerating listen endpoints, or with security issues for inbound requests
HANDLED exceptions caught involving authentication
FINE creating server endpoints, enumerating listen endpoints, creating or closing connections or listen handles, or checking constraints for endpoints or inbound requests
FINEST low level operation tracing

This implementation uses the following security providers:

See the documentation on installing security providers and configuring JSSE for information on configuring these providers.

The JSSE documentation also describes the system properties for configuring the location, type, and password of the truststore that this implementation uses, through JSSE, to make decisions about what certificate chains should be trusted.

This implementation recognizes the following system properties:


Nested Class Summary
 
Nested classes/interfaces inherited from interface net.jini.jeri.ServerEndpoint
ServerEndpoint.ListenContext, ServerEndpoint.ListenCookie, ServerEndpoint.ListenEndpoint, ServerEndpoint.ListenHandle
 
Method Summary
 InvocationConstraints checkConstraints(InvocationConstraints constraints)
          Checks that it is possible to receive requests that either fully or partially satisfy the specified requirements, and returns any constraints that must be fully or partially implemented by higher layers in order to fully satisfy all of the specified requirements.
 Endpoint enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)
          Passes the ListenEndpoint for this SslServerEndpoint to listenContext, which will ensure an active listen operation on the endpoint, and returns an SslEndpoint instance corresponding to the listen operation chosen by listenContext.
 boolean equals(Object object)
          Two instances of this class are equal if they have server subjects that compare equal using ==; have server principals that are either both null or are equal when compared as the elements of a Set; have the same values for server host and port; have socket factories that are either both null, or have the same actual class and are equal; and have server socket factories that are either both null, or have the same actual class and are equal.
 String getHost()
          Returns the host name that will be used in SslEndpoint instances created by listening on this object, or null if enumerateListenEndpoints will use the default server host.
static SslServerEndpoint getInstance(int port)
          Returns a TLS/SSL server endpoint for the specified port.
static SslServerEndpoint getInstance(String serverHost, int port)
          Returns a TLS/SSL server endpoint for the specified server host and port.
static SslServerEndpoint getInstance(String serverHost, int port, SocketFactory socketFactory, ServerSocketFactory serverSocketFactory)
          Returns a TLS/SSL server endpoint for the specified server host, port, and socket factories.
static SslServerEndpoint getInstance(Subject serverSubject, X500Principal[] serverPrincipals, String serverHost, int port)
          Returns a TLS/SSL server endpoint for the specified server subject, server principals, server host, and port.
static SslServerEndpoint getInstance(Subject serverSubject, X500Principal[] serverPrincipals, String serverHost, int port, SocketFactory socketFactory, ServerSocketFactory serverSocketFactory)
          Returns a TLS/SSL server endpoint for the specified server subject, server principals, server host, port, and socket factories.
 int getPort()
          Returns the TCP port on which this object listens for connections, or 0 if it selects a free port.
 Set getPrincipals()
          Returns an immutable set of the principals that this instance uses for authentication, or null if it is anonymous.
 ServerSocketFactory getServerSocketFactory()
          Returns the server socket factory that this server endpoint uses to create ServerSocket instances, or null if it uses default server sockets.
 SocketFactory getSocketFactory()
          Returns the socket factory that the associated SslEndpoint instances created by listening on this server endpoint use to create Socket instances, or null if they use default sockets.
 int hashCode()
          Returns a hash code value for this object.
 String toString()
          Returns a string representation of this object.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

getInstance

public static SslServerEndpoint getInstance(int port)
Returns a TLS/SSL server endpoint for the specified port. Uses the null server host (which requests that enumerateListenEndpoints compute the default server host), the subject associated with the current access control context, the principals in the subject with appropriate public and private credentials for which the caller has AuthenticationPermission to listen, and null socket factories to create default sockets. A port of 0 requests listening on any free port.

Parameters:
port - the port on which to listen for connections, or 0 for any free port
Returns:
an SslServerEndpoint instance
Throws:
IllegalArgumentException - if port is negative or greater than 65535

getInstance

public static SslServerEndpoint getInstance(String serverHost,
                                            int port)
Returns a TLS/SSL server endpoint for the specified server host and port. Uses the subject associated with the current access control context, the principals in the subject with appropriate public and private credentials for which the caller has AuthenticationPermission to listen, and null socket factories to create default sockets. A serverHost of null requests that enumerateListenEndpoints compute the default server host. A port of 0 requests listening on any free port.

Parameters:
serverHost - the name that clients should use to connect to this server, or null to use the default
port - the port on which to listen for connections, or 0 for any free port
Returns:
an SslServerEndpoint instance
Throws:
IllegalArgumentException - if port is negative or greater than 65535

getInstance

public static SslServerEndpoint getInstance(String serverHost,
                                            int port,
                                            SocketFactory socketFactory,
                                            ServerSocketFactory serverSocketFactory)
Returns a TLS/SSL server endpoint for the specified server host, port, and socket factories. Uses the subject associated with the current access control context, and the principals in the subject with appropriate public and private credentials for which the caller has AuthenticationPermission to listen. A serverHost of null requests that enumerateListenEndpoints compute the default server host. A port of 0 requests listening on any free port. A socketFactory of null uses default sockets in the associated SslEndpoint. A serverSocketFactory of null uses default server sockets.

Parameters:
serverHost - the name that clients should use to connect to this server, or null to use the default
port - the port on which to listen for connections, or 0 for any free port
socketFactory - the socket factory for use in the associated SslEndpoint instances, or null
serverSocketFactory - the server socket factory, or null
Returns:
an SslServerEndpoint instance
Throws:
IllegalArgumentException - if port is negative or greater than 65535

getInstance

public static SslServerEndpoint getInstance(Subject serverSubject,
                                            X500Principal[] serverPrincipals,
                                            String serverHost,
                                            int port)
Returns a TLS/SSL server endpoint for the specified server subject, server principals, server host, and port. Uses null socket factories to create default sockets. A serverSubject of null uses the subject associated with the current access control context. A serverPrincipals of null uses the principals in the subject with appropriate public and private credentials for which the caller has AuthenticationPermission to listen; otherwise that argument specifies the principals to use, or that the server should be anonymous if the argument has no elements. If non-null, the value of serverPrincipals is neither retained nor modified; subsequent changes to that argument have no effect on the instance created. A serverHost of null requests that enumerateListenEndpoints compute the default server host. A port of 0 requests listening on any free port.

Parameters:
serverSubject - the Subject to use for authenticating the server or null to use the current subject
serverPrincipals - the principals to use for authenticating the server, or null to use any available principals in the subject
serverHost - the name that clients should use to connect to this server, or null to use the default
port - the port on which to listen for connections, or 0 for any free port
Returns:
an SslServerEndpoint instance
Throws:
IllegalArgumentException - if port is negative or greater than 65535
NullPointerException - if serverPrincipals is not null and any of its elements are null

getInstance

public static SslServerEndpoint getInstance(Subject serverSubject,
                                            X500Principal[] serverPrincipals,
                                            String serverHost,
                                            int port,
                                            SocketFactory socketFactory,
                                            ServerSocketFactory serverSocketFactory)
Returns a TLS/SSL server endpoint for the specified server subject, server principals, server host, port, and socket factories. A serverSubject of null uses the subject associated with the current access control context. A serverPrincipals of null uses the principals in the subject with appropriate public and private credentials for which the caller has AuthenticationPermission to listen; otherwise that argument specifies the principals to use, or that the server should be anonymous if the argument has no elements. If non-null, the value of serverPrincipals is neither retained nor modified; subsequent changes to that argument have no effect on the instance created. A serverHost of null requests that enumerateListenEndpoints compute the default server host. A port of 0 requests listening on any free port. A socketFactory of null uses default sockets in the associated SslEndpoint. A serverSocketFactory of null uses default server sockets.

Parameters:
serverSubject - the Subject to use for authenticating the server or null to use the current subject
serverPrincipals - the principals to use for authenticating the server, or null to use any available principals in the subject
serverHost - the name that clients should use to connect to this server, or null to use the default
port - the port on which to listen for connections, or 0 for any free port
socketFactory - the socket factory for use in the associated SslEndpoint instances, or null
serverSocketFactory - the server socket factory, or null
Returns:
an SslServerEndpoint instance
Throws:
IllegalArgumentException - if port is negative or greater than 65535
NullPointerException - if serverPrincipals is not null and any of its elements are null

getHost

public String getHost()
Returns the host name that will be used in SslEndpoint instances created by listening on this object, or null if enumerateListenEndpoints will use the default server host.

Returns:
the host name to use in SslEndpoint instances created by listening on this object, or null if using the default

getPort

public int getPort()
Returns the TCP port on which this object listens for connections, or 0 if it selects a free port.

Returns:
the TCP port on which this object listens for connections, or 0 if it selects a free port

getPrincipals

public Set getPrincipals()
Returns an immutable set of the principals that this instance uses for authentication, or null if it is anonymous.

Returns:
an immutable set of the principals or null

getSocketFactory

public SocketFactory getSocketFactory()
Returns the socket factory that the associated SslEndpoint instances created by listening on this server endpoint use to create Socket instances, or null if they use default sockets.

Returns:
the socket factory that associated endpoints use to create sockets, or null if they use default sockets

getServerSocketFactory

public ServerSocketFactory getServerSocketFactory()
Returns the server socket factory that this server endpoint uses to create ServerSocket instances, or null if it uses default server sockets.

Returns:
the server socket factory that this server endpoint uses to create server sockets, or null if it uses default server sockets

toString

public String toString()
Returns a string representation of this object.

Overrides:
toString in class Object

checkConstraints

public InvocationConstraints checkConstraints(InvocationConstraints constraints)
                                       throws UnsupportedConstraintException
Checks that it is possible to receive requests that either fully or partially satisfy the specified requirements, and returns any constraints that must be fully or partially implemented by higher layers in order to fully satisfy all of the specified requirements.

This implementation only returns Integrity.YES constraints.

Specified by:
checkConstraints in interface ServerCapabilities
Parameters:
constraints - the constraints that must be supported
Returns:
the constraints that must be at least partially implemented by higher layers
Throws:
SecurityException - if the current security context does not have the permissions necessary to perform this operation
NullPointerException - if constraints is null
UnsupportedConstraintException - if the transport layer aspects of any of the specified requirements are not supported by this instance (either in general or in the current security context)

hashCode

public int hashCode()
Returns a hash code value for this object.

Overrides:
hashCode in class Object

equals

public boolean equals(Object object)
Two instances of this class are equal if they have server subjects that compare equal using ==; have server principals that are either both null or are equal when compared as the elements of a Set; have the same values for server host and port; have socket factories that are either both null, or have the same actual class and are equal; and have server socket factories that are either both null, or have the same actual class and are equal.

Overrides:
equals in class Object

enumerateListenEndpoints

public Endpoint enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)
                                  throws IOException
Passes the ListenEndpoint for this SslServerEndpoint to listenContext, which will ensure an active listen operation on the endpoint, and returns an SslEndpoint instance corresponding to the listen operation chosen by listenContext.

If this server endpoint's server host is null, then the endpoint returned will contain the default server host. This method computes the default by invoking InetAddress.getLocalHost to obtain an InetAddress for the local host. If InetAddress.getLocalHost throws an exception, this method throws that exception. The default host name will be the string returned by invoking getHostAddress on that InetAddress. If there is a security manager, its checkConnect method will be invoked with the string returned by invoking getHostName on that same InetAddress as the host argument and -1 as the port argument; this could result in a SecurityException.

This method invokes addListenEndpoint on listenContext once, passing a ListenEndpoint as described below. If addListenEndpoint throws an exception, then this method throws that exception. Otherwise, this method returns an SslEndpoint instance with the host name described above, the TCP port number bound by the listen operation represented by the ListenHandle returned by addListenEndpoint, and the same SocketFactory as this SslServerEndpoint.

The ListenEndpoint passed to addListenEndpoint represents the server subject, server principals, TCP port number, and ServerSocketFactory of this SslServerEndpoint. Its methods behave as follows:

ListenHandle listen(RequestDispatcher):

Listens for requests received on this endpoint's TCP port, dispatching them to the supplied RequestDispatcher in the form of InboundRequest instances.

When the implementation of this method needs to create a new ServerSocket, it will do so by invoking one of the createServerSocket methods that returns a bound server socket on the contained ServerSocketFactory if non-null, or it will create a ServerSocket directly otherwise.

If there is a security manager, its checkListen method will be invoked with this endpoint's TCP port; this could result in a SecurityException. In addition, for each server principal in this endpoint, the security manager's checkPermission method will be invoked with an AuthenticationPermission containing the server principal and the listen action; this could also result in a SecurityException. Furthermore, before a given InboundRequest gets dispatched to the supplied request dispatcher, the security manager's checkAccept method must have been successfully invoked in the security context of this listen invocation with the remote IP address and port of the Socket used to receive the request, and if the server authenticated itself to the client, the security manager's checkPermission method must have been successfully invoked in the same context with an AuthenticationPermission containing that authenticated server principal as local principal, the client's authenticated principal (if any) as peer principal, and the accept action. The checkPermissions method of the dispatched InboundRequest also performs these latter security checks. (Note that in some cases, the implementation may carry out some of these security checks indirectly, such as through invocations of ServerSocket's constructors or accept method.)

Requests will be dispatched in a PrivilegedAction wrapped by a SecurityContext obtained when this method was invoked, with the AccessControlContext of that SecurityContext in effect.

Dispatched requests will implement populateContext to populate the given collection with an element that implements the ClientHost interface, and an element that implements the ClientSubject interface. The ClientHost element implements getClientHost to return the IP address of the Socket that the request was received over (see Socket.getInetAddress()).

Throws IOException if an I/O exception occurs while performing this operation, such as if the TCP port is already in use.

Throws SecurityException if there is a security manager and an invocation of its checkListen or checkPermission method fails.

Throws NullPointerException if requestDispatcher is null

void checkPermissions():
Verifies that the current security context has all of the security permissions necessary to listen for requests on this endpoint.

If there is a security manager, its checkListen method will be invoked with this endpoint's TCP port; this could result in a SecurityException. In addition, for each server principal in this endpoint, the security manager's checkPermission method will be invoked with an AuthenticationPermission containing the server principal and the listen action; this could also result in a SecurityException.

Throws SecurityException if there is a security manager and an invocation of its checkListen or checkPermission method fails.

boolean equals(Object):
Compares the specified object with this ListenEndpoint for equality.

This method returns true if and only if the specified object is also a ListenEndpoint produced by an SslServerEndpoint, and the two listen endpoints both have server subjects that compare equal using ==; have server principals that are either both null or are equal when compared as the elements of a Set; have the same values for TCP port; and have server socket factories that are either both null, or have the same actual class and are equal.

Specified by:
enumerateListenEndpoints in interface ServerEndpoint
Parameters:
listenContext - the ListenContext to pass this ServerEndpoint's ListenEndpoint instances to
Returns:
the Endpoint instance for sending requests to this ServerEndpoint's communication endpoints being listened on
Throws:
SecurityException - if there is a security manager, and either its checkListen method fails, or serverHost is null and the security manager's checkConnect method fails; or if the calling thread does not have permission to authenticate as each of the endpoint's server principals when listening for connections
IllegalArgumentException - if an invocation of the addListenEndpoint method on the supplied ListenContext returns a ListenCookie that does not correspond to the ListenEndpoint that was passed to it
NullPointerException - if listenContext is null
UnknownHostException - if this instance's server host is null and InetAddress.getLocalHost throws an UnknownHostException
UnsupportedConstraintException - if the server subject is missing any of the endpoint's server principals or the associated credentials
IOException - if an I/O exception occurs while attempting to listen for requests on the communication endpoints represented by this ServerEndpoint. This could occur, for example, if an I/O resource associated with one of the communication endpoints is already in exclusive use, or if there are insufficient I/O resources for the operation.


Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.