SSL properties

Table 26-1 lists the properties that can be set or retrieved using SetGlobalProperty or GetGlobalProperty. For any SSL connection, you must set the qop (quality of protection) property and, unless you implement a callback to obtain it, you must also set the pin property. You also need to connect to a server address that can support your chosen level of security, as described in “Secure server addresses”.

Setting global properties in a PowerBuilder session When you run a client application in PowerBuilder, you can set global properties only once during the PowerBuilder session. You will need to restart PowerBuilder each time you test the code that sets global SSL properties.

If some properties are not set or are set incorrectly, an SSL callback method is invoked. If you do not specify an instance of the SSLCallback object, the default callback implementation aborts the connection attempt.

**Table 26-1: List of SSL properties**
Property	Description	Get	Set
callbackImpl	Instance of the SSLCallback object. For more information, see “Using SSL callbacks”.	Yes	Yes
certificateLabel	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. Required for mutual authentication. If not set and the connection requires mutual authentication, invokes the getCertificateLabel callback method, passing an array of available certificate names as an input parameter.	Yes	Yes
qop	The name of a security characteristic to use. Required for SSL. See “Choosing a security characteristic” for more information.	Yes	Yes
cacheSize	The size of the SSL session ID cache. Default is 100.	Yes	Yes
SessLingerTime	The number of seconds that a session ID entry is kept in the cache after the last connection that used it is terminated. Default is 28800 seconds (8 hours).	Yes	Yes
SessShareCount	The number of concurrent SSL sessions that can use the same session ID. Default is 10.	Yes	Yes
pin	The PKCS #11 token PIN. This is required for logging in to a PKCS #11 token for client authentication and for retrieving trust information. Required for SSL. If not set, set to `any`, or set incorrectly, the getPin callback method is invoked.	No	Yes
availableQop	A list of available security characteristics. The qop property can be set only to values that appear in this list.	Yes	No
availableQopDesc	A list of descriptions for the available security characteristics, in the same order as listed in the value of the availableQop property.	Yes	No
availableVersions	A list of SSL protocol versions supported by the SSL runtime engine.	Yes	No
entrustReady	TRUE if Entrust PKI software is available on the client, FALSE otherwise.	Yes	No
entrustIniFile	The path name for the Entrust INI file that provides information on how to access Entrust. Required when the useEntrustid property is set to true. If not set, the getCredentialAttribute callback method is invoked.	Yes	Yes
entrustUserProfile	The full path to the file containing an Entrust user profile. Optional when the Entrust single-login feature is available, required otherwise. If not set, the getCredentialAttribute callback method is invoked.	Yes	Yes
useEntrustID	Whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a boolean property. If this property is set to FALSE, 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.	Yes	Yes
entrustPassword	The password for logging in to Entrust with the specified user profile. Optional when the Entrust single-login feature is available, required otherwise. If the password is required but not set or set incorrectly, the getPin callback method is invoked.	No	Yes

Table 26-1: List of SSL properties

Property

Description

Get

Set

callbackImpl

Instance of the SSLCallback object. For more information, see “Using SSL callbacks”.

Yes

certificateLabel

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.

Required for mutual authentication. If not set and the connection requires mutual authentication, invokes the getCertificateLabel callback method, passing an array of available certificate names as an input parameter.

Yes

qop

The name of a security characteristic to use. Required for SSL. See “Choosing a security characteristic” for more information.

Yes

cacheSize

The size of the SSL session ID cache. Default is 100.

Yes

SessLingerTime

The number of seconds that a session ID entry is kept in the cache after the last connection that used it is terminated. Default is 28800 seconds (8 hours).

Yes

SessShareCount

The number of concurrent SSL sessions that can use the same session ID. Default is 10.

Yes

The PKCS #11 token PIN.

This is required for logging in to a PKCS #11 token for client authentication and for retrieving trust information. Required for SSL.

If not set, set to any, or set incorrectly, the getPin callback method is invoked.

Yes

availableQop

A list of available security characteristics. The qop property can be set only to values that appear in this list.

Yes

availableQopDesc

A list of descriptions for the available security characteristics, in the same order as listed in the value of the availableQop property.

Yes

availableVersions

A list of SSL protocol versions supported by the SSL runtime engine.

Yes

entrustReady

TRUE if Entrust PKI software is available on the client, FALSE otherwise.

Yes

entrustIniFile

The path name for the Entrust INI file that provides information on how to access Entrust. Required when the useEntrustid property is set to true.

If not set, the getCredentialAttribute callback method is invoked.

Yes

entrustUserProfile

The full path to the file containing an Entrust user profile. Optional when the Entrust single-login feature is available, required otherwise.

If not set, the getCredentialAttribute callback method is invoked.

Yes

useEntrustID

Whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a boolean property.

If this property is set to FALSE, 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.

Yes

entrustPassword

The password for logging in to Entrust with the specified user profile. Optional when the Entrust single-login feature is available, required otherwise.

If the password is required but not set or set incorrectly, the getPin callback method is invoked.

Yes

Choosing a security characteristic

To use SSL, you must specify the name of an available security characteristic for the qop property. 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 EAServer Security Administration and Programming Guide describes the security characteristics that are provided with EAServer. You can retrieve a list of characteristics available on the server and their descriptions by retrieving the availableQop and availableQopDesc properties with GetGlobalProperty.

Secure server addresses

You can connect only to a server listener that uses a security level that is equivalent to or greater than the level requested in the qop setting. If you use JaguarORB.string_to_object to instantiate a proxy for the SessionManager::Manager interface, the listener specified by the server address must use a security profile that matches the client’s qop setting.