Introducing Teradata Wallet

Tools
Tools covers the tools and utilities you use to work with Teradata and its supporting ecosystem. You'll find information on everything from the Teradata Eclipse plug-in to load/extract tools.
Teradata Employee

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:

Picture of three wallets

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:

davidp's wallet contents

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:

Joen's wallet

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:

three wallets

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.

105 REPLIES
Enthusiast

Re: Introducing Teradata Wallet

Can we use this feature for LDAP ids too or only for NON LDAP and generic ids.
And i tried with NON LDAP id, its not working throwing an error: Logon Failed!
Is there any document or KA on this to explore more on this?

Teradata Employee

Re: Introducing Teradata Wallet

Hi geethareddy,

You asked:
...Can we use this feature for LDAP ids...
Yes, Teradata Wallet can be used in conjunction with LDAP authentication.

You wrote:
...its not working throwing an error: Logon Failed!...
Verify that you are using the latest patch of Teradata CLIv2. If it still does not work for you, try it again with TDWALLET_DEBUG_FILE set as described in this article and send the specifics of what you tried along with the output it produced and the output written via TDWALLET_DEBUG_FILE to your local Teradata support representative.

Thanks!
-shawn :-)

Re: Introducing Teradata Wallet

Hi,
I too getting the same Error : "*** Failure 8017 The UserId, Password or Account is invalid.". Currently, We are in v13.10 version and as you said, i installed recent version of cliv2 (13.10.0.8) and also set the environment variable (TDWALLET_DEBUG_FILE) in windows xp machine. but it is not tracing anything in tdwallet.log file. Please assist me to test this tool.
Teradata Employee

Re: Introducing Teradata Wallet

Hi harshateradata,

You must use a 14.0 version of Teradata CLIv2. Teradata Wallet cannot be used from Teradata CLIv2 13.10.

Thanks!
-shawn :-)
Fan

Re: Introducing Teradata Wallet

Please let me know if I understand this correctly:
-The actual wallet data is stored locally on the application server
-The wallet utility is called on the application server by the user looking to set up its wallet
-The wallet is only accessible to the specific user it is created by (how is this security managed on linux vs windows?)

Thanks!
Marty
Teradata Employee

Re: Introducing Teradata Wallet

Hi Marty,

Teradata Wallet is intended for use on the computer which will be connecting to the Teradata Database. The actual wallet data is stored locally on that computer where you used Teradata Wallet. Teradata Wallet makes wallet data available to the user that created the wallet data while protecting that wallet data from access by other users. Teradata Wallet provides this enforcement based on the operating system's notion of a user. On Unix/Linux computers this is by user identifier (UID). On Windows computers this is by security identifier (SID). All application processes have an associated user. On Unix/Linux computers, you can see the user associated with a given process by displaying process status information by executing the "ps" utility with the "-f" option and inspecting the UID column. On Windows computers, you can see the user associated with a given process by viewing the "User Name" column on the Processes tab of Windows Task Manager. Security for wallet data involves a number of measures including, but not limited to, operating system protections (for example, file-system permissions on Unix/Linux computers) and cryptography (for example, AES-256 on Unix/Linux computers and DPAPI on Windows computers).

Thanks!
-shawn :-)
Enthusiast

Re: Introducing Teradata Wallet

Shwan,
i tried with the V14 CLIv2, but when i tried to login, that time i got the ICU 14 is required, which is not available in T@YS, can you confirm what i am missing here, I really want to implement this at my client place instead of maintaining the passwords in an XL or some where. Also i would like to know about the documentation or Knowledge articles on this, can we get any further info in the form of PDF or something on this great feature.

Thanks.
Enthusiast

Re: Introducing Teradata Wallet

OK i got the confirmation from TERADATA, in the incident they have confirmed this feature is not supported right now. HEre is the comment by GSC rep.
All client packages must be 14.x to match. CLIV2, ICU, BTEQ, etc.... all must be 14.x or it will continue to fail. And yes, when it is in this state, this is unsupported because it is mismatched TTU versions which causes a conflict within all the client packages. All must be 13.xx or 14.xx. Yes, this current method you have set up is not supported. Please either downgrade to 13.10 to match all other TTU packages or upgrade to 14.xx which there may not be all the necessary patches available at this time to fix this issue.
Teradata Employee

Re: Introducing Teradata Wallet

Hi geethareddy,

Teradata Wallet is supported right now, and yes, you do need to use matching Teradata Tools and Utilities 14.0 packages. Teradata ICU 14.0 is available on the Teradata Tools and Utilities 14.0 DVD and is also included in the CLIv2 download bundles available at https://downloads.teradata.com/download/connectivity. You should install software from the DVD and/or from Teradata Developer Exchange and only then install patches from T@YS.

Thanks!
-shawn :-)