The PC Integration API allows you to integrate your browser screens with PC applications. For example, you may have the need to call up your PC-based imaging or document management application to view an invoice, part image, etc., based on a user action in the browser screen. The PC Integration API also allows you to copy data to the PC's clipboard. Genie's STRPCCMD command support also makes use of the PC Integration API.

For obvious security reasons, the browser vendors have made it so that Web-based applications cannot call programs on the PC under normal security settings. This makes it challenging to integrate your browser-based screens with other applications in your environment. The PC Integration API solves this challenge by running the PC commands in either a separately installed PC program (PC Command Listener or PC Command Launcher) a Java applet (PC Integration Applet). 

One of the following alternatives must be configured on the end user PC's before the PC Integration API can be used.

When Possible, use Hyperlinks, IFrames, or JavaScript

If your server-side program is calling STRPCCMD to load web pages or files that a web browser can reach, then you do not need the PC Integration API. Instead the best approach is to use HTML and JavaScript (i.e. Profound UI widgets and APIs) to load the URL in a new tab or window in the user's browser. Using a standard web approach avoids the need to install or configure additional software on each user's PC.

There are at least three ways to use the web approach. Each method below involves binding a field in the Rich Display File, changing the server-side program to write the URL to that field instead of calling STRPCCMD, and letting some client-side code handle the bound field data.

1. Bind a Hyperlink widget's "hyperlink reference" property to a field, and change the server-side program to write the URL to the field. Then, the user can click on the hyperlink to load the URL. Set the hyperlink widget's "target" property to "_blank" to open in a new browser tab/window.
2. Bind an IFrame widget's "iframe url" property to a field, and change the server-side program to write to the field. This make a page inside a page. You may need to re-arrange the Rich Display File so that there is space to show the IFrame.
3. Bind a hidden output field's "value" property to a field, and change the server-side program to write the URL to that field. Write custom JavaScript code in the record-format's "onload" property to call window.open.

The widgets can be hidden conditionally until ready by binding the "visibility" property.

Note: when writing a URL to a field, you omit commands like "START IEXPLORE.EXE"; just write the URL. which is the part beginning with "http://" or "https://".

If your server-side logic wants to open a program on the user's machine that cannot be accomplished using standard web technology, then read below in either the PC Command Listener or Launcher.

PC Command Listener

The PC Command Listener is the default mode in Profound UI versions later than 6 Fix Pack 6.0. The Listener enables the PC Integration API to function in any web browser. However, this must be installed separately on end user PCs. The PC Command Listener works by running an embedded HTTP server on the PC that binds on the IP loopback address and configurable port. The PC Integration JavaScript API then communicates with the Listener using standard HTTP communications.

PC Requirements

The PC Command Listener runs on any Windows Vista, 8, 7, or 10 PC. 

Installing and Configuring the PC Command Listener on the PC

This is a standard Windows program installer that works in the typical way. The program is installed for all PC users and registers itself to run on Windows startup. The program runs in the System Tray. The tray icon has a context menu that can be used to start/stop the listener and to configure the port number.

PC Command Listener Command-line Installation

The MSI installation package can also be run from a command prompt or script using the Windows 'msiexec' command. When installing using 'msiexec' the configuration data can be passed on the command line using the --CONFIG parameter. The configuration will be written to the PC's program data directory, which is shared by all PC users. For example, to set the listen port to 8100, disable notification messages, and disable logging:

