Client security in a TCP/IP network

Different connectivity scenarios call for using different levels of authentication. Therefore, an administrator can set the lowest security authentication method required by the client when connecting to a server by setting the preferred authentication method field in each RDB directory entry.

The administrator might also allow the decision about the authentication method to be negotiated with the server, by choosing to allow a lower security authentication method. In this case the preferred authentication method is still attempted, but if the server cannot accept the preferred method, a lower method can be used, depending on the system security setting and other factors such as the availability of cryptographic support. For example, if two systems are in a physically unprotected environment, the administrator might choose to require Kerberos authentication without allowing lower security authentication methods.

If an encrypted server authentication method is used in the RDB directory entry, you have the option to specify *DES or *AES encryption algorithm on the Add RDB Directory Entry (ADDRDBDIRE) or Change RDB Directory Entry (CHGRDBDIRE) command. ENCALG(*DES) or ENCALG(*AES) determine what the encryption algorithm that will be requested by the client for encryption of the user ID or password. A DDM file may also take advantage of using *AES encryption by creating the DDM file with the *RDB value on RMTLOCNAME keyword of the Create DDM File (CRTDDMF) or Change DDM File (CHGDDMF) command and specifying the RDB on the RDB keyword. If you want all data to be encrypted, SSL allows all data over the network to be encrypted and supports a variety of encryption types.

These settings can be used for setting the encryption algorithm requested by the client for encrypted authentication methods:

ENCALG(*AES)
Advanced Encryption Standard (AES) encryption algorithm will be requested.
ENCALG(*DES)
Data Encryption Standard (DES) encryption algorithm will be requested. This is the default.

On the client side, you can use one of two methods to send a password along with the user ID on DRDA TCP/IP connect requests. If you do not use either of these two methods, the SQL CONNECT statement will send only a user ID for the connection attempt.

The first method to send a password is to use the USER/USING form of the SQL CONNECT statement, as in the following example from the interactive SQL environment:

CONNECT TO rdbname USER userid USING 'password'

In a program using embedded SQL, the values of the user ID and of the password can be contained in host variables in the USER/USING database.

In a program using CLI, the following example shows how the user ID and password are presented in host variables to the DRDA client:

SQLConnect(hdbc,sysname,SQL_NTS,					/*do the connect to the server */
			  uid,SQL_NTS,pwd,SQL_NTS);

A server authentication entry is a second method to define a userid & password to send via a connect request over TCP/IP. A server authentication entry list is associated with every user profile, group profile, or supplemental group profile on the system. By default, the list is empty; However, you can add entries by using the Add Server Authentication Entry (ADDSVRAUTE) command.

Authorization Requirement: To use the ADDSVRAUTE command, you must have the following authorizations:

Security administrator (*SECADM) user special authority
Object management (*OBJMGT) user special authority
Use (*USE) authorities to the profile to which the server authentication entry is to be added or be signed on under that user profile.

To store a password using the ADDSVRAUTE command, you must set the QRETSVRSEC system value to '1'. By default, the value is '0'. Type the following command to change this value:

CHGSYSVAL QRETSVRSEC VALUE('1')

The following example shows the syntax of the ADDSVRAUTE command when using an RDB directory entry:

ADDSVRAUTE USRPRF(user-profile) SERVER(rdbname) USRID(userid) PASSWORD(password)

The USRPRF parameter specifies the user profile under which the client job runs. What you put into the SERVER parameter is normally the name of the RDB or QDDMDRDASERVER to which you want to connect for connections made on behalf of RDB DDM files or DRDA connections. The exception is that if you are using non-RDB DDM files which were not created to use the RDB directory, you should specify QDDMDRDASERVER or QDDMSERVER in the SERVER parameter. The value given for the SERVER parameter must be in uppercase. The USRID parameter specifies the user profile under which the server job will run. The PASSWORD parameter specifies the password for the user profile.

