With direct mapping, only security level IDENTIFY can be supported.

Figure 4-3 Direct User ID Mapping

Configuring User ID Mapping

Specify parameters bearing on local domain and Tuxedo Mainframe Adapter for SNA security in the DMCONFIG and UBBCONFIG files in the following four sections:

• DM_LOCAL_DOMAINS section of the DMCONFIG file
• DM_SNALINKS section of the DMCONFIG file
• DM_ACCESS_CONTROL section of the DMCONFIG file
• RESOURCES section of the UBBCONFIG file

Determining Security Parameters

The combined settings of the SECURITY parameters in the UBBCONFIG and the DMCONFIG files have the following effects:

• When the DM_LOCAL_DOMAINS security parameter is set to NONE or APP_PW, no action is taken by the Gateway with regard to security.
• However, when the UBBCONFIG file security parameter is set to APP_PW, the application password is validated by an AUTHSVC when clients join the application. The AUTHSVC is provided by the user application.

If security is to be enforced by both the local domain and the host system for each request inbound from the host system to the local domain, the following settings must be made:

• The UBBCONFIG file SECURITY parameter must be set to one of USER_AUTH, ACL, or MANDATORY_ACL.
• The DMCONFIG file DM_LOCAL_DOMAINS section SECURITY parameter must be set to DM_USER_PW.
• The DMCONFIG file DM_SNALINKS SECURITY parameter must be set to IDENTIFY.
• The SNA stack must be configured with the appropriate parameter for IDENTIFY.
• The ATTACHSEC level for the connection definition in the host system must be set to IDENTIFY or VERIFY to match the DMCONFIG file DM_SNALINKS SECURITY parameter.

Determining Security Parameters for Inbound Requests

Table 4-1 shows settings for the SECURITY parameters in the UBBCONFIG and DMCONFIG files required to achieve local domain and host system security combinations for inbound requests from the host system.

Note: Security setting combinations other than those shown in the tables will have unpredictable results.

For requests sent from the host system, the local domain extracts the remote user ID, or user ID and password, from the conversation start-up request and checks the domain security table. That table contains pairs of local principal user IDs and remote user IDs, maintained on a service-by-service basis. The remote user ID is mapped to the local principal user ID. The local principal user ID and password are used for further ACL checking, as specified in the UBBCONFIG file. If the direct user ID mapping option is specified, the remote user ID is used as the local principal user ID.

When a request is received from the host system, the local domain checks the ACL in the DMCONFIG file for the local service to see if requests from the remote domain are permitted. If the DMCONFIG file does not contain an ACL for the local service, the service is accessible to all requests.

Determining Security Parameters for Outbound Requests

If security is to be enforced by both the local domain and the host system for each request outbound from the local domain, the following settings must be made:

• The UBBCONFIG file SECURITY parameter must be set to one of USER_AUTH, ACL, or MANDATORY_ACL.
• The DMCONFIG file DM_LOCAL_DOMAINS section SECURITY parameter must be set to DM_USER_PW.
• The DMCONFIG file DM_SNALINKS SECURITY parameter must be set to IDENTIFY or VERIFY.
• The SNA stack must be configured with the appropriate parameter for IDENTIFY or VERIFY.
• The ATTACHSEC level for the connection definition in the host system must be set to IDENTIFY or VERIFY to match the DMCONFIG file DM_SNALINKS SECURITY parameter.

Table 4-2 shows settings for the SECURITY parameters in the UBBCONFIG and DMCONFIG files required to achieve local domain and host system security combinations for outbound requests.

Note: Security setting combinations other than those shown in the tables will have unpredictable results.

For a request sent to the host system, the local principal user ID is located in the domain security table and the associated remote user ID, or user ID and password, are put into the conversation start-up request before being sent over the LU6.2 conversation. This situation occurs if SECURITY is set to IDENTIFY or VERIFY in the DM_SNALINKS section of the DMCONFIG file. If the direct user ID mapping option is specified, the local principal user ID is put into the conversation startup request.

Setting DMCONFIG File Security Parameters

Three sections in the DMCONFIG file contain parameters affecting Tuxedo Mainframe Adapter for SNA control of access to the ATMI local domain:

