net.jini.jeri.ssl
Class HttpsEndpoint

java.lang.Object
  extended by 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:

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:

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:

Since:
2.0
Author:
Sun Microsystems, Inc.
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:

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:

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:


Method Summary
 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


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