MIAMEX 172: Password Encryption

Update May 2014; see History

xcall MIAMEX, MX_PWCRYPT, pwin, pwout, {mode}, {seed}, {key}

MX_PWCRYPT is used for for password encryption. It is useful for use in GDI files to avoid revealing SMTP passwords.

Modes 1 and 2

You specify pwin, the clear text version of password, and it returns pwout, the encrypted version. Note that this is a relatively simplistic password encryption mechanism known to A-Shell and ATE, which is recognized by the fact that the first character will be a chr(2). If you have a need to decrypt them, contact MicroSabio for details. We did not publish the decryption scheme because doing so would compromise what limited security the routine offers.

The optional mode argument allows you to create the original 7-bit style password encryption used by earlier versions of ATE, in addition to the newer 8-bit style. The two types of encrypted passwords can be distinguished by the first byte: chr(1) indicates type 1 (7 bit), while chr(2) indicates type 2 (8 bit).

Mode 3

Encryption mode 3 provides a stronger alternative to modes 1 and 2 for passwords and other short strings up to 44 characters in length. The encrypted strings are a convenient and uniform 68 MIME characters long, plus an ASCII 3 identifying prefix, making them easy to insert into both fixed-length data fields and text files (print files, configuration files, etc.) Based on a blowfish-class, 256-bit, seed-generated key incorporating both randomized "salt" and "pepper", it is strong enough to eliminate the need to hide them from public view.

In most of the places where A-Shell currently accepts encrypted passwords—e.g. //PDFX files, EMAILX configuration files, FTPDLX.SBR, etc—you can now specify a mode-3 encrypted password.

Also note:

• Due to the randomized salt and pepper, successive encryptions of the same password, using the same seed and key, will still generate entirely different encryption strings.

• To generate a mode 3 encryption string for //PDFX.Email.SMTP.Password, specify the SMTP.Username value as the seed and omit the key parameter. Also make sure that the SMTP.Username always appears in the print file prior to the SMTP.Password.

• Similarly, for a mode 3 encrypted password compatible with FTP2.SBR, use the FTP user name as the seed.

• For EMAILX, use the SMTP username as the seed; requires EMAILX.SBR 5.1.128.

Parameters

pwin (String) [in]

The password to encrypt or decrypt. In the case of encrypt, it should be no more than 44 characters. For decrypt, it should contain the prefix byte indicating the encrypt mode followed by the encrypted string, null terminated.

pwout (String) [out]

The encrypted or decrypted result. For encryption, the first byte will be chr(1) for mode 1, chr(2) for mode 2, or chr(3) for mode 3. (This allows generalized decryption logic to know which scheme to use.) For modes 1 and 2, the remainder of the string will equal the length of the PWIN parameter. There may be embedded control characters, but no embedded nulls.

For mode 3 encryption, the remainder of the string will consist of 68 MIME characters, regardless of the length of the CLRPW string. Accounting for the prefix and trailing null, you should allow 70 characters for storage.

mode (Num) [in]

Indicates the operation and encryption mode. For encryption, specify the desired mode (1, 2 or 3). For decryption, specify 0. Note, however, that to protect the security of encrypted strings which may be publicly visible in text files, decryption is not supported in the XCALL, except for mode 3 when you supply your own key, for which see below. If not specified, encryption method 2 will be used.

seed (String, 64) [in] (applies to mode 3 only)

Affects the way the encryption key is generated. For passwords, you may want to specify the user name as the SEED, making it that much more difficult for anyone to reverse engineer the key or otherwise break the encryption. May be blank.

key (x,32) [in] (applies to mode 3 only)

The base key used for the encryption or decryption. Note that it is not the actual encryption key; instead, it is used along with SEED and other factors to generate the actual key. It may be omitted or set to all nulls when encrypting in order to use the standard A-Shell encryption key scheme, which can be decrypted internally by A-Shell using internal defaults, allowing it to be used in most places where a password is required; see Comments below.

Note however, that while A-Shell internally knows how to construct the key needed for decryption, to protect the security of such encrypted strings, the automatic decryption capability is not exposed in the XCALL interface. If you want to use MX_PWCRYPT for encrypting and decrypting passwords within your application, you will need to use mode 3 and supply your own explicit key for both operations.

Note also that key is an unformatted 32 byte (256 bit) field, possibly containing nulls. You should use some kind of randomized algorithm to fill the 32 bytes with random values distributed across the bit space, rather than using a simple string like "rosebud".