15 Configuring CSIv2

Introduction to CSIv2 Security Properties

CSIv2 is an Object Management Group (OMG) standard for a secure interoperable wire protocol that supports authorization and identity delegation. You configure CSIv2 properties in three different locations:

• internal-settings.xml (discussed in "CSIv2 Security Properties in internal-settings.xml")

• orion-ejb-jar.xml (discussed in "CSIv2 Security Properties in orion-ejb-jar.xml")

• ejb_sec.properties (discussed in "EJB Client Security Properties in ejb_sec.properties")

EJB Server Security Properties in internal-settings.xml

You specify server security properties in internal-settings.xml.

This file specifies certain properties as values within <sep-property> entities. Table 15-1 contains a list of properties.

The table refers to keystore and truststore files, which use the Java Key Store (JKS), a JDK-specified format, to store keys and certificates. A keystore stores a map of private keys and certificates. A truststore stores trusted certificates for the certificate authorities (CAs, such as VeriSign and Thawte).

Be aware of the following:

• If OC4J is started by the Oracle Process Management Notification service (OPMN) in an Oracle Application Server (as opposed to standalone) environment, then ports specified in internal-settings.xml are overridden. (Note that the IIOP SSL ports may fail to start if the keystore or truststore location or password is missing or incorrect. In such a case, you are advised to look at the log ORACLE_HOME/opmn/logs/OC4J-home-default_island-1 to see the exact nature of the failure.)

• If OPMN is configured to disable IIOP for a particular OC4J instance, then even though IIOP may be enabled through internal-settings.xml (as pointed to by server.xml), IIOP is not enabled.

• Keystore and truststore settings are supported in internal-settings.xml for both standalone OC4J and a full Oracle Application Server environment. In Oracle Application Server, there are no OPMN options to set these values, so they must be configured manually.

• When running in Oracle Application Server with OPMN, absolute path names are required for the keystore and truststore.

The following example shows an internal-settings.xml file:

<server-extension-provider name="IIOP"
        class="com.oracle.iiop.server.IIOPServerExtensionProvider">
    <sep-property name="port" value="5555" />
    <sep-property name="host" value="localhost" />
    <sep-property name="ssl" value="false" />
    <sep-property name="ssl-port" value="5556" />
    <sep-property name="ssl-client-server-auth-port" value="5557" />
    <sep-property name="keystore" value="keystore.jks" />
    <sep-property name="keystore-password" value="123456" />
    <sep-property name="truststore" value="truststore.jks" />
    <sep-property name="truststore-password" value="123456" />
    <sep-property name="trusted-clients" value="*" />
</server-extension-provider>

Here is the DTD for internal-settings.xml:

<!-- A server extension provider that is to be plugged in to the server. 
--> 
<!ELEMENT server-extension-provider (sep-property*) (#PCDATA)> 
<!ATTLIST server-extension-provider name class CDATA #IMPLIED>
<!ELEMENT sep-property (#PCDATA)> 
<!ATTLIST sep-property name value CDATA #IMPLIED>
<!-- This file contains internal server configuration settings. --> 
<!ELEMENT internal-settings (server-extension-provider*)>

CSIv2 Security Properties in internal-settings.xml

This section discusses the semantics of the values you set within the <sep-property> element in internal-settings.xml. Syntax is discussed in the previous section, "EJB Server Security Properties in internal-settings.xml".

To use the CSIv2 protocol with OC4J, you must both set ssl to "true" and specify an IIOP/SSL port (ssl-port).

• If you do not set ssl to "true", then CSIv2 is not enabled. Setting ssl to "true" permits clients and servers to use CSIv2, but does not require them to communicate using SSL.

• If you do not specify an ssl-port, then no CSIv2 component element is inserted by the server into the IOR, even if you configure an <ior-security-config> element in orion-ejb-jar.xml.

When IIOP/SSL is enabled on the server, OC4J listens on two different sockets—one for server authentication alone and one for server and client authentication. Specify the server authentication port within the <sep-property> element; the server and client authentication listener uses the port number immediately following.

For SSL clients using server authentication alone, you can specify any of the following:

• Truststore only

• Both keystore and truststore

• Neither

If you specify neither keystore nor truststore, the handshake may fail if there are no default truststores established by the security provider.

SSL clients using client-side authentication must specify both a keystore and a truststore. The certificate from the keystore is used for client authentication.

CSIv2 Security Properties in ejb_sec.properties

If the client does not use client-side SSL authentication, you must set client.sendpassword in the ejb_sec.properties file in order for the client runtime to insert a security context and send the user name and password. You must also set server.trustedhosts to include your server.

If the client does use client-side SSL authentication, the server extracts the DistinguishedName from the client certificate and then looks it up in the corresponding user manager; it does not perform password authentication.

CSIv2 Security Properties in orion-ejb-jar.xml

This section discusses the CSIv2 security properties for an EJB. You configure CSIv2 security policies for each individual bean in its orion-ejb-jar.xml. The CSIv2 security properties are specified within <ior-security-config> elements. Each element contains a <transport-config> element, an <as-context> element, and a <sas-context> element.

<!ELEMENT ior-security-config (transport-config?, as-context? 
sas-context?) >
<!ELEMENT transport-config (integrity, confidentiality, 
establish-trust-in-target, establish-trust-in-client) >
<!ELEMENT as-context (auth-method, realm, required) >
<!ELEMENT sas-context (caller-propagation) >
<!ELEMENT integrity (#PCDATA) > 
<!ELEMENT confidentiality (#PCDATA)> 
<!ELEMENT establish-trust-in-target (#PCDATA) > 
<!ELEMENT establish-trust-in-client (#PCDATA) >
<!ELEMENT auth-method (#PCDATA) > 
<!ELEMENT realm (#PCDATA) > 
<!ELEMENT required (#PCDATA)> <!-- Must be true or false --> 
<!ELEMENT caller-propagation (#PCDATA) >

<ior-security-config> 
  <transport-config> 
    <integrity>supported</integrity> 
    <confidentiality>supported</confidentiality> 
    <establish-trust-in-target>supported</establish-trust-in-target> 
    <establish-trust-in-client>supported</establish-trust-in-client> 
  </transport-config> 
  <as-context> 
    <auth-method>username_password</auth-method> 
    <realm>default</realm> 
    <required>true</required> 
  </as-context> 
  <sas-context> 
    <caller-propagation>supported</caller-propagation> 
  </sas-context> 
</ior-security-config> 

EJB Client Security Properties in ejb_sec.properties

Any client, whether running inside a server or not, has EJB security properties. Table 15-2 lists the EJB client security properties controlled by the ejb_sec.properties file. By default, OC4J searches for this file in the current directory when running as a client or in ORACLE_HOME/j2ee/instance_name/config when running in the server. You can specify the file location explicitly as follows:

-Dejb_sec_properties_location=pathname

TLS_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_MD5
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_RC4_40_MD5
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA