net.jini.jeri.ssl

Class HttpsServerEndpoint

java.lang.Object

net.jini.jeri.ssl.HttpsServerEndpoint

All Implemented Interfaces:

ServerCapabilities, ServerEndpoint

public final class HttpsServerEndpoint
extends Object
implements ServerEndpoint

An implementation of ServerEndpoint that uses HTTPS (HTTP over TLS/SSL) to support invocation constraints for communication through firewalls.

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

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

• ClientAuthentication
• ClientMaxPrincipal, when it contains an X500Principal
• ClientMaxPrincipalType, when it contains X500Principal
• ClientMinPrincipal, when it contains a single X500Principal only
• ClientMinPrincipalType, when it contains X500Principal only
• Confidentiality
• ConfidentialityStrength, a provider-specific constraint for specifying weak or strong confidentiality
• ConnectionAbsoluteTime, trivially, since this only takes effect on the client side
• ConnectionRelativeTime, trivially, since this only takes effect on the client side
• ConstraintAlternatives, if the elements all have the same actual class and at least one element is supported
• Delegation.NO
• Delegation.YES, trivially, for anonymous clients
• DelegationAbsoluteTime, trivially, when delegation is not supported
• DelegationRelativeTime, trivially, when delegation is not supported
• Integrity.YES
• ServerAuthentication
• ServerMinPrincipal, when it contains a single X500Principal only

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

• One or more principals of type X500Principal
• For each principal, one or more certificate chains, stored as public credentials, and represented by instances of CertPath, whose getType method returns "X.509", and for which calling getSubjectDN on the certificate chain's first element returns that principal's name
• For each certificate chain, an instance of X500PrivateCredential, stored as a private credential, whose getCertificate method returns a value equal to the first element of the certificate chain, and whose getPrivateKey method returns the associated private key

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 HttpsServerEndpoint instance controls the host name that will be contained in HttpsEndpoint 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 HttpsEndpoint 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 HttpsEndpoint 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.

Since:

2.0

See Also:

HttpsEndpoint, 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:

• init - problems during initialization
• server - information about server-side connections

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:

• SSLContext, with the protocol specified by the org.apache.river.jeri.ssl.sslProtocol system property, or "TLS" if that property is not defined, to provide the TLS/SSL implementation. The SSLContext.init method is called with null for the random parameter to use the default SecureRandom implementation.
• CertificateFactory, with type "X.509", to generate CertPath instances from X.509 certificate chains
• TrustManagerFactory, with the algorithm specified by the org.apache.river.jeri.ssl.trustManagerFactoryAlgorithm system property, or the default algorithm if that property is not defined, to implement trust management for the TLS/SSL implementation. The factory must return trust managers that implement X509TrustManager.

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:

• org.apache.river.jeri.ssl.maxServerSessionDuration - The maximum number of milliseconds a server-side TLS/SSL session should be used before expiring. The default is 24 hours. The value used should be larger than the maximum client session duration to allow the client to negotiate a new session before the server timeout occurs.
• org.apache.river.jeri.ssl.sslProtocol - The secure socket protocol used when obtaining SSLContext instances. The default is "TLS".
• org.apache.river.jeri.ssl.trustManagerFactoryAlgorithm - The algorithm used when obtaining TrustManagerFactory instances. The default is the value returned by TrustManagerFactory.getDefaultAlgorithm.
• org.apache.river.jeri.ssl.cipherSuites - The TLS/SSL cipher suites that should be used for communication. The default is the list of suites supported by the JSSE implementation. The value should specify the suite names, separated by commas. The value will be ignored if it contains no suites or specifies suites that are not supported by the JSSE implementation. Suites appearing earlier in the list will be preferred to ones appearing later for suites that support the same requirements and preferences.
• org.apache.river.jeri.https.idleServerConnectionTimeout - The number of milliseconds to retain idle server-side HTTPS connections before closing them. The default is the idle client-side connection timeout (as specified by the org.apache.river.jeri.https.idleConnectionTimeout system property) plus 30000.
• org.apache.river.jeri.https.responseAckTimeout - The number of milliseconds to wait for acknowledgments from AcknowledgmentSource instances. The default is 15000.

Nested Class Summary

Nested classes/interfaces inherited from interface net.jini.jeri.ServerEndpoint

ServerEndpoint.ListenContext, ServerEndpoint.ListenCookie, ServerEndpoint.ListenEndpoint, ServerEndpoint.ListenHandle

Method Summary

Modifier and Type	Method and Description
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 HttpsServerEndpoint to listenContext, which will ensure an active listen operation on the endpoint, and returns an HttpsEndpoint 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 HttpsEndpoint instances created by listening on this object, or null if enumerateListenEndpoints will use the default server host.
static HttpsServerEndpoint	getInstance(int port) Returns an HTTPS server endpoint for the specified port.
static HttpsServerEndpoint	getInstance(String serverHost, int port) Returns an HTTPS server endpoint for the specified server host and port.
static HttpsServerEndpoint	getInstance(String serverHost, int port, SocketFactory socketFactory, ServerSocketFactory serverSocketFactory) Returns an HTTPS server endpoint for the specified server host, port, and socket factories.
static HttpsServerEndpoint	getInstance(Subject serverSubject, X500Principal[] serverPrincipals, String serverHost, int port) Returns an HTTPS server endpoint for the specified server subject, server principals, server host, and port.
static HttpsServerEndpoint	getInstance(Subject serverSubject, X500Principal[] serverPrincipals, String serverHost, int port, SocketFactory socketFactory, ServerSocketFactory serverSocketFactory) Returns an HTTPS 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 HttpsEndpoint 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 HttpsServerEndpoint getInstance(int port)

Returns an HTTPS 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 HttpsServerEndpoint instance

Throws:

IllegalArgumentException - if port is negative or greater than 65535

getInstance

public static HttpsServerEndpoint getInstance(String serverHost,
                                              int port)

Returns an HTTPS 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 HttpsServerEndpoint instance

Throws:

IllegalArgumentException - if port is negative or greater than 65535

getInstance

public static HttpsServerEndpoint getInstance(String serverHost,
                                              int port,
                                              SocketFactory socketFactory,
                                              ServerSocketFactory serverSocketFactory)

Returns an HTTPS 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 HttpsEndpoint. 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 HttpsEndpoint instances, or null

serverSocketFactory - the server socket factory, or null

Returns:

an HttpsServerEndpoint instance

Throws:

IllegalArgumentException - if port is negative or greater than 65535

getInstance

public static HttpsServerEndpoint getInstance(Subject serverSubject,
                                              X500Principal[] serverPrincipals,
                                              String serverHost,
                                              int port)

Returns an HTTPS 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 HttpsServerEndpoint 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 HttpsServerEndpoint getInstance(Subject serverSubject,
                                              X500Principal[] serverPrincipals,
                                              String serverHost,
                                              int port,
                                              SocketFactory socketFactory,
                                              ServerSocketFactory serverSocketFactory)

Returns an HTTPS 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 HttpsEndpoint. 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 HttpsEndpoint instances, or null

serverSocketFactory - the server socket factory, or null

Returns:

an HttpsServerEndpoint 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 HttpsEndpoint instances created by listening on this object, or null if enumerateListenEndpoints will use the default server host.

Returns:

the host name to use in HttpsEndpoint 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 HttpsEndpoint 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 HttpsServerEndpoint to listenContext, which will ensure an active listen operation on the endpoint, and returns an HttpsEndpoint 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 HttpsEndpoint 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 HttpsServerEndpoint.

The ListenEndpoint passed to addListenEndpoint represents the server subject, server principals, TCP port number, and ServerSocketFactory of this HttpsServerEndpoint. 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 HttpsServerEndpoint, 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.