public final class KerberosServerEndpoint extends Object implements ServerEndpoint
ServerEndpoint
implementation that uses Kerberos as the
underlying network security protocol to support security related
invocation constraints for remote requests. Instances of this
class are referred to as the server endpoints of the Kerberos
provider, while instances of KerberosEndpoint
are referred
to as the endpoints of the provider.
Instances of this class are intended to be created for use with the
BasicJeriExporter
class. Calls to enumerateListenEndpoints
return
instances of KerberosEndpoint
.
This class supports at least the following standard constraints:
Integrity.YES
Confidentiality
ClientAuthentication.YES
ConnectionAbsoluteTime
,
trivially, since this only takes effect on the client side
ConnectionRelativeTime
,
trivially, since this only takes effect on the client side
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
KerberosServerEndpoint
, one of
the getInstance
methods of the class has to be
invoked. The returned server endpoint instance encapsulates a set
of properties that it will later use to receive and dispatch
inbound requests. The following describes how some of these
properties are chosen:
serverSubject
- The Subject
that contains
the principal and credential to be used by the server endpoint
to authenticate itself to its remote callers. The subject is
either provided by the caller of the getInstance
method as a non-null
argument, or extracted from
the access control context of the current thread when the
getInstance
method is called. The later value is
also referred to as the default server subject.
serverPrincipal
- The
KerberosPrincipal
that the server endpoint will
authenticate itself as to all clients. If the caller of the
getInstance
method provides a
non-null
serverPrincipal
argument, it
is used without any further checking; otherwise the default
server principal will be used. The default server principal
can be any KerberosPrincipal
instance in the
serverSubject
's principal set, whose corresponding
KerberosKey
is found in the subject's private
credential set and is still valid, provided the caller has been
granted the AuthenticationPermission
with the principal as its local principal and
listen
as its action.
serverHost
- The host name that will be
encapsulated in KerberosEndpoint
instances created
by the server endpoint. If a non-null serverHost
is provided by the caller, it will be used; otherwise the
default value is used, which is the IP address of the local
host, as obtained from InetAddress.getLocalHost
. The host name does not affect the
behavior of the listen operation itself, which always listens
on all of the local system's network addresses, unless a
ServerSocketFactory
is provided by the caller, in
which case the factory will be in charge.
SocketFactory
for creating
the Socket
instances that the associated
KerberosEndpoint
instances use to make remote
connections back to the server, and a ServerSocketFactory
for creating the ServerSocket
instances that the server
endpoint uses to accept remote connections.
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. A ServerSocketFactory
used with instances of
this class should implement Object.equals
to return
true
when passed an instance that represents the same
(functionally equivalent) server socket factory.
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.
KerberosEndpoint
,
KerberosTrustVerifier
ServerEndpoint.ListenContext, ServerEndpoint.ListenCookie, ServerEndpoint.ListenEndpoint, ServerEndpoint.ListenHandle
Modifier and Type | Method and Description |
---|---|
InvocationConstraints |
checkConstraints(InvocationConstraints constraints)
Verifies that this instance supports the transport layer
aspects of all of the specified requirements (both in general
and in the current security context), and returns the
requirements that must be at least partially implemented by
higher layers in order to fully satisfy all of the specified
requirements.
|
Endpoint |
enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)
Passes the
ListenEndpoint for this KerberosServerEndpoint to
listenContext , which will ensure an active listen
operation on the endpoint, and returns a KerberosEndpoint
instance corresponding to the listen operation chosen by
listenContext . |
boolean |
equals(Object obj)
Two instances of this class are equal if they have server
subjects that compare equal using
== ; have the
same server principal; have the same values for server host and
port; have socket factories that are either both
null , or have the same actual class and are equal;
and have server socket factories that are either both
null , or have the same actual class and are equal. |
String |
getHost()
Returns the host name that will be used in
KerberosEndpoint instances created by listening on this
object. |
static KerberosServerEndpoint |
getInstance(int port)
Returns a
KerberosServerEndpoint instance with the
specified port, using the default server subject, server
principal, and server host. |
static KerberosServerEndpoint |
getInstance(String serverHost,
int port)
Returns a
KerberosServerEndpoint instance with the
specified server host and port, using the default server
subject and server principal. |
static KerberosServerEndpoint |
getInstance(String serverHost,
int port,
SocketFactory csf,
ServerSocketFactory ssf)
Returns a
KerberosServerEndpoint instance with the
specified server host, port, and socket factories, using the
default server subject and server principal. |
static KerberosServerEndpoint |
getInstance(Subject serverSubject,
KerberosPrincipal serverPrincipal,
String serverHost,
int port)
Returns a
KerberosServerEndpoint instance with the
specified server subject, server principal, server host, and
port. |
static KerberosServerEndpoint |
getInstance(Subject serverSubject,
KerberosPrincipal serverPrincipal,
String serverHost,
int port,
SocketFactory csf,
ServerSocketFactory ssf)
Returns a
KerberosServerEndpoint instance with the
specified server subject, server principal, server host, port,
and socket factories. |
int |
getPort()
Returns the TCP port that the
ListenEndpoint s
created by this server endpoint listen on. |
KerberosPrincipal |
getPrincipal()
Returns the principal that this server endpoint will
authenticate itself as.
|
ServerSocketFactory |
getServerSocketFactory()
Returns the server socket factory that this server endpoint
uses to create
ServerSocket instances, or
null if it uses default server sockets. |
SocketFactory |
getSocketFactory()
Returns the socket factory that the associated
KerberosEndpoint instances, which are created by listening on
the ListenEndpoint instances of this server
endpoint, use to create Socket instances, or
null if they use default sockets. |
int |
hashCode()
Returns a hash code value for this object.
|
String |
toString()
Returns a string representation of this object.
|
public static KerberosServerEndpoint getInstance(int port) throws UnsupportedConstraintException
KerberosServerEndpoint
instance with the
specified port, using the default server subject, server
principal, and server host.port
- the port this server endpoint will listen on, 0 to
use any free portKerberosServerEndpoint
instanceUnsupportedConstraintException
- if the caller has not
been granted the right
AuthenticationPermission
, or there is no
default server subject
(serverSubject.getSubject(AccessController.getContext())
returns null
), or no appropriate
Kerberos principal and corresponding Kerberos key can
be found in the server subjectSecurityException
- if there is a security manager and
the following condition is true:
AuthPermission
("getSubject")
,
but no listen
AuthenticationPermission
whose local
principal is a principal in the server subject's
principal set, which is required for accessing any
private credentials corresponding to the principal
in the server subject.
IllegalArgumentException
- if serverPort
is
not in the range of 0
to
65535
public static KerberosServerEndpoint getInstance(String serverHost, int port) throws UnsupportedConstraintException
KerberosServerEndpoint
instance with the
specified server host and port, using the default server
subject and server principal.serverHost
- the name or IP address of the server host the
KerberosEndpoint
instances created by this
server endpoint will connect to. If null
,
the default server host will be used.port
- the port this server endpoint will listen on, 0 to
use any free portKerberosServerEndpoint
instanceUnsupportedConstraintException
- if the caller has not
been granted the right
AuthenticationPermission
, or there is no
default server subject
(serverSubject.getSubject(AccessController.getContext())
returns null
), or no appropriate
Kerberos principal and corresponding Kerberos key can
be found in the server subjectSecurityException
- if there is a security manager and
the following condition is true:
AuthPermission
("getSubject")
,
but no listen
AuthenticationPermission
whose local
principal is a principal in the server subject's
principal set, which is required for accessing any
private credentials corresponding to the principal
in the server subject.
IllegalArgumentException
- if serverPort
is
not in the range of 0
to
65535
public static KerberosServerEndpoint getInstance(String serverHost, int port, SocketFactory csf, ServerSocketFactory ssf) throws UnsupportedConstraintException
KerberosServerEndpoint
instance with the
specified server host, port, and socket factories, using the
default server subject and server principal.serverHost
- the name or IP address of the server host the
KerberosEndpoint
instances created by this
server endpoint will connect to. If null
,
the default server host will be used.port
- the port this server endpoint will listen on, 0 to
use any free portcsf
- the SocketFactory
to be used by the
KerberosEndpoint
created by this server
endpoint to create sockets, or null
to let
the KerberosEndpoint
create Socket
s
directly.ssf
- the ServerSocketFactory
to use for this
KerberosServerEndpoint
, or
null
to let the
KerberosServerEndpoint
create ServerSocket
s directly.KerberosServerEndpoint
instanceUnsupportedConstraintException
- if the caller has not
been granted the right
AuthenticationPermission
, or there is no
default server subject
(serverSubject.getSubject(AccessController.getContext())
returns null
), or no appropriate
Kerberos principal and corresponding Kerberos key can
be found in the server subjectSecurityException
- if there is a security manager and
the following condition is true:
AuthPermission
("getSubject")
,
but no listen
AuthenticationPermission
whose local
principal is a principal in the server subject's
principal set, which is required for accessing any
private credentials corresponding to the principal
in the server subject.
IllegalArgumentException
- if serverPort
is
not in the range of 0
to
65535
public static KerberosServerEndpoint getInstance(Subject serverSubject, KerberosPrincipal serverPrincipal, String serverHost, int port) throws UnsupportedConstraintException
KerberosServerEndpoint
instance with the
specified server subject, server principal, server host, and
port.serverSubject
- the server subject to use for
authenticating the server. If null
, the
subject associated with the current access control
context will be used.serverPrincipal
- the principal server should authenticate
as. If null
, then the default server
principal will be used.serverHost
- the name or IP address of the server host the
KerberosEndpoint
instances created by this
server endpoint will connect to. If null
,
the default server host will be used.port
- the port this server endpoint will listen on, 0 to
use any free portKerberosServerEndpoint
instanceUnsupportedConstraintException
- if the caller has not
been granted the right
AuthenticationPermission
, or there is no
default server subject
(serverSubject.getSubject(AccessController.getContext())
returns null
), or no appropriate
Kerberos principal and corresponding Kerberos key can
be found in the server subjectSecurityException
- if there is a security manager and
the following condition is true:
null
,
the caller has the
AuthPermission
("getSubject")
, but no listen
AuthenticationPermission
whose local
principal is a principal in the server subject's
principal set, which is required for accessing any
private credentials corresponding to the principal
in the server subject.
IllegalArgumentException
- if serverPort
is
not in the range of 0
to
65535
public static KerberosServerEndpoint getInstance(Subject serverSubject, KerberosPrincipal serverPrincipal, String serverHost, int port, SocketFactory csf, ServerSocketFactory ssf) throws UnsupportedConstraintException
KerberosServerEndpoint
instance with the
specified server subject, server principal, server host, port,
and socket factories.serverSubject
- the server subject to use for
authenticating the server. If null
, the
subject associated with the current access control
context will be used.serverPrincipal
- the principal server should authenticate
as. If null
, then the default server
principal will be used.serverHost
- the name or IP address of the server host the
KerberosEndpoint
instances created by this
server endpoint will connect to. If null
,
the default server host will be used.port
- the port this server endpoint will listen on, 0 to
use any free portcsf
- the SocketFactory
to be used by the
KerberosEndpoint
created by this server
endpoint to create sockets, or null
to let
the KerberosEndpoint
create Socket
s
directly.ssf
- the ServerSocketFactory
to use for this
KerberosServerEndpoint
, or
null
to let the
KerberosServerEndpoint
create ServerSocket
s directly.KerberosServerEndpoint
instanceUnsupportedConstraintException
- if the caller has not
been granted the right
AuthenticationPermission
, or there is no
default server subject
(serverSubject.getSubject(AccessController.getContext())
returns null
), or no appropriate
Kerberos principal and corresponding Kerberos key can
be found in the server subjectSecurityException
- if there is a security manager and
the following condition is true:
null
,
the caller has the AuthPermission
("getSubject")
, but
no listen
AuthenticationPermission
whose local
principal is a principal in the server subject's
principal set, which is required for accessing any
private credentials corresponding to the principal
in the server subject.
IllegalArgumentException
- if serverPort
is
not in the range of 0
to
65535
public String getHost()
KerberosEndpoint
instances created by listening on this
object.KerberosEndpoint
instances created by listening on this objectpublic int getPort()
ListenEndpoint
s
created by this server endpoint listen on.public KerberosPrincipal getPrincipal()
public SocketFactory getSocketFactory()
KerberosEndpoint
instances, which are created by listening on
the ListenEndpoint
instances of this server
endpoint, use to create Socket
instances, or
null
if they use default sockets.null
if they use
default socketspublic ServerSocketFactory getServerSocketFactory()
ServerSocket
instances, or
null
if it uses default server sockets.null
if
it uses default server socketspublic InvocationConstraints checkConstraints(InvocationConstraints constraints) throws UnsupportedConstraintException
ServerCapabilities
For any given constraint, there must be a clear delineation
of which aspects (if any) must be implemented by the transport
layer. This method must not return a constraint (as a
requirement or a preference, directly or as an element of
another constraint) unless this instance can implement all of
those aspects. Also, this method must not return a constraint
for which all aspects must be implemented by the transport
layer. Most of the constraints in the net.jini.core.constraint
package must be fully implemented by
the transport layer and thus must not be returned by this
method; the one exception is Integrity
, for which the
transport layer is responsible for the data integrity aspect
and higher layers are responsible for the code integrity
aspect.
For any ConstraintAlternatives
in the specified
constraints, this method should only return a corresponding
constraint if all of the alternatives supported by this
instance need to be at least partially implemented by higher
layers in order to be fully satisfied.
The constraints passed to this method may include constraints based on relative time.
checkConstraints
in interface ServerCapabilities
constraints
- the constraints that must be supportedUnsupportedConstraintException
- if the transport layer
aspects of any of the specified requirements are not supported
by this instance (either in general or in the current security
context)public Endpoint enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext) throws IOException
ListenEndpoint
for this KerberosServerEndpoint
to
listenContext
, which will ensure an active listen
operation on the endpoint, and returns a KerberosEndpoint
instance corresponding to the listen operation chosen by
listenContext
.
If this server endpoint's server host is null
,
then the endpoint returned will contain the default server
host. This method computes the default by invoking InetAddress.getLocalHost
to obtain an
InetAddress
for the local host. If
InetAddress.getLocalHost
throws an
UnknownHostException
, this method throws an
UnknownHostException
.
The default host name will be the string returned by invoking
getHostAddress
on the obtained
InetAddress
. If there is a security manager, its checkConnect
method
will be invoked with the string returned by invoking getHostName
on that same
InetAddress
as the host argument and
-1
as the port argument; this could result in a
SecurityException
.
This method invokes addListenEndpoint
on
listenContext
once, passing a ListenEndpoint
as described below. If addListenEndpoint
throws an
exception, then this method throws that exception. Otherwise, this
method returns a KerberosEndpoint
instance with the host
name described above, the TCP port number bound by the listen operation
represented by the ListenHandle
returned by addListenEndpoint
, and the same
server principal and SocketFactory
as this
KerberosServerEndpoint
.
The ListenEndpoint
passed to
addListenEndpoint
represents the server subject, server
principal, TCP port number, and ServerSocketFactory
of this
KerberosServerEndpoint
. Its methods behave as follows:
ListenHandle
listen(RequestDispatcher)
:
Listens for requests received on this endpoint's TCP port, dispatching them to the suppliedRequestDispatcher
in the form ofInboundRequest
instances.When the implementation of this method needs to create a new
ServerSocket
, it will do so by invoking one of thecreateServerSocket
methods that returns a bound server socket on the containedServerSocketFactory
if non-null
, or it will create aServerSocket
directly otherwise.If there is a security manager, its
checkListen
method will be invoked with this endpoint's TCP port; this could result in aSecurityException
. In addition, the security manager'scheckPermission
method will be invoked with anAuthenticationPermission
containing the server principal of this endpoint and thelisten
action; this could also result in aSecurityException
. Furthermore, before a givenInboundRequest
gets dispatched to the supplied request dispatcher, the security manager'scheckAccept
method must have been successfully invoked in the security context of thislisten
invocation with the remote IP address and port of theSocket
used to receive the request, and the security manager'scheckPermission
method must have been successfully invoked in the same context with anAuthenticationPermission
containing the server principal of this endpoint as local principal, the client's authenticated principal as peer principal, and theaccept
action. ThecheckPermissions
method of the dispatchedInboundRequest
also performs these latter security checks. (Note that in some cases, the implementation may carry out some of these security checks indirectly, such as through invocations ofServerSocket
's constructors oraccept
method.)Once a
ListenEndpoint
of this provider starts to listen, each time a new inbound request comes in, it verifies that theserverSubject
of the corresponding server endpoint still holds a validKerberosKey
corresponding to itsserverPrincipal
. It rejects the request if the verification fails. This guarantees that as soon as theKerberosKey
for the principal in theSubject
is destroyed (logout) or expired, no more new requests will be accepted.Requests will be dispatched in a
PrivilegedAction
wrapped by aSecurityContext
obtained when this method was invoked, with theAccessControlContext
of thatSecurityContext
in effect.Dispatched requests will implement
populateContext
to populate the given collection with an element that implements theClientHost
interface, and an element that implements theClientSubject
interface. TheClientHost
element implementsgetClientHost
to return the IP address of theSocket
that the request was received over (seeSocket.getInetAddress()
).Throws
IOException
if an I/O exception occurs while performing this operation, such as if the TCP port is already in use.Throws
SecurityException
if there is a security manager and an invocation of itscheckListen
orcheckPermission
method fails.Throws
NullPointerException
ifrequestDispatcher
isnull
void checkPermissions()
:
Verifies that the current security context has all of the security permissions necessary to listen for requests on this endpoint.If there is a security manager, its
checkListen
method will be invoked with this endpoint's TCP port; this could result in aSecurityException
. In addition, the security manager'scheckPermission
method will be invoked with anAuthenticationPermission
containing the server principal of this endpoint and thelisten
action; this could also result in aSecurityException
.Throws
SecurityException
if there is a security manager and an invocation of itscheckListen
orcheckPermission
method fails.
boolean equals(Object)
:
Compares the specified object with thisListenEndpoint
for equality.This method returns
true
if and only if the specified object is also aListenEndpoint
produced by aKerberosServerEndpoint
, and the two listen endpoints both have server subjects that compare equal using==
; have the same server principal; have the same values for TCP port; and have server socket factories that are either bothnull
, or have the same actual class and are equal.
enumerateListenEndpoints
in interface ServerEndpoint
listenContext
- the ListenContext
to pass
this ServerEndpoint
's ListenEndpoint
instances toEndpoint
instance for sending requests
to this ServerEndpoint
's communication endpoints
being listened onSecurityException
- if there is a security manager, and
either its checkListen
method fails, or serverHost
is null
and the security manager's checkConnect
method
fails; or if the calling thread does not have
permission to authenticate as the endpoint's server
principal when listening for connectionsIllegalArgumentException
- if an invocation of the
addListenEndpoint
method on the supplied
ListenContext
returns a ListenCookie
that does not correspond to the ListenEndpoint
that was passed to itNullPointerException
- if listenContext
is
null
UnknownHostException
- if this instance's server host
is null
and
InetAddress.getLocalHost
throws an
UnknownHostException
UnsupportedConstraintException
- if the server subject is
missing any of the endpoint's server principals or
the associated credentialsIOException
- if an I/O exception occurs while attempting
to listen for requests on the communication endpoints
represented by this ServerEndpoint
. This could
occur, for example, if an I/O resource associated with one of
the communication endpoints is already in exclusive use, or if
there are insufficient I/O resources for the operation.public int hashCode()
public boolean equals(Object obj)
==
; have the
same server principal; have the same values for server host and
port; have socket factories that are either both
null
, or have the same actual class and are equal;
and have server socket factories that are either both
null
, or have the same actual class and are equal.