public final class SslEndpoint extends Object implements Endpoint, Serializable, TrustEquivalence
Endpoint
that uses TLS/SSL to support
invocation constraints for direct communication over TCP sockets.
Instances of this class are intended to be created by the BasicJeriExporter
class when it calls enumerateListenEndpoints
on
instances of SslServerEndpoint
.
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
:
X500Principal
CertPath
, whose
getType
method returns "X.509", and for which calling
getSubjectDN
on the certificate chain's first element
returns that principal's name
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 uses the Jini extensible remote invocation (Jini ERI) multiplexing protocol to map outgoing requests to socket connections.
SslServerEndpoint
,
ConfidentialityStrength
,
SslTrustVerifier
,
Serialized FormModifier and Type | Method and Description |
---|---|
boolean |
checkTrustEquivalence(Object obj)
Returns
true if the argument is an instance of
SslEndpoint 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 SslEndpoint |
getInstance(String serverHost,
int port)
Returns a TLS/SSL endpoint for the specified server host and port.
|
static SslEndpoint |
getInstance(String serverHost,
int port,
SocketFactory socketFactory)
Returns a TLS/SSL 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.
|
public static SslEndpoint getInstance(String serverHost, int port)
null
socket factory to create default sockets.serverHost
- the name of the server hostport
- the server portSslEndpoint
instanceIllegalArgumentException
- if port
is less than or
equal to 0
, or greater than 65535
NullPointerException
- if serverHost
is
null
public static SslEndpoint getInstance(String serverHost, int port, SocketFactory socketFactory)
socketFactory
of null
uses
default sockets.serverHost
- the name of the server hostport
- the server portsocketFactory
- the socket factory, or null
SslEndpoint
instanceIllegalArgumentException
- if port
is less than or
equal to 0
, or greater than 65535
NullPointerException
- if serverHost
is
null
public String getHost()
public int getPort()
public SocketFactory getSocketFactory()
Socket
instances, or null
if it uses default sockets.null
if it uses default socketspublic String toString()
public int hashCode()
public boolean equals(Object object)
null
, or have the same actual class and are equal.public OutboundRequestIterator newRequest(InvocationConstraints constraints)
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 thecreateSocket
methods on theSocketFactory
of thisSslEndpoint
(which produced this iterator) if non-null
, or it will create aSocket
directly otherwise.When the implementation needs to connect a
Socket
, if the host name to connect to resolves to multiple addresses (according toInetAddress.getAllByName
), it attempts to connect to the first resolved address; if that attempt fails with anIOException
or aSecurityException
, 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 anIOException
or aSecurityException
. 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 anUnknownHostException
), the implementation still makes an attempt to connect theSocket
to that host name, which could result in anUnknownHostException
. If the final connection attempt fails with anIOException
or aSecurityException
, then if any connection attempt failed with anIOException
, this method throws anIOException
, and otherwise (if all connection attempts failed with aSecurityException
), this method throws aSecurityException
.If there is a security manager:
- If a new connection is to be created, the security manager's
checkConnect
method is invoked with thisSslEndpoint
's host and-1
for the port; if this results in aSecurityException
, 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 aSecurityException
for that attempt. (Note that the implementation may carry out these security checks indirectly, such as through invocations ofInetAddress.getAllByName
orSocket
's constructors orconnect
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 thisSslEndpoint
's host and-1
for the port without resulting in aSecurityException
, and it also must be possible to invokecheckConnect
with the remote IP address and port of theSocket
without resulting in aSecurityException
(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, ifhasNext
would returnfalse
).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 itscheckConnect
method fails, or if the caller does not have the appropriateAuthenticationPermission
.
newRequest
in interface Endpoint
constraints
- the complete, absolute constraintsOutboundRequestIterator
to use to send
a new request to this remote endpointNullPointerException
- if constraints
is
null
public boolean checkTrustEquivalence(Object obj)
true
if the argument is an instance of
SslEndpoint
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.checkTrustEquivalence
in interface TrustEquivalence
obj
- object to check that is not yet known to be trustedtrue
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