Implementing an SSL callback

When developing applications that interact with end users and support SSL, you should provide an SSL callback. The ORB invokes callback methods when required SSL settings have not been configured, or a setting has an incorrect value.

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 available certificates to the end user for them to choose. Lastly, the callback simplifies the handling of retry logic in the case where the user enters an invalid certificate password.

You can install a C++ callback or an ActiveX callback, but not both.

An ActiveX SSL callback must implement the methods in the CtsSecurity.SSLCallbackIntf interface. To install the callback, add a setting for the -ORBAXSSLCBComponent property in the ORB initialization string passed to the Orb.init method, as in the example below:

Dim orbOptions as String
orbOptions = "-ORBAXSSLCBComponent=mySSLCBProj.mySSLCBComponent,"
orbOptions = orbOptions & "-ORBqop=sybpks_intl"
Set orbRef = New JaguarTypeLibrary.ORB
orbRef.Init (orbOptions)

The SSLCallbackIntf methods are as follows:

getCertificateLabel Called when the session requires mutual authentication and a certificate label has not been provided in ORB properties or in SSLServiceProvider global properties.
The Visual Basic syntax of this method is:
```
Public Function getCertificateLabel( _
    ByVal sessionInfo As Object, _
    ByVal labels As JaguarTypeLibrary.JCollection _
    ) As String
```
where:
- sessionInfo contains details of the potential SSL session. You can retrieve information about the session using the getProperty method.
- labels is a JCollection containing available certificate labels. The callback must return one of them, or raise an ActiveX error to abort the connection attempt.

getCredentialAttribute Called when additional information is required to use an Entrust certificate, such as the path to the Entrust profile file, or the path to the entrust.ini file.

The Visual Basic syntax is:

Public Function getCredentialAttribute( _
    ByVal sessionInfo As CtsSecurity.SSLSessionInfo, _
    ByVal attr As Long, _
    ByVal attrValues As JaguarTypeLibrary.JCollection _
    ) As String

where:

sessionInfo contains details of the potential SSL session. You can retrieve information about the session using the getProperty method.

attr is one of the following numeric codes for the type of request:

Attr value	To request
CtsSecurity. CRED_ATTR_ENTRUST_INIFILE (1)	The full path and file name of the Entrust initialization file, which is usually %SYSTEMROOT%\entrust.ini.
CtsSecurity. CRED_ATTR_ENTRUST_USERPROFILE (2)	The full path and file name for the Entrust profile (.epf file).

attrValues is not currently used.

getCredentialAttribute must return a String containing the requested information, or raise an ActiveX error to abort the SSL session.

getPin Called when the certificate password has not been specified in ORB or SSLServiceProvider properties, or if the supplied password was incorrect.
The Visual Basic syntax of this method is:
```
Public Function getPin( _
    ByVal sessionInfo As Object, _
    ByVal timedOut As Boolean _
    ) As JaguarTypeLibrary.JCollection
```
where:
- sessionInfo contains details of the potential SSL session. You can retrieve information about the session using the getProperty method.
- timedOut value is true if a time limit was set for caching the certificate password and the time has expired (time limits are set as the loginTimeout property in the SSLServiceProvider interface).
The implementation should check the tokenName property of the SSLSessionInfo instance to determine whether the requested password is for the Sybase certificate database or for an Entrust profile, then clearly identify which password is required when prompting the user.

Your implementation can raise an ActiveX error to abort the connection attempt.

The getPin method must return the characters of the PIN as individual items in a JCollection instance. The following Visual Basic code shows how to populate a JCollection (coll in the example) with characters from a string (pin in the example):
```
Dim coll As JCollection
Set coll = New JCollection

Dim c As Byte
Dim iter As Integer
For iter = 1 To Len(pin)
  c = Asc(Mid(pin, iter, 1))
  coll.Item(iter - 1) = c
Next iter
```

trustVerify Called when the correct PIN for the certificate database has not been set, or if the server has presented a questionable certificate. The callback response determines whether the connection is allowed and, optionally, whether the certificate should be added to the local EAServer client certificate database.

The Visual Basic syntax of this method is:

Public Function trustVerify( _
    ByVal sessionInfo As CtsSecurity.SSLSessionInfo, _
    ByVal reason As Long _
    ) As Long

where:

sessionInfo contains details of the potential SSL session. You can retrieve information about the session using the getProperty method.

reason is a numeric code from Table 8-2:

**Table 8-2: trustVerify reason codes**
Reason code	Description
CtsSecurity. REASON_CHAIN_INCOMPLETE (1)	Server's certificate chain is incomplete. The ORB cannot complete the chain using the CA certificates in the Sybase certificate database.
CtsSecurity. REASON_UNKNOWN_CA (2)	The root CA in the server’s certificate chain is not listed in the Sybase certificate database.
CtsSecurity. REASON_CHAIN_EXPIRED (3)	At least one certificate in the server’s certificate chain has expired.
CtsSecurity. REASON_TRUSTDBPINNOTSET (4)	The password for the certificate database has not been set. Return CtsSecurity.TRUST_FAILED to cause the ORB to call the getPin callback method.
CtsSecurity. REASON_TRUSTDBLOGINFAILED (5)	The password for the certificate database was incorrect. Return CtsSecurity.TRUST_FAILED to cause the ORB to call the getPin callback method.

trustVerify must return one of the integer codes listed in Table 8-3:

**Table 8-3: trustVerify return codes**
Return code	Specified response
CtsSecurity.TRUST_ONCE (1)	Accept the certificate, but only trust for one SSL connection.
CtsSecurity.TRUST_FAIL (2)	Fail the session, or if the reason is REASON_TRUSTDBPINNOTSET (4) or REASON_TRUSTDBLOGINFAILED (5), call the getPin method.
CtsSecurity.TRUST_ALWAYS (3)	Accept the certificate and add the server’s CA to the list of trusted CAs in the Sybase certificate database.
CtsSecurity.TRUST_NEVER (4)	Reject the connection and mark the CA as not trusted in the Sybase certificate database.
CtsSecurity.TRUST_SESSION (5)	Trust the server certificate chain only during this client program’s sessions. If the client program is restarted, the certificate chain is not trusted.
CtsSecurity.TRUST_FAIL_SESSION (6)	Reject the certificate now and any time it reappears during the life of this client program. Do not mark the certificate as untrusted in the Sybase certificate database.

Your implementation of the getPin, getCertificateLabel, and getCredentialAttribute method should allow the user to cancel the connection attempt. In response to a user cancel, raise an ActiveX error exception to abort the SSL session. In Visual Basic, you can do this by raising an error with vbObjectError as the error number. If you provide an error description, and error logging has been enabled with the -ORBlogFile Orb property, the error description is written to the log. After an SSL session is cancelled, the client program receives a connection-fail error as it would from any other failed connection attempt.

For more information about these callback methods, see the documentation for the CtsSecurity::SSLCallback interface in the generated Interface Repository documentation.