pathscrambler.exe

The pathscrambler.exe executable is used to protect sensitive information such as paths, connection strings, logon information and logicals in Uniface assignment files, Java Servlet settings, and the ProcScript open command.

It takes an assignment file, text string, or path definition as input, and returns an assignment file or string in which specific data is encrypted and/or encoded.

pathscrambler.exe {-instr String } | {-infile AsnFile} | {-path " Path"} | {-asn AsnFile}

Switches
Option	Description
-instr `"`String`"`	Encrypt any strings in the specified path that are delimited by double parentheses: `((` and `))`. If the String contains no delimiters, or only one delimiter, the entire text string is encrypted.
-infile AsnFile	Encrypt any strings in the specified assignment file that are delimited by double parentheses: `((` and `))`. This can be used for logical values, and other login or connection strings that must remain secure. Note: Encryption of section names is not supported.
-path `"`Path`"`	Encode the provided path specification using Base64 encoding. Use this for scrambling paths in WRD settings.
-asn AsnFile	Obfuscate path specifications in the [PATHS] section of the specified assignment file, using Base64 encoding. (Provided for backward compatibility.)

Description

Pathscrambler was originally designed to obfuscate path specifications used for automatic logon to resources. It has been enhanced several times, first to support encryption of paths as well as other sensitive data, and later to improve security for encrypted data.

Note: As of Uniface 10.3.02.022, the Pathscrambler encryption using -infile and -instr has changed. If you have previously encrypted strings or assignment files, they will continue to work as they did before. However, if you need to make changes in these strings or files, the new encryption has some consequences. For details, see Pathscrambler Compatibility Issues.

To protect path specifications in settings for the Web Request Dispatcher (WRD), use the -path switch to encode the data.

In all other cases, if you need to protect paths, passwords, connector logon strings, or application logicals, it is recommended that you encrypt the data using -infile or -instr.

For more information, see Encrypting Paths and Other Sensitive Data Using PathScrambler.

Encryption

Using the -instr and -infile switches, you can encrypt (rather than just encode) path specifications. The -infile switch also enables you to encrypt other sensitive information such as logical values, and login or connection strings that must remain secure.

To mark data for encryption, you must add the encryption delimiters(( and ))around the strings to be encrypted. The encryption delimiters only have meaning for Pathscrambler.

Pathscrambler replaces the encryption delimiters with the decryption delimiters(! and !), which have meaning for all Uniface executables that read assignment files.

For servlet settings in web.xml, it is only possible to encode the demarcated string using Base64 using -path. In all other cases, using the -instr and -infile switches, Pathscrambler takes input that has been delimited and does the following:

Encrypts the delimited strings using AES-256.
Encodes the encrypted data with Base 64, which turns binary data into printable characters that can be put in a file or ProcScript.
Adds a digest (or hash) to the end of each line that contains encrypted strings. Because the digest is for the complete line, and not just the encrypted data, this ensures that the encrypted line cannot be tampered with in any way. Even adding a space makes the line unusable.
The digest at the end of the line is placed within double parentheses: ((digest)). Elsewhere in the encrypted file these are treated as characters, they have no meaning.

Each time the same text is encrypted with the Pathscrambler, it generates a different string, so it is not possible to copy an encrypted string and paste it in different sections of the assignment file.

The generated string can be used as the logon parameter of the ProcScript open statement, or with the /log (login) command line switch.

Output

For -asn and -infile, Pathscrambler generates an assignment file AsnFile.enc containing encrypted data. On iSeries, two dots are not supported, so _ENC is appended to the physical file name ASN. You can copy and paste the contents of this file into the application assignment file.

For -instr and -path, by default, the encrypted or encoded data is returned to the screen, STDOUT. You can copy and paste it to the open ProcScript statement, the /log (logon) switch, or into a line in the [PATHS] section of an assignment file.

To make it easier to copy and paste the encrypted string, you can direct it to a file, for example, by appending >FileName to the Pathscrambler command.

For more information, see /log and open and [PATHS].

Marking Data for Encryption

To mark the data to be encrypted, add double parentheses (( and )) as start and end delimiters for each string in the assignment file or input text that needs to be encrypted. Note the following:

