...

...

...

...

...

...

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 STRPCCMDcommand 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.

...

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

...

...

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.

...

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

Installing and Configuring the PC Command Listener on the PC

...

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

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:

...

%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;

...

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.

...

...

PC Command Listener on HTTPS (SSL) Servers

To enable a Rich Display session running on HTTPS to send commands to the Listener, the configuration optionPC 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.(

...

PC Command Listener Security

...

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.

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.

...

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

Enabling Signature Verification in Profound UI

...

• "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"

    • Image Added

    • Example Config:

    • Code Block
      language json
      {"port": "8082", "public key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQ ... AwEAAQ==\n-----END PUBLIC KEY-----\n", "verify algorithm":""}

    • 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"yourServer:8080/profoundui/pccmd-pub.pem"

      • Limitations as of PC Command Listener version 1.1.1 to be addressed in future versions:

        • responses from an HTTP server using self-signed certificates are not supported. Instead of using the URL option when the public key is on such a web server, include the public key text inside of the listener-conf.json file (or paste the PEM data inside of the dialog for the PC Command Listener Config as shown above).

        • HTTP redirect headers are not followed.

    • 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"

...

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";

...

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.

...

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

...

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.

...