If you omit the USRPRF parameter, it will default to the user profile under which the ADDSVRAUTE command runs. If you omit the USRID parameter, it will default to the value of the USRPRF parameter. If you omit the PASSWORD parameter, or if you have the QRETSVRSEC value set to 0, no password will be stored in the entry and when a connect attempt is made using the entry, the security mechanism attempted will be user ID only.

You can use the Display Server Authentication Entries (DSPSVRAUTE) command to determine what authentication entries have been added to the server authentication list. The Retrieve Server Authentication Entries (QsyRetrieveServerEntries) (QSYRTVSE) API in a user-written program can also be used.

You can remove a server authentication entry by using the Remove Server Authentication Entry (RMVSVRAUTE) command. You can change a server authentication entry by using the Change Server Authentication Entry (CHGSVRAUTE) command

If a server authentication entry exists for a relational database (RDB), and a user ID and password are passed in on the connection request, the user ID and password passed in take precedence over the server authentication entry.

The two special server authentication entry ADDSVRAUTE command SERVER parameter values that are supported by DRDA and DDM are:

QDDMDRDASERVER special value on the ADDSVRAUTE command SERVER parameter for DDM & DRDA connections allows an administrator to configure a user to work with all possible DDM or DRDA connections to any system in the TCP/IP network via a common userid and password. Once configured for a specific user, no additional changes need to be made for that user as systems are added to the Relational Database Directory. As before, this does not allow a customer to connect over DRDA/DDM unless they specify a valid userid and password on the server authentication entry or CONNECT statement. This special value has all of the support that QDDMSERVER has in addition to supporting connections made by RDB DDM files and DRDA connections.

QDDMSERVER special value on the ADDSVRAUTE command SERVER parameter for non-RDB DDM connections allows an administrator to configure a user to work with all possible non-RDB DDM connections to any system in the TCP/IP network via a common userid and password. Once configured for a specific user, no additional changes need to be made for that user as new non-RDB DDM files are created and used. The disadvantage of using QDDMSERVER is it does not support connection made with RDB DDM files or DRDA connections. It is recommended to use QDDMDRDASERVER if DDM file, RDB DDM files and DRDA connections what to take advantage of server authentication entries where a command user userid and password are needed.

When you attempt a DRDA connection over TCP/IP without specifying a userid & password, the Db2® for i client (AR) checks the server authentication list for the user profile under which the client job is running. If it finds a match between the RDB name or QDDMDRDASERVER on the CONNECT statement and the SERVER name in an authentication entry (which must be in uppercase), the associated USRID parameter in the entry is used for the connection user ID. If a PASSWORD parameter is stored in the entry, that password is also sent on the connection request.

A server authentication entry can also be used to send a password over TCP/IP for a DDM file I/O operation. When you attempt a DDM connection over TCP/IP, Db2 for i checks the server authentication list for the user profile under which the client job is running. If it finds a match between either the RDB name (if RDB DDM file is used) or QDDMSERVER (if non-RDB DDM used) and the SERVER name in an authentication entry, the associated USRID parameter in the entry is used for the connection user ID. If a PASSWORD parameter is stored in the entry, that password is also sent on the connection request.

For DRDA connection requests, if a server authentication entry specifying the system name exists, and a userid and password are not passed in on CONNECT statement, the userid and password associated with the server authentication entry will take precedence over the server authentication entry for QDDMDRDASERVER.

For DRDA connection requests, if a server authentication entry specifying the system name exists, and a user ID and password are passed in on CONNECT statement, the user ID and password associated with the CONNECT statement will take precedence over any server authentication entry.

For RDB DDM file connection requests, the server authentication entry specifying the system name will take precedence over the server authentication entry for QDDMDRDASERVER.

For non-RDB DDM file connection requests, the server authentication entry QDDMSERVER will take precedence over the server authentication entry for QDDMDRDASERVER.

Example 1: Using QDDMDRDASERVER for DRDA connections

Environment: Three systems (SYSA, SYSB, SYSC)

SYSA is the application requestor (AR). SYSB and SYSC are the application servers (AS)

On SYSA:

