Using tdgssauth Syntax - Advanced SQL Engine - Teradata Database

Security Administration

Product
Advanced SQL Engine
Teradata Database
Release Number
17.10
Published
July 2021
Language
English (United States)
Last Update
2022-02-15
dita:mapPath
ppz1593203596223.ditamap
dita:ditavalPath
wrg1590696035526.ditaval
dita:id
B035-1100
lifecycle
previous
Product Category
Teradata Vantage™

Run tdgssauth from the Teradata Vantage command prompt. Enter the tdgssauth options needed for your test. For example:

su - teradata
tdgssauth -u  username  -m  mechanism  -i  IP_address
The following rules apply when using tdgssauth:
  • You can specify tdgssauth options in any order, but they must be separated by spaces.
  • The input is case sensitive.
  • Become the teradata user (su - teradata) if the system is configured for CA certificates as part of setting up TLS. This causes tdgssauth to run under the Linux user teradata instead of root, which accurately represents how the system processes authentication when CA certificates are present. Also see Using TLS with a Directory Server.

Using tdgssauth Options

Option Description
Initialization Options
-t directory Perform a test mode initialization. In this mode the user provides a directory path to the TDGSS package when the package is located outside of the normal TDGSS directory. If this option is not specified, a normal server mode initialization is performed.

Mutually exclusive with -v.

-v version Specifies the TDGSS version to test when performing a server mode initialization.

If the version is not specified, the currently active version of TDGSS is assumed. One can determine the available versions of TDGSS by examining the contents of the directory /opt/teradata/tdat/tdgss.

May not be used with -t. May be used only with server-mode initialization.

-b If the tdgssconfig.bin file is present, this option causes TDGSS to read its configuration information from the selected TDGSS's tdgssconfig.bin file. If this file is not present, the selected TDGSS's tdgssconfig.bin.prebuilt file is read. This option is useful for debugging Unity-based LDAP and Kerberos authentication on Unity nodes.

If neither file is present, the command fails.

Context Establishment Options (see Rules for tdgssauth Options That Control Authentication)
-m mechanism Specifies the security mechanism to exercise. If a mechanism is not specified, the mechanism defaults to TD2.
-n target Specifies the target Service Principal Name (SPN).

This name is required for Kerberos (KRB5) authentication. It is formed by concatenating the string TERADATA, a slash character, and the fully qualified primary DNS name of the node where the tool is running. For example, if the tool is being run from a node named dbc1.example.com, then the target name would be TERADATA/dbc1.example.com.

The user has control of the target name to allow testing non-Teradata targets and to vary the primary node name when case-sensitivity is needed.

-D Requests establishment of a security context capable of delegation. A context so established permits the server to impersonate the client in other services.

Note that specifying this option is only a request; there is no guarantee that the context will be capable of delegation.

-M Requests that mutual authentication occur during context establishment. Mutual authentication requires that the two participants in context establishment fully authenticate each other.

Note that specifying this option is only a request; there is no guarantee that mutual authentication will occur.

-R Request replay detection.
-S Requests that the context be established to permit detection of out of sequence messages.

Note that specifying this option is only a request; there is no guarantee that out of sequence detection will be possible.

-I Requests establishment of a security context capable of guaranteeing message integrity. A context with integrity capability can generate message integrity codes suitable for the authentication mechanism to help the peer determine when a message tampering has occurred.

Note that specifying this option is only a request; there is no guarantee that the context will be capable of guaranteeing message integrity.

-C Requests establishment of a security context capable of confidentiality. A context capable of confidentiality will be capable of encrypting or decrypting network traffic.

Note that specifying this option is only a request; there is no guarantee that the context will be capable of confidentiality.

-? Requests that a usage message be displayed.
-u username Specifies the username to authenticate. This option is required for mechanisms that do not support single sign on.
-w password Specifies the user's password when a credential is required. If -w is omitted the tool prompts for the password and it is read securely from the user's terminal. Teradata recommends that passwords never be provided on a command line because command lines are visible to other users using tools like ps.
-a additional-logdata Specifies additional authorization information other than authcid and password; for example, you can specify profile information: tdgssauth -u user -w password -a profile=myprofile -m ldap
-i ipaddr The IPv4 or IPv6 address of the client to use in security policy tests. If this option is not included, security policy checks will not be performed.

If -i is included but -u has not been specified and the mechanism is non-authenticating (such as TD2), security policy checks will not be performed.

Message Exchange Options
-T text

Requests that the specified text be wrapped and unwrapped. Wrapping is the process where an integrity code is added to the message and the message is optionally encrypted. Unwrapping is the process where a wrapped message is decrypted (if it was encrypted) and the integrity of the message is verified.

Four things happen for each message. First, the client's context is used to wrap the message and the resulting wrapped token is dumped in hex form. Second, the server's context is used to unwrap the message wrapped by the client's context and the results of the unwrap operation are dumped. Third, the server's context is used to wrap the unwrapped message and the results of the wrapping are dumped. Finally, the client's context is used to unwrap the message wrapped by the server's context and the results of the unwrapping are dumped.

The tool accepts zero or more -T options on the command line. The process described above is followed for each -T option.

-e

Requests encryption. Specifically, this option requests that the text specified in -T options have both confidentiality and a message integrity code applied. Normally, TDGSS will add a message integrity code.

If policy enforcement requires confidentiality, then this option will have no effect. If policy enforcement requires integrity only or nothing at all, this option will add confidentiality by causing the text specified in the -T options to be encrypted.

-q qop

Request that wrapping be done with a particular QoP (Quality of Protection). Legitimate values are numbers in the range 0 through 3 or the mnemonic names of default, low, medium, and high.

If policy enforcement requires more protection than the user has requested with -q and -e, policy enforcement's choice overrides the user's selection. If the user's selection is greater than the minimum required by policy enforcement, the user's selection is used.

Tracing Options
-V level

Enable token dumps during context establishment and optionally add low level LDAP tracing depending on the value of level. The level argument is an integer value resulting from OR-ing the following bit values:

  • 0x0001 - Execution traces
  • 0x0002 - LDAP packets
  • 0x0004 - Passed arguments
  • 0x0008 - Connection information

    0x0010 - BER encoding

The output includes the user's password and the database service password. Both the character interpretation and dumped hex need to be changed before sharing this trace information.
-l Enables TDNEGO logging display.

Rules for tdgssauth Options That Control Authentication

The tdgssauth options that control authentication are: -u, -w, and -a. The following rules apply for using these options:
  • If the mechanism supports authentication then at least one of -u or -a must be specified.
  • If the mechanism supports authentication and -u is specified, the user's name and password are hardcoded into a properly escaped and quoted User Principal Name (UPN). If -a has been specified, then a space character and the value provided in the -a option are appended to the UPN and the resulting string is used as mechdata (.logdata).
  • If the mechanism supports authentication and -u is not specified, -a must be specified and the value passed must be complete mechdata, which includes the user's name and password (legacy mode).
  • If the mechanism does not support authentication, then -u must be specified only if security policy checks are to be made.
  • If the mechanism supports authentication but does not support single sign on, a password is required. The password is provided using the –w option (not recommended) or by allowing tdgssauth to securely prompt for the password.