Security for PJSCALL Command and Proxy Programs

Security for PJSCALL Command and Proxy Programs

Instructions on this page apply to Profound.js version 7 and higher.

Overview

Profound.js will only accept connections from PJSCALL and proxy programs that are running on an IBM i system identified by a security key specified in the pjscallKeys configuration setting. All other PJSCALL and proxy program connections are closed immediately by the server.

The first time a Profound.js Connector library is installed on an IBM i system, a security key is generated that can be used to identify the system. To configure Profound.js to accept connections from a given IBM i system, it is necessary to retrieve the security key from the IBM i system and add it to the pjscallKeys configuration setting.

Retrieving the IBM i Security Key

The easiest way to retrieve the IBM i security key is to use the get_pjscall_key.js utility that is provided in the product installation directory. This utility retrieves the security key from the local or a remote IBM i system and automatically populates it in the pjscallKeys configuration setting.

Connections to a remote IBM i system are made via SSH. This requires that the SSH service is running on the remote IBM i system. For details, see Starting OpenSSH server (SSHD) on IBM i.

Running the Utility

get_pjscall_key.js can be run from a command prompt or interactive shell, like this:

node get_pjscall_key.js

The script prompts for IBM i connection details, connects to the system to retrieve the security key, and automatically writes it into the Profound.js configuration file:

If running on IBM i, specify host name localhost to retrieve the security key from the local system.

Configuration File Format

get_pjscall_key.js is only able to update the configuration file automatically if it is in the expected format. The expected format is for the configuration to be specified as an object expression assigned to module.exports at the top level of the config.js module, outside of any function or block. For example:

config.js
module.exports = { "port": 8081, // More settings...

Printing the Key

If the configuration file cannot be automatically updated for some reason, another option is for get_pjscall_key.js to print the key to standard output. From there, you can copy and paste it into the pjscallKeys setting in the configuration file. For example:

node get_pjscall_key.js --print

Using DSPCALLKEY

Another way to retrieve the security key is to sign on to the IBM i system via TN5250 and run the DSPCALLKEY CL command in the PJS_BASE library:

PJS_BASE/DSPCALLKEY

Configuration File Security

The security key specified in the configuration file is a hash of the actual security key – not the key itself. This means that no special measures need to be taken to protect the configuration file. A user with access to the security key hash will still not be able to derive the actual security key.

IBM i Objects and Permissions

The DSPCALLKEY and GENCALLKEY commands are shipped with public *EXCLUDE permission.

The security key is generated the first time a Profound.js Connector library is installed on the system, and is stored in a database table named PJSCONFIG in the Profound.js Base Components (PJS_BASE) library.

The PJSCONFIG table is shipped with public *USE permission, as any user jobs running PJSCALL or proxy programs need to access it to read the key. The data is encrypted in the table to prevent users with the ability to run queries from accessing it. The PJS_BASE/DSPCALLKEY command is the only way to view the key in the clear. The PJS_BASE/GENCALLKEY command can be used to regenerate the security key, if needed.

Regenerating the IBM i Security Key

Regenerating the security key requires any Profound.js configurations to be updated with the new key.

If the IBM i security key is compromised, or if it needs to be regenerated for any reason, the following CL command can be run on the IBM i system:

PJS_BASE/GENCALLKEY REPLACE(*YES)