Skip Headers

Oracle® Application Server Containers for J2EE Security Guide 10g Release 2 (10.1.2) B14013-02 |
| Library | Product | Contents | Index

Previous | Next |

# 15 Configuring CSIv2

OC4J supports the Common Secure Interoperability Version 2 protocol (CSIv2). CSIv2 specifies different conformance levels; OC4J complies with the EJB specification, which requires conformance level 0.

This chapter covers the following topics:

- Introduction to CSIv2 Security Properties

- EJB Server Security Properties in internal-settings.xml

- CSIv2 Security Properties in internal-settings.xml

- CSIv2 Security Properties in ejb_sec.properties

- CSIv2 Security Properties in orion-ejb-jar.xml

- EJB Client Security Properties in ejb_sec.properties

  Note: If your application uses JAAS, you must configure the OracleAS JAAS Provider to use CSIv2, as discussed in Table 4-2, "RealmLoginModule Options" .

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

Note: You cannot edit `internal-settings.xml` with Enterprise Manager.

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

Table 15-1 EJB Server Security Properties

Property | Meaning
--- | ---
`port` | IIOP port number (defaults to `5555`).
`ssl` | This is "`true`" if IIOP/SSL is supported, "`false`" otherwise.
`ssl-port` | IIOP/SSL port number (defaults to `5556`). This port is used for server-side authentication only. If your application uses client and server authentication, you must also set `ssl-client-server-auth-port`.
`ssl-client-server-auth-port` | Port used for client and server authentication (defaults to `5557`). This is the port on which OC4J listens for SSL connections that require both client and server authentication. If this is not set, OC4J will listen on `ssl-port` + 1 for client-side authentication.
`keystore` | Name of keystore (used only if `ssl` is "`true`").
`keystore-password` | Keystore password (used only if `ssl` is "`true`").
`trusted-clients` | Comma-delimited list of hosts whose identity assertions can be trusted. Each entry in the list can be an IP address, a host name, or a host name pattern (such as "`*.example.com`" or "`*`", where "`*`" alone means that all clients are trusted). The default is to trust no clients.
`truststore` | Name of truststore. If you do not specify a truststore for a server, OC4J uses the keystore as the truststore (used only if `ssl` is "`true`").
`truststore-password` | Truststore password (can be set only if `ssl` is "`true`").

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>

Note: Although the default value of `port` is one less than the default value for `ssl-port`, this relationship is not required.

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.

Note: Server-side authentication takes precedence over a user name and password.

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.

### Trust Relationships

Two types of trust relationships exist:

- Clients trusting servers to transmit user names and passwords using non-SSL connections

- Servers trusting clients to send identity assertions, which delegate an originating client identity

Clients list trusted servers in the EJB property `oc4j.iiop.trustedServers`. Servers list trusted clients in the `trusted-client` property of the `<sep-property>` element in `internal-settings.xml`.

See Also: "EJB Client Security Properties in ejb_sec.properties" "EJB Server Security Properties in internal-settings.xml"

Conformance level 0 of the EJB standard defines two ways of handling trust relationships:

- Presumed trust, in which the server presumes that the logical client is trustworthy, even if the logical client has not authenticated itself to the server, and even if the connection is not secure

- Authenticated trust, in which the target trusts the intermediate server based on authentication either at the transport level or in the `trusted-client` list or both

  Note: You can also configure the server to both require SSL client-side authentication and also specify a list of trusted client (or intermediate) hosts that are allowed to insert identity assertions.

OC4J provides both kinds of trust. Configure trust using the <`ior-security-config>` element for the bean in `orion-ejb-jar.xml`, as discussed in "CSIv2 Security Properties in orion-ejb-jar.xml" immediately following.

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

### DT D for <ior-security-config>

Here is the DTD for the `<ior-security-config>` 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) >

### <transport-config>

This element specifies the transport security level. Each element within `<transport-config>` must be set to `supported`, `required`, or `none`—`none` means that the bean neither supports nor uses that feature; `supports` means that the bean permits the client to use the feature; `required` means that the bean insists that the client use the feature. The elements are:

- `<integrity>`: Is there a guarantee that all transmissions are received exactly as they were transmitted?

- `<confidentiality>`: Is there a guarantee that no third party was able to read transmissions?

- `<establish-trust-in-target>`: Does the server authenticate itself to the client? This element may be set to either `supported` or `none`; it cannot be set to `required`.

- `<establish-trust-in-client>`: Does the client authenticate itself to the server? This element must be set to `supported`, `required`, or `none`.

  Notes: If you set <`establish-trust-in-client>` to `required`, this overrides specifying `username_password` in `<as-context>`. If you do this, you must also set the `<required>` node value in the `<as-context>` section to `false`; otherwise access permission issues will arise. Setting any of the `<transport-config>` properties to `required` means that the bean will use RMI/IIOP/SSL to communicate.

### <as-context>

This element specifies the message-level authentication properties.

- `<auth-method>`: Must be set to either `username_password` or `none`. If set to `username_password`, beans use user names and passwords to authenticate the caller.

- `<realm>`: Must be set to `default` in the OC4J 10.1.2 implementation.

- `<required>`: If set to `true`, the bean requires the caller to specify a user name and password.

### <sas-context>

This element specifies the identity delegation properties. It has one element, `<caller-propagation>`, which can be set to `supported`, `required`, or `none`. If the `<caller-propagation>` element is set to `supported`, then this bean accepts delegated identities from intermediate servers. If it is set to `required`, then this bean requires all other beans to transmit delegated identities. If set to `none`, this bean does not support identity delegation.

An example:

    <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

Table 15-2 EJB Client Security Properties

Property | Meaning
--- | ---
`# oc4j.iiop.keyStoreLoc` | The path name for the keystore.
`# oc4j.iiop.keyStorePass` | The password for the keystore.
`# oc4j.iiop.trustStoreLoc` | The path name for the truststore.
`# oc4j.iiop.trustStorePass` | The password for the truststore.
`# oc4j.iiop.enable.clientauth` | Whether the client supports client-side authentication. If this property is set to `true`, you must specify a keystore location and password.
`oc4j.iiop.ciphersuites` | Which cipher suites are to be enabled. The valid cipher suites are:
    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
`nameservice.useSSL` | Whether to use SSL when making the initial connection to the server.
`client.sendpassword` | Whether to send user name and password in clear form (unencrypted) in the service context when not using SSL. If this property is set to `true`, the user name and password are sent only to servers listed in the `trustedServer` list.
`oc4j.iiop.trustedServers` | A list of servers that can be trusted to receive passwords sent in clear form. This has no effect if `client.sendpassword` is set to `false`. The list is comma-delimited. Each entry in the list can be an IP address, a host name, or a host name pattern (such as "`*.example.com`" or "`*`", where "`*`" alone means that all servers are trusted).

Notes: The `ejb_sec.properties` file is used for client-side operations, where `internal-settings.xml` would not be present. The properties marked with a "#" can be set either in `ejb_sec.properties` or as system properties. The settings in `ejb_sec.properties` always override settings specified as system properties.