***  This class provides Binary Compatibility only, not Source Compatibility  ***

com.sas.net.ssl
Class SSLRMIConfiguration

com.sas.net.ssl.SSLRMIConfiguration
All Implemented Interfaces:
RMIExportConfiguration

public final class SSLRMIConfiguration
implements RMIExportConfiguration

Configuration that defines an application's preferences for securing Java remote objects using the Java Secure Sockets Extension (JSSE) API.

Overview

An SSL RMI configuration is defined by the following:

A table summarizing all property names and the property's legal values is presented in the configuration options section below.

Specifying SSL RMI Configuration Properties

An application must define a file that specifying the desired SSL RMI configuration properties. Typically the application will define a system property com.sas.net.ssl.configurationURL which specifies the URL to the configuration file.

 -Dcom.sas.net.ssl.configurationURL=file:/C:/xxx/sas_ssl_rmi_mode_all.config
 
and instantiating an instance of this class using is default constructor.

Alternatively, an application may instantiate this class providing the desired configuration using one of the following constructors: SSLRMIConfiguration(InputStream) or SSLRMIConfiguration(Properties)

Debugging SSL

Interactions with the JSSE API may be debugged by defining the system property javax.net.debug.

Operation Modes

SSL security may be applied to Java remote objects which obtain their socket factories from SSLRMISocketFactories using one of the following operation modes:

Mode Description
None SSL is not used to secure any Java remote objects.
All SSL is used to secure all remote objects that obtain their socket factories from SSLRMISocketFactories
Some SSL is selectively used to secure some remote objects based upon a preferences specified in a selection control configuration file which associates SSL preferences on a per-class or per-package basis. A default selection policy is provided by the sas.core.net.jar or an application may choose to use a customized selection policy.

Configuration Options

This section summarizes the properties, their meaning, and expected values.

Property Name Value
com.sas.net.ssl.mode Specify one of: [None | All | Some] where,
  • None if SSL should not be used for any classes
  • All if SSL should be used for all classes
  • Some if SSL should selectively be used for some classes

These values are case insensitive.

com.sas.net.ssl.protocol Specifies the SSLContext's protocol.
If unspecified, the protocol defaults to "SSL_TLS" for an "IBM Corporation" JVM or to "TLS" for non-IBM JVMs.
com.sas.net.ssl.isAuthenticatingClients Specify [true | false]
true if the server should authenticate clients
false otherwise.
The default is for the server to not authenticate clients.
com.sas.net.ssl.selectionConfigFile If the com.sas.net.ssl.mode specifies "Some", and one wishes to override the default selection policy, then one can use this property to specify a properties configuration file containing customized selection preferences.
Note that an application can also omit this property and use the updateSelectionPolicy(Properties) API to update the selection policy.
javax.net.ssl.keyStore An application that instantiates SSL secured remote objects must define their server's key store file
javax.net.ssl.keyStorePassword An application that instantiates SSL secured remote objects must define their server's key store file's password
javax.net.ssl.trustStore If the server is authenticating clients, then this property may optionally designate the server's trust store file. Do not specify this property if using the standard jssecacerts or cacerts trust store.
javax.net.ssl.trustStorePassword If the server is authenticating clients, this property may optionally designate the server's trust store file's password.
com.sas.net.rmi.platformPort Optional property which may be used to specify a positive integer representing a well-known port for RMI server sockets for cases when SSL is not employed.
com.sas.net.ssl.platformPort Optional property which may be used to specify a positive integer representing a well-known port for RMI server sockets for cases when SSL is employed.
com.sas.net.rmi.RMIServerSocketFactory Optional property which specifies the fully-qualified Java name of a class that implements an RMI server socket factory which should be used to create server sockets when SSL is not employed.
com.sas.net.rmi.RMIClientSocketFactory Optional property which specifies the fully-qualified Java name of a class that implements an RMI client socket factory which should be used to create sockets when SSL is not employed.

Notes:

Configuring Well-Known Ports

An application may be configured to export its Java RMI remote objects on a well-known port instead of an anonymous port. This capability may be used if an application is running behind a fire wall and one wants to grant an external client access to remote objects via a well-known opened port.

Remote objects which are not using an SSL RMI socket factory may be configured to use a well-known port by specifying the com.sas.net.rmi.platformPort system property.

