Technology and Community

Jim O'Neil

Subscribe to Jim O'Neil: eMailAlertsEmail Alerts
Get Jim O'Neil: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn


Related Topics: Java EE Journal

J2EE Journal: Article

PowerBuilder and EAServer: Uniting the .NET and J2EE Communities

Continuing their legacy of synergy and openness

Whether the security attributes are provided explicitly or via the SSLCallback mechanism, the remaining code to connect to the server, instantiate the proxies, and execute component methods remains the same as when accessing a non-secure connection – with the exception, of course, that an IIOPS versus IIOP port must be specified in the server URL.

.NET Targets
For .NET clients, installation of the EAServer Client Runtime is not required. The only runtime components needed are the two .NET assemblies discussed at the beginning of the article. The Windows operating system manages the certificate files, configured via the Microsoft Management Console (MMC). Generally, the files will be made available by the EAServer administrator or obtained from the certificate authority that issued the credentials.

For the purposes of this article and the associated sample application on CodeXchange, we’ll use the sample certificates already installed in EAServer; however, since the standalone files are not distributed with the product, the certificates need to be extracted from the EAServer certificate store. The JSSE keystore is located in the Repository/Security/keystore.jks file of the EAServer installation. You can use the Java keytool utility, which is part of the Java Runtime Environment (JRE), to examine and extract certificates from that repository. However, keytool does not provide for exporting private keys from the certificate store, so you cannot use it to obtain the client certificate file needed for mutual authentication. There are alternative tools available such as the open source Portecle application to do so.

Using Portecle, you can browse to the keystore.jks file, provide a password of ‘changeit’ when prompted, and view the certificates in that store. As shown in Figure 3, you can use the Export option on the context menu to save a specific certificate as a standalone file.

For the sample1 certificate:

  • Select the option to save Private Key and Certificates (see Figure 4). The private key is needed since we’ll use sample1 as the client certificate for mutual authentication.
  • When prompted for a Key Pair Entry Password, enter ‘changeit’ (the keystore password).
  • Optionally enter a password to associate with the exported PCKS #12 file (see Figure 5). The code examples later in this article presume that you’ve set a password of “pbdj.”

For the sample2 certificate, simply select Certificate Chain as the Export Type; there are no further prompts for passwords. Once you have saved the two certificate files, transfer them to the client machine.

To install the certificates on the client machine, select Start>Run from the Windows task bar and enter “mmc” as the application to open. This will launch the default MMC console to which you’ll need to add the Certificates snap-in via the File>Add/Remove Snap-in menu item. When adding the snap-in, you’ll be asked for which account the snap-in should manage certificates; select the Computer account for the local computer to make the certificates available to all users of the client machine.

Once the snap-in has been configured, you should see something similar to Figure 6 (which shows the Sample1 Test ID has already been added). To add additional certificates, such as Sample2 Test ID:

  • Select the appropriate certificate folder (the Personal folder in this case)
  • Right-mouse click and select All Tasks>Import from the context menu
  • Complete the Certificate Import Wizard, which prompts for the certificate file name and a password (for PKCS #12 certificates only).

Assuming there were no errors and the certificates successfully imported, the security configuration for your .NET applications is nearly complete. If you are accessing EAServer from within a Web Forms application or .NET Web Service and require mutual authentication, an additional configuration step is required to grant the ASP .NET process permission to access the client certificate’s private key.

To perform this final configuration step, download and install the Windows HTTP Services Certificate Configuration Tool from the Microsoft Web site. By default, this command-line tool (winhttpcertcfg.exe) will be placed in the \Program Files\Windows Resource Kits\Tools directory. The utility has a number of command-line options used to control access to client certificates by user account. The specific parameters relevant for PowerBuilder Web Forms and Web Services are summarized in Table 3.

On a Windows XP machine, for instance, you would issue the following command to grant the ASP.NET process access to the Sample1 Test ID client certificate for mutual authentication to EAServer:

winhttpcertcfg -g -c LOCAL_MACHINE\MY -s “Sample1 Test ID” -a “ASPNET”

In terms of the .NET client application logic, the code to access an EAServer instance configured for server authentication is no different from the code to access a non-secure connection (with the exception of the port designation of course). Contrast this to Win32 client applications, where a secure connection additionally requires configuration of the ORBqop and ORBpin options or implementation of an SSLCallback mechanism, as well as deployment of the EAServer Client Runtime.

However, when using mutual authentication with .NET client applications, there are two items that must be specified in either the Connection or JaguarORB object’s options property (see Table 4).

These values are analogous to the ORBCertificateLabel setting required for mutual authentication in Win32 client applications and would be set as shown in the following line of code (N.B., these option names are case-sensitive):

orb.options = “ORBclientCertificateFile=”+
“‘c:\easclient\sample1.p12’,” +
“ORBclientCertificatePassword=’pbdj’”

Summary
With the PowerBuilder 11.2 and EAServer 6.1 releases, these products continue their legacy of synergy and openness into the .NET world. Existing PowerBuilder applications that access J2EE resources in EAServer can now be deployed as .NET targets generally with few or even no changes in the PowerScript code. In fact, the two most significant differences affecting EAServer client applications in a .NET environment are the streamlined deployment requirements and the procedures to configure certificate stores on the Windows operating system.

More Stories By Jim O'Neil

Jim is a Technology Evangelist for Microsoft who covers the Northeast District, namely, New England and upstate New York. He is focused on engaging with the development community in the area through user groups, code camps, BarCamps, Microsoft-sponsored events, etc., and just in general serve as ambassador for Microsoft. Since 2009, Jim has been focusing on software development scenarios using cloud computing and Windows Azure. You can follow Jim on Twitter at @jimoneil

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.