ADDSVRAUTE USRPRF(YOURPRF) SERVER(QDDMDRDASERVER) USRID(youruid) PASSWORD(yourpwd)
STRSQL
CONNECT TO SYSB
CONNECT TO SYSC

At this point, you have two DRDA connections made with the userid 'youruid' and password 'yourpwd' specified on the special server authentication entry value QDDMDRDASERVER.

Example 2: Using system name over QDDMDRDASERVER for DRDA connections

Environment: Three systems (SYSA, SYSB, SYSC)

SYSA is the application requestor (AR). SYSB and SYSC are the application servers (AS)

On SYSA:

ADDSVRAUTE USRPRF(YOURPRF) SERVER(QDDMDRDASERVER) USRID(youruid) PASSWORD(yourpwd)
ADDSVRAUTE USRPRF(YOURPRF) SERVER(SYSB) USRID(yourotheruid) PASSWORD(yourotherpwd)
ADDSVRAUTE USRPRF(YOURPRF) SERVER(SYSC) USRID(yourotheruid) PASSWORD(yourotherpwd)
STRSQL
CONNECT TO SYSB
CONNECT TO SYSC

At this point, you have two DRDA connections made with the userid 'yourotheruid' and password 'yourotherpwd'. This occurs because server authentication entries specifying the system name take precedence over server authentication entries specifying QDDMDRDASERVER.

Example 3: Using mix of system name and QDDMDRDASERVER for DRDA connections

Environment: Three systems (SYSA, SYSB, SYSC)

SYSA is the application requestor (AR). SYSB and SYSC are the application servers (AS)

On SYSA:

ADDSVRAUTE USRPRF(YOURPRF) SERVER(QDDMDRDASERVER) USRID(youruid) PASSWORD(yourpwd)
ADDSVRAUTE USRPRF(YOURPRF) SERVER(SYSB) USRID(yourotheruid) PASSWORD(yourotherpwd)
STRSQL
CONNECT TO SYSB user testuserid using 'testpassword'
CONNECT TO SYSC

At this point, you have two DRDA connections. The connection to SYSB would be made with userid 'testuserid' and password 'testpassword'. This occurs because specifying userid and password on a CONNECT statement takes precedence over server authentication entries. The connection to SYSC would be made with userid 'youruid' and password 'yourpwd' since it will use the QDDMDRDASERVER authentication entry when no other server authentication entry exists specifying the system name.

Example 4: Using mix of QDDMDRDASERVER and QDDMSERVER for RDB DDM and non-RDB DDM connections

Environment: Three systems (SYSA, SYSB, SYSC)

SYSA is the application requestor (AR). SYSB and SYSC are the application servers (AS)

On SYSA:

ADDSVRAUTE USRPRF(YOURPRF) SERVER(QDDMDRDASERVER) USRID(youruid) PASSWORD(yourpwd)
ADDSVRAUTE USRPRF(YOURPRF) SERVER(QDDMSERVER) USRID(youruid2) PASSWORD(yourpwd2)
ADDSVRAUTE USRPRF(YOURPRF) SERVER(SYSC) USRID(yourotheruid) PASSWORD(yourotherpwd)
CRTDDMF FILE(QTEMP/DDMF) RMTFILE(FILE) RMTLOCNAME(SYSB *IP)
CRTDDMF FILE(QTEMP/DDMF2) RMTFILE(FILE) RMTLOCNAME(*RDB) RDB(SYSB)
CRTDDMF FILE(QTEMP/DDMF3) RMTFILE(FILE) RMTLOCNAME(*RDB) RDB(SYSC)

SBMRMTCMD CMD('DSPLIB YOURLIB') DDMFILE(QTEMP/DDMF)

The connection to SYSB would be made with userid 'youruid2' and password 'yourpwd2'. This occurs because non-RDB DDM files will use QDDMSERVER for userid and password at connection time. If QDDMSERVER didn't exist, QDDMDRDASERVER would be used.

