PowerScript Reference
PowerScript Functions

Description

Called by EAServer when an SSL certificate chain needs to be approved for use by a client. This function is used by PowerBuilder clients connecting to EAServer.

Applies to

SSLCallBack objects

Syntax

sslcallback.TrustVerify ( thesessioninfo, reason )

Return value

Long.

Returns one of the following values:

1 -- TRUST_ONCE (accept the current connection)

2 -- TRUST_FAIL (reject the current connection)

3 -- TRUST_ALWAYS (accept and mark as trusted in the database)

4 -- TRUST_NEVER (reject and mark as untrusted in the database)

5 -- TRUST_SESSION (accept now and throughout the current session)

6 -- TRUST_FAIL_SESSION (reject throughout the current session)

Usage

A PowerBuilder application does not usually call the TrustVerify function directly. TrustVerify is called by EAServer when the internal SSL trust verification check fails to verify the server's certificate chain or when the PIN to log in to the Sybase PKCS11 token was not supplied or incorrect. TrustVerify can be invoked when you are using any SSL protocol, because server authentication is a required step in the SSL handshake process.

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 TrustVerify, EAServer receives the CORBA::NO_IMPLEMENT exception and the connection is rejected.

To obtain a useful return value, provide the user with information about the reason for failure and ask the user to determine whether the server certificate chain can be trusted so that the session can continue. If the user specifies TRUST_FAIL or TRUST_ONCE, the function may be called again during the current session.

You can enable the user to cancel the attempt to connect by throwing an exception in this callback function. You need to catch the exception by wrapping the ConnectToServer function in a try-catch block.

Examples

This example checks whether the failure was called by a bad or missing PIN and returns TRUST_FAIL to call GetPin if it was. If not, it displays the reason why the server failed to verify the certificate chain and prompts the user to choose whether to continue with the session:

long       rc
string    stmp, stmp2
w_response w_ssl_response
string ls_rc

sslSessionInfo    mySessionInfo
rc = thesessioninfo._narrow(mySessionInfo, &
   "thesessioninfo")

is_tokenName = mySessionInfo.getProperty( "tokenName" )

CHOOSE CASE reason
CASE 4   MessageBox("The SSL session requires a PIN", &
      "Please enter the PIN for access to the " + &
      is_tokenName + " certificate database.")
   return 2
CASE 5   MessageBox("The PIN you entered is incorrect", &
   "Please reenter the PIN for access to the " + &
      is_tokenName + " certificate database.")
   return 2
CASE 1
      MessageBox("Certificate verification failed",  &
      "Server's certificate chain is incomplete.ORB " &
      + "~nis unable to complete the chain using the " &
      + "CA certificates in the " &
      + "~nSybase PKCS11 Token.")

CASE 2
      MessageBox("Certificate verification failed",  &
      "Server's certificate chain expired. One or " &
      + " more of the certificates in the " &
      + "chain is no longer valid.")      
CASE 3
      MessageBox("Certificate verification failed",  &
      "Server's certificate chain contains an " &
      + "unknown root certification authority. "  &
      + "This CA is not found in the trust data in " &
      + "the Sybase PKCS11 Token.")
END CHOOSE

sTmp  = "~nVersion: "
stmp += mySessionInfo.getProperty( "Version" )

sTmp  = "~nHost: "
stmp += mySessionInfo.getProperty( "host" )

stmp += "~nport: "
stmp += mySessionInfo.getProperty( "port" )
stmp += "~nciphersuite: "
stmp += mySessionInfo.getProperty( "ciphersuite" )
stmp += "~nCertificateLabel: "
stmp += mySessionInfo.getProperty( "certificateLabel" )
stmp += "~nUserData: "
stmp += mySessionInfo.getProperty( "UserData" )
stmp += "~ntokenName: "
stmp += mySessionInfo.getProperty( "tokenName" )
stmp += "~npkcs11Module: "
stmp += mySessionInfo.getProperty( "pkcs11Module" )
stmp += "~nPlease enter your choice: "
stmp += "~n 1: Accept this connection"
stmp += "~n 2: Reject this connection"
stmp += "~n 3: Accept this connection and mark CA as
   trusted"
stmp += "~n 4: Reject this connection and mark CA as
   untrusted"
stmp += "~n 5: Accept this CA throughout this session"
stmp += "~n 6: Reject this CA throughout this session"
// Display information in a response window and return
// response with CloseWithReturn
openwithparm(w_response, stmp)
ls_rc = Message.StringParm
return long(ls_rc)

See also

ConnectToServer (obsolete)

GetCertificateLabel (obsolete)

GetCredentialAttribute (obsolete)

GetPin (obsolete)