Info |
---|
You can download the PC Command Listener and the PC Command Launcher directly by using the links below: |
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.
...
The widgets can be hidden conditionally until ready by binding the "visibility" property.Note: when
Info |
---|
When writing a URL to a field, you can omit commands like "START IEXPLORE.EXE" |
...
. Instead, you can just write the URL |
...
– this 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.
...
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
...
Code Block |
---|
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...".
...
Code Block |
---|
%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;
Note |
---|
In Profound UI |
...
Version 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.
...
...
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.
Info |
---|
...
In older versions of Profound UI, the SSL option for the Listener was PC Listener Mode. |
...
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.
Info |
---|
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.
...
Changes to an HTTP server config file, httpd.conf, require a HTTP server restart for that Profound UI instance.Important: make
Note |
---|
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
...
"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"
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"
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:
Code Block | ||
---|---|---|
| ||
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
Info |
---|
The PC Command Launcher works with Profound UI Version 5, Fix Pack 13.0 and later. |
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.
...