Introducing Teradata Wallet

Have you ever wanted to keep your Teradata Database passwords private and not be exposed in scripts?  If you have, then we have a solution for you.

Teradata Wallet is a new software package included in the Teradata Tools and Utilities 14.00.  This article explains how you can use this new software to secure your Teradata Database passwords on your client computer.

Key concepts

Wallets

The information stored by Teradata Wallet is segregated by client user.  So, if a given client computer has three users: davidp, scottr, and joen, then you might visualize the information stored in Teradata Wallet as follows:

A given user can only access information from his own wallet.  So, all Teradata Wallet accesses by davidp will necessarily go to davidp's wallet.  davidp cannot access anything in scottr's wallet and cannot access anything in joen's wallet.

Items

A wallet contains a set of items.  Each item has two parts:

1. The item name.
2. The item value.

The following picture shows a wallet containing four items:

One of the items has a name of "password_for_slugger" and a value of "g0t#L0st#".
One of the items has a name of "password_for_cs4400s3" and a value of "heLP4me$".
One of the items has a name of "password_for_deft1" and a value of "rsKr0myH".
One of the items has a name of "banana" and a value of "YRUhere1$".

Both item names and item values are sequences of Unicode characters.  The Teradata Wallet software preserves the case of item names and item values.

Item names

Item names are arbitrary and are fabricated by the user.  An item name is used to select an item from a user's wallet.  For example, in the following LOGON command, there is a reference to an item named "banana":

.LOGON proddev/dave,$tdwallet(banana)

In this way, wallet item names are similar to filenames... you can name a file just about anything, but it is beneficial to use a name that helps you remember what's in it.

Wallet item names are case insensitive.  As such a name of "banana" is the same as a name of "BANANA".  If you added an item using the name "banana", you could reference that item as "Banana", "BANANA", or even "BaNaNa".  But if you added an item using the name "banana", you could not then add an item named "BANANA" because you would get an error indicating that an item with the given name already exists in your wallet.

It is important to realize that wallet names are within the scope of a user's wallet.  So if davidp added a string named "banana" to his wallet and then scottr then tried to add a string named "banana", the second addition could still succeed because davidp and scottr are using different wallets and an item named "banana" in davidp's wallet is a different item than an item named "banana" in joer's wallet.

Item names are not considered by the Teradata Wallet software to be sensistive/confidential and the software does not take extensive measures to protect them.

Item values

Item values may contain sensitive/confidential information such as Teradata Database passwords.  The Teradata Wallet software takes extensive measures to protect item values such as:

1. Encrypting item values when passing them to any system call.
2. Encrypting item values when they are saved on disk.

The tdwallet utility

The Teradata Wallet package contains a rudimentary command-line tool named "tdwallet".  This tool is used to add items to your wallet, delete items from your wallet, list the names of items in your wallet, etc.  tdwallet includes on-line help information; to access this, execute "tdwallet help" from the command line:

C:\Users\davidp>tdwallet help
USAGE: tdwallet help [<topic>] ...

DESCRIPTION:
    Displays helpful information about the listed topic(s).  If no topic is
    given, displays this information.  Available topics include:
      overview tool security encodings limits add del list help version

SEE ALSO:
    tdwallet help overview

C:\Users\davidp>

This shows the "help" topic itself.  To read another topic, execute "tdwallet help <topicname>" where <topicname> is the name of the topic.  View the "add" topic as follows:

C:\Users\davidp>tdwallet help add
USAGE: tdwallet add <name>

DESCRIPTION:
    Adds a string to your wallet.  The name of the added string
    will be <name>.  tdwallet prompts you for the value of the string.

SEE ALSO:
    tdwallet help overview

EXAMPLE:
    $ tdwallet add password_proddev
    Enter desired value for the string named "password_proddev":
    String named "password_proddev" added.
    $

C:\Users\davidp>

Simple usage scenario

How to get started:

1. If you have not done so already, install the Teradata Wallet software package onto your client computer.  This package is part of the Teradata Tools and Utilities 14.00 release.  Teradata Wallet is an optional package, meaning that you need to select it in order to install it, but you need not install it if you do not want to use Teradata Wallet.  Teradata Wallet is also available for download from http://developer.teradata.com/downloads.
2. Install the Teradata CLIv2 software package onto your client computer.  This should be version 14.00.00.02 or later and should be installed after you install the Teradata Wallet package.
3. Run the tdwallet utility to add items to your wallet.  For example:
       $ tdwallet add password_proddev
       Enter desired value for the string named "password_proddev":
       UR1geek2B
       String named "password_proddev" added.
