Configuring the SSL Protocol

This topic includes the following sections:

•	Setting Parameters for the SSL Protocol

•	Defining a Port for SSL Network Connections

•	Enabling Host Matching

•	Setting the Encryption Strength

•	Setting the Interval for Session Renegotiation

•	Defining Security Parameters for the IIOP Listener/Handler

•	Example of Setting Parameters on the ISL System Process

•	Example of Setting Command-line Options on the CORBA C++ ORB

Notes:

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

Setting Parameters for the SSL Protocol

To use the SSL protocol or certificate authentication with the IIOP Listener/Handler or the CORBA C++ object request broker (ORB), you need to:

•	Specify the secure port on which SSL network connections will be accepted.

•	Specify the strength that will be used when encrypting data.

•	Optionally, set the interval for session renegotiation (IIOP Listener/Handler only).

The following sections detail how to use the options of the ISL command or the command-line options of the CORBA C++ ORB to set these SSL parameters.

Defining a Port for SSL Network Connections

To define a port for SSL network connections:

•	Use the -S option of the ISL command to specify which port of the IIOP Listener/Handler will listen for secure connections using the SSL protocol. You can configure the IIOP Listener/Handler to allow only SSL connections by setting the -S option and -n option of the ISL command to the same value.

•	If you are using a remote CORBA C++ ORB, use the -ORBsecurePort command-line option on the ORB to specify which port of the ORB will listen for secure connections using the SSL protocol. You should set this command-line option when using callback objects or the CORBA Notification Service.

Note:

If you are using the SSL protocol with a joint client/server application, you must specify a port number for SSL network connections. You cannot use the default.

Defining a secure port for SSL network connections requires the license for the SSL protocol to be installed. If the -S option or the -ORBsecurePort command-line option is executed and a license to enable the use of the SSL protocol does not exist, the IIOP Listener/Handler or CORBA C++ ORB will not start.

Enabling Host Matching

The SSL protocol is capable of encrypting messages for confidentiality; however, the use of encryption does nothing to prevent a man-in-the-middle attack. During a man-in-the-middle attack, a principal masquerades as the location from which an initiating application retrieves the initial object references used in the bootstrapping process.

To prevent man-in-the-middle attacks, it is necessary to perform a check to ensure that the digital certificate received during an SSL connection is for the principal for which the connection was intended. Host Matching is a check that the host specified in the object reference used to make the SSL connection matches the common name in the subject in the distinguished name specified in the target’s digital certificate. Host Matching is performed only by the initiator of an SSL connection, and confirms that the target of a request is actually located at the same network address specified by the domain name in the target’s digital certificate. If this comparison fails, the initiator of the SSL connection refuses to authenticate the target and drops the SSL connection. Host Matching is not technically part of the SSL protocol and is similar to the same check done in Web browsers.

The domain name contained in the digital certificate must match exactly the host information contained in the object reference. Therefore, the use of DNS host names instead of IP addresses is strongly encouraged.

By default, Host Matching in enabled in the IIOP Listener/Handler and the CORBA C++ ORB. If you need to enable Host Matching, do one of the following:

•	In the IIOP Listener/Handler, specify the -v option of the ISL command.

•	In the CORBA C++ ORB, specify the –ORBpeerValidate command-line option.

The values for the -v option and the -ORBpeerValidate command-line option are as follows:

•	none—no host matching is performed.

•	detect—if the object reference used to make the SSL connection does not match the host name in the target’s digital certificate, the IIOP Listener/Handler or the ORB does not authenticate the target and drops the SSL connection. The detect value is the default value.

•	warn—if the object reference used to make the SSL connection does not match the host name in the target’s digital certificate, the IIOP Listener/Handler or the ORB sends a message to the user log and continues processing.

If there is more than one IIOP Listener/Handler in an Oracle Tuxedo domain configured for SSL connections (for example, in the case of fault tolerance), Oracle recommends using DNS alias names for the IIOP Listener/Handlers or creating different digital certificates for each IIOP Listener/Handler. The –H switch on the IIOP Listener can be used to specify the DNS alias name so that object references will be created correctly.

