Directives 

Formats

Where: 

Description

Use the PASSWORD directive to assign/remove passwords to/from programs and data files.

Important Note:
When encryption is enabled on a data file, all key and data blocks will be encrypted; therefore, routines that attempt to parse a passworded file in Binary mode will not function correctly. This includes *UFAR, the file recovery utility.

Formats 1 and 2

Assign or Remove Passwords on Programs 

The formats described in this section assign/remove password protection on programs. Passworded programs cannot be listed or edited in PxPlus in any way unless the correct password is used.

PASSWORD pswd$

Apply to Program

To assign a password, load the program, enter the PASSWORD directive followed by the new password pswd$, and then save the program.

Example:

load "MYPROG"
password "CAT"
save "MYPROG"
load "MYPROG"
list
Error #52 -- Program password protected
delete 10
Error #52 -- Program password protected
password "CAT"
list
0010 rem...
0020 ... etc.

Before changing a password, you must reload the program and enter the PASSWORD directive followed by the previously assigned password. At this point, you can either change the password by entering PASSWORD (again) followed by a new string, or remove password protection by entering PASSWORD (again) followed by a null string.

PASSWORD *[,pswd$]

Apply Password Common to All Programs

Use the * (asterisk) to denote a common password. PxPlus will apply a common password automatically to all previously passworded programs when they are loaded and to all new programs.

Note:
To help eliminate the possibility of a hacker attempting to determine a program password by brute force, every wrong password attempt will result in a one second delay.

Formats 3, 4, 5 and 6

Assign Password to Data File

The formats described in this section assign password protection to data files. A KEY=pswd$ option is required to OPEN a passworded file. To define/change a password, you must have exclusive access to the file and it must be empty.

Note:
File passwords are only available for VLR and EFF files.

The maximum length for a file password is determined by the 'EA' system parameter:

•  If the 'EA' system parameter is Off or is not supported by the PxPlus version being used (i.e. PxPlus 2018 and prior), the maximum password length is 8 characters, and any data beyond that is simply ignored.

•  If the 'EA' system parameter is On, the maximum password length is 128 characters, and any data beyond that is simply ignored.

In both cases, a password longer than 240 characters will result in an error.

Use one of the following syntax formats to assign a password to a data file:

The following table outlines the usage, access level, and encryption associated with each syntax format used to assign a password to a data file:

An internal password queue records passwords for successfully opened files and checks when an attempt is made to open a passworded file without specifying a KEY= clause or when a null KEY= value is supplied. The password stored in the queue is used if an entry exists for that file. The number of entries to keep in the queue is controlled by the 'PQ' system parameter. The ability to distinguish between an invalid password and a non-existent password is provided by means of the 'PE' system parameter.

Due to the fact that all key and data blocks are encrypted, routines that attempt to parse a passworded file in binary mode will not function correctly. This includes *UFAR, the file recovery utility.

Encryption Algorithm

Prior to PxPlus 2019, passworded files use custom PxPlus algorithms for hashing a password before it is written to the file and for encrypting data written to the file.

As of PxPlus 2019, the 'EA' system parameter provides the ability to use industry standard algorithms for hashing a password with a salt (SHA-256) before it is written to the file and for encrypting data (AES-256) written to the file. By default, the 'EA' system parameter is Off, which indicates that the legacy custom PxPlus algorithms are used.

To use the industry standard algorithms, set the 'EA' system parameter to On.

Note:
If a password is added to a file when the 'EA' system parameter is On, older versions of PxPlus will not be able to open the file.

With the 'EA' system parameter Off, it is still possible to password a file using the industry standard algorithms if pswd$ is prefixed with "*AES:".

(The 'EA' system parameter and the use of industry standard encryption algorithms for passworded files was added in PxPlus 2019.)

Prompting for Password

PxPlus includes a generic program called get_pswd that will prompt for a password when KEY= is invalid or missing when a passworded file is opened. PxPlus checks the existence of the get_pswd program in the *ext sub-directory first, and then in *ext/system if the former is not found. This feature also allows the developer to customize the interface. As the prompt will be handled by a called program, it is also WindX-aware.

An embedded I/O (EIO) processing entry point called Get_Password provides the ability to prompt the user for a password based on logic associated with the EIO program. Provided the EIO program is valid and the entry point Get_Password exists, it will be used instead of the generic *ext/system/get_pswd or custom *ext/get_pswd. As the file is not in an OPEN state at the point when the entry point is called, the LFO and LFA values do not contain meaningful information. For this reason, the name of the file will be passed in the fourth parameter, normally referred to as Value$.

Example:

keyed "MyFile",[1:1:10],0,0
open lock (1)"MyFile"
password (1)"ABC" required for open
close (1)
open (1,key="ABC")"MyFile"
write (1)"Record A"
lock (1)
password (1)"XYZ" required for open Error #13: File access mode invalid
purge (1)
password (1)"XYZ" required for open
close (1)
open (1,key="XYZ")"MyFile"

Monitoring Attempts 

TCB(68) reports the number of attempts that have been made to prompt for the password. This value is incremented prior to PxPlus calling the embedded I/O or get_pswd routine; therefore, the first attempt will have a TCB(68) value of 1.

By default, the first three attempts to access a passworded file using an invalid password will result in a prompt to re-enter the password. The fourth attempt generates an Error #53: Invalid password. This behavior is controlled via the 'PP' system parameter.

Password Error Reporting 

The following error conditions will be trapped and reported:

Format 7

Copy Password to Data File from Data File

PASSWORD (chan1[,ERR=stmtref]) FROM (chan2[,ERR=stmtref]) [,ERR=stmtref]

PASSWORD FROM allows a password from one file to be copied directly to another file without prompting the user for the password. Its use is primarily for rebuilding data files on the fly.

Note:
An Error #13: File access mode invalid will occur if the destination file has an existing password, and an Error #53: Invalid password is generated when the source file does not contain a password.

Format 8

Remove Password from Data File

PASSWORD (chan) pswd$ REMOVE

This format removes password protection from a data file. To remove a password, you must have exclusive access to the file, and it must be empty.

See Also

'EA' Encryption Algorithm
'EL' Encryption Level
'PE' Password Error Control
'PP' Prompt for Password
'PQ' Password Queue
OPEN Open a File for Processing