SBMRMTCMD CMD('DSPLIB YOURLIB') DDMFILE(QTEMP/DDMF2)

The connection to SYSB would be made with userid 'youruid' and password 'yourpwd'. This occurs because RDB DDM files will use QDDMDRDASERVER for userid and password at connection time if a server authentication entry doesn't exist specifying the system name.

SBMRMTCMD CMD('DSPLIB YOURLIB') DDMFILE(QTEMP/DDMF3)

The connection to SYSC would be made with userid 'yourotheruid' and password 'yourotherpwd'. This occurs because RDB DDM files will not use QDDMDRDASERVER for userid and password at connection time if a server authentication entry exists specifying the system name.

Simplified DDM and DRDA server authentication entry management using group profiles

DDM and DRDA can now take advantage of a common userid and password defined in a server authentication entry under a group profile name or supplemental group profile name. The group profile name or supplemental group profile name is specified on the USRPRF parameter of the Add Server Authentication Entry (ADDSVRAUTE) command. Prior to this enhancement, if server authentication entries were to be used to access an application server that required userid and password authentication, a server authentication entry had to be in place for every user on the system requiring access.

System administration of server authentication entries becomes much simpler when a group profile is used. A common user ID and password profile is used when establishing a group profile based DDM or DRDA connection. Remote connection capability is managed by controlling the users that belong to the group together with their authority to the group profile.

Example:

CRTUSRPRF USRPRF(TESTTEAM) PASSWORD(*NONE)
CRTUSRPRF USRPRF(JIM) PASSWORD(yourpasswordA) GRPPRF(TESTTEAM)
ADDSVRAUTE USRPRF(TESTTEAM) SERVER(QDDMDRDASERVER or <RDB-name of system-B>) USRID(youruseridB) PASSWORD(yourpasswordB)

Signon to <system-A> with Jim's user profile
STRSQL
CONNECT TO <system-B>
(where <system-B> is a RDB entry defined in the Work with Relational Database Directory Entries (WRKRDBDIRE) command.)

A connection is attempted to <system-B> with userid = youruseridB and password = yourpasswordB.

Note: A group member's server authentication entry takes precedence over a group profile's server authentication entry as shown in the order or progression below. The progression of DDM & DRDA server authentication entry checking occurs in the following order. The connection is attempted with the settings of the first match found.

Search the authentication entries where USRPRF=user profile and SERVER= application server name.
Search the authentication entries where USRPRF=user profile and SERVER='QDDMDRDASERVER'.
Search the authentication entries where USRPRF=group profile and SERVER= application server name.
Search the authentication entries where USRPRF=group profile and SERVER='QDDMDRDASERVER'.
Search the authentication entries where USRPRF=supplemental group profile and SERVER= application server name.
Search the authentication entries where USRPRF=supplemental group profile and SERVER='QDDMDRDASERVER'.
If no entry has been found in all previous steps, a USERID-only authentication attempt will be used.

DRDA explicit server name priority when using group profile server authentication entries

By default, group members do not use a group or supplemental group's server authentication entries that explicitly specify an application server name when connecting over DRDA/DDM if that group member uses QDDMDRDASERVER special server authentication entry. This occurs because, QDDMDRDASERVER at the group member is given higher priority over the explicitly named server authentication entries at the group or supplemental group. An environment variable, QIBM_DDMDRDA_SVRNAM_PRIORITY, has been added that allows group or supplemental group's server authentication entries that explicitly specify an application server name to be given higher priority over any use of QDDMDRDASERVER special server authentication entry at the group member, group or supplemental group profile when attempting a DDM/DRDA connection. The benefit of using the environment variable is to allow group or supplemental group's server authentication entries explicitly specifying an application server name to still be used if a group member specifies QDDMDRDASERVER.

To enable explicit server name priority at the system-level:
```
ADDENVVAR ENVVAR(QIBM_DDMDRDA_SVRNAM_PRIORITY) VALUE('Y') LEVEL(*SYS)
```
Restarting the job maybe necessary to pick up the change.

