GetCertificateLabel PowerScript function
Description
Called by EAServer to
allow the user to select one of the available SSL certificate labels
for authentication. This function is used by PowerBuilder clients
connecting to EAServer.
Controls
SSLCallBack objects
Syntax
|
1 |
<span>sslcallback</span>.<span>GetCertificateLabel</span> ( <span>thesessioninfo, </span><span>labels </span>) |
|
Argument |
Description |
|---|---|
|
sslcallback |
An instance of a customized SSLCallBack |
|
thesessioninfo |
A CORBAObject that contains information |
|
labels |
An array of string values that contains |
Return Values
String. Returns one of the labels passed
to the function.
Usage
A PowerBuilder application does not usually call the GetCertificateLabel function
directly. GetCertificateLabel is called by EAServer when an EAServer client has not specified
a certificate label for an SSL connection that requires it.
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 GetCertificateLabel, EAServer receives the CORBA::NO_IMPLEMENT exception
and the default implementation of this callback is used. The default
implementation always returns the first certificate in the list
of labels. If no labels are supplied, the CtsSecurity::NoCertificateException is
raised. Any exceptions that may be raised by the function should
be added to its prototype.
If your implementation of the callback returns an empty string,
the default implementation described above is used and the first
certificate label in the list is returned. If the server requires
mutual authentication and that certificate is acceptable to the
server, the connection proceeds. If the certificate is not acceptable,
the connection is refused.
To obtain a useful return value, provide the user with available
certificate labels from the labels array passed
to the function and ask the user to select one of them. You can
also supply additional information obtained from the passed thesessioninfo object.
You can enable the user to cancel the attempt to connect by
throwing an exception in this callback function. All exceptions
thrown in SSLCallback functions return a CTSSecurity::UserAbortedException to
the server. You need to catch the exception by wrapping the ConnectToServer function
in a try-catch block.
Examples
This example checks whether any certificate labels
are available. To give the user more context, it displays host and
port information obtained from the SSL session information object
in the message box that informs the user that no certificates are
available. If certificates are available, it opens a response window
that displays available certificate labels.
The response window returns the text of the selected item
using CloseWithReturn:
|
1 |
int idx, numLabels<br>long rc<br>String ls_rc, sText, sLocation<br>w_response w_ssl_response<br>CTSSecurity_sslSessionInfo mySessionInfo<br> <br>rc = thesessioninfo._narrow(mySessionInfo, &<br>   "SessionInfo" )<br>sLocation = mySessionInfo.getProperty( "host" ) + &<br>   ":" + mySessionInfo.getProperty( "port" )<br>numLabels = upperbound(labels)<br> <br>IF numLabels <= 0 THEN<br> MessageBox ("Personal certificate required", &<br> "A certificate is required for connection to " &<br> + sLocation + "~nNo certificates are available")<br> ls_rc = "" <br>ELSE <br> sText = "Available certificates: "<br> FOR idx=1 to numLabels<br> sText += "~nCertificate[" + & <br> string(idx) + "]: " + labels[idx]<br> NEXT<br> OpenWithParm( w_ssl_response, SText )<br> ls_rc = Message.StringParm |
|
1 |
<br> IF ls_rc = "cancel" then <br>   userabortedexception uae<br>   uae = create userabortedexception<br>   uae.setmessage("User cancelled connection" &<br> + " when asked for certificate")<br>   throw uae<br> END IF<br>END IF<br>RETURN ls_rc |