net.jini.jeri.ssl (Apache River v3.0.0 API Documentation)

Class Summary
Class	Description
ConfidentialityStrength	Represents a constraint that, if confidentiality of message contents is ensured, the specified strength of confidentiality be used.
HttpsEndpoint	An implementation of `Endpoint` that uses HTTPS (HTTP over TLS/SSL) to support invocation constraints for communication through firewalls.
HttpsServerEndpoint	An implementation of `ServerEndpoint` that uses HTTPS (HTTP over TLS/SSL) to support invocation constraints for communication through firewalls.
SslEndpoint	An implementation of `Endpoint` that uses TLS/SSL to support invocation constraints for direct communication over TCP sockets.
SslServerEndpoint	An implementation of `ServerEndpoint` that uses TLS/SSL to support invocation constraints for direct communication over TCP sockets.
SslTrustVerifier	Trust verifier for the `SslEndpoint`, `HttpsEndpoint`, and `ConfidentialityStrength` classes.

Package net.jini.jeri.ssl Description

Provides implementations of Endpoint and ServerEndpoint that use TLS/SSL and HTTPS (HTTP over TLS/SSL) to support invocation constraints.

The package includes two ServerEndpoint classes to support the server side of remote connections, SslServerEndpoint for direct communication over TCP sockets using TLS/SSL (Secure Socket Layer), and HttpsServerEndpoint for communication through firewalls using HTTPS (Hypertext Transfer Protocol encapsulated in the TLS/SSL protocol), with the associated Endpoint classes, SslEndpoint and HttpsEndpoint.

The package includes the ConfidentialityStrength constraint, supported by the endpoints in the package, for specifying requirements or preferences for weak or strong confidentiality on remote connections.

The package also includes the SslTrustVerifier trust verifier for establishing trust in remote proxies that use instances of the endpoint and constraint classes supplied in this package, as well as principals of type X500Principal.

Supported Constraints

The endpoint classes in this package support 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
ConnectionRelativeTime, trivially on the server side, 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 on the server side, 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 on the client side at higher levels, but should be converted to the associated absolute time constraints for use by the Endpoint classes.

Subject Authentication

The endpoint classes authenticate as a single Principal if the following items are present in the 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, the newRequest methods for the client endpoint classes 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.

Similarly, the server endpoint classes will only dispatch remote calls that authenticate as a given principal if the caller of listen on their 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.

These endpoint classes support 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.

If there is a security manager, the OutboundRequestIterator.next methods defined on the iterators returned by calling the newRequest methods on the client endpoints call the security manager's checkConnect method with the endpoint's server host and port.

Similarly, if there is a security manager, the checkPermissions and listen methods defined on ListenEndpoint instances returned by the server endpoints 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.

The host name specified when creating SslServerEndpoint or HttpsServerEndpoint instances controls the host name that will be contained in associated Endpoint instances produced when ServerEndpoint.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 endpoint 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.

The client and server endpoint classes permit specifying a SocketFactory for creating the Socket instances that client endpoints use to make remote connections back to the server. The server endpoints permit specifying 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 the endpoint classes 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 the server endpoint classes must implement Object.equals to obey the guidelines that are specified for equals methods of ListenEndpoint instances.

The HttpsEndpoint class recognizes the following system properties:

https.proxyHost - The host name for the secure proxy server. The default is to use no proxy server.
https.proxyPort - The port for the secure proxy server. The default is 443.
http.nonProxyHosts - The names of hosts for which direct connections should be made rather than using the proxy server. Each host name may contain '*' 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.

The SslEndpoint and SslServerEndpoint classes use the Jini extensible remote invocation (Jini ERI) multiplexing protocol to map outgoing requests to socket connections.

Since:

2.0

Version:

2.0

Implementation Specifics:

This implementation uses the Java(TM) Secure Socket Extension (JSSE).

This implementation uses the ConnectionManager and ServerConnectionManager classes to manage connections.

Loggers and Logging Levels

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

init - problems during initialization
client - information about client-side connections
server - information about server-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.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

**`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

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

**`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

See the LogManager class for one way to use the FAILED and HANDLED logging levels in standard logging configuration files.

Configuration

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 the endpoints use, through JSSE, to make decisions about what certificate chains should be trusted.

Both the TLS/SSL and HTTPS implementations recognize the following system properties:

org.apache.river.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.
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.

The following system properties are recognized by HTTPS implementation only:

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.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 org.apache.river.jeri.https.idleConnectionTimeout system property) plus 30000.
org.apache.river.jeri.https.responseAckTimeout - The number of milliseconds to wait for acknowledgments from AcknowledgmentSource instances, or to keep track of acknowledgements that have not yet been sent. 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).