To enable explicit server name priority at the job-level:

ADDENVVAR ENVVAR(QIBM_DDMDRDA_SVRNAM_PRIORITY) VALUE('Y') LEVEL(*JOB)

Example:

ADDENVVAR ENVVAR(QIBM_DDMDRDA_SVRNAM_PRIORITY) VALUE('Y') LEVEL(*JOB)
CRTUSRPRF USRPRF(TESTTEAM) PASSWORD(*NONE)
CRTUSRPRF USRPRF(JIM) PASSWORD(yourpasswordA) GRPPRF(TESTTEAM)
ADDSVRAUTE USRPRF(JIM) SERVER(QDDMDRDASERVER) USRID(youruseridA) PASSWORD(yourpasswordA)
ADDSVRAUTE USRPRF(TESTTEAM) SERVER(<RDB-name for system-B>) USRID(youruseridB) PASSWORD(yourpasswordB)

Signon to <system-A> with Jim's user profile
STRSQL
CONNECT TO <system-B>
(where <system-B> is a RDB entry defined in the Work with Relational Database Directory Entries (WRKRDBDIRE) command.)

A connection is attempted to <system-B> with userid = youruseridB and password = yourpasswordB.
A connection made to any other system will use userid = youruseridA and password = yourpasswordA.

Note: A group member's server authentication entry takes precedence over a group profile's server authentication entry as shown in the order or progression below. The progression of DDM & DRDA server authentication entry checking occurs in the following order when the environment variable is set. The connection is attempted with the settings of the first match found.

Search the authentication entries where USRPRF=user profile and SERVER= application server name.
Search the authentication entries where USRPRF=group profile and SERVER= application server name.
Search the authentication entries where USRPRF=supplemental group profile and SERVER= application server name.
Search the authentication entries where USRPRF=user profile and SERVER='QDDMDRDASERVER'.
Search the authentication entries where USRPRF=group profile and SERVER='QDDMDRDASERVER'.
Search the authentication entries where USRPRF=supplemental group profile and SERVER='QDDMDRDASERVER'.
If no entry has been found in all previous steps, a USERID-only authentication attempt will be used.

Enable DRDA and DDM authentication using user profile's password

This improvement has been officially called DRDA/DDM Conjoined Mutual Authentication and is only supported for IBM i to IBM i connections and enabled through a environmental variable QIBM_CONJOINED_MUT_AUTH.

Prior to this enhancement, users attempting a Distributed Relational Database Architecture™ (DRDA) or Distributed Data Management (DDM) connection needed to specify a password on the SQL CONNECT statement or specify a server authentication entry containing a password if the application server was configured to required a password. This required users or system administrators to spend time managing server authentication entries for all target systems or specify a password at CONNECT time when connecting remotely. If a password was not provided on the SQL CONNECT statement or not specified in a server authentication entry for the application server, the DRDA/DDM connection to the application server requiring a password would fail.

With this enhancement enabled, a IBM i to IBM i DRDA or DDM connection attempt will be made to the application server using the currently signed in user profile's userid & password. This connection attempt is only done if the environment variable is set to a value of Y, and the user has not explicitly specified a userid and password on the SQL CONNECT statement or in a server authentication entry for the application server configured to require a password.

This enhancement in beneficial in networks where users have the same userid and password combination across multiple systems. This enhancement allows users to not have to specify server authentication entries for 3-part connections.

Requirements:

Both the application requestor and application server must be anIBM i at v7r2m0 for it to be supported. This enhancement is enabled when the application requester's job adds an environment variable QIBM_CONJOINED_MUT_AUTH with value of 'Y' (see the Add Environment Variable (ADDENVVAR) command to add the environment variable). The application server must be set to a require a password (see the Change DDM TCP/IP Attributes (CHGDDMTCPA) command PWDRQD keyword). Both systems must have the same userid and password defined for it to connect. Both systems must have the same password level specified in the system value QPWDLVL. The user must not explicitly specify a userid and password on the SQL CONNECT statement or in a server authentication entry for the application server configured to require a password.

