net.jini.jeri.ssl

Class HttpsEndpoint

java.lang.Object

net.jini.jeri.ssl.HttpsEndpoint

All Implemented Interfaces:

Serializable, Endpoint, TrustEquivalence

public final class HttpsEndpoint
extends Object
implements Endpoint, Serializable, TrustEquivalence

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

Instances of this class are intended to be created by the BasicJeriExporter class when it calls enumerateListenEndpoints on instances of HttpsServerEndpoint.

The SslTrustVerifier trust verifier may be used for establishing trust in remote proxies that use instances of this class.

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
• 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
• Integrity.YES
• ServerAuthentication
• ServerMinPrincipal, when it contains a single X500Principal only

Note that ConnectionRelativeTime and DelegationRelativeTime constraints may be used at higher levels, but should be converted to the associated absolute time constraints for use by this class.

This class authenticates as a single Principal if the following items are present in the current 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's newRequest method will only authenticate as a given principal if the caller has been granted AuthenticationPermission with that principal as the local principal, the principal representing the authenticated identity of the server as the peer principal, and the connect 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.

This class permits specifying a SocketFactory for creating the Socket instances that it uses to make remote connections. These socket factories should not be instances of SSLSocketFactory or return instances SSLSocket; it is the responsibility of the implementation to establish a TLS/SSL connection over the socket it obtains from the socket factory.

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.

This class recognizes the following system properties:

• https.proxyHost - The host name for the secure proxy server. The default is to use no proxy server.
• https.proxyPort - The port for the secure proxy server. The default is 443.
• http.nonProxyHosts - The names of hosts for which direct connections should be made rather than using the proxy server. Each host name may contain '*' wildcard characters in any position to match zero or more of any characters within the name. Multiple host names may be specified by separating the names with '|' characters. The default is for all connections to use the proxy server if one is specified.

Since:

2.0

See Also:

HttpsServerEndpoint, ConfidentialityStrength, SslTrustVerifier, Serialized Form

Implementation Specifics:

This implementation uses the Java(TM) Secure Socket Extension (JSSE).

This implementation uses the ConnectionManager class to manage connections.

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

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

net.jini.jeri.ssl.init

Level	Description
WARNING	problems with initializing JSSE

net.jini.jeri.ssl.client

Level	Description
FAILED	problems with outbound requests
HANDLED	exceptions caught involving authentication
FINE	authentication decisions; creating, choosing, expiring, or closing connections; or handling outbound 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.maxClientSessionDuration - The maximum number of milliseconds a client-side TLS/SSL session should be used. The default is 23.5 hours. The value should be smaller than the maximum server 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.idleConnectionTimeout - The number of milliseconds to retain idle client-side HTTPS connections before closing them. The default is 15000.
• org.apache.river.jeri.https.responseAckTimeout - The number of milliseconds to keep track of acknowledgments that have not yet been sent for AcknowledgmentSource instances. The default is 15000.
• org.apache.river.jeri.https.pingProxyConnections - If the value is case-insensitive equal to true, then if an HTTP proxy is being used, ping the server endpoint to verify whether it is alive and reachable. The ping occurs before the first request and before each subsequent request which follows the expiration of the ping proxy timeout period (below) following the previous ping. When using an HTTP proxy it is often impossible to distinguish between inability to reach the server endpoint (such as because the server process refused a connection by the HTTP proxy) and the lack of response from a delivered request (which might result in an UnmarshalException). The ping increases the likelihood that the inability to reach the server endpoint can be explicitly identified. The default value is false, and no pings are done.
• org.apache.river.jeri.https.pingProxyConnectionTimeout - The number of milliseconds from the time a server endpoint was last pinged before a ping will precede the next request. The default is Long.MAX_VALUE (essentially meaning, ping only before the first request).

Method Summary

Modifier and Type	Method and Description
boolean	checkTrustEquivalence(Object obj) Returns true if the argument is an instance of HttpsEndpoint with the same values for server host and port; and either both this instance and the argument have null socket factories, or the factories have the same actual class and are equal; and returns false otherwise.
boolean	equals(Object object) Two instances of this class are equal if they have the same values for server host and port; and have socket factories that are either both null, or have the same actual class and are equal.
String	getHost() Returns the server host that this endpoint connects to.
static HttpsEndpoint	getInstance(String serverHost, int port) Returns an HTTPS endpoint for the specified server host and port.
static HttpsEndpoint	getInstance(String serverHost, int port, SocketFactory socketFactory) Returns an HTTPS endpoint for the specified server host, port, and socket factory.
int	getPort() Returns the TCP port that this endpoint connects to.
SocketFactory	getSocketFactory() Returns the socket factory that this endpoint uses to create Socket instances, or null if it uses default sockets.
int	hashCode() Returns a hash code value for this object.
OutboundRequestIterator	newRequest(InvocationConstraints constraints) Returns an OutboundRequestIterator to use to send a new request to this remote endpoint using the specified constraints.
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 HttpsEndpoint getInstance(String serverHost,
                                        int port)

Returns an HTTPS endpoint for the specified server host and port. Uses a null socket factory to create default sockets.