-Dcom.sas.net.rmi.platformPort=6099

If remote objects are using an SSL RMI socket factory, then they may be configured to use a well-known port by specifying the com.sas.net.ssl.platformPort system property.

-Dcom.sas.net.ssl.platformPort=7099

Selection Policy Configuration

If an application is operating in a mode where SSL security is selectively being applied to Java remote objects, then the application may employ one of the following strategies to control whether security is employed.

Default Security Policy

A default selection policy file, packaged in the sas.core.net.jar provides controls to selectively secure only those classes for which security is recommended. This non-editable file provides the default selection policy. This policy will be used unless the application customizes the configuration using one of the following approaches.

Customized Security Policy

The default security policy recommendations may be overridden by designating an alternate selection policy configuration and/or using the API to update an SSL RMI configuration's selection policy.

Customize Security Policy specifying File

An application may elect to designate a customized security policy file using the SSL RMI configuration property PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE.

Customize Security Policy using API

The default selection policy may be customized by an application using either the updateSelectionPolicy(Properties selectionControlProperties) API. Invoking updateSelectionPolicy should be used to update the selection policy to include an application's custom policies. The default behavior is to permit an application to specify new policies, so long as they do not conflict with a previously defined preference which relaxes security. If one desires the application to always override pre-existing selection policies, then set the property PROPERTY_NAME_SSL_IS_OK_TO_RELAX_SELECTION_POLICY to true.

Socket Address Re-use

An application may optionally specify whether a socket can re-use its address by specifying either true or false for the following properties. When a socket is closed the operating system will time out the socket which can take several minutes. Enabling the socket to re-use its address will allow a connection to be bound without having to wait for the system to timeout to release the socket's address.

Sample Configuration Files

Sample configuration files are provided for the following use cases. A summary of supported properties is provide in the following section.

  1. configuration file that does not apply SSL to any remote objects
  2. configuration file that applies SSL to all remote objects
  3. selectively apply SSL to remote objects

It is envisioned that the typical usage scenario will be to just have the client authenticate the server, but if one also desires for the server to authenticate its clients, then add the following property to the configuration.

 com.sas.net.ssl.mutual.enabled = true
 
View the sample configuration file for an example that applies SSL to all remote objects and performs mutual authentication.

Since:
9.1.3

Field Summary
static java.lang.String PROPERTY_NAME_CLIENT_SOCKET_FACTORY_CLASS
          Name of an optional property which specifies the fully-qualified Java name of a class that implements an RMI client socket
static java.lang.String PROPERTY_NAME_IS_REUSE_SERVERSOCKET
          Name of the optional property used to specify whether a server socket can re-use its address.
static java.lang.String PROPERTY_NAME_IS_REUSE_SOCKET
          Name of the optional property used to specify whether a socket can re-use its address.
static java.lang.String PROPERTY_NAME_JSSE_KEYSTORE_FILE
          Name of the property designating the absolute path to a file containing the key store.
static java.lang.String PROPERTY_NAME_JSSE_KEYSTORE_PASSWORD
          Name of the property designating password used to access the key store.
static java.lang.String PROPERTY_NAME_JSSE_TRUSTSTORE_FILE
          Name of the optional property designating the absolute path to a file containing the trust store.
static java.lang.String PROPERTY_NAME_JSSE_TRUSTSTORE_PASSWORD
          Name of the optional property designating the password used to access the trust store.
static java.lang.String PROPERTY_NAME_PLATFORM_PORT
          Name of an optional property which may be used to specify a positive integer representing a well-known port on which RMI server sockets should be opened for cases when SSL is not employed.
static java.lang.String PROPERTY_NAME_SERVER_SOCKET_FACTORY_CLASS
          Name of an optional property which specifies the fully-qualified Java name of a class that implements an RMI server socket
static java.lang.String PROPERTY_NAME_SSL_IS_AUTHENTICATING_CLIENTS
          Name of the optional property designating whether a server application should authenticate its clients during SSL handshaking.
static java.lang.String PROPERTY_NAME_SSL_IS_OK_TO_RELAX_SELECTION_POLICY
          Name of the optional property that determines whether it is OK to relax a selection control policy.
