Establishing a secure connection

To establish a secure connection to EAServer, follow these steps:

Create an instance of the SSLServiceProvider object.
Optionally use the GetGlobalProperty function to obtain security information from the server.
Set properties required by the server using the SetGlobalProperty function.
Connect to the server using the ConnectToServer function of the Connection object.

Creating an instance of SSLServiceProvider

This code creates an instance of the SSLServiceProvider object:

SSLServiceProvider sp
GetContextService( "SSLServiceProvider", sp )

Getting information from the server

Use GetGlobalProperty to obtain information about the security characteristics of the server. This example gets information about supported CipherSuites from the availableQop property, and displays the information in a drop-down list:

int i, rc
string ls_values[]

rc = sp.GetGlobalProperty("availableQop", ls_values)

IF rc <> 0 THEN
   MessageBox("Get Qop Failed", "rc = " + string(rc))
   RETURN
END IF

FOR i = 1 to UpperBound(ls_values)
   ddlb_1.AddItem( ls_values[i] )
NEXT
RETURN

Setting global properties

Before you connect to the server, you must set required global properties. This code sets qop to the value sybpks_intl and pin to the value sybase:

int rc

rc = sp.SetGlobalProperty( "qop", "sybpks_intl" )
IF rc <> 0 THEN
   MessageBox( "Setting QOP Failed", &
      "rc = " + string(rc) )
ELSE
   MessageBox( "Set SSL QOP Property", "succeeded" )
END IF
rc = sp.SetGlobalProperty( "pin", "sybase" )
IF rc <> 0 THEN
   MessageBox( "Setting PIN Failed", &
      "rc = " + string(rc) )
ELSE
   MessageBox( "Set SSL PIN Property", "succeeded" )
END IF

Most of the properties set using SetGlobalProperty can be set only once for the lifetime of the client executable. The properties remain in effect when the client disconnects from or reconnects to the server.

Restarting PowerBuilder When you run a client application in PowerBuilder, you can set global properties only once during the PowerBuilder session. You will need to restart PowerBuilder each time you test the code that sets global SSL properties.

If you want to use an instance of the SSLCallback object to obtain user input interactively, you need to set the global property CallBackImpl. See “Using SSL callbacks”.

Connecting to the server

When you begin a secure session, the client and server exchange messages in the SSL handshake process. The client provides information that the server needs in order to communicate with the server, then the server must always authenticate itself to the client before the process can continue. If the server requires client authentication, the client must be authenticated before the process can continue. When the required authentication is complete, the client and server create symmetric keys that will be used for encryption, decryption, and tamper detection in the SSL session. To catch any exceptions that are raised during this process, you should enclose the ConnectToServer call in a try-catch block.

When you establish a secure connection, use iiops instead of iiop in the location property of the connection object. The server typically listens for secure connections on ports 9001 or 9002. This example uses a Connection object, g_connect, that has been declared as a global variable. The example uses the options property of the Connection object to specify a different CypherSuite for this connection:

long l_rc
g_connect.userid   = sle_user.text
g_connect.password = sle_password.text
g_connect.driver   = "jaguar"
g_connect.application = "myserverpkg"
g_connect.location = "iiops://myserver:9001"
g_connect.options = "ORBqop='sybpks_simple'"

TRY
   l_rc = g_connect.ConnectToServer()
CATCH (userabortedexception uae)   
   MessageBox("UserAbortedException Caught", &
      "ConnectToServer caught: " +  uae.getMessage() )
   l_rc = 999

CATCH ( CORBASystemException cse )
   MessageBox("CORBASystemException Caught", &
      "ConnectToServer caught: " +  cse.getMessage() )
   l_rc = 998
END TRY
IF l_rc <> 0 THEN
   MessageBox("Error", "Connection Failed - code: " &
      + string(l_rc) )
   MessageBox("Error Info", "ErrorCode= " &
      + string(g_connect.ErrCode) + "~nErrText= " &
      + g_connect.ErrText)
ELSE
   MessageBox("OK", "Connection Established")
END IF

Troubleshooting connections

When a secure connection fails, the error message that displays is the same as for insecure connections. It does not provide any additional information about the reason for failure. To obtain more information in a log file, you can enable the ORBLogIIOP option and specify a value for the ORBLogFile option. In the example above, you would replace the g_connect.options statement with something like this:

g_connect.options = "ORBqop='sybpks_simple'" + &
  "ORBLogIIOP='TRUE', ORBLogFile='d:\temp\ORBLog.txt'"

Alternatively, you can set the JAG_LOGFILE environment variable to specify the log file in which initialization errors are recorded.