SSLRMIConfiguration (SAS AppDevStudio API Developer Documentation for Java)

Operation mode which defines whether SSL security is to be applied to Java remote objects which obtain their socket factories from SSLRMISocketFactories
Whether or not the server should authenticate its clients
An optional custom selection policy configuration file which an application would use to override default selection policies.
JSSE properties
- key store and its password
- trust store if not using a JRE default trust store (jre/lib/security/jssecacerts or jre/lib/security/cacerts)
- Trust store's password if verifying the integrity of the trust store

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:

all properties may be defined using system properties (i.e. -Djavax.net.ssl.keyStorePassword=TheKeyStorePassword)
system properties take precedence over any properties defined in a configuration file
all properties whose name is prefixed by "javax.net.ssl" are standard JSSE properties

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

use the default security policy

customize the default security policy

specify a customized selection policy file
use the API to customize the selection policy

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.

using a custom properties configuration
using the API

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.

configuration file that does not apply SSL to any remote objects
configuration file that applies SSL to all remote objects
selectively apply SSL to remote objects
- using the default configuration file
- using a custom configuration file and overriding the default selection policy with a selection policy configuration file specified by the end-user.

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 or not 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 or not a class should use a custom RMI socket factory.

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 or not 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 or not 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

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 final void updateSelectionPolicy(java.io.InputStream selectionControlInputStream)
                                 throws SSLRMIConfigurationException,
                                        java.lang.IllegalArgumentException

Specifies the properties that should be used to control whether or not 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".

updateSelectionPolicy

public final void updateSelectionPolicy(java.util.Properties selectionControlProperties)
                                 throws SSLRMIConfigurationException,
                                        java.lang.IllegalArgumentException

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

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.

Parameters:: selectionControlProperties - Properties which will be used to selectively control whether or not 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 final 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 final 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

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 final 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 final 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 final 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 final boolean isModeToSecureNone()

Determines whether the mode is to secure no remote objects.

Returns:: true if not securing any remote objects.

isModeToSecureAll

public final boolean isModeToSecureAll()

Determines whether the mode is to secure all remote objects.

Returns:: true if securing all remote objects.

isModeToSecureSome

public final boolean isModeToSecureSome()

Determines whether the mode is to secure some remote objects.

Returns:: true if securing some remote objects.

initializeUsingSystemProperty

public final 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 final 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 final 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 final 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 final 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 final 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 final 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 ***

All Libraries

This Library

Package

Class

Use

Tree

Deprecated

Index

Grand Index

Help

Components

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.sas.net.ssl Class SSLRMIConfiguration

Overview

Specifying SSL RMI Configuration Properties

Debugging SSL

Operation Modes

Configuration Options

Configuring Well-Known Ports

Selection Policy Configuration

Default Security Policy

Customized Security Policy

Customize Security Policy specifying File

Customize Security Policy using API

Socket Address Re-use

Sample Configuration Files

PROPERTY_NAME_SSL_MODE

PROPERTY_NAME_PLATFORM_PORT

PROPERTY_NAME_SSL_PLATFORM_PORT

PROPERTY_NAME_SERVER_SOCKET_FACTORY_CLASS

PROPERTY_NAME_CLIENT_SOCKET_FACTORY_CLASS

PROPERTY_NAME_SSL_IS_AUTHENTICATING_CLIENTS

PROPERTY_NAME_JSSE_KEYSTORE_FILE

PROPERTY_NAME_JSSE_KEYSTORE_PASSWORD

PROPERTY_NAME_JSSE_TRUSTSTORE_FILE

PROPERTY_NAME_JSSE_TRUSTSTORE_PASSWORD

PROPERTY_NAME_SSL_IS_OK_TO_RELAX_SELECTION_POLICY

PROPERTY_NAME_SSL_SELECTION_CONFIG_FILE

PROPERTY_NAME_SSL_PROTOCOL

PROPERTY_NAME_IS_REUSE_SERVERSOCKET

PROPERTY_NAME_IS_REUSE_SOCKET

SSL_SELECTION_MODE_NONE

SSL_SELECTION_MODE_ALL

SSL_SELECTION_MODE_SOME

SYSTEM_PROPERTY_NAME_SSL_RMI_CONFIG_FILE_URL

SSLRMIConfiguration

SSLRMIConfiguration

SSLRMIConfiguration

updateSelectionPolicy

updateSelectionPolicy

getRMIClientSocketFactory

getRMIClientSocketFactoryForClass

getRMIServerSocketFactory

getRMIServerSocketFactoryForClass

getSelectionPolicyMap

isModeToSecureNone

isModeToSecureAll

isModeToSecureSome

initializeUsingSystemProperty

setDefaultRMIServerSocketFactory

setDefaultRMIClientSocketFactory

isAuthenticatingClients

isAuthenticatingServer

isOKToRelaxSelectionPolicy

getPortForClass

com.sas.net.ssl
Class SSLRMIConfiguration