public final class KerberosEndpoint extends Object implements Endpoint, TrustEquivalence, Serializable
Endpoint
implementation that uses Kerberos as the
underlying network security protocol to support security related
invocation constraints its caller specified for the corresponding
remote request. Instances of this class are referred to as the
endpoints of the Kerberos provider, while instances of KerberosServerEndpoint
are referred to as the server endpoints of
the provider.
Instances of this class are intended to be created by the BasicJeriExporter
class when it calls enumerateListenEndpoints
on instances of
KerberosServerEndpoint
.
The KerberosTrustVerifier
may be used for establishing
trust in remote proxies that use instances of this class.
This class supports at least the following standard constraints:
Integrity.YES
Confidentiality
ClientAuthentication.YES
ConnectionAbsoluteTime
ServerAuthentication.YES
ClientMaxPrincipal
, when it
contains at least one KerberosPrincipal
ClientMaxPrincipalType
, when
it contains the KerberosPrincipal
class
ClientMinPrincipal
, when it
contains exactly one KerberosPrincipal
ClientMinPrincipalType
, when
it contains only the KerberosPrincipal
class
ServerMinPrincipal
, when it
contains exactly one KerberosPrincipal
Delegation
ConstraintAlternatives
, if the
elements all have the same actual class and at least one
element is supported
An endpoint of this provider uses Kerberos Ticket Granting Tickets
(TGTs), which are stored as private credentials in the Subject
associated with the access control context of the current
thread, to authenticate the caller of the remote request to the
server.
A TGT is an instance of KerberosTicket
whose server
principal is of the form "krbtgt/REALM1@REALM2"
. The
client principal of the TGT indicates what principal the endpoint
can use the TGT to authenticate the caller as to the server.
Instances of this class contain a server host name, a server TCP
port number, a server principal, as well as an optional SocketFactory
for customizing the type of Socket
to
use.
A SocketFactory
used with instances of this class
should be serializable, and should implement Object.equals
to return true
when passed an instance
that represents the same (functionally equivalent) socket
factory.
To make a remote request through an endpoint of this provider, the
caller or initiator of the request supplies the endpoint with a set
of InvocationConstraints
. The client principal used
for the request is a KerberosPrincipal
that appears in
the principal set of the current subject, allowable by the given
set of constraints, whose corresponding TGT is in the private
credential set of the subject, and the connect
AuthenticationPermission
has been granted to the
current access control context with the client principal as the
local
principal and the serverPrincipal
contained in this endpoint as the peer
principal.
If the set of constraints for the request specifies that encryption and/or delegation is required or preferred, they will be enforced by the provider. If encryption is unspecified in the constraints, the provider may or may not encrypt messages exchanged with the server. If delegation is unspecified in the constraints, the provider will not do delegation for the request. For delegation to happen, the TGT for the request has to be forwardable.
This class uses the Jini extensible remote invocation (Jini ERI) multiplexing protocol to map outgoing requests to the underlying secure connection streams.
The secure connection streams in this provider are implemented using the Kerberos Version 5 GSS-API Mechanism, defined in RFC 1964, over socket connections between client and server endpoints.
Note that, because Kerberos inherently requires client authentication,
this transport provider does not support distributed garbage collection
(DGC); if DGC is enabled using BasicJeriExporter
,
all DGC remote calls through this provider will silently fail.
KerberosServerEndpoint
,
KerberosTrustVerifier
,
Serialized FormModifier and Type | Method and Description |
---|---|
boolean |
checkTrustEquivalence(Object obj)
Returns
true if the argument is an instance of
KerberosEndpoint with the same values for server
principal, 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 obj)
Two instances of this class are equal if they contain the same
server principal, host, and port, and their socket factories
are both
null or have the same actual class and
are equal. |
String |
getHost()
Returns the server host that this endpoint connects to.
|
static KerberosEndpoint |
getInstance(String serverHost,
int serverPort,
KerberosPrincipal serverPrincipal)
Returns a
KerberosEndpoint instance for the given
server host name, TCP port number, and server
principal. |
static KerberosEndpoint |
getInstance(String serverHost,
int serverPort,
KerberosPrincipal serverPrincipal,
SocketFactory csf)
Returns a
KerberosEndpoint instance for the given
server host name, TCP port number, server principal, and
SocketFactory . |
int |
getPort()
Returns the TCP port that this endpoint connects to.
|
KerberosPrincipal |
getPrincipal()
Returns the principal this endpoint requires the server
to authenticate as.
|
SocketFactory |
getSocketFactory()
Returns the
SocketFactory that this endpoint uses
to create Socket objects. |
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 endpoint.
|
public static KerberosEndpoint getInstance(String serverHost, int serverPort, KerberosPrincipal serverPrincipal)
KerberosEndpoint
instance for the given
server host name, TCP port number, and server
principal. Internally this endpoint uses Socket
objects
to connect to its server endpoint.serverHost
- the host for the endpoint to connect toserverPort
- the TCP port on the given host for the
endpoint to connect toserverPrincipal
- principal the server can authenticate asKerberosEndpoint
instanceNullPointerException
- if serverHost
or
serverPrincipal
is null
IllegalArgumentException
- if serverPort
is
not in the range of 1
to
65535
public static KerberosEndpoint getInstance(String serverHost, int serverPort, KerberosPrincipal serverPrincipal, SocketFactory csf)
KerberosEndpoint
instance for the given
server host name, TCP port number, server principal, and
SocketFactory
.
If the socket factory argument is null
, then
this endpoint will create Socket
objects directly.
serverHost
- the host for the endpoint to connect toserverPort
- the TCP port on the given host for the
endpoint to connect toserverPrincipal
- principal the server can authenticate ascsf
- the SocketFactory
to use for this
KerberosEndpoint
, or null
KerberosEndpoint
instanceNullPointerException
- if serverHost
or
serverPrincipal
is null
IllegalArgumentException
- if serverPort
is
not in the range of 1
to
65535
SocketFactory
public String getHost()
public int getPort()
public KerberosPrincipal getPrincipal()
public SocketFactory getSocketFactory()
SocketFactory
that this endpoint uses
to create Socket
objects.null
if no factory is usedpublic 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 thisKerberosEndpoint
(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 (thisKerberosEndpoint
'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 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 thisKerberosEndpoint
'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 the
KerberosPrincipal
, and permissions required to use it, that would be necessary if the the connection were being created. In addition, it must be possible to invokecheckConnect
in the current security context with thisKerberosEndpoint
'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. Also, aSecurityException
may be thrown 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
KerberosEndpoint
with the same values for server
principal, 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
otherwisepublic int hashCode()
public boolean equals(Object obj)
null
or have the same actual class and
are equal.