How to use Stored Password Protection with encrypted SMB

• Preface
• Prerequisites
• Set up systems in the same domain
• Create the encrypted password properties files for Stored Password Protection
• Server setup for encrypted SMB
• Client setup for encrypted SMB
• Access the encrypted password properties files for Stored Password Protection
• Run a Java program using Stored Password Protection
• Securing the Stored Password Protection files

Preface

This document describes how to configure the Teradata JDBC Driver with Stored Password Protection feature on the Windows platform using Server Message Block (SMB 3.0).

Stored Password Protection uses two Java properties files: a password-encryption-key file and an encrypted-password file to provide a password for logging onto a database. The properties files can be located on a network volume to prevent loss of the file in case the physical client machine is stolen. To protect their contents while in transit, an encrypted protocol is used.

Prerequisites

This document was written using Windows Server 2016 & Windows 10 Enterprise systems and JDK 8.0.

A total of four Windows systems will be used as shown in the table below.

Set up systems in the same domain

The systems "client1", "server1", and "server2" should be set up in the same domain. The systems used in this document were set up on a Kerberos domain. The details of that are beyond the scope of this document and is recommended to be completed by a system administrator.

A Windows user, who will run the sample Java program on the client system and access the shares on the server systems should also be set up in the Windows Active Directory. For the example that follows, we will use the user "guestKrb1".

Create the encrypted password properties files for Stored Password Protection

This section will create the encrypted password properties files needed for the Stored Password Protection example. The properties files will be created with the TJEncryptPassword.java sample program that is part of the Teradata JDBC Driver sample programs. Full documentation on how to run the program is included in the program file.

On "system1", the properties files that will be created are:

• PassKeyGuestKrb1.properties
• EncPassGuestKrb1.properties

In a directory on the Windows system "system1" as listed in Prerequisites, compile TJEncryptPassword.java and run the program as follows:

javac TJEncryptPassword.java

java -cp .;terajdbc4.jar TJEncryptPassword AES/CBC/NoPadding -default HmacSHA1 PassKeyGuestKrb1.properties EncPassGuestKrb1.properties dbs1 user1 password1

Older versions prior to Teradata JDBC Driver 16.20.00.11 require tdgssconfig.jar to be listed on the classpath as follows:

java -cp .;terajdbc4.jar;tdgssconfig.jar TJEncryptPassword AES/CBC/NoPadding -default HmacSHA1 PassKeyGuestKrb1.properties EncPassGuestKrb1.properties dbs1 user1 password1

The command will encrypt the database password "password1" and generate two Stored Password Protection properties files. One file contains the password-encryption-key and the other contains the encrypted-password. These two files that have been created on "system1" will be copied to the server systems in the next section.

Server setup for encrypted SMB

These steps should be done while logged in as administrator on the Windows server systems.

Create directory to hold the Stored Password Protection files

server1:

1. create a directory to store the password-encryption-key properties file with this format:

   C:\Users\username\JdbcKey_username

   For our example, we will create C:\Users\guestKrb1\JdbcKey_guestKrb1


2. copy the password-encryption-key properties file that was created in Create the encrypted password properties files for Stored Password Protection to the directory
• (in the address bar in File Explorer, enter the path to "system1" where the properties file reside, copy & paste the file)

server2:

1. create a directory to store the encrypted-password properties file with this format:

   C:\Users\username\JdbcPassword_username

   For our example, we will create C:\Users\guestKrb1\JdbcPassword_guestKrb1


2. copy the encrypted-password properties file that was created in Create the encrypted password properties files for Stored Password Protection to the directory
• (in the address bar in File Explorer, enter the path to "system1" where the properties file reside, copy & paste the file)

Turn on Network Discovery & File Sharing

Using "Search Windows" to the right of the Start button, enter dcomcnfg.exe to open Component Services.

1. Expand Component Services → Computers
2. Right click "My Computer" and select "Properties"

3. Select "Default Properties"
4. Select "Connect" in the Default Authentication Level

5. Select "Apply"
6. Select "Yes" to modify machine wide DCOM settings

7. Select "OK"

Using "Search Windows" to the right of the Start button, enter Server Manager to open Server Manager.

1. Select "Add roles and features" to run the "Add Roles and Features Wizard"



2. Click "Next" at the "Before you begin" screen if you have not selected to "Skip this page by default" from previous uses of Server Manager.
3. Select Role-based or Feature-based installation
4. Select local machine → select your server system



5. Select "File and Storage Services" to expand
6. Expand "File and iSCSI Services"
7. "File Server" will already be selected as will "File and iSCSI Services"
8. Click "Next" → "Next"



