Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.jeri.ssl
Class HttpsServerEndpoint

    java.lang.Object
      net.jini.jeri.ssl.HttpsServerEndpoint

All Implemented Interfaces:
  ServerCapabilities, ServerEndpoint

public final class HttpsServerEndpoint
extends Object
implements ServerEndpoint

An implementation of `ServerEndpoint` that uses HTTPS (HTTP over TLS/SSL) to support invocation constraints for communication through firewalls.

Instances of this class are intended to be created for use with the `BasicJeriExporter` class. Calls to `enumerateListenEndpoints` return instances of `HttpsEndpoint`.

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`, trivially, since this only takes effect on the client side
- `ConnectionRelativeTime`, trivially, since this only takes effect on the client side
- `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
- `DelegationRelativeTime`, trivially, when delegation is not supported
- `Integrity.YES`
- `ServerAuthentication`
- `ServerMinPrincipal`, when it contains a single `X500Principal` only

This class authenticates as a single `Principal` if the following items are present in the server `Subject`:

- One or more principals of type `X500Principal`
- For each principal, one or more certificate chains, stored as public credentials, and represented by instances of `CertPath`, whose `getType` method returns "X.509", and for which calling `getSubjectDN` on the certificate chain's first element returns that principal's name
- For each certificate chain, an instance of `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 will only dispatch remote calls that authenticate as a given principal if the caller of `listen` on the class's `ServerEndpoint.ListenEndpoint` has been granted `AuthenticationPermission` with that principal as the local principal, the principal representing the authenticated identity of the client for the call (if any) as the peer principal, and the `accept` 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.

If the server subject contains principals and credentials that would permit authentication of more than one `X500Principal`, the endpoint will make an arbitrary choice of the principal to use for authentication, and will continue to make the same choice so long as subject contents, validity of credentials, and security permissions do not change.

The host name specified when creating an `HttpsServerEndpoint` instance controls the host name that will be contained in `HttpsEndpoint` instances produced when `enumerateListenEndpoints` is invoked to listen on the server endpoint; the host name does not affect the behavior of the listen operation itself, which listens on all of the local system's network addresses. If the host name in the server endpoint is `null`, then the host name in the `HttpsEndpoint` instances that it produces will be the default server host name, which is the IP address string of the `InetAddress` returned by `InetAddress.getLocalHost` when `enumerateListenEndpoints` is invoked.

This class permits specifying a `SocketFactory` for creating the `Socket` instances that the associated `HttpsEndpoint` 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. These socket factories and sockets should not implement the TLS/SSL protocol; it is the responsibility of the implementation to establish TLS/SSL connections over the sockets it obtains from the socket factories. In particular, instances of `SSLSocketFactory` and `SSLServerSocketFactory` should not be used, and the factories used should not return instances of `SSLSocket` or `SSLServerSocket`.

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. A `ServerSocketFactory` used with instances of this class must implement `Object.equals` to obey the guidelines that are specified for `equals` methods of `ListenEndpoint` instances.

Since:
  2.0
See Also:
  `HttpsEndpoint`, `ConfidentialityStrength`
Implementation Specifics:
  This implementation uses the Java(TM) Secure Socket Extension (JSSE).

  This implementation uses the `ServerConnectionManager` class to manage connections.

  This implementation uses the following `Logger` instances in the `net.jini.jeri.ssl` namespace:

  - init - problems during initialization
  - server - information about server-side connections

  `net.jini.jeri.ssl.init`
  Level | Description
  --- | ---
  `WARNING` | problems with initializing JSSE

  `net.jini.jeri.ssl.server`
  Level | Description
  --- | ---
  `INFO` | problems with accepting or handling server connections, or with handling inbound requests
  `FAILED` | problems with checking constraints or permissions, with enumerating listen endpoints, or with security issues for inbound requests
  `HANDLED` | exceptions caught involving authentication
  `FINE` | creating server endpoints, enumerating listen endpoints, creating or closing connections or listen handles, or checking constraints for endpoints or inbound requests
  `FINEST` | low level operation tracing

  This implementation uses the following security providers:

  - `SSLContext`, with the protocol specified by the `com.sun.jini.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 `com.sun.jini.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:

  - `com.sun.jini.jeri.ssl.maxServerSessionDuration` - The maximum number of milliseconds a server-side TLS/SSL session should be used before expiring. The default is 24 hours. The value used should be larger than the maximum client session duration to allow the client to negotiate a new session before the server timeout occurs.
  - `com.sun.jini.jeri.ssl.sslProtocol` - The secure socket protocol used when obtaining `SSLContext` instances. The default is `"TLS"`.
  - `com.sun.jini.jeri.ssl.trustManagerFactoryAlgorithm` - The algorithm used when obtaining `TrustManagerFactory` instances. The default is the value returned by `TrustManagerFactory.getDefaultAlgorithm`.
  - `com.sun.jini.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.
  - `com.sun.jini.jeri.https.idleServerConnectionTimeout` - The number of milliseconds to retain idle server-side HTTPS connections before closing them. The default is the idle client-side connection timeout (as specified by the `com.sun.jini.jeri.https.idleConnectionTimeout` system property) plus `30000`.
  - `com.sun.jini.jeri.https.responseAckTimeout` - The number of milliseconds to wait for acknowledgments from `AcknowledgmentSource` instances. The default is `15000`.