The (( and )) delimiters must be on one physical line. If one logical line is spread over two physical lines with a continuation marker, then it still must be on one physical line.
However, you can have multiple delimited parts in one line. For example:
ORA:database|((username))|((password))
If the data for encryption contains the delimiter characters ((, )), (! or!), use the caret symbol (^) to escape them. For example: ^(( and ^(!.
When using -instr, if the whole string is to be encrypted, enclose the whole string with the delimiters. If no pair of (( and )) is found in the string, the whole string is encrypted.
When delimiting data to be encrypted, do not delimit section headings, such as [SETTINGS], [PATHS], and so on. Scrambling section headings is not supported.
An assignment file containing the encryption delimiters (( and )) cannot be used by Uniface executables.

When Pathscrambler is executed, it replaces the encryption delimiters with the decryption delimiters and resolves ^-escaped characters within the delimited text, before encrypting the data and returning the resulting output.

Escaping Literal Characters

Use the caret (^) to escape characters that must be treated as part of the data rather than interpreted by Uniface. The caret can be used to escape any non-alphanumeric and non-whitespace character. This applies to:

Encryption or decryption delimiters: (()), (! or!).
For example, ^!) will be treated as literal !) and not a decryption end marker.
Line continuation characters: %\
For example, %^\ will be a literal %\ and not a line continuation marker.
The caret symbol itself, when it is not followed by an alphanumeric character or whitespace.
For example, ^^\ will be literal ^\
Note: There is no need to escape the caret in trigger names such as ^retrieve
Other non-alphanumeric and non-whitespace characters that must be treated as a literals.

It is good practice to always escape delimiter characters that must be treated as literals, but it is not always required. For example:

The start delimiter (( has no special meaning inside an encryption delimiter pair, for example ((abc((def)), so you can choose to escape it or not.
A start delimiter that is not followed by an end delimiter on the same line is always a literal string, and does not have to be escaped.

The end delimiter ))does have a special meaning when it occurs inside an encryption delimiter pair, so it must be escaped: ((abc^))def)).

Line Continuation

Uniface has a limit of 1023 characters per line. Encryption has a tendency to lengthen the line, which can be a problem on some operating systems or when specifying many parameters.

When the Pathscrambler detects that the length of the line after encryption exceeds 1023 on Windows and Unix, and 228 on iSeries, it writes a line of maximum length minus two, ends that line with %\, and writes the remainder on the next line. If the remainder is still too long it will do the same again. The 1023-character limit applies to the individual lines that make up the whole line, so this provides a useful way of handling lines that are too long as a result of encryption.

If the Pathscrambler is invoked with -infile and it sees lines with a (( delimiter that ends with the %\ marker, it first concatenates the line(s) that follows before doing the encryption. The marker is not put back in the assignment file produced, unless the maximum length of 1023 (or 228) characters is exceeded. Lines containing no (( delimiter and ending with a %\ marker are not changed, but are written to the .enc file unchanged.

The same applies for the -asn switch but only for the [PATHS] section. Any lines in that section using the %\ marker are first concatenated before encoding and the %\ marker is not put back. In any other section the lines remain unchanged.

For more information, see Line Continuation in Assignment Files.

Encrypting Strings

Given the following assignment file with encryption delimiters:

; ASN file myapp.asn
[PATHS]
$DB       ORA:database|((username|password))
$REM_DB   TCP:((machine1+port|user|passwd)) + DB2:((database.schema|db2user|db2passwd))

The following command:

pathscrambler -infile D:uniface\projects\myapp.asn

Generates the assignment file myapp.asn.enc in D:uniface\projects with contents something like this:

[PATHS]
$DB       ORA:database|(!AY9WoJPqwtjmFMtDVGVjR2cAYV+uhYMTyQuRvCkDhUpgEY=!)
$REM_DB   TCP:(!AcJLdYGkG7hWWuG8BOHD2vBXeQ3oVNdJhoCayGBC1yl9!) + DB2:(!Af46Mb3EmIYtXLOWbH6plKty0Ggz97A3YwzKp8QtjldvaqwniPDKQTugjZ3nqVimXg==!)

Encoding Paths

```
pathscrambler -asn myasn.asn
```
Results in: myasn.asn.enc containing scrambled paths in the [PATHS] section.

pathscrambler -path "localhost|UUSR_C1565|PASS-C156|ASV_ACME"

Returns something like the following in the console window:

(fC=n]S|kf7J4bBRRQ5NbU~A5JnR<QABPQ}5@IPQ6bABPRh=FU45B)

Pathscrambler Compatibility Issues

As of Uniface 9.7.05.035, the Pathscrambler appends a digest to any assignment file line or string in which it has encrypted delimited text. This has the following consequences:

Files and strings can no longer be generated using the old encryption

If you encrypted strings or assignment files prior to 9.7.05.034, they will continue to work as they did before.

However, Pathscrambler can no longer generate encrypted strings or files using the old algorithm (without the appended digest). If you need to make a change, you will need to edit the unencrypted file or string and have Pathscrambler generate new encrypted output.

Any line with a digest in an assignment file, or any string with a digest, cannot be altered in any way.

Previously unencrypted text in a line that included encrypted strings could be changed; now any change invalidates the digest.

Any string provided for open or /log must be encrypted in its entirety.

As a consequence, it is no longer possible to dynamically construct a database path using separately encrypted database, user, and password elements. You need to encrypt the complete LogonParameters string for the open statement (or the /log (login) command line qualifier).

Instead, you can dynamically construct a database path in ProcScript using the $password function, which encrypts the password, and the $user function, which does not encrypt the data.

Mixed encryption is not supported in a single string, line, or file.

It is not possible to use an older encryption mixed with the new encryption in one line or string.

You cannot mix lines from an old assignment file and a new one. For example, you cannot cut and paste some lines from an older assignment file into a new one, or add new encryption to an old file.

However, you can use the #FILE command to include an old assignment file in a newly-encrypted one.

Version	Change
10.3.02.022	Security enhancements to prevent tampering with encrypted data
9.7.04 G303	Introduced -instr and -infile to encrypt rather than encode paths, and extend coverage to other sensitive data.