The Digital Certificate Access Server (DCAS) API object (DCASClient) encapsulates the passticket requests. The following are its members and methods.
Members:
v Port Number v Keystore File Name v Keystore Password
v Use WellKnownTrustedCAs v Server Authentication v Trace Level
If you have previously written your own plug-in using the DCASClient object prior to HATS V7.0, you do not need to change your code for it to continue to work. However, new APIs are available starting with HATS V7.0 and should 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.
v traceLevel - Trace level (0=None, 1=Minimum, 2=Normal, 3=Maximum) v logFile - Trace log file name. This parameter is not used in HATS. Traces
are recorded in the HATS 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
v hostAddress - The DCAS server IP address.
v hostPort - The DCAS server port number. If not specified, the default port number 8990 will be used.
v 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.
v trustStorePassword - The password of the specified truststore. The password is set to null if you are using the default truststore or WellKnownTrustedCAs.p12.
v 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, trustStoreTypemethod instead.
v dcasAddr - The DCAS server's IP address
v dcasPort - The DCAS's port number. If not specified, the default port number of 8990 will be used.
v 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 HATS 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);
v 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 6 on page 86.
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 6 on page 86. An SSL client-authenticated connection is established with the DCAS, and it is reused for all subsequent passticket requests.
v hostUserID - User ID for which the passticket is being requested.
v hostApplID - Application ID for which the passticket is being requested.
v hostAddr - The DCAS's address.
v timeout - The time available for the DCAS protocol to return a passticket, specified in milliseconds.
Public void Destroy()
This method closes the DCAS connection.
Chapter 10. Using the HATS bidirectional API
Note: There is no bidirectional support for standard portlet Integration Objects, global variable overrides, portlet communication, Web Services for Remote Portlets, and Light pen (attention) and Light pen (selection) host
components.
If you create HATS applications that use bidirectional (Arabic or Hebrew) code pages, and you add business logic or create your own custom components or widgets, you can use the bidirectional API to handle the recognition of host components and the presentation of widgets on the Web page. This chapter describes this API. Before using the material in this chapter you should be familiar with the bidirectional concepts described in HATS User's and Administrator's Guide.