9. Click "Install"
10. Click "Close" when the installation is complete

Set up sharing

This section describes setting up sharing of the password-encryption-key file and the encrypted-password file. The sharing is set up on the servers as listed above in Prerequisites.

Bring up Windows PowerShell and run as administrator. To run as administrator, go to the Start button and scroll to "Windows PowerShell". Expand "Windows PowerShell" and right-click on "Windows PowerShell" and select "Run as Administrator"

The syntax for "New-SmbShare" & "Set-SmbShare" is shown below.

New-SmbShare [-Name] <String> [-Path] <String> [[-ScopeName] <String> ] [-CachingMode <CachingMode> {None | Manual | Documents | Programs | BranchCache | Unknown} ] [-CATimeout <UInt32> ] [-ChangeAccess <String[]> ] [-CimSession <CimSession[]> ] [-ConcurrentUserLimit <UInt32> ] [-ContinuouslyAvailable <Boolean> ] [-Description <String> ] [-EncryptData <Boolean> ] [-FolderEnumerationMode <FolderEnumerationMode> {AccessBased | Unrestricted} ] [-FullAccess <String[]> ] [-NoAccess <String[]> ] [-ReadAccess <String[]> ] [-SecurityDescriptor <System.String> ] [-Temporary] [-ThrottleLimit <Int32> ] [-Confirm] [-WhatIf] [ <CommonParameters>] [ <WorkflowParameters>]

For information on the parameters, refer to New-SmbShare at Microsoft Developer Network.

Set-SmbShare [-Name] <String[]> [[-ScopeName] <String[]> ] [-CachingMode <CachingMode> {None | Manual | Documents | Programs | BranchCache | Unknown} ] [-CATimeout <UInt32> ] [-CimSession <CimSession[]> ] [-ConcurrentUserLimit <UInt32> ] [-ContinuouslyAvailable <Boolean> ] [-Description <String> ] [-EncryptData <Boolean> ] [-FolderEnumerationMode <FolderEnumerationMode> {AccessBased | Unrestricted} ] [-Force] [-PassThru] [-SecurityDescriptor <String> ] [-SmbInstance <Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbShare.SmbInstance> {Default | CSV} ] [-ThrottleLimit <Int32> ] [-Confirm] [-WhatIf] [ <CommonParameters>] [ <WorkflowParameters>]

For information on the parameters, refer to Set-SmbShare at Microsoft Developer Network.

For our example, we will create the following SMB shares as follows:

Example shown below for password-encryption-key file on "server1":

Example shown below for encrypted-password file on "server2":

Validate encryption

Validate that encryption was turned on using the following steps:

Using "Search Windows" to the right of the Start button, enter Server Manager to open Server Manager.

1. Select "File and Storage Services" to expand
2. Select "Shares"
3. Right click on the share that was just created and select "Properties"
4. Click "Settings" and "Encrypt data access" should be checked

Client setup for encrypted SMB

Create new user

Logged in as administrator on the Windows client system, create a new standard user with a home directory of C:\Users\username.

Once the new standard user is created, log out as administrator and log in as the new standard user to proceed.

Copy the Teradata JDBC Driver terajdbc4.jar from "system1" to directory C:\Users\username. Older versions prior to Teradata JDBC Driver 16.20.00.11 also require tdgssconfig.jar.

Verify access to the encrypted password properties files

Verify that the password-encryption-key and encrypted-password properties files stored on the server systems "server1" and "server2" are accessible. This can be done from Windows PowerShell or File Explorer.

To verify using Windows PowerShell, enter:

• ls //server1/JdbcKey_guestKrb1
• ls //server2/JdbcPassword_guestKrb1

An example of the output:

To verify using File Explorer, in the address bar enter the path for "server1" <enter>. Repeat again for "server2".

* where JdbcKey_guestKrb1 and JdbcPassword_guestKrb1 are the directories created to hold the key & password properties files in Create directories to hold the Stored Password Protection files.

An example for "server1" is shown.

Access the encrypted password properties files for Stored Password Protection

The encrypted password properties files generated above in Create the encrypted password properties files for Stored Password Protection created by the TJEncryptPassword.java sample program are resources that will be accessed by the Teradata JDBC Driver. These resources are accessed via the classpath or direct files by specifying a prefix of either classpath: or file: in the ENCRYPTED_PASSWORD string.

Use Stored Password Protection with Classpath Access

To access the resource files using the classpath access, the following syntax is used:

