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

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

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

- `PROPERTY_NAME_IS_REUSE_SERVERSOCKET`
- `PROPERTY_NAME_IS_REUSE_SOCKET`

## 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
   - 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 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 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".
  See Also:
    `getRMIClientSocketFactoryForClass(Class)`, `getRMIServerSocketFactoryForClass(Class)`

### updateSelectionPolicy

    public final void updateSelectionPolicy(java.util.Properties selectionControlProperties)
                                     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:
    `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

  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

Copyright © 2009 SAS Institute Inc. All Rights Reserved.