Chapter 21 Using SSL in ActiveX Clients

SSL properties

The following table lists the ORB and SSLServiceProvider properties that govern the use of SSL. In addition, you need to connect to a server address that can support your chosen level of security, as described in "Secure server addresses".

Some properties, if not set or set incorrectly, cause the ORB to invoke an SSL callback method. If you do not install an SSL callback, the default callback implementation aborts the connection attempt.

Table 21-1: SSL Properties
Property name for ORB.init	Property name for SSLServiceProvider	Description
-ORBpin	pin	Always required when using SSL. Specifies the PKCS #11 token PIN. This is required for logging in to a PKCS #11 token for client authentication and for retrieving trust information. This property cannot be retrieved. If not set, set to "any", or set incorrectly, the ORB invokes the getPin callback method.
-ORBcertificateLabel	certificateLabel	Required when using mutual authentication. Specifies the client certificate to use if the connection requires mutual authentication. The label is a simple name that identifies an X.509 certificate/private key in a PKCS #11 token. If the property is not set and the connection requires mutual authentication, the ORB invokes the getCertificateLabel callback method, passing the list of available certificate names as an input parameter.
-ORBqop	qop	Always required when using SSL. Specifies the name of a security characteristic to use. See "Choosing a security characteristic" for more information.
-ORBuserData	userData	Specifies user data (String datatype). This is an optional property. Client code can set user data during ORB initialization and access it using SSLSessionInfo::getProperty method in the SSL callback implementation. This may be useful as a mechanism to store ORB-level context information that is otherwise not available through the SSLSessionInfo interface.
-ORBuseEntrustID	useEntrustID	Specifies whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. If this property is set to "false" (the default), Sybase PKCS #11 token properties are valid and Entrust-specific properties are ignored. If this property is set to "true", Entrust-specific properties are valid and Sybase PKCS #11 token properties are ignored.
-ORBentrustUserProfile	entrustUserProfile	Specifies the full path to the file containing an Entrust user profile. This property is optional when the Entrust single-login feature is available and required when this feature is not available. If not set, the ORB invokes the getCredentialAttribute callback method.
-ORBentrustPassword	entrustPassword	Specifies the password for logging in to Entrust with the specified user profile. This property is optional when the Entrust single-login feature is available and required when this feature is not available. If the password is required but not set or set incorrectly, the ORB invokes the getPin callback method. This property cannot be retrieved.
-ORBentrustIniFile	entrustIniFile	Specifies the path name for the Entrust INI file that provides information on how to access Entrust. This is required when the useEntrustid property is set to true. If not set, the ORB invokes the getCredentialAttribute callback method.
-ORBAXSSLCBComponent	none	The PROGID for an ActiveX component that acts as an SSL callback.
none	callbackImpl	DLL, package, and component name of a C++ pseudocomponent that acts as an SSL callback, specified as: myDLL/myPackage/myComponent See "Implementing an SSL callback" for more information.
none	availableQop	Retrieve only. A list of available security characteristics. The qop property can be set only to values that appear in this list.
none	availableQopDesc	Retrieve only. A list of descriptions for the available security characteristics, in the same order as listed in the value of the "availableQop" property.
none	entrustReady	Retrieve only. Returns "true" if Entrust PKI software is available on the client, "false" otherwise.
none	loginTimeout	The time in seconds before the login to the Sybase certificate database expires. The default timeout is indefinite. Before the login times out, the certificate password is cached and used for multiple SSL connections. In other words, the PIN must be presented only once before the timeout expires or the client program terminates, whichever occurs first.

Choosing a security characteristic

To use SSL, you must specify a value for the qop property in ORB properties or using the SSLServiceProvider interface. Set the qop to the name of an available security characteristic. The characteristic describes the CipherSuites the client uses when negotiating an SSL connection. When connecting, the client sends the list of CipherSuites that it uses to the server, and the server selects a CipherSuite from that list. The server chooses the first CipherSuite in the list that it can use. If the server cannot use any of the available CipherSuites, the connection fails.

The "Security Configuration" chapter in the Jaguar CTS System Administraion Guide describes the security characteristics that are provided with Jaguar. At run time, you can retrieve a list of characteristics and their descriptions by retrieving the availableQop and availableQopDesc properties.

Set the qop to "sybpks_none" to prevent any use of SSL on a connection. This setting can be useful if you have set the qop globally for all ORBs using the SSLServiceProvider interface, and you want to override the qop for an individual ORB instance.

Secure server addresses

The client ORB only connects to a server listener that uses an equivalent or greater level of security as requested in the qop setting. When you use ORB.string_to_object to instantiate a SessionManager::Manager proxy, the listener specified by the server address must use a security profile that matches the client's qop setting.

For more information on instantiating proxies, see "Instantiating proxies using CORBA-style interfaces".

Other useful ORB properties

The following ORB properties are not required in programs that use SSL, but affect the behavior of programs that use SSL:

Property	Description
-ORBLogFile	Specifies the name of a file to receive error logging information from the client ORB. There is no default, and logging is enabled by specifying a filename as this property. The filename is recreated each time a client program is run with the same setting. You can also specify a log file by setting the JAG_LOGFILE environment variable. (The latter is useful when troubleshooting an executable).
-ORBretryCount	The number of times to retry a connection attempt that has failed; the default is 5. You can also configure this property by setting the -ORB_RETRYCOUNT environment variable.