For security, classpath resources are required to have specific resource name prefixes. The PasswordEncryptionKeyResourceName (PassKeyGuestKrb1.properties is used in this document) must begin with "PassKey" and the EncryptedPasswordResourceName (EncPassGuestKrb1.properties is used in this document) must begin with "EncPass".

Use Stored Password Protection with File Access

To access the resource files using the file access, the following syntax is used:

There is no prefix requirement for the resource name when using file access.

For simplicity, the examples in this document use the same resource names "PassKeyGuestKrb1.properties" and "EncPassGuestKrb1.properties" for both classpath and file access.

For futher examples of file access using the current directory, relative paths, and absolute paths refer to the documentation in the program file.

Comparison of Classpath Access Versus File Access

Teradata JDBC Driver Stored Password Protection offers flexibility for accessing the password-encryption-key file and the encrypted-password file.

• If the resource name begins with the "classpath:" prefix, then the Teradata JDBC Driver loads the resource from the classpath.
• If the resource name begins with a prefix other than "classpath:", then the Teradata JDBC Driver loads the resource via the new URL(resourcename).openStream() method. In particular, if the resource name begins with the "file:" prefix, then the Teradata JDBC Driver loads the resource from a file.

In general, classpath access offers greater control and security, whereas file access offers greater flexibility.

• Classpath access is intended for applications that are packaged in a completely self-contained jar file, war file, or ear file. Classpath access is suitable for applications that use a small number of database passwords that are known in advance, and that rarely change.
• In contrast, file access can more easily accommodate an ever-changing set of database passwords

Run a Java program using Stored Password Protection

In this section, we will run a sample Java program LogonTest.java using Stored Password Protection on the Windows client system "client1" as described below.

On the Windows client system:

1. Log in as the user that was set up to run the sample Java program as mentioned in Set up systems in the same domain
2. Copy the Teradata JDBC Driver terajdbc4.jar from "system1" to a directory on "client1". Older versions prior to Teradata JDBC Driver 16.20.00.11 also require tdgssconfig.jar.
3. Save LogonTest.java to the same directory used for step #2
4. Compile the sample program LogonTest.java with the command: javac LogonTest.java
5. Run the sample Java program using encrypted-password using either classpath or file access (see examples below)

Run the sample Java program with classpath access

java -classpath .;./terajdbc4.jar;//server1/JdbcKey_guestKrb1;//server2/JdbcPassword_guestKrb1 LogonTest jdbc:teradata://dbs1 user1 "ENCRYPTED_PASSWORD(classpath:PassKeyGuestKrb1.properties,classpath:EncPassGuestKrb1.properties)"

Older versions prior to Teradata JDBC Driver 16.20.00.11 also require tdgssconfig.jar to be listed on the classpath.

The following results are returned:

Connecting to jdbc:teradata://dbs1 with user user1 and password ENCRYPTED_PASSWORD(classpath:PassKeyGuestKrb1.properties,classpath:EncPassGuestKrb1.properties)
Successfully logged on
Closing Connection
Pass

Run the sample Java program with file access

java -classpath .;./terajdbc4.jar LogonTest jdbc:teradata://dbs1 user1 "ENCRYPTED_PASSWORD(file://server1/JdbcKey_guestKrb1/PassKeyGuestKrb1.properties,file://server2/JdbcPassword_guestKrb1/EncPassGuestKrb1.properties)"

Older versions prior to Teradata JDBC Driver 16.20.00.11 also require tdgssconfig.jar to be listed on the classpath.

The following results are returned:

Connecting to jdbc:teradata://dbs1 with user user1 and password ENCRYPTED_PASSWORD(file://server1/JdbcKey_guestKrb1/PassKeyGuestKrb1.properties,file://server2/JdbcPassword_guestKrb1/EncPassGuestKrb1.properties)
Successfully logged on
Closing Connection
Pass

These examples use the encrypted password properties files created in the previous section Create the encrypted password properties files for Stored Password Protection.

Securing the Stored Password Protection files

Once the previous sections are working, you can provide more security for the password-encryption-key & encrypted-password properties files.

Using "Search Windows" to the right of the Start button, enter Server Manager to open Server Manager.

1. Select "File and Storage Services" to expand
2. Select "Shares"
3. Click on the share that holds the JDBC property file and right click to select "Properties"
4. Click "Permissions"

This screen will show who has specific permissions to the share and what those permissions are. Any unnecessary permissions can be removed here.

Under the settings tab, you can check "Enable access-based enumeration" to hide the folder from a user's view if they don't have read access to it.