Using SSL callbacks
The SSLCallback object
handles SSL requests for additional authentication information from
a server to a client application. The C++ ORB
invokes callback methods when a required setting, such as a pin,
has not been specified, or when the value specified is invalid.
The callback can respond to exceptional conditions, such as
server certificates that have expired. When using mutual authentication,
the callback getCertificateLabel method allows
you to present a list of available certificates to the user. Using
a callback can also simplify handling of retry logic when the user
enters an invalid certificate or password.
To use the SSL callback mechanism, you need to follow these
steps:
- Create proxy objects for the
CTS Security module in EAServer to
obtain SSL session information. - Create a standard custom class user object inherited
from the SSLCallback object and implement the callback functions
you need. - Set the global SSL property CallBackImpl to the
name of your SSLCallback object and connect to the server.
Getting session information
SSL callback functions all have access to the SSL session
information. You should use this information to provide the user
of the client application with information needed to supply the
required authentication information.
To make the SSL session information available to the callback
functions, create an EAServer proxy
for the CTSSecurity module.
To create a proxy for the CTSSecurity module:
-
Select the EAServer Proxy
wizard from the Project page in the New dialog box and select your
client application target from the Target drop-down list. -
Connect to any EAServer host
and select the CTSSecurity module.The CTSSecurity module is a standard module that is available
on all servers. -
Complete the wizard and build the project.
Among the proxy objects you will see in the System Tree is
the Sessioninfo object that is passed to all the SSLCallback functions.
Implementing the SSLCallback object
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 |
| 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 |
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.
Default implementations
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.
Handling exceptions
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.
Specifying the SSLCallback object
Before you connect to the server, specify the name of your
SSLCallback object in the CallbackImpl property of SSLServiceProvider:
|
1 |
SSLServiceProvider sp<br />int rc<br /><br />getcontextservice("SSLServiceProvider", sp)<br />rc = sp.setglobalproperty( "CallbackImpl", &<br /> "uo_sslcallback" )<br />IF rc <> 0 THEN<br /> MessageBox("Set CallbackImpl Failed", "rc= " + &<br /> string(rc)) <br /> RETURN<br />END IF<br />MessageBox( "Set CallbackImpl Property", "succeeded" )<br />RETURN |
To make sure that the executable version of your client application
can reference your callback object, you need to declare a variable
of its type in your application, for example:
|
1 |
uo_sslcallback iuo_sslcb |
This is because the callback object
is referenced only by its string name so that it is technically
an unreferenced object and is not included in the executable file.
Your code does not need to use the declared variable.