To enable conjoined mutual authentication at the system-level:
```
ADDENVVAR ENVVAR(QIBM_CONJOINED_MUT_AUTH) VALUE('Y') LEVEL(*SYS)
```
Restarting the job maybe necessary to pick up the change.

To enable conjoined mutual authentication at the job-level:

ADDENVVAR ENVVAR(QIBM_CONJOINED_MUT_AUTH) VALUE('Y') LEVEL(*JOB)

Note: An IBM i to IBM i DRDA or DDM connection, where a password or a server authentication entry is not specified by the application requestor and the support is enabled, will result in an additional connection attempt to be made to the application server requiring a password to connect. This additional connection attempt will be made using an encrypted userid and password security mechanism where the userid is from the user profile making the connection, and the password is retrieved from that user profile. If it is determined that the passwords match, the connection is allowed as normal. If the passwords do not match, there is a security failure, or a requirement above is not met, a CPF22E2 message will be signaled, and a PW audit record is written. This invalid connection attempt is counted as one invalid signon attempt for the user profile.

Security audit records are written to the QSYS/QAUDJRN security audit journal when auditing is enabled and the auditing level is configured to authorization failures. A PW audit record appears when the userid or password fails to connect.

Kerberos source configuration

Distributed Relational Database Architecture (DRDA) and Distributed Data Management (DDM) can take advantage of Kerberos authentication if both systems are configured for Kerberos.

If a job's user profile has a valid ticket-granting ticket (TGT), the DRDA client uses this TGT to generate a service ticket and authenticate the user to the remote system. Having a valid TGT makes the need for a server authentication entry unnecessary, because no password is directly needed in that case. However, if the job's user profile does not have a valid TGT, the user ID and password can be retrieved from the server authentication entry to generate the necessary TGT and service ticket.

When using Kerberos, the remote location (RMTLOCNAME) in the RDB directory entry must be entered as the remote host name. IP addresses will not work for Kerberos authentication.

In cases where the Kerberos realm name differs from the DNS suffix name, it must be mapped to the correct realm. To do that, there must be an entry in the Kerberos configuration file (krb5.conf) to map each remote host name to its correct realm name. This host name entered must exactly match the remote location name (RMTLOCNAME). The remote location parameter displayed by the Display Relational Database Directory Entries (DSPRDBDIRE) or Display DDM File (DSPDDMF) command must match the domain name in the krb5.conf file. The following figure shows an example of the Display Relational Database Directory Entries (DSPRDBDIRE) command display:


                      Display Relational Database Detail

Relational database  . . . . . . :   RCHASXXX             
Remote location:                                          
  Remote location  . . . . . . . :   rchasxxx.rchland.ibm.com
    Type . . . . . . . . . . . . :   *IP                  
  Port number or service name  . :   *DRDA                
  Remote authentication method:                           
    Preferred method . . . . . . :   *KERBEROS            
    Allow lower authentication . :   *NOALWLOWER          
  Secure connection  . . . . . . :   *NONE                
  Encryption algorithm . . . . . :   *DES                 
Text . . . . . . . . . . . . . . :                        
                                                          
                                                          
Relational database type . . . . :   *REMOTE
                                                                                              
                                                                                              
                                                                                              
                                                                                              
  Press Enter to continue.                                                                    
   F3=Exit   F12=Cancel

Here is a portion of the corresponding krb5.conf file contents showing the domain name matching the remote location name (Note: The Display File (DSPF) command is used to display the configuration file contents):

DSPF STMF('/QIBM/UserData/OS400/NetworkAuthentication/krb5.conf')

[domain_realm]
; Convert host names to realm names. Individual host names may be
; specified. Domain suffixes may be specified with a leading period
; and will apply to all host names ending in that suffix.
 rchasxxx.rchland.ibm.com = REALM.RCHLAND.IBM.COM

Jobs using Kerberos must be restarted when configuration changes occur to the krb5.conf file.