Nested Class Summary

Nested classes inherited from class net.jini.jeri.ServerEndpoint
`ServerEndpoint.ListenContext, ServerEndpoint.ListenCookie, ServerEndpoint.ListenEndpoint, ServerEndpoint.ListenHandle`

Method Summary
`InvocationConstraints` | `checkConstraints(InvocationConstraints constraints)` Checks that it is possible to receive requests that either fully or partially satisfy the specified requirements, and returns any constraints that must be fully or partially implemented by higher layers in order to fully satisfy all of the specified requirements.
`Endpoint` | `enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)` Enumerates the communication endpoints represented by this `ServerEndpoint` by passing the `ListenEndpoint` for each of them to `listenContext`, which will ensure an active listen operation on each endpoint, and returns an `Endpoint` instance corresponding to the listen operations chosen by `listenContext`.
`boolean` | `equals(Object object)` Two instances of this class are equal if they have server subjects that compare equal using `==`; have server principals that are either both `null` or are equal when compared as the elements of a `Set`; 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 `HttpsEndpoint` instances created by listening on this object, or `null` if `enumerateListenEndpoints` will use the default server host.
`static HttpsServerEndpoint` | `getInstance(int port)` Returns an HTTPS server endpoint for the specified port.
`static HttpsServerEndpoint` | `getInstance(String serverHost, int port)` Returns an HTTPS server endpoint for the specified server host and port.
`static HttpsServerEndpoint` | `getInstance(String serverHost, int port, SocketFactory socketFactory, ServerSocketFactory serverSocketFactory)` Returns an HTTPS server endpoint for the specified server host, port, and socket factories.
`static HttpsServerEndpoint` | `getInstance(Subject serverSubject, X500Principal[] serverPrincipals, String serverHost, int port)` Returns an HTTPS server endpoint for the specified server subject, server principals, server host, and port.
`static HttpsServerEndpoint` | `getInstance(Subject serverSubject, X500Principal[] serverPrincipals, String serverHost, int port, SocketFactory socketFactory, ServerSocketFactory serverSocketFactory)` Returns an HTTPS server endpoint for the specified server subject, server principals, server host, port, and socket factories.
`int` | `getPort()` Returns the TCP port on which this object listens for connections, or `0` if it selects a free port.
`Set` | `getPrincipals()` Returns an immutable set of the principals that this instance uses for authentication, or `null` if it is anonymous.
`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 `HttpsEndpoint` instances created by listening on 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.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Method Detail

### getInstance

    public static HttpsServerEndpoint getInstance(int port)

  Returns an HTTPS server endpoint for the specified port. Uses the `null` server host (which requests that `enumerateListenEndpoints` compute the default server host), the subject associated with the current access control context, the principals in the subject with appropriate public and private credentials for which the caller has `AuthenticationPermission` to listen, and `null` socket factories to create default sockets. A `port` of `0` requests listening on any free port.

  Parameters:
    `port` - the port on which to listen for connections, or `0` for any free port
  Returns:
    an `HttpsServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if `port` is negative or greater than `65535`

