Stored Password Protection

Overview

Stored Password Protection enables an application to provide a connection password in encrypted form to the Teradata SQL Driver for Node.js.

An encrypted password may be specified in the following contexts:

• A login password specified as the password connection parameter.
• A login password specified within the logdata connection parameter.

If the password, however specified, begins with the prefix ENCRYPTED_PASSWORD( then the specified password must follow this format:

ENCRYPTED_PASSWORD(file:PasswordEncryptionKeyFileName,file:EncryptedPasswordFileName)

Each filename must be preceded by the file: prefix. The PasswordEncryptionKeyFileName must be separated from the EncryptedPasswordFileName by a single comma.

The PasswordEncryptionKeyFileName specifies the name of a file that contains the password encryption key and associated information. The EncryptedPasswordFileName specifies the name of a file that contains the encrypted password and associated information. The two files are described below.

Stored Password Protection is offered by the Teradata JDBC Driver and the Teradata SQL Driver for Node.js. The same file format is used by both drivers.

Test Example

See the following test for example code using Stored Password Protection with the Teradata SQL Driver for Node.js

• https://github.com/Teradata/nodejs-driver/blob/develop/test/security/encrypted-password.ts

Password Encryption Key File Format

The password encryption key file is a text file in Java Properties file format, using the ISO 8859-1 character encoding.

The file must contain the following string properties:

Encrypted Password File Format

The encrypted password file is a text file in Java Properties file format, using the ISO 8859-1 character encoding.

The file must contain the following string properties:

While params is technically optional, an initialization vector is required by all three block cipher modes CBC, CFB, and OFB that are supported by the Teradata SQL Driver for Node.js. ECB (Electronic Codebook) does not require params, but ECB is not supported by the Teradata SQL Driver for Node.js.

Transformation, Key Size, and MAC

A transformation is a string that describes the set of operations to be performed on the given input, to produce transformed output. A transformation specifies the name of a cryptographic algorithm such as DES or AES, followed by a feedback mode and padding scheme.

The Teradata SQL Driver for Node.js supports the following transformations and key sizes.

Stored Password Protection uses a symmetric encryption algorithm such as DES or AES, in which the same secret key is used for encryption and decryption of the password. Stored Password Protection does not use an asymmetric encryption algorithm such as RSA, with separate public and private keys.

CBC (Cipher Block Chaining) is a block cipher encryption mode. With CBC, each ciphertext block is dependent on all plaintext blocks processed up to that point. CBC is suitable for encrypting data whose total byte count exceeds the algorithm's block size, and is therefore suitable for use with Stored Password Protection.

Stored Password Protection hides the password length in the encrypted password file by extending the length of the UTF8-encoded password with trailing null bytes. The length is extended to the next 512-byte boundary.

• A block cipher with no padding, such as AES/CBC/NoPadding, may only be used to encrypt data whose byte count after extension is a multiple of the algorithm's block size. The 512-byte boundary is compatible with many block ciphers. AES, for example, has a block size of 128 bits (16 bytes), and is therefore compatible with the 512-byte boundary.
• A block cipher with padding, such as AES/CBC/PKCS5Padding, can be used to encrypt data of any length. However, CBC with padding is vulnerable to a "padding oracle attack", so Stored Password Protection performs Encrypt-then-MAC for protection from a padding oracle attack. MAC algorithms HmacSHA1 and HmacSHA256 are supported.
• The Teradata SQL Driver for Node.js does not support block ciphers used as byte-oriented ciphers via modes such as CFB8 or OFB8.

The strength of the encryption depends on your choice of cipher algorithm and key size.

• AES uses a 128-bit (16 byte), 192-bit (24 byte), or 256-bit (32 byte) key.
• DESede uses a 192-bit (24 byte) key. The The Teradata SQL Driver for Node.js does not support a 128-bit (16 byte) key for DESede.
• DES uses a 64-bit (8 byte) key.

Sharing Files with the Teradata JDBC Driver

The Teradata SQL Driver for Node.js and the Teradata JDBC Driver can share the files containing the password encryption key and encrypted password, if you use a transformation, key size, and MAC algorithm that is supported by both drivers.

• Recommended choices for compatibility are AES/CBC/NoPadding and HmacSHA256.
• Use a 256-bit key if your Java environment has the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from Oracle.
• Use a 128-bit key if your Java environment does not have the Unlimited Strength Jurisdiction Policy Files.
• Use HmacSHA1 for compatibility with JDK 1.4.2.

File Locations

For the ENCRYPTED_PASSWORD( syntax of the Teradata SQL Driver for Node.js, each filename must be preceded by the file: prefix. The PasswordEncryptionKeyFileName must be separated from the EncryptedPasswordFileName by a single comma. The files can be located in the current directory, specified with a relative path, or specified with an absolute path.

Example for files in the current directory:

ENCRYPTED_PASSWORD(file:JohnDoeKey.properties,file:JohnDoePass.properties)

Example with relative paths:

ENCRYPTED_PASSWORD(file:../dir1/JohnDoeKey.properties,file:../dir2/JohnDoePass.properties)

Example with absolute paths on Windows:

ENCRYPTED_PASSWORD(file:c:/dir1/JohnDoeKey.properties,file:c:/dir2/JohnDoePass.properties)

Example with absolute paths on Linux:

ENCRYPTED_PASSWORD(file:/dir1/JohnDoeKey.properties,file:/dir2/JohnDoePass.properties)

Processing Sequence

The two filenames specified for an encrypted password must be accessible to the Teradata SQL Driver for Node.js and must conform to the properties file formats described above. The Teradata SQL Driver for Node.js raises an exception if the file is not accessible, or the file does not conform to the required file format.

The Teradata SQL Driver for Node.js verifies that the match values in the two files are present, and match each other. The Teradata SQL Driver for Node.js raises an exception if the match values differ from each other. The match values are compared to ensure that the two specified files are related to each other, serving as a "sanity check" to help avoid configuration errors. The TJEncryptPassword program uses a timestamp as a shared match value, but a timestamp is not required. Any shared string can serve as a match value. The timestamp is not related in any way to the encryption of the password, and the timestamp cannot be used to decrypt the password.

Before decryption, the Teradata SQL Driver for Node.js calculates the MAC using the ciphertext, transformation name, and algorithm parameters if any, and verifies that the calculated MAC matches the expected MAC. The Teradata SQL Driver for Node.js raises an exception if the calculated MAC differs from the expected MAC, to indicate that either or both of the files may have been tampered with.

Finally, the Teradata SQL Driver for Node.js uses the decrypted password to log on to the Teradata Database.