• DM_LOCAL_DOMAINS section contains a SECURITY parameter which specifies the type of security enforced for the ATMI local domain.
• DM_SNALINKS section contains a SECURITY parameter that records the security in effect for the host system.
• DM_ACCESS_CONTROL section contains local access control lists used by the ATMI local domain to associate local resources with host systems permitted to have access to them.

Caution: Do not delete the DMCONFIG binary file before running the dmloadcf command. Tables of remote users, remote passwords, and remote mappings are stored in this file. If deleted, all security information must be re-entered.

DM_LOCAL_DOMAINS Section

The SECURITY parameter settings in this section work in conjunction with the SECURITY parameter in the RESOURCES section of the ATMI local domain's UBBCONFIG file to establish how Tuxedo Mainframe Adapter for SNA controls access to the ATMI local domain. The parameter takes the form:

SECURITY = {value}

In this parameter, value can be set as:

NONE

No security is enforced.

APP_PW

No security is enforced.

DM_USER_PW

User and password security is enforced.

If this parameter is set to NONE or APP_PW, the local domain takes no action with regard to security. If this parameter is set to DM_USR_PW, the local domain enforces security according to the setting in the UBBCONFIG file (refer to "Setting DMCONFIG File Security Parameters").

DM_SNALINKS Section

This section of the DMCONFIG file is dedicated to Tuxedo Mainframe Adapter for SNA parameters. It records the security in effect for the host system. It correlates to the values set for the ATTACHSEC parameter in the connection resource definition. In the following parameter definition, remote refers to the ATMI domain and local refers to the host system. The parameter takes the form:

SECURITY_TYPE = {value}

In this parameter, value can be set as:

LOCAL

Specifies that a user identifier is not to be supplied by the remote system. LOCAL is the default value.

IDENTIFY

Specifies that a user identifier is expected on every attach request. All remote users of a system must be identified to the remote external security manager.

VERIFY

Attaches a user ID and valid password to the remote region. The user ID and password are controlled by the region's external security manager.

PERSISTENT

Not fully supported. Functions the same as VERIFY.

MIXIDPE

Not fully supported. Functions the same as VERIFY.

The values LOCAL and IDENTIFY are roughly equivalent to NONE and APP_PW for the SECURITY parameter in the DMCONFIG file.

DM_ACCESS_CONTROL Section

This section contains local ACL used by the ATMI local domain to restrict access by remote regions to local resources. Refer to the "ATMI Security Administration" section in the BEA Tuxedo 8.0 documentation.) Each entry consists of an ACL_NAME resource identifier along with a list of required parameters designating remote domains permitted to access the resource. If no entry exists for a local service, the service is accessible to all remote domains.

Setting UBBCONFIG File Security Parameters

The RESOURCES section in this file contains a SECURITY parameter that works in conjunction with the SECURITY parameter in the DMCONFIG file to establish how Tuxedo Mainframe Adapter for SNA controls access to the ATMI local domain. This parameter takes the form:

SECURITY = {value}

In this parameter, value can be set as:

NONE

No security is enforced (default).

APP_PW

Requires password authorization for the Gateway and administrative tools to connect to the local application.

USER_AUTH

Same as APP_PW, but additional authorization is required on a per-user basis.

ACL

Same as USER_AUTH, but additional access-control checks are done on service names, queue names, and event names. If no Access Control Lists (ACL) exists for a given name, access is granted.

MANDATORY_ACL

Same as ACL, but if no ACL exists for a given name, access is denied.

In most cases, the UBBCONFIG file has already been configured and you do not need to establish the SECURITY parameter settings, but examining this file enables you to see how Tuxedo Mainframe Adapter for SNA enforces security.

If this parameter is set to NONE, no security is enforced. If set to APP_PW, the local ATMI domain's Authorization Server prompts for the application password. If set to USER_AUTH, ACL, or MANDATORY_ACL, the qualified security is enforced as specified.

Bypassing User ID Mapping

To use direct user ID mapping, use the -m parameter in the GWSNAX process start-up command line entry. This parameter allows you to establish direct user ID mapping, rather than ATMI-to-host user ID mapping.

Note: If you bypass user ID mapping, the local and host domains must have identical user IDs in effect, otherwise a security error occurs.

For example, to set the Gateway server process to bypass user ID mapping, enter a command in the following format:

GWSNAX SRVGRP = <groupname> SRVID = <number>  CLOPT = "-A -- -m" 

