Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs.beasys.com   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WLE Doc Home   |   Security & Related Topics   |   Previous   |   Next   |   Contents   |   Index

This topic includes the following sections:

• Setting Parameters for the SSL Protocol

• Defining a Port for SSL Communications

• Enabling Certificate-based Authentication

• 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

Perform the tasks in this topic only if you are using the SSL Protocol or certificate-based authentication.

Setting Parameters for the SSL Protocol

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

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

• Enable certificate-based authentication.

• 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, the command line options of the CORBA C++ ORB, or the system properties of the CORBA Java ORB to set these SSL parameters.

Defining a Port for SSL Communications

To define a port for SSL communications:

• 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++ or CORBA Java ORB, use the -ORBsecurePort command line option or system property 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 or system property when using callback objects or the WLE Notification Service.

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

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

Enabling Certificate-based Authentication

To enable certificate-based authentication:

• Use the -a option of the ISL command to specify that certificate-based authentication must be used by applications connecting to the IIOP Listener/Handler.

• Use the -ORBmutualAuth command line option or system property on the ORB to specify that certificate-based authentication must be used by applications connecting to the CORBA C++ or CORBA Java ORB.

Enabling certificate-based authentication requires the WLE Security Pack to be installed. If the -a option or the -ORBmutualAuth command line option or system property is executed and a license to enable the use of the SSL protocol does not exist, the IIOP Listener/Handler, CORBA C++ ORB, or CORBA Java 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 in the CORBA C++ and CORBA Java ORBs. 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++ or CORBA Java ORBs, specify the -ORBpeerValidate command line option or system property.

The values for the -v option and the -ORBpeerValidate command line option or system property 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 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 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 a WLE domain configured for SSL connections (for example, in the case of fault tolerance), BEA 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 or system property on the ORB to set the encryption strength in the CORBA C++ or CORBA Java ORB.

The -z option and the -ORBminCrypto command line option or system property set the minimum level of encryption used when an application establishes an SSL connection with the IIOP Listener/Handler, the CORBA C++ ORB, or the CORBA Java ORB. The valid values are 0, 40, 56, and 128. 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 or system property set the maximum level of encryption used when an application establishes an SSL connection with the IIOP Listener/Handler, the CORBA C++ ORB, or the CORBA Java ORB. The valid values are 0, 40, 56, and 128. 0 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 or system properties are available only if the WLE Security pack is installed.

To change the strength of encryption currently used in a WLE 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 3-1 lists combinations of encryption values and describes the encryption behavior.

Table 3-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 3-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. The WLE product supports the cipher suites described in Table 3-2.

Table 3-2 SSL Cipher Suites Supported by the WLE Product

Cipher Suite	Key Exchange Type	Symmetric Key Strength
SSL_RSA_WITH_RC4_128_SHA	RSA	128
SSL_RSA_WITH_RC4_128_MD5	RSA	128
SSL_RSA_WITH_DES_CDC_SHA	RSA	56
SSL_RSA_EXPORT_WITH_RC4_40_MD5	RSA	40
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA	RSA	40
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5	RSA	40
SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA	Diffie Hellman	40
SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA	Diffie Hellman	40
SSL_RSA_WITH_3DES_EDE_CBC_SHA	RSA	112
SSL_RSA_WITH_NULL_SHA	RSA	0
SSL_RSA_WITH_NULL_MD5	RSA	0

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 can not use session renegotiation when enabling certificate-based 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. If this parameter is not specified, you will be prompted for it when you enter the tmloadcf command.

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

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 3-1 includes code from a UBBCONFIG file that set parameters to configure the IIOP Listener/Handler for the SSL protocol and certificate-based authentication.

Listing 3-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"

Listing 3-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 3-2 Example of Setting the Command Line Options on the CORBA C++ ORB

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

Listing 3-3 contains sample code that illustrates using the system properties of the CORBA Java ORB to configure the ORB for the SSL protocol.

Listing 3-3 Example of Setting the System Properties on the CORBA Java ORB

ChatClient		-DTOBJADDR=corbalocs://piglet:1900
		-Dorg.omg.CORBA=ORBPort=1948
		-classpath=%CLASSPATH% client
		-ORBMaxCrypto 128