4. Use $tdwallet in login information when connecting to the Teradata Database.  For example:
       $ cat deptquery.txt
       .logon proddev/davepickard,$tdwallet(password_proddev)
       .SET SEPARATOR ' | '
       SELECT * FROM department;
       .logoff
       .exit
       $ bteq < deptquery.txt
       BTEQ 14.00.00.00 Mon Jun 12 15:55:38 2011
       +---------+---------+---------+---------+---------+---------+---------+----
       .LOGON proddev/davepickard,
        *** Logon successfully completed.
        *** Teradata Database Release is 14.00.00.00
       ...

When the logon information is processed, "$tdwallet(password_proddev)" will be replaced with the value of the item named "password_proddev" from the current user's wallet.

Logon information processing

When found during logon processing, a string of the form $tdwallet(somestring) is replaced as follows:

1. Process somestring as follows:
       (a) Replace "\)" with ")".
       (b) Replace "\$" with "$".
       (c) Replace "\\" with "\".
       (d) Replace "$(tdpid)" with the Teradata Database system.
2. Query the current user's wallet for an item with a name matching the result of the processing in step 1.
3. The value of the item found by the query in step 2 is the replacement.

Thus, instead of:

.logon proddev/davepickard,$tdwallet(password_proddev)

we could have used:

.logon proddev/davepickard,$tdwallet(password_$(tdpid))

When found during logon processing, a string of the form $tdwallet (without "(somestring)") is replaced as follows:

1. Query the current user's wallet for an item with a name matching com.teradata.mechanism, where mechanism is the logon mechanism being used (for example, "TD2").
2. The value of the item found by the query in step 1 is the replacement.

The replacement process is iterative, querying the wallet repeatedly until no instances of $tdwallet(somestring) or $tdwallet remain.

To demonstrate, consider the following:

If joen uses a script that starts as follows:
    .logmech TD2
    .logon proddev/joen,$tdwallet

The logon processing will detect the $tdwallet in the logon information.  Since logon processing is using the TD2 logon mechanism, the logon processing queries joen's wallet for an item named com.teradata.TD2.  This query will result in an item having a value of $tdwallet(password_$(tdpid)).  This matches $tdwallet(somestring) where somestring is password_$(tdpid).  Next "password_$(tdpid)" is processed into "password_proddev".  The logon processing queries joen's wallet for an item named password_proddev.  This query will result in an item having a value of UR1geek2B.  This does not contain any matches of $tdwallet(somestring) or $tdwallet.  So, UR1geek2B is the ultimate replacement yielding logon information of proddev/joen,UR1geek2B, which is used to attempt to log on to the Teradata Database.

Replacement processing can be useful on other parts of the logon information.  To demonstrate, consider the following:

All three of these users could use a shared script having a LOGON command like:

    .logon proddev/$tdwallet(u),$tdwallet(p)

When each user runs the script, the Teradata Database username and Teradata Database password are retrieved from the appropriate wallet during the logon processing.

Notes

Teradata Wallet prevents one user from accessing the wallet information of another user.  However, it makes a user's wallet information freely available to the owning user.  The software provides this enforcement based on the client system's notion of a user.  On Unix/Linux this is by user identifier (UID).  On Windows this is by security identifier (SID).  Obviously, the client computer cannot tell what human is typing on the keyboard, it provides security based on the logged in user.  As such, it is important to secure access to your user account, for example, by logging off or locking your computer when you leave your computer unattended.

At present, only logon processing that is initiated through Teradata CLIv2 for Network Attached Systems and Teradata ODBC Driver utilizes Teradata Wallet.  This includes tools such as:
    - Basic Teradata Query Utility (BTEQ)
    - Teradata FastLoad
    - Teradata MultiLoad
    - Teradata Parallel Data Pump (TPump)
    - Teradata FastExport
    - Teradata ARC
    - Teradata Preprocessor2 (PP2)
    - Teradata Parallel Transporter (TPT)

As a diagnostic tool, you can set the TDWALLET_DEBUG_FILE environment variable before attempting to use Teradata Wallet.  For example:

TDWALLET_DEBUG_FILE=tdwallet.log
export TDWALLET_DEBUG_FILE
fastload < flinsert.fastload
cat tdwallet.log

This will produce a trace of the calls to the Teradata Wallet subsystem.

Good judgment comes from experience and experience comes from bad judgment.