Setting the Encryption Strength

To set the encryption strength:

•	Use the -z and -Z options of the ISL command to set the encryption strength in the IIOP Listener/Handler.

•	Use the -ORBminCrypto and -ORBmaxCrypto command-line option on the ORB to set the encryption strength in the CORBA C++ ORB.

The -z option and the -ORBminCrypto command-line option set the minimum level of encryption used when an application establishes an SSL connection with the IIOP Listener/Handler or the CORBA C++ ORB. The valid values are 0, 40, 56, and 128. A value of 0 means the data is signed but not sealed while 40, 56, and 128 specify the length (in bits) of the encryption key. If this minimum level of encryption is not met, the SSL connection fails. The default is 40.

The -Z option and the -ORBmaxCrypto command-line option set the maximum level of encryption used when an application establishes an SSL connection with the IIOP Listener/Handler or the CORBA C++ ORB. The valid values are 0, 40, 56, and 128. Zero means that data is signed but not sealed while 40, 56, and 128 specify the length (in bits) of the encryption key. The default minimum value is 40. The default maximum value is whatever capability is specified by the license.

The –z or –Z options and the -ORBminCrypto and -ORBmaxCrypto command-line options are available only if the license for the SSL protocol is installed.

To change the strength of encryption currently used in a CORBA application, you need to shut down the IIOP Listener/Handler or the ORB.

The combination in which you set the encryption values is important. The encryption values set in the initiator of an SSL connection need to be a subset of the encryption values set in the target of an SSL connection.

Table 6‑1 lists combinations of encryption values and describes the encryption behavior.

 

Table 6‑1 Combinations of Encryption Values 

-z -ORBminCrypto	-Z -ORBmaxCrypto	Description
No value specified	No value specified	If the use of the SSL protocol is specified by some other command-line option or system property but no values are specified for ORBminCrypto and ORBmaxCrypto, these command-line options or system properties are assigned their default values.
0	No value specified	Maximum encryption defaults to the maximum value specified in the license. Tamper/replay detection and privacy protection are negotiated.
No value specified	0	Tamper/replay detection is negotiated. Privacy protection is not provided.
0	0	Tamper/replay detection is negotiated. Privacy protection is not provided.
40, 56, 128	No value specified	Maximum encryption defaults to the maximum value specified in the license. Privacy protection can be negotiated to the maximum allowed by the SSL license.
No value specified	40, 56, 12	Privacy protection can be negotiated to the value specified by the -Z option as long as it is less than the maximum allowed by the SSL license. The -z option defaults to 40.
40, 56, 128	40, 56, 128	Privacy protection can be negotiated between the values specified by the -z option up to the value specified by the -Z option as long as the values are less than the maximum allowed by the SSL license.

Note:

In all combinations listed in Table 6‑1, the value of the SSL license controls the maximum bit strength. If a bit strength is specified beyond the maximum licensed value, the IIOP Listener/Handler or ORB will not start and an error will be generated indicating the bit strength setting is invalid. Stopping the IIOP Listener/Handler or ORB from starting, instead of lowering the maximum value and giving only a warning, protects against an incorrectly configured application running with less protection than was expected.

If a cipher that exceeds the maximum licensed bit strength is somehow negotiated, the SSL connection is not established.

For a list of cipher suites supported by the CORBA security environment, see “Supported Cipher Suites” on page 2‑10.

Setting the Interval for Session Renegotiation

Note:

You set the interval for session renegotiation only in the IIOP Listener/Handler.

Use the -R option of the ISL command to control the time between session renegotiations. Periodic renegotiation of an SSL session refreshes the symmetric keys used to encrypt and decrypt information which limits the time a symmetric key is exposed. You can keep long-term SSL connections more secure by periodically changing the symmetric keys used for encryption.

The –R option specifies the renegotiation interval in minutes. If an SSL connection does renegotiate within the specified interval, the IIOP Listener/Handler will request the application to renegotiate the SSL session for inbound connections or actually perform the renegotiation in the case of outbound connections. The default is 0 minutes which results in no periodic session renegotiations.

