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

The package includes the {@link net.jini.jeri.ssl.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 {@link net.jini.jeri.ssl.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

• {@link net.jini.core.constraint.ClientAuthentication}
• {@link net.jini.core.constraint.ClientMaxPrincipal}, when it contains an {@link javax.security.auth.x500.X500Principal}
• {@link net.jini.core.constraint.ClientMaxPrincipalType}, when it contains X500Principal
• {@link net.jini.core.constraint.ClientMinPrincipal}, when it contains a single X500Principal only
• {@link net.jini.core.constraint.ClientMinPrincipalType}, when it contains X500Principal only
• {@link net.jini.core.constraint.Confidentiality}
• {@link net.jini.jeri.ssl.ConfidentialityStrength}, a provider-specific constraint for specifying weak or strong confidentiality
• {@link net.jini.core.constraint.ConnectionAbsoluteTime}
• {@link net.jini.core.constraint.ConnectionRelativeTime}, trivially on the server side, since this only takes effect on the client side
• {@link net.jini.core.constraint.ConstraintAlternatives}, if the elements all have the same actual class and at least one element is supported
• {@link net.jini.core.constraint.Delegation#NO}
• {@link net.jini.core.constraint.Delegation#YES}, trivially, for anonymous clients
• {@link net.jini.core.constraint.DelegationAbsoluteTime}, trivially, when delegation is not supported
• {@link net.jini.core.constraint.DelegationRelativeTime}, trivially on the server side, when delegation is not supported
• {@link net.jini.core.constraint.Integrity#YES}
• {@link net.jini.core.constraint.ServerAuthentication}
• {@link net.jini.core.constraint.ServerMinPrincipal}, when it contains a single X500Principal only

Note that {@link net.jini.core.constraint.ConnectionRelativeTime} and {@link net.jini.core.constraint.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

• One or more principals of type X500Principal
• For each principal, one or more certificate chains, stored as public credentials, and represented by instances of {@link java.security.cert.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 {@link javax.security.auth.x500.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 {@link net.jini.jeri.Endpoint#newRequest newRequest} methods for the client endpoint classes will only authenticate as a given principal if the caller has been granted {@link net.jini.security.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 {@link net.jini.jeri.ServerEndpoint.ListenEndpoint#listen listen} on their {@link net.jini.jeri.ServerEndpoint.ListenEndpoint 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 {@link net.jini.core.constraint.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 {@link net.jini.jeri.OutboundRequestIterator#next OutboundRequestIterator.next} methods defined on the iterators returned by calling the {@link net.jini.jeri.Endpoint#newRequest newRequest} methods on the client endpoints call the security manager's {@link java.lang.SecurityManager#checkConnect checkConnect} method with the endpoint's server host and port.

Similarly, if there is a security manager, the {@link net.jini.jeri.ServerEndpoint.ListenEndpoint#checkPermissions checkPermissions} and {@link net.jini.jeri.ServerEndpoint.ListenEndpoint#listen listen} methods defined on ListenEndpoint instances returned by the server endpoints call the security manager's {@link java.lang.SecurityManager#checkListen 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 {@link net.jini.jeri.ServerEndpoint#enumerateListenEndpoints 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 {@link java.net.InetAddress} returned by {@link java.net.InetAddress#getLocalHost InetAddress.getLocalHost} when enumerateListenEndpoints is invoked.

The client and server endpoint classes permit specifying a {@link javax.net.SocketFactory} for creating the {@link java.net.Socket} instances that client endpoints use to make remote connections back to the server. The server endpoints permit specifying a {@link javax.net.ServerSocketFactory} for creating the {@link java.net.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 {@link javax.net.ssl.SSLSocketFactory} and {@link javax.net.ssl.SSLServerSocketFactory} should not be used, and the factories used should not return instances of {@link javax.net.ssl.SSLSocket} or {@link javax.net.ssl.SSLServerSocket}.

A SocketFactory used with instances of the endpoint classes should be serializable, and must implement {@link java.lang.Object#equals Object.equals} to obey the guidelines that are specified for equals methods of {@link net.jini.jeri.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 {@link net.jini.jeri.ServerEndpoint.ListenEndpoint 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.

This implementation uses the {@link net.jini.jeri.connection.ConnectionManager} and {@link net.jini.jeri.connection.ServerConnectionManager} classes to manage connections.

Loggers and Logging Levels

This implementation uses the following {@link java.util.logging.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
{@link java.util.logging.Level#WARNING WARNING}	problems with initializing JSSE or with registering internal entry points with discovery providers

net.jini.jeri.ssl.client

Level	Description
{@link org.apache.river.logging.Levels#FAILED FAILED}	problems with outbound requests
{@link org.apache.river.logging.Levels#HANDLED HANDLED}	exceptions caught involving authentication
{@link java.util.logging.Level#FINE FINE}	authentication decisions; creating, choosing, expiring, or closing connections; or handling outbound requests
{@link java.util.logging.Level#FINEST FINEST}	low level operation tracing

net.jini.jeri.ssl.server

Level	Description
{@link java.util.logging.Level#INFO INFO}	problems with accepting or handling server connections, or with handling inbound requests
{@link org.apache.river.logging.Levels#FAILED FAILED}	problems with checking constraints or permissions, with enumerating listen endpoints, or with security issues for inbound requests
{@link org.apache.river.logging.Levels#HANDLED HANDLED}	exceptions caught involving authentication
{@link java.util.logging.Level#FINE FINE}	creating server endpoints, enumerating listen endpoints, creating or closing connections or listen handles, or checking constraints for endpoints or inbound requests
{@link java.util.logging.Level#FINEST FINEST}	low level operation tracing

See the {@link org.apache.river.logging.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:

• {@link javax.net.ssl.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 {@link javax.net.ssl.SSLContext#init SSLContext.init} method is called with null for the random parameter to use the default {@link java.security.SecureRandom} implementation.
• {@link java.security.cert.CertificateFactory}, with type "X.509", to generate CertPath instances from X.509 certificate chains
• {@link javax.net.ssl.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 {@link javax.net.ssl.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 {@link javax.net.ssl.SSLContext} instances. The default is "TLS".
• org.apache.river.jeri.ssl.trustManagerFactoryAlgorithm - The algorithm used when obtaining {@link javax.net.ssl.TrustManagerFactory} instances. The default is the value returned by {@link javax.net.ssl.TrustManagerFactory#getDefaultAlgorithm 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 {@link net.jini.io.context.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).