Refer to GWSNAX in Appendix A, "Administrative Command Reference Pages" for more information.

Using dmadmin Commands to Administer User ID Mapping

When ATMI-to-host user ID mapping is used, you must create mappings in the BDMCONFIG file.

Note: If the direct user ID mapping option is specified, creation of mappings in the BDMCONFIG file is not necessary. Any mappings in the BDMCONFIG file are ignored.

User ID mapping between the local domain and the host system is configured using the addumap, addusr, delumap, modusr, and delusr commands of the dmadmin utility to accomplish the following tasks:

• Adding a User ID and Password
• Mapping a User ID
• Removing User ID Mapping
• Deleting a User ID and Password
• Modifying a Password

Refer to Appendix A, "Administrative Command Reference Pages" for more information about each ATMI command.

To use these commands, enter dmadmin at the system prompt. At the dmadmin ">" prompt, enter the commands as described.

Adding a User ID and Password

Use the addusr ATMI command to add an ATMI local domain user ID and password to the remote domain user and password file. Enter the following command:

addusr {-d} local_domain_id {-R} remote_domain_id {-u} remote_userid [{-w}]

The arguments and options in this command are defined in the following way:

-d

Specifies the name of the local domain with which the user ID and password are associated.

-R

Specifies the name of the remote domain to which the user ID and password are added.

-u

Specifies the user name to be added. Enter the user's password when prompted.

-w

Specifies not to prompt for password. Use when running with IDENTIFY.

Mapping a User ID

Use the addumap ATMI command to map a local domain principal user ID number to a remote domain user name. The user ID must be added before it can be mapped. Refer to the "Adding a User ID and Password" section. Enter the following command:

addumap {-d} local_domain_id {-R} remote_domain_id
{-p} local_principal_userid {-u} remote_userid

The arguments and options in this command are defined in the following way:

-d

Specifies the name of the local domain with which the user ID is associated.

-R

Specifies the name of the remote domain to which the user ID is mapped.

-p

Specifies the local principal user ID number defined in the tpusr.

-u

Specifies the remote user name as defined in the security application of the remote domain.

Removing User ID Mapping

Use the delumap ATMI command to remove the mapping for a local domain principal user ID to a remote domain user name. Enter the following command:

delumap {-d} local_domain_id {-R} remote_domain_id
{-p} local_principal_userid {-u} remote_userid

The arguments and options in this command are defined in the following way:

-d

Specifies the name of the local domain with which the user ID is associated.

-R

Specifies the name of the remote domain to which the user ID is mapped.

-p

Specifies the local principal user ID number defined in the tpusr.

-u

Specifies the remote user name as defined in the security application of the remote domain.

Deleting a User ID and Password

Use the delusr ATMI command to remove a local ATMI domain user ID and password from the remote domain user and password file. The mapping for a user ID must be removed before the user ID can be removed. Enter the following command:

delusr {-d} local_domain_id {-R} remote_domain_id {-u} remote_userid

The arguments and options in this command are defined in the following way:

-d

Specifies the name of the local domain with which the user ID and password are associated.

-R

Specifies the name of the remote domain from which the user ID and password are to be deleted.

-u

Specifies the user name to be deleted.

Modifying a Password

Use the modusr ATMI command to modify a local domain user's password recorded in a remote domain's user and password file. Enter the following command:

modusr {-d} local_domain_id {-R} remote_domain_id {-u} remote_userid [{-w}]

The arguments and options in this command are defined in the following way:

-d

Specifies the name of the local domain the user ID and password are associated with.

-R

Specifies the name of the remote domain in which the user ID and password are to be modified.

-u

Specifies the user name to be modified. Enter the user's password when prompted.

-w

Specifies not to prompt for password. Use when running with IDENTIFY.

Setting Security Scenario

This section provides an example of step-by-step instructions for setting up security in an application that has already been configured.

Configuring Security in the ATMI Domain

Edit the UBBCONFIG file.
In the RESOURCES section, add SECURITY USER_AUTH.
In the SERVERS section, add the AUTHSVR server.

Note: SECURITY USER_AUTH level implies that application passwords, user IDs, and user passwords are required to join the application. AUTHSVR is the ATMI-supplied authentication server. It advertises the service AUTHSVC.

Enter the tmloadcf command to load the ATMI configuration, for example:

