Security for PJSCALL Command and Proxy Programs

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

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 will be 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’s 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. See here for details.

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

node get_pjscall_key.js

The script will prompt for IBM i connection details, connect to the system to retrieve the security key, and automatically write 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

get_pjscall_key.js will only be 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:

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

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

node get_pjscall_key.js --print

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:

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 security key is generated and stored the first time a Profound.js Connector library is installed on the system and is stored in a database table 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 will 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. A command PJS_BASE/GENCALLKEY can be used to regenerate the security key, if needed.

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

Regenerating the IBM i Security Key

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

Note: Regenerating the security key will require any Profound.js configurations to be updated with the new key.