Description
Called by EAServer to obtain a PIN for use with an SSL connection. This function is used by PowerBuilder clients connecting to EAServer.
Obsolete function
GetPin is obsolete, because EAServer is no longer supported since PowerBuilder 2017.
Applies to
SSLCallBack objects
Syntax
sslcallback.GetPin ( thesessioninfo, timedout )
|
Argument |
Description |
|---|---|
|
sslcallback |
An instance of a customized SSLCallBack object. |
|
thesessioninfo |
A CORBAObject that contains information about the SSL session. This information can optionally be displayed to the user to provide details about the session. |
|
timedout |
A boolean value that indicates the reason for the callback. A value of true indicates that the PIN timed out and must be obtained again. A value of false indicates that the PIN was not specified at the time of the SSL connection. |
Return value
String.
Returns the PIN specified by the user.
Usage
A PowerBuilder application does not usually call the GetPin function directly. GetPin is called by EAServer when an EAServer client has not specified a PIN for logging in to a PKCS 11 token for an SSL connection.
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 GetPin, EAServer receives the CORBA::NO_IMPLEMENT exception and an empty string is returned. To obtain a useful return value, code the function to request the user to provide a PIN. You can supply information to the user such as the token name from the passed thesessioninfo object.
If an incorrect PIN or an empty string is returned, EAServer invokes the TrustVerify callback.
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 prompts the user to enter a PIN for a new SSL session or when a session has timed out. In practice you would want to replace the user's entry in the text box with asterisks and allow the user more than one attempt to enter a correct PIN:
//instance variables
//string is_tokenName
//SSLServiceProvider issp_jag
CTSSecurity_sslSessionInfo mySessionInfo
is_tokenName = mySessionInfo.getProperty( "tokenName" )
w_response w_pin
IF timedout THEN
MessageBox("The SSL session has expired", &
"Please reenter the PIN for access to the " + &
ls_tokenName + " certificate database.")
ELSE
MessageBox("The SSL session requires a PIN", &
"Please enter the PIN for access to the " + &
ls_tokenName + " certificate database.")
END IF
string s_PIN
userabortedexception ue_cancelled
// open prompt for PIN
Open(w_pin)
// get value entered
s_PIN = Message.StringParm
// set property if we're not to abort
if s_PIN <> ABORT_VALUE then
issp_jag.setglobalproperty("pin", s_PIN)
// otherwise, abort..
else
ue_cancelled = CREATE userabortedexception
ue_cancelled.text = "User cancelled request when " &
+ "asked for PIN."
throw ue_cancelled
end if
return s_PINSee also
GetCertificateLabel (obsolete)