tmloadcf -y ubbconfig.sna

Set the application password. (The tmloadcf command prompts for the application password.)
Add users to the ATMI domain by using the tpusradd command. The command prompts for each password, for example:

tpusradd me 

(Enter password for me.)

Note: Do not use the command tpaddusr.

Modify the ATMI client to specify security parameters in the tpinit call. Listing 4-1 is an example of the code to do this.

Listing 4-1 Security Parameters Added to tpinit Call

    TPINIT *tpinitbuf;
    char passwd[30];
    int security_level;

/* Initialize security parameters */

    if ((tpinitbuf = (TPINIT *) tpalloc("TPINIT", NULL,
    TPINITNEED(sizeof(passwd)))) == NULL)

    {
	userlog("tpalloc tpinit failed %s \n", tpstrerror(tperrno));
	exit(1);
    }
    strcpy(tpinitbuf->usrname,"");
    strcpy(tpinitbuf->cltname,"");
    strcpy(tpinitbuf->passwd,"");
    strcpy(tpinitbuf->grpname,"");

/* Determine level of enforced security */
    security_level = tpchkauth();

    if ((security_level == TPSYSAUTH) || (security_level ==
    TPAPPAUTH))

    {
	fprintf(stdout,"\nApplication passwd required.");
	fprintf(stdout,"\nApplication passwd:");
	gets(tpinitbuf->passwd);
    }

    if (security_level == TPAPPAUTH)

    {
	fprintf(stdout,"\nUser Name required.");
	fprintf(stdout,"\nUser Name:");
	gets(tpinitbuf->usrname);

	fprintf(stdout,"\nUser Password required.");
	fprintf(stdout,"\nUser Password:");
	gets(passwd);
	strcpy(&tpinitbuf->data,passwd);
	tpinitbuf->datalen=strlen(passwd);
    }

    if (tpinit(tpinitbuf) == -1) 
    {
        userlog("TPINIT %s \n", tpstrerror(tperrno));
        exit(1);
    }

Verify security in the ATMI domain by running the client.
Enter the dmloadcf command to load the domain configuration. For example:

dmloadcf -y dmconfig.sna

Enter the tmboot command to boot the ATMI domain, for example:

tmboot -y

Configure security for the SNA domain by editing the DMCONFIG file.
In the DM_LOCAL_DOMAINS section, add the parameter:

SECURITY=DM_USER_PW

In the DM_SNALINKS section, add the parameter for the remote link:

SECURITY=VERIFY

Add the user name mapping for the remote domain by invoking dmadmin and using the addumap command to map local user IDs to remote user IDs. For example:

dmadmin
>addumap -d myldom -R myrdom -p localme -u REMOTEME

Add a password for remote user IDs for the remote domain by invoking dmadmin and using the addusr command to provide remote password(s). For example:

dmadmin
>addusr -d myldom -R myrdom -u REMOTEME