### getInstance

    public static HttpsServerEndpoint getInstance(String serverHost,
                                                  int port)

  Returns an HTTPS server endpoint for the specified server host and port. Uses the subject associated with the current access control context, the principals in the subject with appropriate public and private credentials for which the caller has `AuthenticationPermission` to listen, and `null` socket factories to create default sockets. A `serverHost` of `null` requests that `enumerateListenEndpoints` compute the default server host. A `port` of `0` requests listening on any free port.

  Parameters:
    `serverHost` - the name that clients should use to connect to this server, or `null` to use the default
    `port` - the port on which to listen for connections, or `0` for any free port
  Returns:
    an `HttpsServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if `port` is negative or greater than `65535`

### getInstance

    public static HttpsServerEndpoint getInstance(String serverHost,
                                                  int port,
                                                  SocketFactory socketFactory,
                                                  ServerSocketFactory serverSocketFactory)

  Returns an HTTPS server endpoint for the specified server host, port, and socket factories. Uses the subject associated with the current access control context, and the principals in the subject with appropriate public and private credentials for which the caller has `AuthenticationPermission` to listen. A `serverHost` of `null` requests that `enumerateListenEndpoints` compute the default server host. A `port` of `0` requests listening on any free port. A `socketFactory` of `null` uses default sockets in the associated `HttpsEndpoint`. A `serverSocketFactory` of `null` uses default server sockets.

  Parameters:
    `serverHost` - the name that clients should use to connect to this server, or `null` to use the default
    `port` - the port on which to listen for connections, or `0` for any free port
    `socketFactory` - the socket factory for use in the associated `HttpsEndpoint` instances, or `null`
    `serverSocketFactory` - the server socket factory, or `null`
  Returns:
    an `HttpsServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if `port` is negative or greater than `65535`

### getInstance

    public static HttpsServerEndpoint getInstance(Subject serverSubject,
                                                  X500Principal[] serverPrincipals,
                                                  String serverHost,
                                                  int port)

  Returns an HTTPS server endpoint for the specified server subject, server principals, server host, and port. Uses `null` socket factories to create default sockets. A `serverSubject` of `null` uses the subject associated with the current access control context. A `serverPrincipals` of `null` uses the principals in the subject with appropriate public and private credentials for which the caller has `AuthenticationPermission` to listen; otherwise that argument specifies the principals to use, or that the server should be anonymous if the argument has no elements. If non-`null`, the value of `serverPrincipals` is neither retained nor modified; subsequent changes to that argument have no effect on the instance created. A `serverHost` of `null` requests that `enumerateListenEndpoints` compute the default server host. A `port` of `0` requests listening on any free port.

  Parameters:
    `serverSubject` - the `Subject` to use for authenticating the server or `null` to use the current subject
    `serverPrincipals` - the principals to use for authenticating the server, or `null` to use any available principals in the subject
    `serverHost` - the name that clients should use to connect to this server, or `null` to use the default
    `port` - the port on which to listen for connections, or `0` for any free port
  Returns:
    an `HttpsServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if `port` is negative or greater than `65535`
    `NullPointerException` - if `serverPrincipals` is not `null` and any of its elements are `null`

### getInstance

    public static HttpsServerEndpoint getInstance(Subject serverSubject,
                                                  X500Principal[] serverPrincipals,
                                                  String serverHost,
                                                  int port,
                                                  SocketFactory socketFactory,
                                                  ServerSocketFactory serverSocketFactory)

  Returns an HTTPS server endpoint for the specified server subject, server principals, server host, port, and socket factories. A `serverSubject` of `null` uses the subject associated with the current access control context. A `serverPrincipals` of `null` uses the principals in the subject with appropriate public and private credentials for which the caller has `AuthenticationPermission` to listen; otherwise that argument specifies the principals to use, or that the server should be anonymous if the argument has no elements. If non-`null`, the value of `serverPrincipals` is neither retained nor modified; subsequent changes to that argument have no effect on the instance created. A `serverHost` of `null` requests that `enumerateListenEndpoints` compute the default server host. A `port` of `0` requests listening on any free port. A `socketFactory` of `null` uses default sockets in the associated `HttpsEndpoint`. A `serverSocketFactory` of `null` uses default server sockets.

  Parameters:
    `serverSubject` - the `Subject` to use for authenticating the server or `null` to use the current subject
    `serverPrincipals` - the principals to use for authenticating the server, or `null` to use any available principals in the subject
    `serverHost` - the name that clients should use to connect to this server, or `null` to use the default
    `port` - the port on which to listen for connections, or `0` for any free port
    `socketFactory` - the socket factory for use in the associated `HttpsEndpoint` instances, or `null`
    `serverSocketFactory` - the server socket factory, or `null`
  Returns:
    an `HttpsServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if `port` is negative or greater than `65535`
    `NullPointerException` - if `serverPrincipals` is not `null` and any of its elements are `null`