msiexec /package pccommand-listener-setup.msi CONFIG={\"notifications\":false,\"port\":8100,\"log commands\":false}

PC Command Listener Logging

By default, PC Command Listener does not log any information regarding the commands it receives. As of Launcher version 1.0.10, the Listener can be configured to log the commands received. Logging can be enabled via the Listener's System Tray context menu under "Configure...". Alternately, the "log commands" property can be passed in an argument to the "msiexec" command as indicated in the section above.

The log file will either be located here:

%ALLUSERSPROFILE%\Profound UI\pccommand-listener-log.txt

or here

%APPDATA%\Profound UI\pccommand-listener-log.txt

Configuring the Server for the PC Command Listener

In the latest versions of Profound UI set the configuration option, PC Command Mode, to the Listener; e.g. pui["pc command mode"] = 2;

In Profound UI versions Release 6 Fix Pack 6.0 and earlier, the default mode of operation for the PC Integration API is to use the Java applet. In those versions the configuration option pui["use pc listener"] must be set in order to use the Listener.

With all versions, optionally pui["pc listener port"] must be set in order to use the Listener, depending on which TCP port your Profound UI instance expects the listener on. Options to configure the PC Command Listener are also provided in the Genie Administrator. If specified, these will take precedence.

(Profound UI Version 5, Fix Pack 12.0 and earlier)

PC Command Listener on HTTPS (SSL) Servers

To enable a Rich Display session running on HTTPS to send commands to the Listener, the configuration option PC Command Mode must be set to the listener mode 2 (e.g. pui["pc command mode"] = 2). Genie automatically detects when the site is using HTTPS, so that option isn't necessary for Genie.

(In older versions of Profound UI the SSL option for the Listener was PC Listener Mode.)

PC Command Listener Security

By default and in older versions of the PC Command Listener than 1.1.0, the Listener runs commands sent to it from any website that knows its port and the format of the commands. That configuration could potentially be exploited by malicious actors who know the port used by the PC Command Listener and the command format. Version 1.1.0 of the Listener* addresses that security concern with the ability to verify that commands were sent from a trusted source. *PC Command Listener 1.1.0 was released February 16, 2023.

The trust verification happens via public key cryptography. With public key cryptography, a private and corresponding public key get generated. They are mathematically linked, and someone cannot use the public key to determine the private key. The private key is kept secret and can "sign" data–i.e. perform a one-way calculation on the data that cannot be reproduced without the private key. The public key can be safely shared with anyone and is used to verify the generated signature. The public key will only verify data that was signed by the its matching private key.

Creating the public/private key pair is a one-time operation. Distributing the public key to users can be automated. Once the keys are in place, then signing and verification happen automatically.

In Profound UI and the PC Command listener, the private RSA key remains on the Profound UI server in some private location. Presuming that only trusted admins can setup the private key, then trust in the key is established--the server can generate signatures that clients can trust. In fact, the server will only generate signatures for authenticated users with active Profound UI sessions. The public RSA key gets stored with each user's PC Command Listener program running on their PCs. Using the public key, the Listener can only verify commands signed by the trusted private key. Therefore, only trusted websites running Profound UI will cause commands to run on a user's PC.

Releases of Profound UI newer than Version 6 Fix Pack 20.0 can be configured to sign commands for the PC Command Listener.

Generating RSA Key Pairs

The private and public RSA key pair can be generated many ways, in multiple programming language APIs. Better yet, a free, open-source tool, OpenSSL can be used to generate the key pairs. OpenSSL can be obtained on the IBM i via "yum" or on other platforms via open-source package managers.

A sample script below is provided for generating RSA key pairs on an IBM i system in the PASE environment that already has "yum" and "openssl" installed.

#!/bin/bash
# Generate private and public key pair for the PC Command Listener. 

# Stop on error
set -e

privkeydir="/profoundui"
pubkeydir="/www/profoundui/htdocs"

[[ ! -d "$privkeydir" ]] && mkdir "$privkeydir"
cd "$privkeydir"

# Generate a 4096-bit private RSA key.
echo -n "Generating Private RSA key. This will take a few seconds..."
openssl genrsa -out "$privkeydir/pccmd-priv.pem" 4096
echo "done"

# OpenSSL "genrsa" outputs in the ASCII PEM format. Profound UI requires the key 
# to be in a binary DER format.
# Convert the PEM key to the DER format so that Profound UI can use it.
#
openssl rsa -inform PEM -outform DER -in "$privkeydir/pccmd-priv.pem" -out "$privkeydir/pccmd-priv.der"
# The HTTP server must have read access for the private key in order for a PUI CGI program to read it.
# Make sure the key directory is in a location that is outside the DocumentRoot.
chown qtmhhtp1 pccmd-priv.der
  
# Next, export the public key so that the PC Command Listener can use it. The PC
# Command Listener expects a public key in a PEM format. Store the public key in 
# a location that the Listener clients can download when they run.
openssl rsa -inform DER -in "$privkeydir/pccmd-priv.der" -outform PEM -pubout -out "$pubkeydir/pccmd-pub.pem"

echo "  Private key: $privkeydir/pccmd-priv.der"
echo "  Public key: $pubkeydir/pccmd-pub.pem"
echo "Finished."

exit 0

The private key file must be stored in the binary DER or BER formats. BER and DER keys are similar and can both be used. A key generated into PEM format can be converted into DER using the open source "openssl" tool, as the script above demonstrates.

The HTTP server providing the Profound UI instance must have "read" permission on the private key file so that the CGI programs reading the private certificate can add a cryptographic signature to the command string.

Private Key File Location

Profound UI by default will look in the IFS for a private RSA key file, "/profoundui/pccmd-priv.der", in a directory that should not be publicly accessible. If the private key file is stored in another IFS location, then add this configuration option to the Profound UI instance's HTTP server configuration:

SetEnv PUI_PCCMD_PRIV_KEY "/some-secret-location/your-file-name-here"

Changes to an HTTP server config file, httpd.conf, require a HTTP server restart for that Profound UI instance.

Important: make sure that the private key file is not in some location that is publicly accessible. E.g. the file should never be in a sub-directory of a document root, such as /www/profoundui/htdocs/. (The public key, however, can exist in a publicly accessible location.)

Enabling Signature Verification in Profound UI

To get an instance of Profound UI to sign commands using cryptography, the PC Command Mode configuration option must be set. Two modes will add signature verification. For example:

pui["pc command mode"] = "listener_m1s";  //The web page attempts to send a command and signature to the PC Listener program.
pui["pc command mode"] = "listener_m2s";  //Mode 2, which makes the listener work on HTTPS (SSL) pages as well as HTTP pages

See PC Command Mode for more information.

PC Command Listener Security Configuration

Configuration options for public keys for the PC Command Listener program are explained below:

• "public key"

  • "" – (default) A blank string. The Listener does not attempt to verify command signatures. Any command sent to it is run.

  • "local" – The listener attempts to find a file named "pccmd-pub.pem" in the %ALLUSERSPROFILE%\Profound UI\ or %APPDATA%\Profound UI\ directories.
    • If the file does not exist, then the Listener will reject the command.
    • The user/admin is responsible for obtaining the public key and storing it in the correct location on each end user's PC.
  • A public key in PEM form, formatted to fit in a JSON string.
    • e.g. "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQ ... AwEAAQ==\n-----END PUBLIC KEY-----\n"
    • The key string can be distributed via the "CONFIG" parameter for the MSI installation (see section on installation above).
  • A URL pointing to a file where the public key can be downloaded.
    • e.g. "http://yourServer:8080/profoundui/pccmd-pub.pem"
    • When it starts, the PC Command Listener downloads the key file from that URL and keeps it in memory.
    • This is the easiest public key distribution approach.
    • The key file is not cached, allowing system administrators to generate new keys periodically if desired. (Though, note that guessing a private key using many bits, such as 4096, would take billions of years using current computing technology.)
    • The configuration value can be set via the "CONFIG" parameter for the MSI installation (see section on installation above).
• "verify algorithm" – When public keys are used, then the this option specifies an algorithm to use as part of verifying the signature. Not only must the private and public keys match, the hashing algorithm used to verify a signature must be the same algorithm used to generate the signature. Few people will need to change the algorithm. Typically, older algorithms are less secure.
  
  • "" – (default) a blank string. In this case, the algorithm used is SHA-512 ("sha512").
  • Other options that can be specified: "sha512", "sha384", "sha256", "sha224", "sha1", "md5"

Server-side Hash Algorithm

Most people do not need to change the hashing algorithm used in generating signatures. The hashing algorithm on the server must be the same type as the "verify algorithm" used in the PC Listener program. The server algorithm can be set using a JavaScript configuration option, e.g. in htdocs/profoundui/userdata/custom/js/settings.js:

pui["pccmd hash sign algorithm"] = "SHA-512";

For the server, the valid values for hashing algorithm are: SHA-512, SHA-384, SHA-256, SHA-224, SHA-1, and MD5 . The default is SHA-512.

Because the option is in the JavaScript, the keys can be changed to use a different algorithm without restarting the Profound UI instance.

PC Command Launcher

The PC Command Launcher is an alternative to the Command Listener and the applet. The Launcher enables the PC Integration API to function in any web browser, in HTTP or HTTPS (SSL) pages, and in browsers running in Terminal Services sessions. However, as with the Listener, a program must be installed separately on end user PCs. Another disadvantage is that the Integration API gets no feedback about the command's status. If the command fails to run, then the API doesn't know. Consequently, the command "wait" is not implemented. Each command is executed as soon as it is received, and no commands can wait until the previous command finished.

Once the PC Command Launcher program is installed on a PC, the Launcher will handle any requests to a custom protocol. The Integration API will open a custom URL containing some encrypted information with the command, and the browser will attempt to run the Launcher. There is no interface to the PC Command Launcher. However, the first time a PC Command is sent via the Launcher mode, the browser will prompt the user before running the launcher:

If your web browser supports it, the user can check the "Always open these types of links in the associate app" checkbox and then click the "Open..." option, so that they will no longer be prompted before the command runs. 

PC Command Launcher works with Profound UI Version 5, Fix Pack 13.0 and later.

Installing and Configuring the PC Command Launcher on the PC

The download is a standard Windows program installer that works in the typical way. The program is installed for all PC users.

PC Command Launcher Command-line Installation

The installer package can be installed from a Windows command line without displaying an interface. For example, do an install with no UI:

msiexec /i pccommand-launcher-setup.msi /quiet

The installer needs administrative privileges.

Configuring the Server for the PC Command Launcher

The default mode of operation for the PC Integration API is to use the PC Command Listener. To use the PC Command Launcher, pui["pc command mode"] must be set to "launcher". Options to configure the PC Command Listener are also provided in the Genie Administrator. If specified, PC Command Mode will override "pc listener mode" and "pc listener" options. 

Enable Logging for PC Command Launcher

By default, the Launcher does not track any information about the commands it receives. As of Launcher version 1.0.2, the Launcher can be configured to log the commands received. A log may assist in debugging commands sent from the IBM i, or logs can be reviewed for security auditing.

To enable logging, a Windows Registry key must be modified: Computer\HKEY_CLASSES_ROOT\puilaunch\Shell\Open\Command. A flag, "/logtofile", must be added to the end of the (default) entry in that key.

"C:\Program Files (x86)\Profound UI\PC Command Launcher\pccommand-launcher.exe" "%1" /logtofile

The log is saved to the Windows "All Users" folder, %ProgramData%, which is usually c:\ProgramData and hidden from most users. The log file is %ProgramData%\Profound UI\Logs\pccommand-launcher.txt. The date and the PC user's username appear first, then the unencrypted command or filename received. If the command fails, then an error code is also recorded.

Uninstalling the PC Command Launcher from the PC

The launcher can be uninstalled like any other program, using Windows' Add/Remove Programs:

Or the Windows Control Panel:

PC Integration Applet

The applet was the original mode of operation. However, this is being phased out as browser vendors drop support for the Java plug-in. The applet is digitally signed so the end-user's PC can trust the applet to call programs on the PC. The applet is a piece of Java code, but no Java programming is required to use it. The applet is packaged into a JAR file that is placed on your server's file system, and downloaded by the user's browser through the HTTP server. There is a JavaScript function provided that you can use to easily load the applet in your browser page. Once this is done, you can access the applet's functionality using simple JavaScript API that are provided.

PC Requirements

The PC Integration applet runs in the Java Virtual Machine's browser plug-in on the end user's PC. The only current browser that supports the Java plug-in is Internet Explorer. Chrome, Firefox, and Edge do not support the Java plug-in. 

Installing PC Java Plug-in and Verifying Version

As mentioned above, the Sun plug-in is required. The user can verify the version and install it if necessary at this URL: http://www.java.com.

1. Click on the "Do I have Java?" hyperlink to test the version.
2. This brings up the verification page. If the latest version of Sun Java is installed, a "congratulations" message will appear.

Related Videos