There are four callback functions.
Function |
When it is called |
|---|---|
GetCertificateLabel |
Called when the client application has not set a certificate label for client authentication and the server has requested client authentication. |
GetCredentialAttribute |
Called when the client application has not set credential attributes. These attributes are used when the client application has set the UseEntrustId property using the SSLServiceProvider object. GetCredentialAttribute is useful only if you are using Entrust IDs. For more information about Entrust and PKCS 11 tokens, see the EAServer Security Administration and Programming Guide. |
GetPin |
Called if the PKCS11 token is not logged in and the PIN has not been set as a property of the SSLServiceProvider object. It can also be called if the login session has timed out. |
TrustVerify |
Called when the server’s 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 is incorrect. TrustVerify can be invoked when you are using any SSL protocol, because server authentication is a required step in the SSL handshake process. The user can choose whether to override the internal check and proceed with the SSL connection. |
Each of these functions is implemented by the SSLCallback class and has a default implementation. You need to implement any function for which you want to use the callback. For sample implementations of each function, see the PowerScript Reference or the online Help.
To implement the SSLCallBack class:
Select Standard Class from the PBObject page of the New dialog box.
Select SSLCallback in the Select Standard Class Type dialog box and click OK.
Code a callback function to provide the user with information about the session and prompt the user to return the required authentication information.
Repeat step 3 for any other callback functions you want to implement.
If you do not provide an implementation, or if your implementation returns an empty string, the default implementation of the callback is used.
For both GetCertificateLabel and GetCredentialAttribute, the argument list includes an array of string values that are valid return values for the callback. The default implementation of these callbacks throws an exception if the array is empty, and returns the first value in the array if it exists. As a result, the connection process continues if the first value in the array is acceptable to the server, but fails if the value is unacceptable.
For TrustVerify, the default implementation rejects the current connection.
Your implementation of GetPin, GetCertificateLabel, and GetCredentialAttribute should allow users to cancel the connection if they are unable to provide the requested information. You can do this by throwing an exception in your implementation of the function and catching it in a try-catch block that surrounds the call to ConnectToServer. Exceptions thrown in any of the callback functions raise the CTSSecurity::UserAbortedException exception. You should add any exceptions that can be thrown by the function to the throws clause of the function’s prototype.