You cannot use session renegotiation when enabling certificate authentication using the -a option of the ISL command.

Defining Security Parameters for the IIOP Listener/Handler

For the IIOP Listener/Handler to participate in SSL connections, the IIOP Listener/Handler authenticates itself to the peer that initiated the SSL connection. This authentication requires a digital certificate. The private key associated with the digital certificate is used as part of establishing an SSL connection that results in an agreement between the principal and the peer (in this case a client application and the IIOP Listener/Handler) on the session key. The session key is a symmetric key (as opposed to the private-public keys) that is used to encrypt data during an SSL session. You define the following information for the IIOP Listener/Handler so that it can be authenticated by peers:

•	SEC_PRINCIPAL_NAME

Specifies the identity of the IIOP Listener/Handler.

•	SEC_PRINCIPAL_LOCATION

Specifies the location of the private key file. For example, $TUXDIR/udataobj/security/keys/milozzi.pem.

•	SEC_PRINCIPAL_PASSVAR

Specifies an environment variable that holds the pass phrase for the private key of the IIOP Listener/Handler when the tmloadcf command is not run interactively. Otherwise, you will be prompted for the pass phrase when you enter the tmloadcf command.

Note:

If you define any of the security parameters for the IIOP Listener/Handler incorrectly, the following errors are reported in the ULOG file:

ISH.28014: LIBPLUGIN_CAT:2008:ERROR:No such file or directory SEC_PRINCIPAL_LOCATION
ISH.28014:ISNAT_CAT:1552:ERROR:Could not open private key, erro =-3011
ISH.28104:ISNAT_CAT:1544:ERROR:Could not perform SSL accept from host/port//IPADDRESS:PORT

To resolve the errors, correct information in the security parameters and reboot the IIOP Listener/Handler.

These parameters are included in the part of the SERVERS section of the UBBCONFIG file that defines the ISL system process.

You also need to use the tpusradd command to define the IIOP Listener/Handler as an authorized user in the Oracle Tuxedo domain. You will be prompted for a password for the IIOP Listener/Handler. Enter the pass phrase you defined for SEC_PRINCIPAL_PASSVAR.

During initialization, the IIOP Listener/Handler includes its principal name as defined by SEC_PRINCIPAL_NAME as an argument when calling the authentication plug-in to acquire its credentials. An IIOP Listener/Handler requires credentials so that it can authenticate remote client applications that want to interact with the CORBA application, and get authorization and auditing tokens for remote client applications.

Because the IIOP Listener/Handler must authenticate its own identity to the Oracle Tuxedo domain in order to become a trusted system process, it is necessary to configure an authentication server when using the default authentication plug-in. See “Configuring the Authentication Server” on page 7‑2 for more information.

Example of Setting Parameters on the ISL System Process

You set parameters for the SSL protocol in the portion of the SERVERS section of the UBBCONFIG that defines information for the ISL server process. Listing 6‑1 includes code from a UBBCONFIG file that set parameters to configure the IIOP Listener/Handler for the SSL protocol and certificate authentication.

Listing 6‑1 Using the ISL Command in the UBBCONFIG File

...
ISL
SRVGRP = SYS_GRP
SRVID = 5
CLOPT = “-A -- -a -z40 -Z128 -S3579 -n //ICEPICK:2569
SEC_PRINCIPAL_NAME=”BLOTTO”
SEC_PRINCIPAL_LOCATION=”BLOTTO.pem”
SEC_PRINCIPAL_VAR=”AUDIT_PASS”

 

Example of Setting Command-line Options on the CORBA C++ ORB

Listing 6‑2 contains sample code that illustrates using the command-line options on the CORBA C++ ORB to configure the ORB for the SSL protocol.

Listing 6‑2 Example of Setting the Command-line Options on the CORBA C++ ORB

ChatClient -ORBid BEA_IIOP
-ORBsecurePort 2100
-ORBminCrypto 40
-ORBMaxCrypto 128
TechTopics