Chapter 26 Using HTTP and HTTPS Connections in Java

SSL properties

Table 26-1 lists the SSL properties that can be set and retrieved with the HttpsURLConnection getSSLProperty, getGlobalProperty, setSSLProperty, and setGlobalProperty methods. Global properties are set and read with the getGlobalProperty and setGlobalProperty methods. Global properties affect all HTTPS connections, not just the HttpsUrlConnection instance on which they are set. The right column in Table 26-1 lists which methods are valid for each property.

Some properties, if not set or set incorrectly, cause the connection to invoke an SSL callback method. You can install a callback to respond to these cases with the "callbackImpl" global property. If you do not install an SSL callback, the default callback implementation aborts the connection attempt.

Table 26-1: SSL Properties
Property name	Description	Valid for methods
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 connection invokes the getPin callback method.	setSSLProperty setGlobalProperty
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 connection invokes the getCertificateLabel callback method, passing an array of available certificate names as an input parameter.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
qop	Always required when using SSL. Specifies the name of a security characteristic to use. See "Choosing a security characteristic" for more information.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
userData	Specifies user data (String datatype). This is an optional property. Client code can set user data during connection initialization and access it using SSLSessionInfo::getProperty method in the SSL callback implementation. This may be useful as a mechanism to store connection-level context information that is otherwise not available through the SSLSessionInfo interface.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
useEntrustID	Specifies whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a Boolean (true or false) 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.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
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 connection invokes the getCredentialAttribute callback method.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
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 connection invokes the getPin callback method. This property cannot be retrieved.	setSSLProperty setGlobalProperty
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 connection invokes the getCredentialAttribute callback method.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
callbackImpl	Specifies the name of a Java class that implements the CtsSecurity.SSLCallbackIntf interface. For example: com.acme.AcmeSSLCallback See "Implementing an SSL callback" for more information.	setGlobalProperty getGlobalProperty
availableQop	Retrieve only. A list of available security characteristics. The qop property can be set only to values that appear in this list.	getGlobalProperty
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.	getGlobalProperty
entrustReady	Retrieve only. Returns true if Entrust PKI software is available on the client, false otherwise.	getGlobalProperty

Choosing a security characteristic

To use SSL, you must specify the name of an available security characteristic as the value 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.

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