public final class HttpsEndpoint extends Object implements Endpoint, Serializable, TrustEquivalence
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
:
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 recognizes the following system properties:
*
' 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.
This implementation uses the ConnectionManager
class to manage
connections.
This implementation uses the following Logger
instances in the
net.jini.jeri.ssl
namespace:
Level | Description |
---|---|
WARNING | problems with initializing JSSE |
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).
HttpsServerEndpoint
,
ConfidentialityStrength
,
SslTrustVerifier
,
Serialized FormConstructor and Description |
---|
HttpsEndpoint(AtomicSerial.GetArg arg) |
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.
|
public HttpsEndpoint(AtomicSerial.GetArg arg) throws IOException
IOException
public static HttpsEndpoint getInstance(String serverHost, int port)
null
socket factory to create default sockets.serverHost
- the name of the server hostport
- the server portHttpsEndpoint
instanceIllegalArgumentException
- if port
is less than or
equal to 0
, or greater than 65535
NullPointerException
- if serverHost
is
null
public static HttpsEndpoint 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
HttpsEndpoint
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 thisHttpsEndpoint
(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 (if an HTTP proxy is to be used for the communication, the proxy's host name; otherwise, thisHttpsEndpoint
's host name) resolves to multiple addresses (according toInetAddress.getAllByName
), it attempts to connect to the first resolved address; if that attempt fails with anIOException
or (as is possible in the case that an HTTP proxy is not to be used) 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 and an HTTP proxy is to be used for the communication, the security manager's
checkConnect
method is invoked with thisHttpsEndpoint
's host and port; if this results in aSecurityException
, 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 thisHttpsEndpoint
'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 thisHttpsEndpoint
'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
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.checkTrustEquivalence
in interface TrustEquivalence
Copyright © 2016–2018. All rights reserved.