GetCredentialAttribute

Description

Called by EAServer to allow the user to supply user credentials dynamically. This function is used by PowerBuilder clients connecting to EAServer.

Applies to

SSLCallBack objects

Syntax

sslcallback.GetCredentialAttribute ( thesessioninfo, attr, attrvalues )

Argument	Description
sslcallback	An instance of a customized SSLCallBack object.
thesessioninfo	A CORBAObject that contains information about the SSL session. This information can optionally be displayed to the user to provide details about the session.
attr	A long indicating whether the user needs to specify the path name of an INI file or a profile file. Values are: 1 CRED_ATTR_ENTRUST_INIFILE 2 CRED_ATTR_ENTRUST_USERPROFILE
attrvalues	An array of string values that contains the available attribute values.

Returns

String. Returns the selected attribute value.

Usage

A PowerBuilder application does not usually call the GetCredentialAttribute function directly. GetCredentialAttribute is called by EAServer if the useEntrustID property has been set and the EAServer client has not specified the path name of an Entrust INI file or profile.

To override the behavior of any of the functions of the SSLCallBack object, create a standard class user object that descends from SSLCallBack and customize this object as necessary. To let EAServer know which object to use when a callback is required, specify the name of the object in the callbackImpl SSL property. You can set this property value by calling the SetGlobalProperty function.

If you do not provide an implementation of GetCredentialAttribute, EAServer receives the CORBA::NO_IMPLEMENT exception and the default implementation of this callback is used. The default implementation always returns the first value in the list of values supplied. If there are no values supplied, it raises CtsSecurity::NoValueException. Any exceptions that may be raised by the function should be added to its prototype.

If your implementation of the callback returns an empty string, the default implementation described above is used and the first value in the list is returned. If that value is acceptable to the server, the connection proceeds. If the value is not acceptable, the connection is refused.

To obtain a useful return value, provide the user with available attribute values from the attrvalues array passed to the function and ask the user to select one of them. You can also supply additional information, such as the server certificate, obtained from the passed thesessioninfo object.

You can enable the user to cancel the attempt to connect by throwing an exception in this callback function. All exceptions thrown in SSLCallback functions return a CTSSecurity::UserAbortedException to the server. You need to catch the exception by wrapping the ConnectToServer function in a try-catch block.

Examples

Example 1

This example checks whether the server requires the location of an INI file or an Entrust user profile and displays an appropriate message. If the attrvalues array provides a list of choices, it displays the choices in a message box and prompts the user to enter a selection in a text box:

int   idx, numAttrs
String   sText, sLocation
numAttrs = upperbound(attrValues)
w_response w_ssl_response

IF attr = 1 THEN
    MessageBox("Entrust INI file required", &
      "Please specify the location of the INI file")
ELSEIF attr = 2 THEN
    MessageBox("Entrust profile required", &
      "Please specify the location of the profile")
END IF

IF numAttrs <> 0 THEN
  sText = "Locations available: "
  FOR idx = 1 to numAttrs
    sText += "~nattrValues[" + string(idx) + "]: " &
      + attrvalues[idx]
  NEXT
  OpenWithParm( w_ssl_response, SText )
  ls_rc = Message.StringParm
  IF ls_rc = "cancel" then 
    userabortedexception uae
    uae = create userabortedexception
    uae.setmessage("User cancelled connection")
    throw uae
  END IF
END IF
RETURN ls_rc