static java.lang.String PROPERTY_NAME_SSL_MODE
          Name of the property designating the desired SSL mode for remote objects.
static java.lang.String PROPERTY_NAME_SSL_PLATFORM_PORT
          Name of an optional property which may be used to specify a positive integer representing a well-known port on which RMI server sockets should be opened for cases when SSL is employed.
static java.lang.String PROPERTY_NAME_SSL_PROTOCOL
          Name of the system property which can be used to specify the protocol for the SSLContext (e.g.
static java.lang.String PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE
          Name of the optional property used to designate a file which contains the controls which are to be used when applying SSL selectively.
static java.lang.String SSL_SELECTION_MODE_ALL
          Policy mode specifying that custom RMI socket factories should be used for all classes if custom socket factories are defined.
static java.lang.String SSL_SELECTION_MODE_NONE
          Policy mode specifying that custom RMI socket factories should not be used for any classes.
static java.lang.String SSL_SELECTION_MODE_SOME
          Policy mode specifying whether custom RMI socket factories should be used based upon the specified policy mappings.
static java.lang.String SYSTEM_PROPERTY_NAME_SSL_RMI_CONFIG_FILE_URL
          Name of a system property which may optionally define the URL to the SSL RMI configuration file which should override a configuration provided to initialize this object using either SSLRMIConfiguration(java.util.Properties) or SSLRMIConfiguration(java.io.InputStream).
 
Constructor Summary
SSLRMIConfiguration()
          Constructs a default instance of an SSL RMI configuration that does not secure any remote objects.
SSLRMIConfiguration(java.io.InputStream configurationInputStream)
          Constructs an SSL configuration considering the values specified in the properties file as well as the system environment.
SSLRMIConfiguration(java.util.Properties configurationProperties)
          Constructs an SSL configuration considering the values specified in the properties file as well as the system environment.
 
Method Summary
 int getPortForClass(int requestedPort, java.lang.Class javaClass)
          Gets the port which should be used to export the remote object.
 java.rmi.server.RMIClientSocketFactory getRMIClientSocketFactory()
          Gets the RMI client socket factory or null if the default factory should be used.
 java.rmi.server.RMIClientSocketFactory getRMIClientSocketFactoryForClass(java.lang.Class javaClass)
          Gets the RMI client socket factory based upon the class's name.
 java.rmi.server.RMIServerSocketFactory getRMIServerSocketFactory()
          Gets the custom RMI server socket factory or null if the default factory should be used.
 java.rmi.server.RMIServerSocketFactory getRMIServerSocketFactoryForClass(java.lang.Class javaClass)
          Gets the RMI server socket factory for a Java class.
 java.util.Map getSelectionPolicyMap()
          Gets a copy of the selection policy map that is used to determine the Java remote objects for which SSL security is recommended when operating in Some mode.
 void initializeUsingSystemProperty()
          Initializes the SSL RMI configuration by using an SSL RMI configuration file designated by a system property.
 boolean isAuthenticatingClients()
          Determines whether SSL authentication is required for the server to authenticate its clients.
 boolean isAuthenticatingServer()
          Determines whether SSL authentication is required for clients to authenticate the server.
 boolean isModeToSecureAll()
          Determines whether the mode is to secure all remote objects.
 boolean isModeToSecureNone()
          Determines whether the mode is to secure no remote objects.
 boolean isModeToSecureSome()
          Determines whether the mode is to secure some remote objects.
 boolean isOKToRelaxSelectionPolicy()
          Gets the preference indicating whether it is OK to relax a security recommendation in the selection policy.
 void setDefaultRMIClientSocketFactory(java.rmi.server.RMIClientSocketFactory rmiClientSocketFactory)
          Sets the RMI server socket factory.
 void setDefaultRMIServerSocketFactory(java.rmi.server.RMIServerSocketFactory rmiServerSocketFactory)
          Sets the RMI server socket factory.
 void updateSelectionPolicy(java.io.InputStream selectionControlInputStream)
          Specifies the properties that should be used to control whether a class should use a custom RMI socket factory.
 void updateSelectionPolicy(java.util.Properties selectionControlProperties)
          Specifies the properties that should be used to control whether a class should use a custom RMI socket factory.
 

Field Detail

PROPERTY_NAME_SSL_MODE

public static final java.lang.String PROPERTY_NAME_SSL_MODE
Name of the property designating the desired SSL mode for remote objects.

Value Control Mode
None SSL authentication will not be used for any remote objects
All SSL authentication will be used for all remote objects
Some SSL authentication will be used selectively for some remote objects deemed to require secure data transmission

If the mode is set to the value "Some", then SSL authentication, by default, will be selectively applied to classes as specified in a default selection policy file that is provided by the sas.core.net.jar. If use of this default selection policy file meets your needs do not define this property.

However, if you wish to override the default controls, then define the location of the controls configuration file using a property named "com.sas.net.ssl.selectionConfigFile".

See Also:
PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE, Constant Field Values

PROPERTY_NAME_PLATFORM_PORT

public static final java.lang.String PROPERTY_NAME_PLATFORM_PORT
Name of an optional property which may be used to specify a positive integer representing a well-known port on which RMI server sockets should be opened for cases when SSL is not employed. If this property is specified and the caller requests an anonymous port, then the well-known port will be used instead.

See Also:
Constant Field Values

PROPERTY_NAME_SSL_PLATFORM_PORT

public static final java.lang.String PROPERTY_NAME_SSL_PLATFORM_PORT
Name of an optional property which may be used to specify a positive integer representing a well-known port on which RMI server sockets should be opened for cases when SSL is employed. If this property is specified and the caller requests an anonymous port and an SSL socket factory is configured, then the well-known port will be used instead.

See Also:
Constant Field Values

PROPERTY_NAME_SERVER_SOCKET_FACTORY_CLASS

public static final java.lang.String PROPERTY_NAME_SERVER_SOCKET_FACTORY_CLASS
Name of an optional property which specifies the fully-qualified Java name of a class that implements an RMI server socket factory. For example, -Dcom.sas.net.rmi.RMIServerSocketFactory=com.acme.MyRMIServerSocketFactory

Note that this property is only used if the mode specified by PROPERTY_NAME_SSL_MODE is set to None or Some and the requested class is not configured to be secured using SSL.

See Also:
PROPERTY_NAME_SSL_MODE, PROPERTY_NAME_CLIENT_SOCKET_FACTORY_CLASS, Constant Field Values

PROPERTY_NAME_CLIENT_SOCKET_FACTORY_CLASS

public static final java.lang.String PROPERTY_NAME_CLIENT_SOCKET_FACTORY_CLASS
Name of an optional property which specifies the fully-qualified Java name of a class that implements an RMI client socket factory. For example, -Dcom.sas.net.rmi.RMIClientSocketFactory=com.acme.MyRMIClientSocketFactory

Note that this property is only used if the mode specified by PROPERTY_NAME_SSL_MODE is set to None or Some and the requested class is not configured to be secured using SSL.

See Also:
PROPERTY_NAME_SSL_MODE, PROPERTY_NAME_SERVER_SOCKET_FACTORY_CLASS, Constant Field Values

PROPERTY_NAME_SSL_IS_AUTHENTICATING_CLIENTS

public static final java.lang.String PROPERTY_NAME_SSL_IS_AUTHENTICATING_CLIENTS
Name of the optional property designating whether a server application should authenticate its clients during SSL handshaking.

This property should be set to either true or false. Setting this property to any value other than true will be interpreted as a false. If this property is not specified then the server will not authenticate its clients.

See Also:
Constant Field Values

PROPERTY_NAME_JSSE_KEYSTORE_FILE

public static final java.lang.String PROPERTY_NAME_JSSE_KEYSTORE_FILE
Name of the property designating the absolute path to a file containing the key store.

Instead of specifying this property in the services deployment properties file, one may specify it as a system environment variable (i.e. -Djavax.net.ssl.keyStore=C:/xxx/keyStore).

See Also:
Constant Field Values

PROPERTY_NAME_JSSE_KEYSTORE_PASSWORD

public static final java.lang.String PROPERTY_NAME_JSSE_KEYSTORE_PASSWORD
Name of the property designating password used to access the key store.

Instead of specifying this property in the services deployment properties file, one may specify it as a system environment variable (i.e. -Djavax.net.ssl.keyStorePassword=Xxx).

See Also:
Constant Field Values

PROPERTY_NAME_JSSE_TRUSTSTORE_FILE

public static final java.lang.String PROPERTY_NAME_JSSE_TRUSTSTORE_FILE
Name of the optional property designating the absolute path to a file containing the trust store. Note that this property does not need to be defined if one is using a default trust store provided by the JRE (i.e. "lib/security/cacerts" or "lib/security/jssecacerts").

Instead of specifying this property in the services deployment properties file, one may specify it as a system environment variable (i.e. -Djavax.net.ssl.trustStore=C:/xxx/trustStore).

See Also:
Constant Field Values

PROPERTY_NAME_JSSE_TRUSTSTORE_PASSWORD

public static final java.lang.String PROPERTY_NAME_JSSE_TRUSTSTORE_PASSWORD
Name of the optional property designating the password used to access the trust store. A password should be specified if one desires verification of the trust store.

Instead of specifying this property in the services deployment properties file, one may specify it as a system environment variable (i.e. -Djavax.net.ssl.trustStorePassword=Yyy).

See Also:
Constant Field Values

PROPERTY_NAME_SSL_IS_OK_TO_RELAX_SELECTION_POLICY

public static final java.lang.String PROPERTY_NAME_SSL_IS_OK_TO_RELAX_SELECTION_POLICY
Name of the optional property that determines whether it is OK to relax a selection control policy. This property should be assigned a value of true if it is OK to relax a security preference or false if it is invalid to toggle a setting from requiring security to not requiring security.

See Also:
PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE, Constant Field Values

PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE

public static final java.lang.String PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE
Name of the optional property used to designate a file which contains the controls which are to be used when applying SSL selectively.

A default selection control file is packaged in this class's .jar file. Selection configuration preferences specified in this file may be overridden by specifying a custom selection control file if desired.

See Also:
PROPERTY_NAME_SSL_MODE, Constant Field Values

PROPERTY_NAME_SSL_PROTOCOL

public static final java.lang.String PROPERTY_NAME_SSL_PROTOCOL
Name of the system property which can be used to specify the protocol for the SSLContext (e.g. "TLS", "SSL", "SSL_TLS", etc.).

See Also:
Constant Field Values

PROPERTY_NAME_IS_REUSE_SERVERSOCKET

public static final java.lang.String PROPERTY_NAME_IS_REUSE_SERVERSOCKET
Name of the optional property used to specify whether a server socket can re-use its address.

See Also:
PROPERTY_NAME_IS_REUSE_SOCKET, Constant Field Values

PROPERTY_NAME_IS_REUSE_SOCKET

public static final java.lang.String PROPERTY_NAME_IS_REUSE_SOCKET
Name of the optional property used to specify whether a socket can re-use its address.

See Also:
PROPERTY_NAME_IS_REUSE_SERVERSOCKET, Constant Field Values

SSL_SELECTION_MODE_NONE

public static final java.lang.String SSL_SELECTION_MODE_NONE
Policy mode specifying that custom RMI socket factories should not be used for any classes.

Specifies that all classes should use custom RMI socket factories if defined. This is the default policy.

See Also:
SSL_SELECTION_MODE_ALL, SSL_SELECTION_MODE_SOME, Constant Field Values

SSL_SELECTION_MODE_ALL

public static final java.lang.String SSL_SELECTION_MODE_ALL
Policy mode specifying that custom RMI socket factories should be used for all classes if custom socket factories are defined.

See Also:
SSL_SELECTION_MODE_NONE, SSL_SELECTION_MODE_SOME, Constant Field Values

SSL_SELECTION_MODE_SOME

public static final java.lang.String SSL_SELECTION_MODE_SOME
Policy mode specifying whether custom RMI socket factories should be used based upon the specified policy mappings.

A default selection mapping is provided, but may be overridden if desired by designating an alternate security recommendation configuration file using the PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE property.

See Also:
SSL_SELECTION_MODE_NONE, SSL_SELECTION_MODE_SOME, Constant Field Values

SYSTEM_PROPERTY_NAME_SSL_RMI_CONFIG_FILE_URL

public static final java.lang.String SYSTEM_PROPERTY_NAME_SSL_RMI_CONFIG_FILE_URL
Name of a system property which may optionally define the URL to the SSL RMI configuration file which should override a configuration provided to initialize this object using either SSLRMIConfiguration(java.util.Properties) or SSLRMIConfiguration(java.io.InputStream).

For example one might define a properties configuration file using a URL like "file:/C:/xxx/sas_ssl_rmi_mode_all.config".

See Also:
Constant Field Values
Constructor Detail

SSLRMIConfiguration

public SSLRMIConfiguration()
Constructs a default instance of an SSL RMI configuration that does not secure any remote objects.

Use SSLRMIConfiguration(Properties) to construct a configuration using a properties object or SSLRMIConfiguration(InputStream) to construct a configuration using an input stream to the desired configuration.

Use initializeUsingSystemProperty() to reconfigure an instance instantiated with this default constructor if one desires to employ an SSL RMI configuration specified by the system property SYSTEM_PROPERTY_NAME_SSL_RMI_CONFIG_FILE_URL.


SSLRMIConfiguration

public SSLRMIConfiguration(java.io.InputStream configurationInputStream)
                    throws SSLRMIConfigurationException,
                           java.lang.IllegalArgumentException
Constructs an SSL configuration considering the values specified in the properties file as well as the system environment.

Note that if a system property SYSTEM_PROPERTY_NAME_SSL_RMI_CONFIG_FILE_URL is defined it will override the configuration input stream passed into this method.

Parameters:
configurationInputStream - Input stream to an SSL RMI configuration. Note that this input stream will be closed after the properties have been loaded.
Throws:
SSLRMIConfigurationException - if unable to initialize a configuration from the specified input stream.
java.lang.IllegalArgumentException - if an invalid parameter is specified such as an invalid input stream or an inability to load properties from the specified input stream.

SSLRMIConfiguration

public SSLRMIConfiguration(java.util.Properties configurationProperties)
                    throws SSLRMIConfigurationException,
                           java.lang.IllegalArgumentException
Constructs an SSL configuration considering the values specified in the properties file as well as the system environment.

Parameters:
configurationProperties - SSL RMI configuration properties.
Throws:
SSLRMIConfigurationException - if unable to initialize a configuration from the specified properties.
java.lang.IllegalArgumentException - if an invalid configuration is specified.
Method Detail

updateSelectionPolicy

public void updateSelectionPolicy(java.io.InputStream selectionControlInputStream)
                           throws SSLRMIConfigurationException,
                                  java.lang.IllegalArgumentException
Specifies the properties that should be used to control whether a class should use a custom RMI socket factory. Each property name represents a fully-qualified Java class or package name. Its corresponding value should be either "true" or "false" to indicate whether custom RMI socket factories should be used.

For example, consider the following configuration:

 com.sas.services=false
 com.sas.services.authentication=true
 com.sas.services.user=false
 com.sas.services.user.UserService=true
 com.sas.services.user.UserContext=true
 

This configuration would not employ SSL authentication for classes in packages com.sas.services and com.sas.services.user, but would employ SSL for the UserService and UserContext classes since they've been explicitly enabled.

All classes in package com.sas.services.authentication and any of its sub-packages would employ SSL authentication unless they explicitly declare a false entry for a class wishing to be excluded.

Logic will attempt to match a specified class name and if a control has been specified it will be used. If no control has been defined for the class, then its package will be checked next. This process will repeat until a control matching a package has been met or until all parenting packages have been checked.

Parameters:
selectionControlInputStream - Input stream to a properties configuration that defines name/value pairs where the name represents the fully qualified Java class or package and the value is a String whose value is either "true" or "false" indicating whether custom socket factories should be used. These selection preferences determine whether a an SSL RMI socket factory is used when one asks for a socket factory based upon a class name.

The input stream will be closed by this method.

Throws:
SSLRMIConfigurationException - if unable to process the selection control policy defined by the input stream or if an attempt is made to relax security when not permitted. Consult the exception's root cause for more details.
  • IOException if unable to process the input stream successfully.
java.lang.IllegalArgumentException - if an invalid parameter is specified. A non-null input stream object referencing selection policy controls is required. The selection policy defines name/value pairs where the name represents the fully qualified Java class or package and the value is a String whose value is either "true" or "false" indicating whether custom socket factories should be used. Any value other than "true" will be interpreted as "false".
See Also:
getRMIClientSocketFactoryForClass(Class), getRMIServerSocketFactoryForClass(Class)

updateSelectionPolicy

public void updateSelectionPolicy(java.util.Properties selectionControlProperties)
                           throws SSLRMIConfigurationException,
                                  java.lang.IllegalArgumentException
Specifies the properties that should be used to control whether a class should use a custom RMI socket factory. Each property name represents a fully-qualified Java class or package name. Its corresponding value should be either "true" or "false" to indicate whether custom RMI socket factories should be used.

For example, consider the following configuration:

 com.sas.services=false
 com.sas.services.authentication=true
 com.sas.services.user=false
 com.sas.services.user.UserService=true
 com.sas.services.user.UserContext=true
 

This configuration would not employ SSL authentication for classes in packages com.sas.services and com.sas.services.user, but would employ SSL for the UserService and UserContext classes since they've been explicitly enabled.

All classes in package com.sas.services.authentication and any of its sub-packages would employ SSL authentication unless they explicitly declare a false entry for a class wishing to be excluded.

Logic will attempt to match a specified class name and if a control has been specified it will be used. If no control has been defined for the class, then its package will be checked next. This process will repeat until a control matching a package has been met or until all parenting packages have been checked.

Parameters:
selectionControlProperties - Properties which will be used to selectively control whether a custom RMI socket factory is used when one asks for a socket factory based upon a class name.
Throws:
SSLRMIConfigurationException - if an attempt is made to relax a security control preference for a class for which security is recommended. This exception is only possible in the case where the parameter "isOKToOverridePreferenceToSecure" is set to false.
java.lang.IllegalArgumentException - if an invalid parameter is specified. A Non-null properties object containing name/value pairs where the name represents the fully qualified Java class or package and the value is a String whose value is either "true" or "false" indicating whether custom socket factories should be used.
See Also:
getRMIClientSocketFactoryForClass(Class), getRMIServerSocketFactoryForClass(Class)

getRMIClientSocketFactory

public java.rmi.server.RMIClientSocketFactory getRMIClientSocketFactory()
Gets the RMI client socket factory or null if the default factory should be used.

Specified by:
getRMIClientSocketFactory in interface RMIExportConfiguration
Returns:
Returns the RMI client socket factory or null if the default client socket factory should be used.
See Also:
RMIExportConfiguration.getRMIClientSocketFactoryForClass(Class)

getRMIClientSocketFactoryForClass

public java.rmi.server.RMIClientSocketFactory getRMIClientSocketFactoryForClass(java.lang.Class javaClass)
Gets the RMI client socket factory based upon the class's name.

Mode Behavior
None always returns a null socket factory indicating that the default should be used
All always returns the custom socket factory, regardless of the control policy
Some a socket factory will be returned considering the settings in the control policy

Specified by:
getRMIClientSocketFactoryForClass in interface RMIExportConfiguration
Parameters:
javaClass - The Java class for which an RMI client socket factory is desired.
Returns:
Returns the RMI client socket factory or null if the default factory should be used.
Throws:
java.lang.IllegalArgumentException - if a null Java class name is specified.
See Also:
RMIExportConfiguration.getRMIClientSocketFactory()

getRMIServerSocketFactory

public java.rmi.server.RMIServerSocketFactory getRMIServerSocketFactory()
Gets the custom RMI server socket factory or null if the default factory should be used.

Specified by:
getRMIServerSocketFactory in interface RMIExportConfiguration
Returns:
Returns an RMI server socket factory or null if the default factory should be used.
See Also:
RMIExportConfiguration.getRMIServerSocketFactoryForClass(Class)

getRMIServerSocketFactoryForClass

public java.rmi.server.RMIServerSocketFactory getRMIServerSocketFactoryForClass(java.lang.Class javaClass)
Gets the RMI server socket factory for a Java class.

Mode Behavior
None always returns a null socket factory indicating that the default should be used
All always returns the custom socket factory, regardless of the control policy
Some a socket factory will be returned considering the settings in the control policy

Specified by:
getRMIServerSocketFactoryForClass in interface RMIExportConfiguration
Parameters:
javaClass - The Java class for which an RMI server socket factory is desired.
Returns:
Returns the RMI server socket factory or null if the default factory should be used.
Throws:
java.lang.IllegalArgumentException - if a null Java class is specified.
See Also:
RMIExportConfiguration.getRMIServerSocketFactory()

getSelectionPolicyMap

public java.util.Map getSelectionPolicyMap()
Gets a copy of the selection policy map that is used to determine the Java remote objects for which SSL security is recommended when operating in Some mode.

Returns:
A copy of the selection policy map that is used to determine the Java remote objects for which SSL security is recommended. This map is keyed by the String Java class name to a Boolean value indicating whether SSL security is recommended. For example, one might have a key "com.sas.services.UserService" representing the fully-qualified class name for the User Service remote object and an associated value of either Boolean.TRUE or Boolean.FALSE. A non-null map will be returned.

isModeToSecureNone

public boolean isModeToSecureNone()
Determines whether the mode is to secure no remote objects.

Returns:
true if not securing any remote objects.

isModeToSecureAll

public boolean isModeToSecureAll()
Determines whether the mode is to secure all remote objects.

Returns:
true if securing all remote objects.

isModeToSecureSome

public boolean isModeToSecureSome()
Determines whether the mode is to secure some remote objects.

Returns:
true if securing some remote objects.

initializeUsingSystemProperty

public void initializeUsingSystemProperty()
                                   throws SSLRMIException
Initializes the SSL RMI configuration by using an SSL RMI configuration file designated by a system property. The system property com.sas.net.ssl.configurationURL must be defined to specify the URL to the desired SSL RMI configuration file. An example illustrating this usage scenario is provided.

Throws:
SSLRMIException - if a system property com.sas.net.ssl.configurationURL designates an invalid configuration or if the system property is undefined.

setDefaultRMIServerSocketFactory

public void setDefaultRMIServerSocketFactory(java.rmi.server.RMIServerSocketFactory rmiServerSocketFactory)
                                      throws SSLRMIConfigurationException
Sets the RMI server socket factory. If the system property PROPERTY_NAME_SERVER_SOCKET_FACTORY_CLASS is set, then it will override the specified socket factory.

Parameters:
rmiServerSocketFactory - RMI server socket factory or null if the default socket factory should be used.
Throws:
SSLRMIConfigurationException - if unable to set the RMI server socket factory.

setDefaultRMIClientSocketFactory

public void setDefaultRMIClientSocketFactory(java.rmi.server.RMIClientSocketFactory rmiClientSocketFactory)
                                      throws SSLRMIConfigurationException
Sets the RMI server socket factory. If the system property PROPERTY_NAME_CLIENT_SOCKET_FACTORY_CLASS is set, then it will override the specified socket factory.

Parameters:
rmiClientSocketFactory - RMI client socket factory or null if the default socket factory should be used.
Throws:
SSLRMIConfigurationException - if unable to set the RMI client socket factory.

isAuthenticatingClients

public boolean isAuthenticatingClients()
Determines whether SSL authentication is required for the server to authenticate its clients.

Returns:
true if the server is required to authenticate its clients.
See Also:
isAuthenticatingServer()

isAuthenticatingServer

public boolean isAuthenticatingServer()
Determines whether SSL authentication is required for clients to authenticate the server.

Returns:
true if the client is required to authenticate the server.
See Also:
isAuthenticatingClients()

isOKToRelaxSelectionPolicy

public boolean isOKToRelaxSelectionPolicy()
Gets the preference indicating whether it is OK to relax a security recommendation in the selection policy.

Returns:
true if one is permitted to update the selection policy to change a security recommendation from true to false.

getPortForClass

public int getPortForClass(int requestedPort,
                           java.lang.Class javaClass)
Gets the port which should be used to export the remote object.

Specified by:
getPortForClass in interface RMIExportConfiguration
Parameters:
requestedPort - The port requested by the caller. An anonymous port may be requested by specifying a value of 0.
javaClass - The Java class for which an export port is desired or null if a default non-SSL server port is desired.
Returns:
The requested port or the platform port if an anonymous port was requested and a platform port is defined.

***  This class provides Binary Compatibility only, not Source Compatibility  ***




Copyright © 2009 SAS Institute Inc. All Rights Reserved.