TrustVerify PowerScript function
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.
Controls
SSLCallBack objects
Syntax
|
1 |
<span>sslcallback</span>.<span>TrustVerify</span> ( <span>thesessioninfo, </span><span>reason </span>) |
|
Argument |
Description |
|---|---|
|
sslcallback |
An instance of a customized SSLCallBack |
|
thesessioninfo |
A CORBAObject that contains information |
|
reason |
A long value indicating the reason for
|
Return Values
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:
|
1 |
long rc<br>string stmp, stmp2<br>w_response w_ssl_response<br>string ls_rc<br> <br>sslSessionInfo    mySessionInfo<br>rc = thesessioninfo._narrow(mySessionInfo, &<br>   "thesessioninfo")<br> <br>is_tokenName = mySessionInfo.getProperty( "tokenName" )<br> <br>CHOOSE CASE reason<br>CASE 4<br>   MessageBox("The SSL session requires a PIN", &<br>      "Please enter the PIN for access to the " + &<br>      is_tokenName + " certificate database.")<br>   return 2<br>CASE 5<br>   MessageBox("The PIN you entered is incorrect", &<br> "Please reenter the PIN for access to the " + &<br> is_tokenName + " certificate database.")<br> return 2<br>CASE 1<br> MessageBox("Certificate verification failed", &<br> "Server's certificate chain is incomplete.ORB " &<br> + "~nis unable to complete the chain using the " &<br> + "CA certificates in the " &<br> + "~nSybase PKCS11 Token.")<br> |
|
1 |
CASE 2<br> MessageBox("Certificate verification failed", &<br> "Server's certificate chain expired. One or " &<br> + " more of the certificates in the " &<br> + "chain is no longer valid.") <br>CASE 3<br> MessageBox("Certificate verification failed", &<br> "Server's certificate chain contains an " &<br> + "unknown root certification authority. " &<br> + "This CA is not found in the trust data in " &<br> + "the Sybase PKCS11 Token.")<br>END CHOOSE<br> <br>sTmp = "~nVersion: "<br>stmp += mySessionInfo.getProperty( "Version" )<br> <br>sTmp = "~nHost: "<br>stmp += mySessionInfo.getProperty( "host" )<br> <br>stmp += "~nport: "<br>stmp += mySessionInfo.getProperty( "port" )<br>stmp += "~nciphersuite: "<br>stmp += mySessionInfo.getProperty( "ciphersuite" )<br>stmp += "~nCertificateLabel: "<br>stmp += mySessionInfo.getProperty( "certificateLabel" )<br>stmp += "~nUserData: "<br>stmp += mySessionInfo.getProperty( "UserData" )<br>stmp += "~ntokenName: "<br>stmp += mySessionInfo.getProperty( "tokenName" )<br>stmp += "~npkcs11Module: "<br>stmp += mySessionInfo.getProperty( "pkcs11Module" )<br>stmp += "~nPlease enter your choice: "<br>stmp += "~n 1: Accept this connection"<br>stmp += "~n 2: Reject this connection"<br>stmp += "~n 3: Accept this connection and mark CA as<br> trusted"<br>stmp += "~n 4: Reject this connection and mark CA as<br> untrusted"<br>stmp += "~n 5: Accept this CA throughout this session"<br>stmp += "~n 6: Reject this CA throughout this session"<br>// Display information in a response window and return<br>// response with CloseWithReturn<br>openwithparm(w_response, stmp)<br>ls_rc = Message.StringParm<br>return long(ls_rc) |