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 SslEndpoint

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

All Implemented Interfaces:
  Endpoint, Serializable, TrustEquivalence

public final class SslEndpoint
extends Object
implements Endpoint, Serializable, TrustEquivalence

An implementation of `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`:

- 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'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(TM) extensible remote invocation (Jini ERI) multiplexing protocol to map outgoing requests to socket connections.

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

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

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

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

  `net.jini.jeri.ssl.init`
  Level | Description
  --- | ---
  `WARNING` | problems with initializing JSSE or with registering internal entry points with discovery providers

  `net.jini.jeri.ssl.client`
  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 `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.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.
  - `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.

Method Summary
`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. The constraints must be the complete, absolute constraints for the request. If there is a security manager, the `next` method defined on the iterator returned by this method calls the security manager's `checkConnect` method with the endpoint's server host and port.
`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 SslEndpoint getInstance(String serverHost,
                                          int port)

  Returns a TLS/SSL endpoint for the specified server host and port. Uses a `null` socket factory to create default sockets.

  Parameters:
    `serverHost` - the name of the server host
    `port` - the server port
  Returns:
    an `SslEndpoint` instance
  Throws:
    `IllegalArgumentException` - if `port` is less than or equal to `0`, or greater than `65535`
    `NullPointerException` - if `serverHost` is `null`

### getInstance

    public static SslEndpoint getInstance(String serverHost,
                                          int port,
                                          SocketFactory socketFactory)

  Returns a TLS/SSL endpoint for the specified server host, port, and socket factory. A `socketFactory` of `null` uses default sockets.

  Parameters:
    `serverHost` - the name of the server host
    `port` - the server port
    `socketFactory` - the socket factory, or `null`
  Returns:
    an `SslEndpoint` instance
  Throws:
    `IllegalArgumentException` - if `port` is less than or equal to `0`, or greater than `65535`
    `NullPointerException` - if `serverHost` is `null`

### getHost

    public String getHost()

  Returns the server host that this endpoint connects to.

  Returns:
    the server host that this endpoint connects to

### getPort

    public int getPort()

  Returns the TCP port that this endpoint connects to.

  Returns:
    the TCP port that this endpoint connects to

### getSocketFactory

    public SocketFactory getSocketFactory()

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

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

### toString

    public String toString()

  Returns a string representation of this object.

### 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 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.

### newRequest

    public OutboundRequestIterator newRequest(InvocationConstraints constraints)

  Returns an `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.

  If there is a security manager, the `next` method defined on the iterator returned by this method calls the security manager's `checkConnect` method with the endpoint's server host and port.

  Specified by:
    `newRequest` in interface `Endpoint`
  Parameters:
    `constraints` - the complete, absolute constraints
  Returns:
    an `OutboundRequestIterator` to use to send a new request to this remote endpoint
  Throws:
    `NullPointerException` - if `constraints` is `null`

### checkTrustEquivalence

    public 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.

  Specified by:
    `checkTrustEquivalence` in interface `TrustEquivalence`
  Parameters:
    `obj` - object to check that is not yet known to be trusted
  Returns:
    `true` 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

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