The DCAS API object

The Digital Certificate Access Server (DCAS) API object (DCASClient) encapsulates the passticket requests. The following are its members and methods.

Members:

Port Number
Keystore File Name
Keystore Password
Use WellKnownTrustedCAs
Server Authentication
Trace Level

New APIs are available that can be used when developing new plug-ins. The preferred APIs are flagged below with a Preferred symbol.

Methods:

Public DCASClient(): This constructor should be used if you want to use the default trace level and log file name when the object is created.

Public DCASClient(int traceLevel, String logFile)

This constructor should be used if you want to specify a trace level and log file name when the object is created.

traceLevel - Trace level (0=None, 1=Minimum, 2=Normal, 3=Maximum)
logFile - Trace log file name. This parameter is not used in ZIETrans. Traces are recorded in the ZIETrans trace files. Web Express Logon traces are controlled with the runtime trace flag, trace.RUNTIME.

public int Init (String hostAddress, int hostPort, String trustStoreName, String trustStorePassword, String trustStoreType)

Preferred

hostAddress - The DCAS server IP address.
hostPort - The DCAS server port number. If not specified, the default port number 8990 will be used.
trustStoreName - The name of the truststore to be used by JSSE to connect to DCAS. It should include the full path name. The name is set to null if you are using the default truststore or WellKnownTrustedCAs.p12.
trustStorePassword - The password of the specified truststore. The password is set to null if you are using the default truststore or WellKnownTrustedCAs.p12.
trustStoreType - The type of the specified truststore. Valid values are:
- DCASClient.TRUSTSTORE_TYPE_PKCS12 (pkcs12)
- DCASClient.TRUSTSTORE_TYPE_JCEKS (jceks)
- DCASClient.TRUSTSTORE_TYPE_JKS (jks)
The truststore type is set to null if you are using the default truststore or WellKnownTrustedCAs.p12.
This method should be called after creating the DCASClient object. The parameters are stored in the object, and they do not change for the life of the object. The truststore name should include the full path name. The truststore must contain the DCAS client certificate and DCAS server certificate, unless the default truststore or WellKnownTrustedCAs.p12 will be used. The truststore password should be encrypted using the encrypt password tool. It will be decrypted before being stored in the object. The valid return codes are described in the SSOConstants object. Return 0 on success, nonzero otherwise. See SSOConstants for return codes.

Public int Init(String dcasAddr, int dcasPort, String keystoreFileName, String keystorePassword)

This method should be called after creating the DCASClient object. The parameters are stored in the object, and they do not change for the life of the object. The keystoreFileName should include the full path name. The keystore database must contain a DCAS client certificate and the DCAS server certificate. If WellKnownTrustedCAs.p12 or the default truststore is being used for these certificates, set keystoreFileName and keystorePassword to null. The keystore password should be encrypted using the encrypt password tool. It will be decrypted before being stored in the object. The valid return codes are described in the SSOConstants object.

If a keystore of a type other than p12 is being used, use the Init(hostAddress, hostPort, trustStoreName, trustStorePassword, trustStoreType method instead.

dcasAddr - The DCAS server's IP address
dcasPort - The DCAS's port number. If not specified, the default port number of 8990 will be used.
keystoreFileName - The name of the SSL keystore database file. The name should include the full path name. While you are developing your plug-in, you will not know the full path that will be used when you deploy your ZIETrans application. Following is an example of code that you can use to convert a provided file name parameter into a fully qualified file name, relative to the EAR directory, at runtime:
```
import com.ibm.eNetwork.security.sso.cms.CredMapper;
import com.ibm.eNetwork.security.sso.cms.PluginResourceLocator;

    if ( (p12FileName != null) && 
					(CredMapper.getPluginResourceLocator() != null))  
       	p12FileName = 
					CredMapper.getPluginResourceLocator().findResource(p12FileName); 
```
keystorePassword - The password of the above keystore database.

The keystore Password should be encrypted with the PasswordCipher.encrypt() method. If it is provided by an encrypted parameter (that is, a parameter with cmiEncrypted="true", it is provided to the plug-in in encrypted form. If it is not provided by an encrypted parameter, you can use this code to encrypt it:

import com.ibm.eNetwork.HOD.common.PasswordCipher;
keystorePW = PasswordCipher.encrypt(keystorePW);

The valid return codes are listed in Table 1.

public void setUseDefaultTrustStore(boolean def)

public void setNoFIPS(boolean nof)

Public void setWellKnownTrustedCAs(boolean wellKnownCAs)

Public void setServerAuthentication(boolean serverAuth)

Public CMResponse getPassticket(String hostUserID, String hostApplID, String hostAddr, long timeout)

This method should be called after creating and initializing the DCASClient object to obtain a passticket from the DCAS server. The passticket and the user ID are returned in a CMResponse object. The caller should check the status field of the CMResponse object to see whether the call was successful or not. If the call was successful, the status field will be set to SSO_CMR_SUCCESS. The valid values for the status field are listed in Table 1. An SSL client-authenticated connection is established with the DCAS, and it is reused for all subsequent passticket requests.

hostUserID - User ID for which the passticket is being requested.
hostApplID - Application ID for which the passticket is being requested.
hostAddr - The DCAS's address.
timeout - The time available for the DCAS protocol to return a passticket, specified in milliseconds.

Public void Destroy(): This method closes the DCAS connection.