### getHost

    public String getHost()

  Returns the host name that will be used in `HttpsEndpoint` instances created by listening on this object, or `null` if `enumerateListenEndpoints` will use the default server host.

  Returns:
    the host name to use in `HttpsEndpoint` instances created by listening on this object, or `null` if using the default

### getPort

    public int getPort()

  Returns the TCP port on which this object listens for connections, or `0` if it selects a free port.

  Returns:
    the TCP port on which this object listens for connections, or `0` if it selects a free port

### getPrincipals

    public Set getPrincipals()

  Returns an immutable set of the principals that this instance uses for authentication, or `null` if it is anonymous.

  Returns:
    an immutable set of the principals or `null`

### getSocketFactory

    public SocketFactory getSocketFactory()

  Returns the socket factory that the associated `HttpsEndpoint` instances created by listening on this server endpoint use to create `Socket` instances, or `null` if they use default sockets.

  Returns:
    the socket factory that associated endpoints use to create sockets, or `null` if they use default sockets

### getServerSocketFactory

    public ServerSocketFactory getServerSocketFactory()

  Returns the server socket factory that this server endpoint uses to create `ServerSocket` instances, or `null` if it uses default server sockets.

  Returns:
    the server socket factory that this server endpoint uses to create server sockets, or `null` if it uses default server sockets

### toString

    public String toString()

  Returns a string representation of this object.

### checkConstraints

    public InvocationConstraints checkConstraints(InvocationConstraints constraints)
                                           throws UnsupportedConstraintException

  Checks that it is possible to receive requests that either fully or partially satisfy the specified requirements, and returns any constraints that must be fully or partially implemented by higher layers in order to fully satisfy all of the specified requirements.

  This implementation only returns `Integrity.YES` constraints.

  Specified by:
    `checkConstraints` in interface `ServerCapabilities`
  Parameters:
    `constraints` - the constraints that must be supported
  Returns:
    the constraints that must be at least partially implemented by higher layers
  Throws:
    `SecurityException` - if the current security context does not have the permissions necessary to perform this operation
    `NullPointerException` - if `constraints` is `null`
    `UnsupportedConstraintException` - 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)

### hashCode

    public int hashCode()

  Returns a hash code value for this object.

### equals

    public boolean equals(Object object)

  Two instances of this class are equal if they have server subjects that compare equal using `==`; have server principals that are either both `null` or are equal when compared as the elements of a `Set`; 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.

### enumerateListenEndpoints

    public Endpoint enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)
                                      throws IOException

  Enumerates the communication endpoints represented by this `ServerEndpoint` by passing the `ListenEndpoint` for each of them to `listenContext`, which will ensure an active listen operation on each endpoint, and returns an `Endpoint` instance corresponding to the listen operations 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 exception, this method throws that exception. The default host name will be the string returned by invoking `getHostAddress` on that `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`.

  If this server endpoint's `ServerSocketFactory` is not `null`, then the `listen` method defined on the `ListenEndpoint` this method passes to `listenContext` will create new `ServerSocket` instances by invoking one of the factory's `createServerSocket` methods that returns bound server sockets, and otherwise it will create server sockets directly.

  If there is a security manager, the `checkPermissions` and `listen` methods defined on the listen endpoint will call the security manager's `checkListen` method, as well as requiring the caller to have `AuthenticationPermission` with all the server principals specified in the server endpoint and the `listen` action.

  Specified by:
    `enumerateListenEndpoints` in interface `ServerEndpoint`
  Parameters:
    `listenContext` - the `ListenContext` to pass this `ServerEndpoint`'s `ListenEndpoint` instances to
  Returns:
    the `Endpoint` instance for sending requests to this `ServerEndpoint`'s communication endpoints being listened on
  Throws:
    `SecurityException` - 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 each of the endpoint's server principals when listening for connections
    `IllegalArgumentException` - 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 it
    `NullPointerException` - 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 credentials
    `IOException` - 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved