# Overview

This API is intended for use by application developers who need to secure RMI communication for remote Java objects. Default socket factories employed by Java remote objects provide a non-secure implementation. If developers have remote objects which exchange sensitive data, there is a need to provide the capability to provide for secure communication with remote clients.

Java applications may also need to be able to control the level of security they provide to their consumer. Some applications may desire to fully secure their remote objects while others may not require remote object security. Others may fall somewhere in between where they need to secure some remote objects which exchange sensitive data and employ non-secure communications for other remote objects which do not represent a security risk. In summary, we may encounter the following scenarios:

- Secure all remote objects
- Do not secure any remote objects
- Secure some remote objects

When a Java remote object is exported to the RMI system, it may optionally designate the RMI client and/or server socket factories. Sun's default implementation is to employ non-secure sockets.

This API provides the capability for an application developer to designate that all or some of its remote objects use secure socket factories provided by Sun's Java Secure Socket Extension (JSSE) implementation. Note that JSSE is not available in some locales where banned by U.S. export policy.

The approach taken by this API is to permit an application's remote objects component to obtain its RMI socket factories from an instance of SSLRMISocketFactories. The default configuration is to not use secure sockets, but an application may enable security by initializing the `SSLRMISocketFactories` object with the desired SSL RMI configuration prior to executing any code which obtains socket factories. This configuration specifies the security mode (None, All, Some) and other parameters necessary to initialize an SSL context. Refer to the documentation for SSLRMIConfiguration for additional details.

Remote object implementations will then obtain its RMI client and server socket factories from the SSLRMISocketFactories instance. Socket factories may be obtained based upon their fully-qualified Java class name which provides the capability to selectively employ a secure socket factory implementation based upon the application's security needs. A default selection policy configuration is packaged with the sas.core.net.jar file, but may be overridden by an application if necessary. Refer to the documentation for SSLRMIConfiguration for additional details.

For example, if the selection policy configuration specifies that class com.sas.xxx.MyRemoteObject requires security then secure socket factories will be provided. If an explicit entry does not match the fully qualified class name, then a process is initiated whereby the suffix is dropped to obtain the parenting package name. A check is then made to determine if a selection policy is specified for this package. This process continues until either a policy is defined for a package or until there are no more packages to test.

## JRE Configuration

The Java Secure Socket Extension (JSSE) Reference Guide presents information from an application developer's perspective on securing Java remote objects.

In order to use SSL to secure RMI communication for remote Java objects, one must configure the JRE's key store and its trust store to meet the application's authentication needs. The two typical configuration scenarios and procedures necessary to configure the JRE are discussed in the Configuring the JRE for JSSE document.

## Notes

1. The Java Runtime Environment must include `jsse.jar` in order to use SSL.
2. SSL authentication may be applied selectively to classes based upon their fully-qualified Java class name. A default selection configuration (com/sas/net/ssl/sas_ssl_rmi_selection.config) is provided in the sas.core.net.jar file which contains the SSL RMI API implementation, but may be overridden if desired. If one has configured SSL to be applied selectively and wants to provide their own selection configuration then specify a file containing name/value pairs where the name is a fully qualified Java class or package name and its corresponding value is either "true" or "false" to indicate whether the class/package should be secured or not. If an explicit entry is not found for a particular class or package, then its parent package's rule will apply if defined. The first ancestor package rule that is defined will be used. Sample custom selection configuration configuration file
. Refer to the class documentation for SSLRMIConfiguration for a description of the selective control configuration file's syntax and additional usage examples.

## Related Information

- Java Security
- Review Sun's JSSE Reference Guide for additional details on secure sockets.
- Debugging SSL using the system property `javax.net.debug`