Parameters:

serverHost - the name of the server host

port - the server port

Returns:

an HttpsEndpoint instance

Throws:

IllegalArgumentException - if port is less than or equal to 0, or greater than 65535

NullPointerException - if serverHost is null

getInstance

public static HttpsEndpoint getInstance(String serverHost,
                                        int port,
                                        SocketFactory socketFactory)

Returns an HTTPS endpoint for the specified server host, port, and socket factory. A socketFactory of null uses default sockets.

Parameters:

serverHost - the name of the server host

port - the server port

socketFactory - the socket factory, or null

Returns:

an HttpsEndpoint instance

Throws:

IllegalArgumentException - if port is less than or equal to 0, or greater than 65535

NullPointerException - if serverHost is null

getHost

public String getHost()

Returns the server host that this endpoint connects to.

Returns:

the server host that this endpoint connects to

getPort

public int getPort()

Returns the TCP port that this endpoint connects to.

Returns:

the TCP port that this endpoint connects to

getSocketFactory

public SocketFactory getSocketFactory()

Returns the socket factory that this endpoint uses to create Socket instances, or null if it uses default sockets.

Returns:

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

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class Object

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 the same values for server host and port; and have socket factories that are either both null, or have the same actual class and are equal.

Overrides:

equals in class Object

newRequest

public OutboundRequestIterator newRequest(InvocationConstraints constraints)

Returns an OutboundRequestIterator to use to send a new request to this remote endpoint using the specified constraints.

The constraints must be the complete, absolute constraints for the request.

The returned OutboundRequestIterator's next method behaves as follows:

Initiates an attempt to communicate the request to this remote endpoint.

When the implementation of this method needs to create a new Socket, it will do so by invoking one of the createSocket methods on the SocketFactory of this HttpsEndpoint (which produced this iterator) if non-null, or it will create a Socket directly otherwise.

When the implementation needs to connect a Socket, if the host name to connect to (if an HTTP proxy is to be used for the communication, the proxy's host name; otherwise, this HttpsEndpoint's host name) resolves to multiple addresses (according to InetAddress.getAllByName), it attempts to connect to the first resolved address; if that attempt fails with an IOException or (as is possible in the case that an HTTP proxy is not to be used) a SecurityException, it then attempts to connect to the next address; and this iteration continues as long as there is another resolved address and the attempt to connect to the previous address fails with an IOException or a SecurityException. If the host name resolves to just one address, the implementation makes one attempt to connect to that address. If the host name does not resolve to any addresses (InetAddress.getAllByName would throw an UnknownHostException), the implementation still makes an attempt to connect the Socket to that host name, which could result in an UnknownHostException. If the final connection attempt fails with an IOException or a SecurityException, then if any connection attempt failed with an IOException, this method throws an IOException, and otherwise (if all connection attempts failed with a SecurityException), this method throws a SecurityException.

If there is a security manager and an HTTP proxy is to be used for the communication, the security manager's checkConnect method is invoked with this HttpsEndpoint's host and port; if this results in a SecurityException, this method throws that exception.

If there is a security manager and an HTTP proxy is not to be used for the communication:

• If a new connection is to be created, the security manager's checkConnect method is invoked with this HttpsEndpoint's host and -1 for the port; if this results in a SecurityException, this method throws that exception. checkConnect is also invoked for each connection attempt, with the remote IP address (or the host name, if it could not be resolved) and port to connect to; this could result in a SecurityException for that attempt. (Note that the implementation may carry out these security checks indirectly, such as through invocations of InetAddress.getAllByName or Socket's constructors or connect method.)

• In order to reuse an existing connection for the communication, the current security context must have all of the permissions that would be necessary if the connection were being created. Specifically, it must be possible to invoke checkConnect in the current security context with this HttpsEndpoint's host and -1 for the port without resulting in a SecurityException, and it also must be possible to invoke checkConnect with the remote IP address and port of the Socket without resulting in a SecurityException (if the remote socket address is unresolved, its host name is used instead). If no existing connection satisfies these requirements, then this method must behave as if there are no existing connections.

Throws NoSuchElementException if this iterator does not support making another attempt to communicate the request (that is, if hasNext would return false).

Throws IOException if an I/O exception occurs while performing this operation, such as if a connection attempt timed out or was refused or there are unsupported or conflicting constraints.

Throws SecurityException if there is a security manager and an invocation of its checkConnect method fails, or if the caller does not have the appropriate AuthenticationPermission.

Specified by:

newRequest in interface Endpoint

Parameters:

constraints - the complete, absolute constraints

Returns:

an OutboundRequestIterator to use to send a new request to this remote endpoint

Throws:

NullPointerException - if constraints is null

checkTrustEquivalence

public boolean checkTrustEquivalence(Object obj)

Returns true if the argument is an instance of HttpsEndpoint with the same values for server host and port; and either both this instance and the argument have null socket factories, or the factories have the same actual class and are equal; and returns false otherwise.

Specified by:

checkTrustEquivalence in interface TrustEquivalence

Parameters:

obj - object to check that is not yet known to be trusted

Returns:

true if the specified object (that is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and returns false otherwise