(The system responds with the following prompts:

ERROR: Enter Remote User's Password:
ERROR: Re-enter Remote User's Password:)

Configuring Security in the Local Domain

To configure security in the local domain:

• Set the security parameters in the SNA stack.

Refer to the appropriate stack documentation.

Configuring Security in the Remote Domain

Change the security of connection definitions on the mainframe host by doing the following:

Expand the group that contains the connection definitions. For example:

CEDA EX GR(MYCONNGRP)

Replace MYCONNGRP with the name of the group that contains your connection definitions.

Alter security of each connection definition by changing the value of ATTACHSEC to VERIFY on each connection definition.
Put each connection out of service by inquiring on the connection's CEMT I CONN(MYCN) and tabbing to the connection, then changing the INS entry to OUT.
Install the modified connection definitions. For example:

CEDA I GR(MYCONNGRP)

Replace MYCONNGRP with the name of the group that contains your connection definitions.

The security definition is complete. Run the application.

Setting the Security Level to IDENTIFY

To configure the previous example with a security level of IDENTIFY, complete the following steps:

Change the SECURITY parameter in the DMCONFIG file to IDENTIFY.
Change the ATTACHSEC parameter on the connection to IDENTIFY.
Change the remote user password by using the addusr -w option so that no password is specified as in the following example:

addusr -d myldom -R myrdom -u REMOTEME -w

Using Encryption

To establish secure communications between the Communication Resource Manager (CRM) and the Gateway (GWSNAX) over a distributed network, Tuxedo Mainframe Adapter for SNA uses a link-level encryption process.

Illustration of Encryption Process

As illustrated in the following diagram, this encryption feature only applies to the link between the Tuxedo Mainframe Adapter for SNA Gateway and the CRM.

Note: The appropriate ATMI security add-on (40 bit or 128 bit) must be purchased to enable encryption.

Figure 4-4 Encrypted Links

The encryptions process occurs in the following way:

When the Gateway establishes a connection to the CRM, the entities exchange messages to determine if encryption is enabled.
If both entities have encryption capability, a negotiation is performed to determine the level of encryption established.

Each process has a range of acceptable encryption levels, as specified on the process start-up command line. The lowest common level of encryption is used.

Note: When encryption is established for communications between the CRM and the Gateway, system performance may deteriorate. The higher the encryption level, the more likely deterioration may occur.

Configuring the Tuxedo Mainframe Adapter for SNA Gateway and CRM for Encryption

To configure the Tuxedo Mainframe Adapter for SNA Gateway:

Determine acceptable range of encryption levels (min and max).
Edit the GWSNAX entry in the UBBCONFIG file to add the -n option with the desired min and max.

See GWSNAX in Appendix A, "Administrative Command Reference Pages."

To configure the CRM:

Determine acceptable range of encryption levels (min and max).
Configure the CRM in one of the following ways:
• If the CRM is started from the command line, add the -n option with the desired min and max, as described in SNACRM in Appendix A, "Administrative Command Reference Pages."
• If the CRM is started as an ATMI server, modify the SNACRM server entry to contain the -n option with the desired min and max, as described in SNACRM in Appendix A, "Administrative Command Reference Pages."

If crmlkoff, crmlkon, or crmdown are used with encrypted CRM, no additional command line arguments are needed.

Using TCP/IP Link Authentication

In addition to encryption, Tuxedo Mainframe Adapter for SNA uses an authentication process to establish secure communications between the CRM and Gateway over a distributed network.

Table 4-3 lists the processes that support authentication.

Illustration of Authentication Process

As illustrated in the following diagram, this authentication feature only applies to the link between the Gateway and the CRM.

Figure 4-5 Authenticated Links

When the Gateway establishes a connection to the CRM, the following events occur:

Each entity issues a challenge.
• The challenge is based on a random number combined with an authentication key.
• The authentication key is contained in a key file designated by the process command line specification.
Each entity issues a response to the challenge it receives. This response is based on the challenge combined with the entity's authentication key.
Each entity verifies the response by comparing the response to its own calculated result.
• If the challenge/response exchange fails, the connection is closed and an error is logged.
• If the challenge/response succeeds, full communications are enabled.

Configuring the Tuxedo Mainframe Adapter for SNA Gateway and CRM for Authentication

To configure the Gateway for authentication, complete the following steps:

Establish an authentication key file.
• Create a text file containing the authentication key. This key should be no more than eight characters. Communicating processes must have the same entry in their key files for authentication to be successful.
• Store the keyfile in a protected location.
Use a general command line entry with the following format to establish authentication, as described in GWSNAX in Appendix A, "Administrative Command Reference Pages":

 [-u <keyfile>] 

To configure the CRM:

Establish an authentication key file.
• Create a text file containing the authentication key. This key should be no more than eight characters. Communicating processes must have the same entry in their key files for authentication to be successful.
• Store the keyfile in a protected location.
Configure the CRM in one of the following ways:
• If the CRM is started from the command line, add the -u<keyfile> option, as described in SNACRM in Appendix A, "Administrative Command Reference Pages."
• If the CRM is started as an ATMI server, modify the SNACRM server entry to contain the -u<keyfile> option as described in SNACRM in Appendix A, "Administrative Command Reference Pages."
If crmlkoff, crmlkon, or crmdown are used with a CRM with authentication enabled, use the -u<keyfile> command line option as described in SNACRM in Appendix A, "Administrative Command Reference Pages."

Using Third-Party Security Software

The Tuxedo security plug-in allows users to customize security functions and use alternate implementations of third-party security software. The Tuxedo security plug-in is set up during Tuxedo plug-in configuration. Refer to the Tuxedo documentation for specific information about this feature.