Using Security in ATMI Applications

Administering Security

The following sections explain how to set security policies for a BEA Tuxedo ATMI application:

• What Administering Security Means
• Security Administration Tasks
• Setting the BEA Tuxedo Registry
• Configuring an ATMI Application for Security
• Setting Up the Administration Environment
• Administering Default Authentication and Authorization
• Using the Kerberos Authentication Plug-in
• Kerberos Plug-In
• Kerberos Plug-In Pre-configuration
• Kerberos Plug-In Configuration
• Using the Cert-C PKI Encryption Plug-in
• Cert-C PKI Encryption Plug-In
• Cert-C PKI Encryption Plug-In Pre-configuration
• Cert-C PKI Encryption Plug-In Configuration

 

---

What Administering Security Means

Administering security for an ATMI application involves setting and enforcing security policies for the components of the application, including its clients, server machines, and gateway links. The application administrator sets the security policies for the ATMI application, and the BEA Tuxedo system upon which the ATMI application is built enforces those policies.

The BEA Tuxedo system offers the following ATMI security capabilities:

• Authentication
• Authorization
• Auditing
• Link-level encryption
• Public key security

All but one of the security capabilities can be configured by the application administrator. The exception is auditing, which cannot be configured, as shown in the following figure.

Figure 2-1 Administering ATMI Security

 

See Also

• Security Administration Tasks
• What Security Means
• What Programming Security Means

 

---

Security Administration Tasks

Security administration consists of the following tasks:

• Setting the BEA Tuxedo registry
• Configuring an ATMI application for security
• Setting up the administration environment
• Administering operating system (OS) security
• Administering authentication
• Administering authorization
• Administering link-level encryption
• Administering public key security

See Also

• Setting the BEA Tuxedo Registry

 

---

Setting the BEA Tuxedo Registry

The application administrator needs to know about the BEA Tuxedo registry if the ATMI application is to be configured with one or more custom security capabilities. On the other hand, if the ATMI application is to be configured only with default security, the BEA Tuxedo registry does not need to be changed.

The BEA Tuxedo registry is a disk-based repository for storing information related to plug-in modules. Initially, this registry holds registration information about the default security plug-ins.

Purpose of the BEA Tuxedo Registry

Most BEA middleware products use a common transaction processing (TP) infrastructure that consists of a set of core services, such as security. The TP infrastructure is available to ATMI applications through well defined interfaces. These interfaces allow application administrators to change the default behavior of the TP infrastructure by loading and linking their own service code modules, referred to as plug-in modules or simply plug-ins.

The first step in loading a plug-in is to register the plug-in with the host operating system. Registering a plug-in adds an entry for the plug-in to the BEA Tuxedo registry, which is a set of binary files that stores information about active plug-ins. There is one registry per BEA Tuxedo installation.

• On a UNIX host machine, the BEA Tuxedo registry is in the $TUXDIR/udataobj directory.
• On a Windows 2003 host machine, the BEA Tuxedo registry is in the %TUXDIR%\udataobj directory.

Every Workstation client and server machine in an ATMI application must use the same set of plug-in modules.

Registering Plug-ins

The administrator of an ATMI application in which custom plug-ins will be used is responsible for registering those plug-ins and performing other registry related tasks. An administer can register plug-ins in the BEA Tuxedo registry only from the local machine. That is, an administrator cannot register plug-ins while logged on to the host machine from a remote location.

Three commands are available for administering plug-ins:

• epifreg—for registering a plug-in
• epifunreg—for unregistering a plug-in
• epifregedt—for editing registry information

Instructions for using these commands are available in Developing Security Services for ATMI and CORBA Environments. (This document contains the specifications for the security plug-in interface, and describes the plug-in framework feature that makes the dynamic loading and linking of security plug-in modules possible.) Also, when installing custom plug-ins, the supplying third-party security vendor should provide instructions for using these commands to set up the BEA Tuxedo registry to access the custom plug-ins.

For more information about security plug-ins, including installation and configuration procedures, see your BEA account executive.

See Also

• Configuring an ATMI Application for Security

 

---

Configuring an ATMI Application for Security

An application administrator configures security for the ATMI application on the MASTER machine when the application is inactive. The underlying BEA Tuxedo system propagates the configuration information to the other machines in the ATMI application when the application is booted.

As the administrator, you can configure security for your ATMI application by:

• Editing the configuration file (UBBCONFIG)
• Changing the TM_MIB, or
• Using the BEA Administration Console

The set of security parameters involved depends upon the security capability (authentication, authorization, link-level encryption, or public key) and whether you are using the default or custom security software.

Editing the Configuration File

You can edit the UBBCONFIG configuration file to set security policies for an ATMI application. The UBBCONFIG configuration file may have any filename, as long as the content of the file conforms to the format described on the UBBCONFIG(5) reference page in the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

For more details about UBBCONFIG and its binary equivalent, TUXCONFIG, see About the Configuration File on page 2-1 and Creating the Configuration File on page 3-1 in Setting Up a BEA Tuxedo Application.

Changing the TM_MIB

The TM_MIB defines a set of classes through which the fundamental aspects of an ATMI application may be configured and managed. Separate classes are designated for machines, servers, networks, and so on. You should use the reference page TM_MIB(5) in combination with the generic Management Information Base (MIB) reference page MIB(5) to format administrative requests and interpret administrative replies. The MIB reference pages are defined in the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

Other component MIBs, including the ACL_MIB, DM_MIB, and WS_MIB, also play a role in managing security for an ATMI application. The reference page ACL_MIB(5) defines the ACL_MIB, the reference page DM_MIB(5) defines the DM_MIB, and the reference page WS_MIB(5) defines the WS_MIB.

For more information about BEA Tuxedo MIBs, start with MIB(5) in the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference. Also, see Introducing BEA Tuxedo ATMI.

Using the BEA Administration Console

You can also use the BEA Administration Console to change security policies for an ATMI application. The BEA Administration Console is a Web-based tool used to configure, monitor, and dynamically re-configure an application.

For details about the BEA Administration Console, see Introducing BEA Tuxedo ATMI.

See Also

• Setting Up the Administration Environment

 

---

Setting Up the Administration Environment

The application administrator defines certain environment variables for an ATMI application as part of configuring the application. The values defined for the variables are absolute pathnames that reference BEA Tuxedo executables and data libraries.

Being able to find such files is essential to the job of administering an ATMI application. For example, all commands needed to manage application security are located in $TUXDIR/bin on a UNIX host machine, and in %TUXDIR%\bin on a Windows 2003 host machine.

For details on setting up the administration environment, see Administering a BEA Tuxedo Application at Run Time.

See Also

• Administering Operating System (OS) Security
• Administering Authentication
• Administering Authorization
• Administering Link-Level Encryption
• Administering Public Key Security
• Security Administration Tasks

 

---

Administering Operating System (OS) Security

In addition to the security features in the ATMI environment of the BEA Tuxedo product, the application administrator needs to take full advantage of the security features of the host operating system to control access to files, directories, and system resources.

Most ATMI applications are managed by an application administrator who configures and boots the application, monitors the running application, and makes changes to it dynamically, as necessary. Because the ATMI application is started and run by the administrator, server programs are run with the administrator's permissions and are therefore considered secure or "trusted." This working method is supported by the login mechanism and the read and write permissions on the files, directories, and system resources provided by the underlying operating system.

Clients, on the other hand, are not started by the administrator. Instead, they are run directly by users with their own permissions. As a result, clients are not trusted.

In addition, users running native clients (that is, clients running on the same machine on which the server is running) have access to the configuration file and interprocess communication (IPC) mechanisms such as the bulletin board (in shared memory). Users running native clients always have such access, even when additional ATMI security is configured.

Recommended Practices for OS Security

As the administrator, you can improve operating system security by observing the following general rules:

• Limit access to files and IPC resources to the application administrator.
• Have "trusted" client programs run only with the permissions of the administrator (using a setuid utility).
• For maximum security on your operating system, allow only Workstation clients to access the application; client programs should not be allowed to run on the same machines on which application servers and administrative programs run.
• Combine all of these practices with ATMI security so that the application can identify any client making a request.

See Also

• Operating System (OS) Security
• Security Administration Tasks

 

---

Administering Authentication

Authentication allows communicating processes to prove their identities. It is the foundation for most other security capabilities.

Except for the configuration instructions identified in this topic, the procedures for administering authentication depend upon the underlying authentication system of the application. For procedures to administer a custom authentication system, see the documentation for that system. For procedures to administer the default authentication system, see Administering Default Authentication and Authorization.

The following figure demonstrates the use of the delegated trust authentication model by applications running BEA Tuxedo release 7.1 or later software. Workstation handlers (WSHs) and domain gateways (GWTDOMAINs) are known as trusted system gateway processes in the delegated trust authentication model, which is described in Understanding Delegated Trust Authentication.

 

Figure 2-2 Mutual Authentication in the Delegated Trust Authentication Model

 

Note: Mutual authentication is not used for a native client, which authenticates with itself.

The following topics provide the instructions needed to set up the configuration shown in the preceding figure. All of the topics involve authentication and the authentication plug-in.

• Specifying principal names
• Mandating interoperability policy
• Establishing a link between domains
• Setting ACL policy
• Setting credential policy

See Also

• Authentication
• Default Authentication and Authorization
• Administering Default Authentication and Authorization
• Security Administration Tasks
• Security Interoperability
• Security Compatibility
• BEA Tuxedo Domains (Multiple-Domain) Servers on page 3-14 in Introducing BEA Tuxedo ATMI

 

---

Specifying Principal Names

As the administrator, you use the following configuration parameters to specify principal names for the workstation handler (WSH), domain gateway (GWTDOMAIN), and server processes running in your ATMI application built with release 7.1 or later of the BEA Tuxedo software.

 

SEC_PRINCIPAL_NAME may be specified any of the following four levels in the configuration hierarchy:

• RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
• MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
• GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
• SERVERS section in UBBCONFIG or T_SERVER class in TM_MIB

A security principal name at a particular configuration level can be overridden at a lower level. For example, suppose you configure terri as the principal name for machine mach1, and john as the principal name for server serv1 running on mach1. The processes on mach1 behave as follows:

• All WSH, domain gateway, and server processes on mach1 except serv1 processes use terri as a principal name.
• All serv1 processes use john as a principal name.

How System Processes Acquire Credentials

During application booting, each WSH, domain gateway, and server process in the ATMI application includes its security principal name as an argument when calling the authentication plug-in to (1) acquire security credentials and (2) get authorization and auditing tokens for itself. The following figure demonstrates the procedure.

Figure 2-3 Acquiring Credentials and Tokens During Application Booting

 

Each domain gateway process in the application calls the authentication plug-in a second time to acquire credentials and tokens for its assigned connection principal name.

Why System Processes Need Credentials

A WSH needs credentials so that it can authenticate Workstation clients that want to join the application, and to get authorization and auditing tokens for the authenticated Workstation clients. A WSH needs its own authorization and auditing tokens when handling requests from pre-release 7.1 clients (clients running BEA Tuxedo release 6.5 or earlier software) so that it can call the authentication plug-in to establish identities for the older clients. This behavior is described in Mandating Interoperability Policy.

A domain gateway needs one set of credentials so that it can authenticate remote domain gateways for the purpose of establishing links between ATMI applications, as described in Establishing a Link Between Domains. (No authorization or auditing tokens are assigned to authenticated remote domain gateways.) A domain gateway acquires these credentials for the principal name specified in the CONNECTION_PRINCIPAL_NAME parameter.

A domain gateway needs a second set of credentials so that it can handle requests from pre-release 7.1 clients, which involves calling the authentication plug-in to establish identities for the older clients. This behavior is described in Mandating Interoperability Policy. It also needs these credentials to establish identities when enforcing the local access control list (ACL) policy, as described in Setting ACL Policy. A domain gateway acquires these credentials for the principal name specified in the SEC_PRINCIPAL_NAME parameter.

A system or application server needs its own authorization and auditing tokens when handling requests from pre-release 7.1 clients so that it can call the authentication plug-in to establish identities for the older clients. This behavior is described in Mandating Interoperability Policy.

A server also needs its own tokens when performing a server permission upgrade, which occurs when the authorization and auditing tokens of the server are assigned to messages that pass through the server but originate at a client. The service upgrade capability is described in Replacing Client Tokens with Server Tokens.

Note: An application server cannot call the authentication plug-in itself. It is the underlying system code that calls the authentication plug-in for the application server.

Example UBBCONFIG Entries for Principal Names

The following example pertains to specifying security principal names in the UBBCONFIG file using the SEC_PRINCIPAL_NAME parameter. For an example of specifying connection principal names in the DMCONFIG file using the CONNECTION_PRINCIPAL_NAME parameter, see Example DMCONFIG Entries for Establishing a Link.

*RESOURCES
SEC_PRINCIPAL_NAME    "Tommy"
     .
     .
     .

*SERVERS
"TMQUEUE"       SRVGRP="QUEGROUP"      SRVID=1
   CLOPT="-t -s secsdb:TMQUEUE"
   SEC_PRINCIPAL_NAME="TOUPPER"

See Also

• Mandating Interoperability Policy
• Establishing a Link Between Domains
• Setting ACL Policy
• Security Administration Tasks

 

---

Mandating Interoperability Policy

As the administrator, you use the CLOPT -t option in the UBBCONFIG file to allow WSH, domain gateway (GWTDOMAIN), and server processes in your ATMI application to interoperate with machines running BEA Tuxedo pre-release 7.1 (6.5 or earlier) software. In addition, you use the WSINTOPPRE71 environment variable to allow Workstation clients to interoperate with machines running BEA Tuxedo pre-release 7.1 software. The following four figures show what interoperability means for these processes.

Figure 2-4 WSH Operating with Older Workstation Client

 

In the preceding figure, the WSH authenticates with the Workstation client using an older (pre-release 7.1) authentication protocol, calls the internal impersonate user function to get authorization and auditing tokens for the client, and attaches the tokens to the client request. If the CLOPT -t option is not specified for the workstation listener (WSL) that controls the WSH, no communication is possible between the newer WSH and the older Workstation client.

Note: The impersonate user function involves calling the authentication plug-in to establish an identity for the older client. See Establishing an Identity for an Older Client for details.

Figure 2-5 Older WSH Operating with Workstation Client

 

In the preceding figure, the WSH authenticates with the Workstation client using an older (pre-release 7.1) authentication protocol; the client request does not receive authorization and auditing tokens. If the WSINTOPPRE71 environment variable is not set at the Workstation client or is set to N, no communication is possible between the older WSH and the newer Workstation client.

Figure 2-6 Server Interoperating with Older ATMI Application

 

In the preceding figure, the local domain gateway (GWTDOMAIN) in application 1 authenticates with the remote domain gateway in application 2 using an older (pre-release 7.1) authentication protocol. Upon receiving a request from a remote client, the local domain gateway calls the internal impersonate user function to get authorization and auditing tokens for the remote client and then attaches the tokens to the client request. For any outbound client request (client request originating in application 1 and destined for application 2), the local domain gateway strips the tokens from the request before sending the request along with the client's application key to the older application. (See Application Key for a description of the application key.)

If the CLOPT -t option is not specified for the domain gateway, no communication is possible between the newer ATMI application and the older ATMI application.

Figure 2-7 Server Interoperating with Older BEA Tuxedo Systems

 

In the preceding figure, the destination server on machine 1 calls the internal impersonate user function to get authorization and auditing tokens for the remote client on machine 2, attaches the tokens to the client request, and then performs the request assuming the client passes any authorization checks. If the CLOPT -t option is not specified for the server, no communication is possible between the newer server and the older client.

Note: Also, in the preceding figure, if the WSH on machine 1 receives a client request destined for a server on machine 2, the WSH strips the tokens from the request before sending the request along with the client's application key to the older system. Similarly, if the native client on machine 1 sends a request to a server on machine 2, the native client strips the tokens from the request before sending the request along with the client's application key to the older system. See Application Key for a description of the application key.

Establishing an Identity for an Older Client

For a WSH, domain gateway (GWTDOMAIN), or server process to establish an identity for an older client, the process calls the internal impersonate user function to obtain authorization and auditing tokens for the older client. The following figure demonstrates the procedure.

Figure 2-8 Obtaining Authorization and Auditing Tokens for an Older Client

 

How the WSH Establishes an Identity for an Older Client

When the CLOPT -t option is specified, the WSH establishes an identity for an older client using the usrname field of the TPINIT buffer for C, or the USRNAME field of the TPINFDEF-REC record for COBOL. (The WSH receives a TPINIT buffer/ TPINFDEF-REC record from a client when the client attempts to join the application, as described in Joining the ATMI Application.) The WSH includes the user name as the principal name when calling the impersonate user function.

For default authentication plug-ins, the impersonate user function finds the user name and its associated application key (user identifier, group identifier combination) in the local tpusr file, and then includes the user name and application key in both the authorization and auditing tokens created for the older client. The tpusr file is briefly described in Setting Up the User and Group Files.

How the Domain Gateway Establishes an Identity for an Older Client

When the CLOPT -t option is specified, the domain gateway establishes an identity for an older client using the LOCAL_PRINCIPAL_NAME string configured for the remote domain access point. (The domain gateway searches the DM_REMOTE section of the local BDMCONFIG file—the binary equivalent of the DMCONFIG(5) file—to find the LOCAL_PRINCIPAL_NAME string for the remote domain access point. If not specified, the identity defaults to the ACCESSPOINTID string for the remote domain access point.) The domain gateway uses the LOCAL_PRINCIPAL_NAME string as the principal name when calling the impersonate user function.

For default authentication plug-ins, the impersonate user function finds the LOCAL_PRINCIPAL_NAME string and its associated application key in the local tpusr file, and then includes that string (identity) and application key in both the authorization and auditing tokens created for the older client.

How the Server Establishes an Identity for an Older Client

When the CLOPT -t option is specified, the server establishes an identity for an older client using the client's assigned application key. (The client request received by the server contains the client's assigned application key.) The server finds the application key and its associated name in the local tpusr file, and then includes the name as the principal name when calling the impersonate user function.

For default authentication plug-ins, the impersonate user function finds the name and its associated application key in the local tpusr file, and then includes the name and application key in both the authorization and auditing tokens created for the older client.

Summarizing How the CLOPT -t Option Works

The following table summarizes the functionality of WSH, domain gateway, and server processes when interoperability is and is not allowed using the CLOPT -t option.

 

Example UBBCONFIG Entries for Interoperability

In the following example, all WSHs controlled by the workstation listener (WSL) are configured for interoperability.

*SERVERS
WSL    SRVGRP="group_name" SRVID=server_number ...
       CLOPT="-A -t ..."

See Also

• Specifying Principal Names
• Establishing a Link Between Domains
• Setting ACL Policy
• Security Administration Tasks
• Security Interoperability
• Setting Up Security in a Domains Configuration on page 2-41 and Setting Up Connections in a Domains Configuration on page 2-55 in Using the BEA Tuxedo Domains Component

 

---

Establishing a Link Between Domains

When a domain gateway (GWTDOMAIN) attempts to establish a network link with another domain gateway, the following major events occur.

The initiator domain gateway and the target domain gateway exchange link-level encryption (LLE) min-max values to be used to set up LLE on the link between the gateways. LLE is described in Link-Level Encryption.
The initiator and target domain gateways authenticate one another through the exchange of security tokens assuming that both gateways are running BEA Tuxedo release 7.1 or later software.

If one or both of the domain gateways are running BEA Tuxedo pre-release 7.1 software, the gateway processes use an older (pre-release 7.1) authentication protocol when setting up the connection.

As the administrator, you use the following configuration parameter to establish a link between domain gateways running BEA Tuxedo release 7.1 or later software.

 

The following figure demonstrates how a link is established between domains using default authentication plug-ins.

Figure 2-9 Establishing a Link Between Domains Using Default Authentication

 

Note: The "Credentials" shown in the preceding figure were acquired by each domain gateway process at application booting using the CONNECTION_PRINCIPAL_NAME identity configured for the local domain access point.

In the preceding figure, notice that the information exchanged between the initiator and target domain gateways involves the CONNECTION_PRINCIPAL_NAME strings configured for the domain gateways, as specified in the BDMCONFIG files. Each authentication plug-in uses the password assigned to the remote domain access point (as defined in the DM_PASSWORDS section of the BDMCONFIG file) to encrypt the string before transmitting it over the network, and uses the password assigned to the local domain access point (as defined in the DM_PASSWORDS section of the BDMCONFIG file) to decrypt the received string. The encryption algorithm used is 56-bit DES, where DES is an acronym for the Data Encryption Standard.

For the encryption/decryption operation to succeed, the assigned password for the remote domain access point in the local BDMCONFIG file must be the same as the assigned password for the local domain access point in the remote BDMCONFIG file. (Similarly, if the domain security level is set to APP_PW, the application passwords in the respective TUXCONFIG files must be identical for the encryption/decryption operation to succeed.) For the authentication process to succeed, the received string must match the CONNECTION_PRINCIPAL_NAME string configured for the sender.

When the domain gateways pass the security checks, the link is established, and the gateways can forward service requests and receive replies over the established link.

Example DMCONFIG Entries for Establishing a Link

In the following example, the configurations shown in the local DMCONFIG file are used when establishing a connection through the local domain access point c01 and the remote domain access point b01.

*DM_LOCAL
# <local domain access point name> <gateway group name> <domain type> 
# <domain id> [<connection principal name>] [<security>]...
c01    GWGRP=bankg1
       TYPE=TDOMAIN
       ACCESSPOINTID="BA.CENTRAL01"
       CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"
       SECURITY=DM_PW
   .
   .
   .

*DM_REMOTE
# <remote domain access point name> <domain type> <domain id> 
# [<connection principal name>]...
b01    TYPE=TDOMAIN
       ACCESSPOINTID="BA.BANK01"
       CONNECTION_PRINCIPAL_NAME="BA.BANK01"

See Also

• Specifying Principal Names
• Mandating Interoperability Policy
• Setting ACL Policy
• Security Administration Tasks
• Setting Up Security in a Domains Configuration on page 2-41 in Using the BEA Tuxedo Domains Component

 

---

Setting ACL Policy

As the administrator, you use the following configuration parameters to set and control the access control list (ACL) policy between ATMI applications running BEA Tuxedo release 7.1 or later software.

 

The following three figures show how the ACL_POLICY configuration affects the operation of local domain gateway (GWTDOMAIN) processes.

Figure 2-10 Establishing a Local ACL Policy

 

In the preceding figure, each domain gateway (GWTDOMAIN) modifies inbound client requests (requests originating from the remote application and received over the network connection) so that they take on the LOCAL_PRINCIPAL_NAME identity configured for the remote domain access point and thus have the same access permissions as that identity. Each domain gateway passes outbound client requests without change.

In this configuration, each ATMI application has an ACL database containing entries only for users in its own domain. One such user is the LOCAL_PRINCIPAL_NAME identity configured for the remote domain access point.

Note: The preceding description also applies to ATMI applications running BEA Tuxedo pre-release 7.1 software except that the system uses the ACCESSPOINTID identity configured for the remote domain access point. Essentially, the local ACL policy is hardcoded in BEA Tuxedo release 6.5 or earlier software.

Figure 2-11 Establishing a Global ACL Policy

 

In the preceding figure, each domain gateway (GWTDOMAIN) passes inbound and outbound client requests without change. In this configuration, each ATMI application has an ACL database containing entries for users in its own domain as well as users in the remote domain.

Figure 2-12 Establishing a One-way Local and One-way Global ACL Policy

 

In the preceding figure, the domain gateway (GWTDOMAIN) in ATMI application 1 modifies inbound client requests so that they take on the LOCAL_PRINCIPAL_NAME identity configured for the remote domain access point for ATMI application 2 and thus have the same access permissions as that identity; the domain gateway passes outbound client requests without change. The domain gateway (GWTDOMAIN) in ATMI application 2 passes inbound and outbound client requests without change.

In this configuration, ATMI application 1 has an ACL database containing entries only for users in its own domain; one such user is the LOCAL_PRINCIPAL_NAME identity configured for the remote domain access point for application 2. ATMI application 2 has an ACL database containing entries for users in its own domain as well as users in ATMI application 1.

Impersonating the Remote Domain Gateway

If the domain gateway receives a client request from a remote domain for which the ACL_POLICY parameter is set (or defaulted) to LOCAL in the local DMCONFIG file, the domain gateway performs the following tasks.

Calls the internal impersonate user function to get authorization and auditing tokens for the client based on the LOCAL_PRINCIPAL_NAME identity configured for the remote domain access point.
Uses these tokens to overwrite the tokens already attached to the client request.
Forwards the request to the destination server.

For more detail on the impersonate user function, see Establishing an Identity for an Older Client.

Example DMCONFIG Entries for ACL Policy

In the following example, the connection through the remote domain access point b01 is configured for global ACL in the local DMCONFIG file, meaning that the domain gateway process for domain access point c01 passes client requests from and to domain access point b01 without change. For global ACL, the LOCAL_PRINCIPAL_NAME entry for domain access point b01 is ignored.

*DM_LOCAL
# <local domain access point name> <gateway group name> 
# <domain type> <domain id> [<connection principal name>] 
# [<security>]...
c01    GWGRP=bankg1
       TYPE=TDOMAIN
       ACCESSPOINTID="BA.CENTRAL01"
       CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"
       SECURITY=DM_PW
   .
   .
   .

*DM_REMOTE
# <remote domain access name> <domain type> <domain id> 
# [<ACL policy>] [<connection principal name>] 
# [<local principal name>]...
b01    TYPE=TDOMAIN
       ACCESSPOINTID="BA.BANK01"
       ACL_POLICY=GLOBAL
       CONNECTION_PRINCIPAL_NAME="BA.BANK01"
       LOCAL_PRINCIPAL_NAME="BA.BANK01.BOB"

See Also

• Specifying Principal Names
• Mandating Interoperability Policy
• Establishing a Link Between Domains
• Security Administration Tasks

 

---

Setting Credential Policy

As the administrator, you use the following configuration parameter to set and control the credential policy between ATMI applications running BEA Tuxedo release 8.0 or later software.

 

 

---

Administering Authorization

Authorization enforces limitations on user access to resources or facilities within an ATMI application in accordance with application-specific rules. Only when users are authenticated to join an ATMI application does authorization go into effect.

The procedures for administering authorization depend upon the underlying authorization system of the ATMI application. For procedures to administer a custom authorization system, see the documentation for that system. For procedures to administer the default authorization system, see Administering Default Authentication and Authorization.

See Also

• Authorization
• Default Authentication and Authorization
• Administering Default Authentication and Authorization
• Security Administration Tasks
• Security Compatibility

 

---

Administering Link-Level Encryption

Link-level encryption establishes data privacy for messages moving over the network links that connect the machines in an ATMI application. There are three levels of link-level encryption (LLE) security: 0-bit (no encryption), 56-bit (International), and 128-bit (United States and Canada). The International LLE version allows 0-bit and 56-bit encryption. The United States and Canada LLE version allows 0, 56, and 128-bit encryption.

LLE applies to the following types of ATMI links:

• Workstation client to workstation handler (WSH)
• Bridge-to-Bridge
• Administrative utility (such as tmboot) to tlisten
• Domain gateway to domain gateway

Understanding min and max Values

Before you can configure LLE for your ATMI application, you need to be familiar with the LLE notation: (min, max). The defaults for these parameters are:

• For min: 0
• For max: Number of bits that indicates the highest level of encryption possible for the installed LLE version

For example, the default min and max values for the United States and Canada LLE version are (0, 128). If you want to change the defaults, you can do so by assigning new values to min and max in the UBBCONFIG file for your application.

For more information, see How LLE Works and Encryption Key Size Negotiation.

Verifying the Installed LLE Version

You can verify the LLE version installed on a machine by running the tmadmin command in verbose mode.

tmadmin -v

Key lines from the local BEA Tuxedo lic.txt file will appear on your computer screen, similar to the sample display shown below. The sample entry STRENGTH=128 indicates a United States and Canada LLE version.

[BEA Tuxedo] VERSION=9.0
[LINK ENCRYPTION] VERSION=9.0
STRENGTH=128
   .
   .
   .

All BEA Tuxedo licenses are in the $TUXDIR/udataobj/lic.txt file on a UNIX host machine, or in the %TUXDIR%\udataobj\lic.txt file on a Windows 2003 host machine.

How to Configure LLE on Workstation Client Links

If Workstation clients are included in an application, the administrator must configure one or more workstation listeners (WSLs) to listen for connection requests from Workstation clients. Each WSL uses one or more associated workstation handlers (WSHs) to handle the Workstation client workload. Each WSH can manage multiple Workstation clients by multiplexing all requests and replies with a particular Workstation client over a single connection.

As the administrator, you enable Workstation client access to the ATMI application by specifying a WSL server in the SERVERS section of the application's UBBCONFIG file. You need to specify the -z and -Z command-line options for the WSL server if you want to override the defaults for the LLE min and max parameters. (See Understanding min and max Values for details.) Of course, link-level encryption is possible only if LLE is installed on both the local machine and the Workstation client.

Note: At the Workstation client end of a network connection, you use environment variables TMMINENCRYPTBITS and TMMAXENCRYPTBITS to override the defaults for the LLE min and max parameters.

To configure LLE on Workstation client links, follow these steps.

Ensure that you are working on the ATMI application MASTER machine and that the application is inactive.
Open UBBCONFIG with a text editor and add the following lines to the SERVERS section:

*SERVERS
WSL    SRVGRP="group_name" SRVID=server_number ...
       CLOPT="-A -- -z min -Z max ..."

Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.

In the preceding example, when tmboot(1) starts the ATMI application, it passes the "-A -- -z min -Z max" command-line options to the WSL server. When establishing a network link between a Workstation client and the WSH, the Workstation client and WSL negotiate the key size until they agree on the largest key size supported by both.

See WSL(5), WS_MIB(5), and UBBCONFIG(5) in the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information.

How to Configure LLE on Bridge Links

The BEA Tuxedo system architecture optimizes network communications by establishing a multiplexed channel among the machines in a multiple-machine application. BEA Tuxedo messages flow in both directions over this channel, and the message traffic is managed by a specialized ATMI server known as a Bridge server.

As the administrator, you place an entry in the NETWORK section of the UBBCONFIG file for each machine in an ATMI application on which a Bridge server resides. You need to specify the MINENCRYPTBITS and MAXENCRYPTBITS optional run-time parameters for the Bridge server if you want to override the defaults for the LLE min and max parameters. (See Understanding min and max Values for details.) Of course, Bridge-to-Bridge link-level encryption is possible only if LLE is installed on the machines where the Bridge servers reside.

To configure LLE on Bridge links, follow these steps.

Ensure that you are working on the ATMI application MASTER machine and that the application is inactive.
Open UBBCONFIG with a text editor and add the following lines to the NETWORK section:

*NETWORK
LMID   NADDR="bridge_network_address" BRIDGE="bridge_device"
       NLSADDR="listen_network_address"
       MINENCRYPTBITS=min
       MAXENCRYPTBITS=max

LMID is the logical machine where the Bridge server resides; it has direct access to the network device specified in the BRIDGE parameter.

Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.

In the preceding example, when tmboot(1) starts the ATMI application, the Bridge server reads the TUXCONFIG file to access various parameters, including MINENCRYPTBITS and MAXENCRYPTBITS. When establishing a network link with a remote Bridge server, the local and remote Bridge servers negotiate the key size until they agree on the largest key size supported by both.

See TM_MIB(5) and UBBCONFIG(5) in the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information.

How to Configure LLE on tlisten Links

tlisten(1) is a network-independent listener process that provides connections between nodes of a multiple-machine application, on which administrative utilities such as tmboot(1) can run. The application administrator installs tlisten on all machines defined in the NETWORK section of the UBBCONFIG file.

To configure LLE on tlisten links, follow the steps given in the previous topic, How to Configure LLE on Bridge Links. If you so desire, you can start a separate instance of tlisten on the local machine by entering a command such as:

tlisten -l nlsaddr [-z min -Z max]

The nlsaddr value must be the same as that specified for the NLSADDR parameter for this machine in the NETWORK section of the UBBCONFIG file. See tlisten(1) in the BEA Tuxedo Command Reference, and TM_MIB(5) and UBBCONFIG(5) in the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information.

How to Configure LLE on Domain Gateway Links

A domain gateway is a GWTDOMAIN process that relays service requests and service replies between two or more ATMI applications. It provides interoperability through a specially designed transaction processing (TP) protocol that flows over network transport protocols such as TCP/IP.

A domain gateway belongs to a domain gateway group, for which a Domains configuration file is required. A domain gateway group represents a local domain access point that communicates with one or more remote domain access points. Like the application configuration files, UBBCONFIG and TUXCONFIG, a Domains configuration file is created in text format and then converted to binary format. The text and binary files are referred to as DMCONFIG and BDMCONFIG, respectively. The DMCONFIG and BDMCONFIG files, and the environment variables associated with them, are described on reference page DMCONFIG(5) in BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

As the administrator, you must place an entry in the DM_TDOMAIN section of the DMCONFIG file for each:

• Local domain access point that will accept requests for local services from remote domain access points
• Remote domain access point accessible by a defined local domain access point
• TDomain session between specific local and remote access points

You need to specify the MINENCRYPTBITS and MAXENCRYPTBITS optional run-time parameters for each domain access point and TDomain session for which you want to override the defaults for the LLE min and max parameters. (See Understanding min and max Values for details.) Of course, domain-to-domain link-level encryption is possible only if LLE is installed on the machines where the domains reside.

To configure LLE on domain gateway links, follow these steps.

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
Open DMCONFIG with a text editor and add the following lines to the DM_TDOMAIN section:

*DM_TDOMAIN
# Local network addresses
LDOM   NWADDR="local_domain_network_address"
       NWDEVICE="local_domain_device"
       MINENCRYPTBITS=min
       MAXENCRYPTBITS=max
       .
       .
       .

# Remote network addresses
RDOM   NWADDR="remote_domain_network_address"
       NWDEVICE="remote_domain_device"
       MINENCRYPTBITS=min
       MAXENCRYPTBITS=max
       .
       .
       .

# TDomain network addresses
RDOM   NWADDR="remote_domain_network_address"
       NWDEVICE="remote_domain_device"
       CONNECTION_POLICY=ON_START
       LACCESSPOINT="local_domain_access_point_identifier"
       FAILOVERSEQ=100
       MINENCRYPTBITS=min
       MAXENCRYPTBITS=max

LDOM is replaced with a local domain access point identifier, and RDOM is replaced with a remote domain access point identifier.

Load the configuration by running dmloadcf(1). The dmloadcf command parses DMCONFIG and loads the binary BDMCONFIG file to the location referenced by the BDMCONFIG variable.

In the preceding example, when tmboot(1) starts the ATMI application, each domain gateway reads the BDMCONFIG file to access various parameters, including MINENCRYPTBITS and MAXENCRYPTBITS, and propagates those parameters to its local and remote domains. When the local domain is establishing a network link with a remote domain, the two domains negotiate the key size until they agree on the largest key size supported by both.

See DMCONFIG(5) in BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information. Also, see Setting Up Security in a Domains Configuration on page 2-41" in Using the BEA Tuxedo Domains Component.

See Also

• Link-Level Encryption
• Security Administration Tasks
• Security Interoperability
• Security Compatibility

 

---

Administering Public Key Security

The most effective way to make a distributed ATMI application secure is to combine link-level encryption with public key encryption. Public key encryption is the framework on which public key security is built.

Public key security allows you to incorporate message-based digital signatures and message-based encryption into your ATMI applications. Together, these capabilities provide data integrity and privacy, which are especially important when an ATMI application interacts with other ATMI applications or Workstation clients from outside the company.

Recommended Practices for Public Key Security

• The ATMI application's operating environment largely determines the level of security achieved. For maximum safety, install hardware devices that protect private key information.
• Establish policies regarding key expiration intervals and key renewal procedures. Expiration of a Certification Authority's certificate might have a dramatic impact on system operation, and should be anticipated so updated user certificates can be issued in advance.

Assigning Public-Private Key Pairs

Application administrators and developers need to choose a Certification Authority to provide public-private key pairs and the digital certificates associated with them. Then they must decide how to assign the key pairs to the ATMI application. There are many options for assigning key pairs. An administrator can assign one or more of the following:

• One public-private key to an entire ATMI application
• A public-private key pair to each machine in an ATMI application
• A public-private key pair to each server in an ATMI application
• A public-private key pair to each service in an ATMI application
• A public-private key pair to each end user

Application administrators and developers are responsible for choosing a method of assigning key pairs and assigning them. Once key pairs are assigned, however, no more administrative work is required; the plug-ins for public key security distribute and manage the keys.

Setting Digital Signature Policy

As the administrator, you use the following configuration parameters to set the digital signature policy for your ATMI application.

Setting a Postdated Limit for Signature Timestamps

SIGNATURE_AHEAD is specified at the domain-wide level of the configuration hierarchy, meaning that the value you assign to it applies to all processes running in the ATMI application. Domain-wide parameters are set in the RESOURCES section in the UBBCONFIG file, and the T_DOMAIN class in the TM_MIB.

The SIGNATURE_AHEAD parameter establishes the maximum permissible time difference between (1) the timestamp attached to the incoming message buffer and (2) the current time shown on the verifying system's local clock. The minimum value is 1 second; the maximum, 2147483647 seconds. The default is 3600 seconds (one hour).

If the attached timestamp shows a time too far into the future, the signature is considered invalid. This parameter is useful for rejecting signatures that are postdated, while allowing a certain amount of leeway for unsynchronized local clocks.

Example UBBCONFIG Entries for Postdated Limit

*RESOURCES
SIGNATURE_AHEAD 2400

Setting a Predated Limit for Signature Timestamps

SIGNATURE_BEHIND is specified at the domain-wide level of the configuration hierarchy, meaning that the value you assign to it applies to all processes running in the ATMI application. Domain-wide parameters are set in the RESOURCES section in the UBBCONFIG file, and the T_DOMAIN class in the TM_MIB.

The SIGNATURE_BEHIND parameter establishes the maximum permissible time difference between (1) the current time shown on the verifying system's local clock and (2) the timestamp attached to the incoming message buffer. The minimum value is 1 second; the maximum, 2147483647 seconds. The default is 604800 seconds (one week).

If the attached timestamp shows a time too far into the past, the signature is considered invalid. This parameter is useful for resisting replay attacks, in which a valid signed buffer is injected into the system a second time. However, in a system with asynchronous communication—for example, in a system in which disk-based queues are used—buffers signed a long time ago may still be considered valid. So, in a system with asynchronous communication, you may want to increase the SIGNATURE_BEHIND setting.

Example UBBCONFIG Entries for Predated Limit

*RESOURCES
SIGNATURE_BEHIND 300000

Enforcing the Signature Policy for Incoming Messages

SIGNATURE_REQUIRED may be specified any of the following four levels in the configuration hierarchy:

• RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
• MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
• GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
• SERVICES section in UBBCONFIG or T_SERVICE class in TM_MIB

Setting SIGNATURE_REQUIRED to Y (yes) at a particular level means that signatures are required for all processes running at that level or below. For example, setting SIGNATURE_REQUIRED to Y for a machine named mach1 means that all processes running on mach1 will accept only incoming messages that are digitally signed.

• Set at the domain-wide level (RESOURCES section or T_DOMAIN class), this parameter covers all application services advertised within the domain, including those advertised by gateway processes. The default is N.
• Set at the machine level (MACHINES section or T_MACHINE class), this parameter covers all application services advertised on a particular machine, including those advertised by gateway processes. The default is N.
• Set at the group level (GROUPS section or T_GROUP class), this parameter covers all application services advertised by a particular group, including those advertised by gateway processes. The default is N.
• Set at the service level (SERVICES section T_SERVICE class), this parameter covers all instances of a particular service advertised within the domain, including those advertised by gateway processes. The default is N.

You may specify both SIGNATURE_REQUIRED=Y and ENCRYPTION_REQUIRED=Y together at the domain-wide level, machine level, group level, or service level. See Enforcing the Encryption Policy for Incoming Messages for a description of ENCRYPTION_REQUIRED.

Qualifier

The enforcement policy for SIGNATURE_REQUIRED applies only to application services, application events, and application enqueue requests. It does not apply to system-generated service invocations and system event postings.

Example

To configure SIGNATURE_REQUIRED for a machine named mach1, follow these steps.

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
Open UBBCONFIG with a text editor and add the following lines to the MACHINES section:

*MACHINES
mach1  LMID="machine_logical_name"
       TUXCONFIG="absolute_path_name_to_tuxconfig_file"
       TUXDIR="absolute_path_name_to_BEA_Tuxedo_directory"
       APPDIR="absolute_path_name_to_application_directory"
       SIGNATURE_REQUIRED=Y

Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.

In the preceding example, when tmboot(1) starts the ATMI application, it passes the SIGNATURE_REQUIRED=Y parameter to the machine named mach1. At that point, all application services advertised by mach1, including those advertised by gateway processes, are allowed to accept only messages that include valid digital signatures. If a process controlled by mach1 receives a message that does not include a valid digital signature, the system takes the following actions:

• Generates a userlog(3c) message (severity WARN)
• Discards the buffer as if it were never received by the process

Note: A NULL (empty) buffer cannot be digitally signed, meaning that the system rejects any NULL buffer received by a process requiring digital signatures, in the manner stated in the preceding bullet list.

How the EventBroker Signature Policy Is Enforced

When digital signatures are attached to a posted message buffer, these signatures are preserved and forwarded along with the message buffer to subscribers for the relevant event.

If the TMUSREVT(5) system server is running in a domain, machine, or server group that requires digital signatures, it rejects any incoming posting without a TPSIGN_OK composite signature status—see Understanding the Composite Signature Status.

Possible subscription notification actions that the TMUSREVT server might take include invoking a service or enqueuing a message. If the target service or queue requires a valid digital signature, but one is not attached to the posted message, the subscription notification action fails.

System events (events that are posted by the system itself and processed by the TMSYSEVT server) may be digitally signed. The administrative policies regarding digital signature do not apply to the TMSYSEVT(5) server.

How the /Q Signature Policy Is Enforced

When digital signatures are attached to a queued buffer, the signatures are preserved in the queue and forwarded to the dequeuing process. Also, if a message is processed by TMQFORWARD(5) to invoke a service, signatures are preserved.

If the TMQUEUE(5) system server is running in a domain, machine, or server group that requires digital signatures, it rejects any incoming enqueue request without a TPSIGN_OK composite signature status—see Understanding the Composite Signature Status. In addition, the TMQUEUE server requires a digital signature if such a policy is in effect for the service name associated with the queue space.

How the Remote Client Signature Policy Is Enforced

If the workstation handler (WSH) is running in a domain, machine, or server group that requires digital signatures, it rejects any incoming message buffer containing application data without a TPSIGN_OK composite signature status—see Understanding the Composite Signature Status.

Setting Encryption Policy

As the administrator, you use the following configuration parameter to set the encryption policy for your ATMI application.

Enforcing the Encryption Policy for Incoming Messages

ENCRYPTION_REQUIRED may be specified at any of the following four levels in the configuration hierarchy:

• RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
• MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
• GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
• SERVICES section in UBBCONFIG or T_SERVICE class in TM_MIB

Setting ENCRYPTION_REQUIRED to Y (yes) at a particular level means that encryption is required for all processes running at that level or below. For example, setting ENCRYPTION_REQUIRED to Y for a machine named mach1 means that all processes running on mach1 will accept only incoming messages that are encrypted.

• Set at the domain-wide level (RESOURCES section or T_DOMAIN class), this parameter covers all application services advertised within the domain, including those advertised by gateway processes. The default is N.
• Set at the machine level (MACHINES section or T_MACHINE class), this parameter covers all application services advertised on a particular machine, including those advertised by gateway processes. The default is N.
• Set at the group level (GROUPS section or T_GROUP class), this parameter covers all application services advertised by a particular group, including those advertised by gateway processes. The default is N.
• Set at the service level (SERVICES section T_SERVICE class), this parameter covers all instances of a particular service advertised within the domain, including those advertised by gateway processes. The default is N.

You may specify both ENCRYPTION_REQUIRED=Y and SIGNATURE_REQUIRED=Y together at the domain-wide level, machine level, group level, or service level. See Enforcing the Signature Policy for Incoming Messages for a description of SIGNATURE_REQUIRED.

Qualifier

The enforcement policy for ENCRYPTION_REQUIRED applies only to application services, application events, and application enqueue requests. It does not apply to system-generated service invocations and system event postings.

Example

To configure ENCRYPTION_REQUIRED for a server group named STDGRP, follow these steps.

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
Open UBBCONFIG with a text editor and add the following lines to the GROUPS section:

*GROUPS
STDGRP LMID="machine_logical_name"
       GRPNO="server_group_number"
       ENCRYPTION_REQUIRED=Y

Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.

In the preceding example, when tmboot(1) starts the ATMI application, it passes the ENCRYPTION_REQUIRED=Y parameter to the server group named STDGRP. At that point, all application services advertised by STDGRP, including those advertised by gateway processes, are allowed to accept only messages protected by an encryption envelope. If a process controlled by STDGRP receives an unencrypted message, the system takes the following actions:

• Generates a userlog(3c) message (severity ERROR)
• Discards the buffer as if it were never received by the process

Note: A NULL (empty) buffer cannot be encrypted, meaning that the system rejects any NULL buffer received by a process requiring encryption, in the manner stated in the preceding bullet list.

How the EventBroker Encryption Policy Is Enforced

When a posted message buffer is encrypted, encryption envelopes are preserved and forwarded, along with the encrypted message content, to subscribers for the relevant event.

If the TMUSREVT(5) system server is running in a domain, machine, or server group that requires encryption, it rejects any incoming posting message that is not encrypted.

Possible subscription notification actions that the TMUSREVT server might take include invoking a service or enqueuing a message. If the target service or queue requires encrypted input, but the posted message is not encrypted, the subscription notification action fails. Also, if the subscriber does not possess an appropriate decryption key, the event notification action fails.

System events (events that are posted by the system itself and processed by the TMSYSEVT server) may be encrypted. The administrative policies regarding encryption do not apply to the TMSYSEVT(5) server.

How the /Q Encryption Policy Is Enforced

When a queued message buffer is encrypted, this status is preserved in the queue, and the buffer is forwarded, in encrypted form, to the dequeuing process. Also, if a message is processed by TMQFORWARD(5) to invoke a service, encryption status is preserved.

If the TMQUEUE(5) system server is running in a domain, machine, or server group that requires encryption, it rejects any incoming enqueue request that is not encrypted. In addition, the TMQUEUE server requires encryption if such a policy is in effect for the service name associated with the queue space.

How the Remote Client Encryption Policy Is Enforced

If the workstation handler (WSH) is running in a domain, machine, or server group that requires encryption, it rejects any incoming message buffer containing an unencrypted application data buffer.

Initializing Decryption Keys Through the Plug-ins

As the administrator, you use the following configuration parameters to specify principal names and decryption keys for the system processes running in your ATMI application.

This trio of configuration parameters can be specified at any of the following four levels in the configuration hierarchy:

• RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
• MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
• GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
• SERVERS section in UBBCONFIG or T_SERVER class in TM_MIB

A principal name and decryption key at a particular configuration level can be overridden at a lower level. For example, suppose you configure a principal name and decryption key for machine mach1, and a principal name and decryption key for a server called serv1 running on mach1. The processes on mach1 behave as follows:

• All processes on mach1 except serv1 processes use the decryption key assigned to mach1 to decrypt any received message buffer that is encrypted.
• All serv1 processes use the decryption key assigned to serv1 to decrypt any received message buffer that is encrypted.

Configured decryption keys are automatically opened when an ATMI application is booted. The following figure demonstrates how the process works.

Figure 2-13 How a Decryption Key Is Initialized Example

 

The following is a detailed description of how the operation shown in the preceding figure is performed.

The administrator defines SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR at a particular level in the ATMI application's UBBCONFIG file.
The administrator loads the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.
When prompted, the administrator enters and then re-enters the password for the target principal.
The administrator enters the tmboot(1) command to boot the ATMI application.
During the boot process, the map_proof plug-in reads SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR, analyzes their values, and then determines whether the calling process has proven its right to access the requested decryption key. (Having access to a decryption key, or private key, is equivalent to possessing the principal's identity.)
If the password associated with SEC_PRINCIPAL_PASSVAR matches the assigned password for the principal specified in SEC_PRINCIPAL_NAME, the map_proof plug-in passes the name, location, and password of the principal to the PKi_init plug-in.
The PKi_init plug-in calls tpkey_open(3c) with the name, location, and password of the principal as arguments. It returns a decryption key handle for the principal.

Each time you invoke tmloadcf to load the configuration, you are prompted to enter the password for each of the decryption keys configured with SEC_PRINCIPAL_PASSVAR. If you want to avoid having to enter each password manually, you can write a script that automatically enters the passwords. The script must include a definition of each password variable, and it must end with the following line:

tmloadcf -y ubbconfig_name < /dev/null

No application process has permission to close a decryption key opened during ATMI application booting. The decryption keys stay open until you run the tmshutdown(1) command to shut down the ATMI application.

Example UBBCONFIG Entries for Principal Names and Decryption Keys

*RESOURCES
SEC_PRINCIPAL_NAME     "Tommy"
SEC_PRINCIPAL_LOCATION "/home/jhn/secsapp/cert/tommy.pvk"
SEC_PRINCIPAL_PASSVAR  "TOMMY_VAR"
     .
     .
     .

*SERVERS
"TMQUEUE"       SRVGRP="QUEGROUP"      SRVID=1
   CLOPT="-s secsdb:TMQUEUE"
   SEC_PRINCIPAL_NAME=    "TOUPPER"
   SEC_PRINCIPAL_LOCATION="/home/jhn/secsapp/cert/TOUPPER.pvk"
   SEC_PRINCIPAL_PASSVAR= "TOUPPER_VAR"

Failure Reporting and Auditing

This topic explains how the system manages errors found through digital signatures and message encryption.

Digital Signature Error Handling

If message tampering is detected (that is, if the composite signature status is either TPSIGN_TAMPERED_MESSAGE or TPSIGN_TAMPERED_CERT—see Understanding the Composite Signature Status), the system takes the following actions:

• Generates a userlog(3c) message (severity ERROR)
• Discards the buffer as if it were never received by the process

If any individual signature associated with an expired certificate, revoked certificate, expired signature, or postdated signature is detected, the system takes the following actions:

• Generates a userlog() message (severity WARN)
• Discards the buffer as if it were never received by the process unless the buffer's composite signature status is TPSIGN_OK or TPSIGN_UNKNOWN

If a process that requires a valid digital signature (based on the SIGNATURE_REQUIRED=Y setting) receives a message with the composite signature status TPSIGN_UNKNOWN, the system takes the following actions:

• Generates a userlog() message (severity WARN)
• Discards the buffer as if it were never received by the process

Encryption Error Handling

If a process receives an encrypted message but does not possess an open decryption key matching one of the message's encryption envelopes, the system takes the following actions:

• Generates a userlog(3c) message (severity ERROR)
• Discards the buffer as if it were never received by the process

If a process that requires encrypted input (based on the ENCRYPTION_REQUIRED=Y setting) receives an unencrypted message, the system takes the following actions:

• Generates a userlog() message (severity ERROR)
• Discards the buffer as if it were never received by the process

See Also

• Public Key Security
• Public Key Implementation
• Security Administration Tasks
• Security Interoperability
• Security Compatibility

 

---

Administering Default Authentication and Authorization

Default authentication and authorization work in the same manner that authentication and authorization have worked since they were first made available with the BEA Tuxedo system.

Default authentication provides three levels of security: no authentication (NONE), application password (APP_PW), and user-level authentication (USER_AUTH). Default authorization provides two levels of security: optional access control list (ACL) and mandatory access control list (MANDATORY_ACL). Only when users are authenticated to join an ATMI application does the access control list become active.

Designating a Security Level

As the administrator, you can use one of three ways to designate a security level for an ATMI application: by editing the UBBCONFIG configuration file, by changing the TM_MIB, or by using the BEA Administration Console.

Establishing Security by Editing the Configuration File

In your UBBCONFIG file, set the SECURITY parameter to the appropriate value:

SECURITY {NONE | APP_PW | USER_AUTH | ACL | MANDATORY_ACL}

The default is NONE. If SECURITY is set to USER_AUTH, ACL, or MANDATORY_ACL, then a system-supplied authentication server named AUTHSVR is invoked to perform per-user authentication.

If you select any value other than NONE, make sure that the value of the APPDIR variable is unique for each ATMI application running on the MASTER site. Multiple ATMI applications cannot share the same application directory if security features are being used.

Establishing Security by Changing the TM_MIB

To designate a security level through the TM_MIB, you must assign a value to the TA_SECURITY attribute in the T_DOMAIN class. When an ATMI application is inactive, the administrator can SET the value of TA_SECURITY to any of the values that are valid in UBBCONFIG. To complete this task, run the administrative interface tpadmcall(3c).

Establishing Security by Using the BEA Administration Console

You can also designate a security level through the BEA Administration Console. The BEA Administration Console is a Web-based tool used to configure, monitor, and dynamically reconfigure an ATMI application.

Configuring the Authentication Server

The BEA Tuxedo server called AUTHSVR provides a single service, AUTHSVC, which performs authentication. AUTHSVC is advertised by the AUTHSVR server as ..AUTHSVC when the security level is set to ACL or MANDATORY_ACL.

To add AUTHSVC to an ATMI application, you need to define AUTHSVC as the authentication service and AUTHSVR as the authentication server in the UBBCONFIG file. For example:

*RESOURCES
SECURITY   USER_AUTH
AUTHSVC    AUTHSVC
   .
   .
   .

*SERVERS
AUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"

If you omit the parameter-value entry AUTHSVC  AUTHSVC, the system calls AUTHSVC by default.

As another example:

*RESOURCES
SECURITY   ACL
AUTHSVC    ..AUTHSVC
   .
   .
   .

*SERVERS
AUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"

If you omit the parameter-value entry AUTHSVC  ..AUTHSVC, the system calls ..AUTHSVC by default.

AUTHSVR may be replaced with an authentication server that implements logic specific to the ATMI application. For example, a company may want to develop a custom authentication server so that it can use the popular Kerberos mechanism for authentication.

To add a custom authentication service to an ATMI application, you need to define your authentication service and server in the UBBCONFIG file. For example:

*RESOURCES
SECURITY   USER_AUTH
AUTHSVC    KERBEROS
   .
   .
   .

*SERVERS
KERBEROSSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"

Note: To use the WebLogic Server as your security database to authenticate Tuxedo users, you must implement single point security administration using LAUTHSVR as your authentication server. For information about LAUTHSVR and single point security administration with WebLogic Server, refer to Implementing Single Point Security Administration.

See Also

• How to Enable Application Password Security
• How to Enable User-Level Authentication Security
• Enabling Access Control Security
• Default Authentication and Authorization
• Security Administration Tasks
• Implementing Single Point Security Administration
• AUTHSVR(5) in the BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference

 

---

How to Enable Application Password Security

Default authentication offers an application password security level that you invoke by specifying SECURITY APP_PW in your configuration file. This level requires that every client provide an application password as part of the process of joining the ATMI application. The administrator defines a single password for the entire ATMI application and gives the password only to authorized users.

To enable the APP_PW security level, follow these steps.

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
Set the SECURITY parameter in the RESOURCES section of the UBBCONFIG file to APP_PW.
Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.
The system prompts you for a password. The password you enter may be up to 30 characters long. It becomes the password for the ATMI application and remains in effect until you change it by using the passwd command of tmadmin.
Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.

See Also

• Default Authentication and Authorization
• Administering Default Authentication and Authorization
• Security Administration Tasks

 

---

How to Enable User-Level Authentication Security

Default authentication offers a user-level authentication security level that you invoke by specifying SECURITY USER_AUTH in your configuration file. This security level requires that in addition to the application password, each client must provide a valid username and user-specific data, such as a password, to join the ATMI application. The per-user password must match the password associated with the combination user-client name stored in a file named tpusr. The checking of per-user password against the password and user-client name in tpusr is carried out by the authentication service AUTHSVC, which is provided by the authentication server AUTHSVR.

To enable the USER_AUTH security level, follow these steps.

Set up the UBBCONFIG file.
Set up the user and group files.

Instructions for these steps are provided in the following two topics.

Setting Up the UBBCONFIG File

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and SERVERS sections:

*RESOURCES
SECURITY   USER_AUTH
AUTHSVC    AUTHSVC
     .
     .
     .

*SERVERS
AUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"

CLOPT="-A" causes tmboot(1) to pass only the default command-line options (invoked by "-A") to AUTHSVR when tmboot starts the ATMI application. By default, AUTHSVR uses the client user information in a file named tpusr to authenticate clients that want to join the ATMI application. tpusr resides in the directory referenced by the first pathname defined in the ATMI application's APPDIR variable.

Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.
The system prompts you for a password. The password you enter may be up to 30 characters long. It becomes the password for the ATMI application and remains in effect until you change it by using the passwd command of tmadmin.
Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.

Setting Up the User and Group Files

AUTHSVR and the access control checking feature available with the default authorization system require a user file named tpusr, which contains a list of client users allowed to join the ATMI application. tpusr is maintained by the application administrator using the tpusradd(1), tpusrdel(1), and tpusrmod(1) commands. The AUTHSVR server takes as input the client user information stored in the tpusr file; it uses this information to authenticate clients that want to join the ATMI application.

The following display is a sample entry in the tpusr file.

 

 

AUTHSVR and the access control checking feature also require a group file named tpgrp, which contains a list of groups associated with the client users allowed to join the ATMI application; tpgrp is maintained by the application administrator using the tpgrpadd(1), tpgrpdel(1), and tpgrpmod(1) commands.

AUTHSVC assigns an authenticated client user an application key, which contains a user identifier and associated group identifier for the USER_AUTH, ACL, or MANDATORY_ACL security level. (See Application Key for more information about application keys.)

The following display is a sample entry in the tpgrp file.

 

As the administrator, you must define lists of users and groups in the tpusr and tpgrp files, both of which are located in the directory referenced by the first path name defined in the ATMI application's APPDIR variable. The files are colon-delimited, flat text files, readable and writable only by the application's administrator.

Converting System Security Data Files to BEA Tuxedo User and Group Files

You may already have files containing lists of users and groups on your host system. You can use them as the user and group files for your ATMI application, but only after converting them to the format required by the BEA Tuxedo system. To convert your files, run the tpaclcvt(1) command, as shown in the following sample procedure. The sample procedure is written for a UNIX host machine.

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
To convert the /etc/password file into the format needed by the BEA Tuxedo system, enter the following command.

tpaclcvt -u /etc/password

This command creates the tpusr file and stores the converted data in it. If the tpusr file already exists, tpaclcvt adds the converted data to the file, but it does not add duplicate user information to the file.

Note: For systems on which a shadow password file is used, you are prompted to enter a password for each user in the file.

To convert the /etc/group file into the format needed by the BEA Tuxedo system, enter the following command.

tpaclcvt -g /etc/group

This command creates the tpgrp file and stores the converted data in it. If the tpgrp file already exists, tpaclcvt adds the converted data to the file, but it does not add duplicate group information to the file.

Adding, Modifying, or Deleting Users and Groups

The BEA Tuxedo system requires that you maintain a list of your application users in a file named tpusr, and a list of groups, in a file named tpgrp. There are two methods of modifying the entries in these files: by issuing commands or by changing the values of the appropriate attributes in the ACL_MIB.

Changing Entries for Users and Groups Through Commands

You can add, modify, or delete entries in the tpusr and tpgrp files at any time by running one of the following commands.

To run any of these commands, follow these steps.

For an inactive ATMI application, make sure you are working from the application MASTER machine. For an active ATMI application, you may work from any machine in the configuration.
For specific instructions on running a command, see the entry for that command in BEA Tuxedo Command Reference.

Changing Entries for Users and Groups Through the ACL_MIB

If you prefer not to use the command-line interface, you can add, modify, or delete user entries in tpusr by changing the appropriate attribute values in the T_ACLPRINCIPAL class in the ACL_MIB(5). This method is more efficient than the command-line interface if you want to add several user entries simultaneously, since tpusradd(1) allows you to add only one user at a time.

Similarly, you can add, modify, or delete group entries in tpgrp by changing the appropriate attribute values in the T_ACLGROUP class in the ACL_MIB(5). This method is more efficient than the command-line interface if you want to add several group entries simultaneously, since tpgrpadd(1) allows you to add only one group at a time.

Of course, the easiest way to access the MIB is via the BEA Administration Console.

See Also

• Default Authentication and Authorization
• Administering Default Authentication and Authorization
• Security Administration Tasks

 

---

Enabling Access Control Security

Default authorization consists of an access control checking feature that determines which users can execute a service, post an event, or enqueue (or dequeue) a message on an application queue. There are two levels of access control security: optional access control list (ACL) and mandatory access control list (MANDATORY_ACL). Only when users are authenticated to join an ATMI application does the access control list become active.

By using an access control list, an administrator can organize users into groups and associate the groups with objects that the member users have permission to access. Access control is done at the group level for the following reasons:

• System administration is simplified. It is easier to give a group of people access to a new service than it is to give individual users access to the service.
• Performance is improved. Because access permission needs to be checked for each invocation of an entity, permission should be resolved quickly. Because there are fewer groups than users, it is quicker to search through a list of privileged groups than it is to search through a list of privileged users.

The access control checking feature is based on three files that are created and maintained by the application administrator:

• tpusr contains a list of users
• tpgrp contains a list of groups
• tpacl contains a list of mappings of groups to application entities (such as services) known as the access control list (ACL)

By parsing the client's application key, which contains information identifying the client as a valid user and valid group member, an entity (such as a service, event, or application queue) can identify the group to which the user belongs; by checking the tpacl file, an entity can determine whether the client's group has access permission.

The application administrator, application operator, and processes or service requests running with the privileges of the application administrator/operator are not subject to ACL permission checking.

If user-level ACL entries are needed, they may be implemented by creating a group for each user, and then mapping the group to the appropriate application entities in the tpacl file.

How to Enable Optional ACL Security

Default authentication offers an optional ACL (ACL) security level that you invoke by specifying SECURITY ACL in your configuration file. This security level requires that each client provide an application password, a username, and user-specific data, such as a password, to join the ATMI application. If there is no entry in the tpacl file associated with the target application entity, the user is permitted to access the entity.

This security level enables an administrator to configure access for only those resources that need more security. That is, there is no need to add entries to the tpacl file for services, events, or application queues that are open to everyone. Of course, if there is an entry in the tpacl file associated with the target application entity and a user attempts to access that entity, the user must be a member of a group that is allowed to access that entity; otherwise, permission is denied.

To enable the ACL security level, follow these steps.

Set up the UBBCONFIG file.
Set up the ACL file.

Instructions for these steps are provided in the following two topics.

Setting Up the UBBCONFIG File

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and SERVERS sections:

*RESOURCES
SECURITY   ACL
AUTHSVC    ..AUTHSVC
     .
     .
     .

*SERVERS
AUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"

CLOPT="-A" causes tmboot(1) to pass only the default command-line options (invoked by "-A") to AUTHSVR when tmboot starts the ATMI application. By default, AUTHSVR uses the client user information in a file named tpusr to authenticate clients that want to join the ATMI application. tpusr resides in the directory referenced by the first pathname defined in the ATMI application's APPDIR variable.

Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.
The system prompts you for a password. The password you enter may be up to 30 characters long. It becomes the password for the ATMI application and remains in effect until you change it by using the passwd command of tmadmin.
Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.

Setting Up the ACL File

The access control checking feature requires a user file named tpusr, a group file named tpgrp, and an ACL file named tpacl. The ACL file contains mappings of groups to application entities. An entity may be a service, event, or application queue.

The following display is a sample entry in the tpacl file.

 

As the administrator, you must define the entries in the tpacl file, which is located in the directory referenced by the first pathname defined in the ATMI application's APPDIR variable. The file is a colon-delimited, flat text file, readable and writable only by the application's administrator.

There are two methods of modifying the ACL entries in the tpacl file: by issuing commands or by changing the values of the appropriate attributes in the ACL_MIB.

Changing ACL Entries Through Commands

You can add, modify, or delete ACL entries in the tpacl file at any time by running one of the following commands.

To run any of these commands, follow these steps.

For an inactive ATMI application, make sure you are working from the application MASTER machine. For an active ATMI application, you may work from any machine in the configuration.
For specific instructions on running a command, see the entry for that command in BEA Tuxedo Command Reference.

Changing ACL Entries Through the ACL_MIB

If you prefer not to use the command-line interface, you can add, modify, or delete ACL entries in tpacl by changing the appropriate attribute values in the T_ACLPERM class in the ACL_MIB(5). This method is more efficient than the command-line interface if you want to add several ACL entries simultaneously, since tpacladd(1) allows you to add only one ACL entry at a time.

Of course, the easiest way to access the MIB is via the BEA Administration Console.

How to Enable Mandatory ACL Security

Default authentication offers a mandatory ACL security level that you invoke by specifying SECURITY MANDATORY_ACL in your configuration file. This security level requires that each client provide an application password, a username, and user-specific data, such as a password, to join the ATMI application. If there is no entry in the tpacl file associated with the target application entity, the client is not permitted to access the entity. In other words, an entry must exist in the tpacl file for every application entity that a client needs to access. For this reason, this level is called mandatory.

Of course, if there is an entry in the tpacl file associated with the target application entity and a user attempts to access that entity, the user must be a member of a group that is allowed to access that entity; otherwise, permission is denied.

To enable the MANDATORY_ACL security level, follow these steps.

Set up the UBBCONFIG file.
Set up the ACL file.

Instructions for these steps are provided in the following two topics.

Setting Up the UBBCONFIG File

Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and SERVERS sections:

*RESOURCES
SECURITY   MANDATORY_ACL
AUTHSVC    ..AUTHSVC
     .
     .
     .

*SERVERS
AUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"

CLOPT="-A" causes tmboot(1) to pass only the default command-line options (invoked by "-A") to AUTHSVR when tmboot starts the ATMI application. By default, AUTHSVR uses the client user information in a file named tpusr to authenticate clients that want to join the ATMI application. tpusr resides in the directory referenced by the first pathname defined in the ATMI application's APPDIR variable.

Load the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.
The system prompts you for a password. The password you enter may be up to 30 characters long. It becomes the password for the ATMI application and remains in effect until you change it by using the passwd command of tmadmin.
Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.

Setting Up the ACL File

See Setting Up the ACL File.

See Also

• Default Authentication and Authorization
• Administering Default Authentication and Authorization
• Security Administration Tasks

 

---

Using the Kerberos Authentication Plug-in

Kerberos is a network authentication protocol. It is designed to provide strong authentication for client/server applications by using secret-key cryptography. The Kerberos authentication protocol provides a mechanism for mutual authentication between a client and a server, or between one server and another, before opening a network connection between them. The protocol assumes that initial transactions between clients and servers take place on an open network where most computers are not physically secure. It also assumes that packets traveling along the network can be monitored and modified at will.

After using Kerberos to prove the identity of a client and server, their communications can be encrypted to ensure privacy and data integrity. Refer to the See Also section for more information about Kerberos.

The following sections describe the Kerberos authentication plug-in feature included in Tuxedo:

• Kerberos Plug-In
• Kerberos Plug-In Pre-configuration
• Kerberos Plug-In Configuration

 

---

Kerberos Plug-In

Tuxedo provides a general security framework that can be customized. This framework is further enhanced with the inclusion of a Kerberos plug-in.

Kerberos Supported Platforms

Currently the Kerberos plug-in supports the following platforms:

• Microsoft Kerberos bundled with Windows 2000/2003 server
• Kerberos V systems on HP-UX(PA-RISC) provided by HP
• Kerberos V systems on Solaris 9 (SPARC) provided by Sun Microsystems

Kerberos Plug-in Features

The Kerberos Plug-in is a dynamic library that must be registered into the Tuxedo system, and a Kerberos authentication server (KAUTHSVR(5)). The Tuxedo implementation of the Kerberos plug-in supports the following:

• Authentication between Tuxedo native client and server
• Full support of Tuxedo ACL security mechanism

Note: Authentication between the security protocols of Tuxedo workstation client and workstation handler, authentication between two domain gateways and CORBA components are not supported.

 

---

Kerberos Plug-In Pre-configuration

To use Kerberos authentication, you must make sure the following system requirements are set up properly:

• Supported systems run well with the correct Kerberos settings
• User/service accounts are set correctly
• The Kerberos authentication server key table is created correctly on UNIX
• Kerberos interoperability between UNIX and Windows is set correctly and verified if a heterogeneous (UNIX/Windows mixed) environment is needed.

 

---

Kerberos Plug-In Configuration

This section provides configuration information to get the Kerberos plug-in set up and running.

Configure the Kerberos Plug-in
Configure KAUTHSVR
Configure Tuxedo Native Client

Each of these steps are explained in more detail in the subsections that follow.

Configure the Kerberos Plug-in

You must first register the Kerberos plug-in on UNIX and Windows platforms.

The Kerberos plug-in must be configured using the EPIF commands epifreg and epifregedt. These commands will automatically add the plug-in to the Tuxedo registry in UNIX and Windows. For example:

Listing 2-1 UNIX Registration

epifreg -r -p krb5/atn -i engine/security/authentication -o SYSTEM -v 1.0 \
-f $TUXDIR/lib/libkrb5atn.so \
	-e krb5_plugin_entry \
	-u KRB5_CONFIG=/etc/krb5.conf \
	-u KRB5_KDC=/etc/krb5.kdc\
	-u KAUTHSVRPRINC="krbauth@host.yourcomany.com"
epifregedt -s -k SYSTEM/interfaces/engine/security/authentication \
	-a Selector=native/security/authentication \
	-a native/security/authentication=krb5/atn

Listing 2-2 Windows Registration

epifreg -r -p krb5/atn -i engine/security/authentication -o SYSTEM -v 1.0 \
	-f %TUXDIR%\bin\libkrb5atn.dll \
	-e krb5_plugin_entry \
	-u KAUTHSVRPRINC="krbauth/host.yourcomany.com@REALM"
epifregedt -s -k SYSTEM/interfaces/engine/security/authentication \
	-a Selector=native/security/authentication \
	-a native/security/authentication=krb5/atn

Notes: On a Windows platform, the plug-in KRB5_CONFIG and KRB5_KDC parameters are not required. These parameters are used on a UNIX platform to locate the Kerberos-related configuration files. KAUTHSVRPRINC specifies the principal name for the KAUTHSVR server and Tuxedo clients use it as the server principal name.

On UNIX platforms, the GSS format is used. Because Microsoft does not support standard GSS name representation, the KAUTHSVRPRINC parameter must be given a complete Kerberos realm name.

The name format is illustrated as follows:

• A UNIX Tuxedo client must use GSS format to access KAUTHSVR.
• A WindowsTuxedo client always uses the complete Kerberos realm name to access KAUTHSVR.

KAUTHSVRPRINC can also be set as an environment variable.

Restore Default Plug-in

The following commands restore the plug-in to its default state.

Listing 2-3 Restore Default Plug-In Settings

epifreg -r -p bea/native/atn \
	-i engine/security/authentication \
	-v 1.0 -f libtux.so -e _ep_dl_atnlcl
epifregedt -s -k SYSTEM/interfaces/engine/security/authentication \

		-a Selector=native/security/authentication \

		-a native/security/authentication=bea/native/atn

Note: In Listing 2-3, libtux.so is used as an example. You must use the file name libtux plus your platform specific dynamic library extension.

Configure KAUTHSVR

KAUTHSVR is a Tuxedo server located in TUXDIR/bin directory and must be manually configured in the UBBCONFIG file. KAUTHSVR authenticates client identity by validating the client security token. It addresses the Tuxedo ACL mechanism when the security level is set above "USER_AUTH" in the UBBCONFIG file.

The following are examples of how KAUTHSVR is configured in the UBBCONFIG file for both UNIX and Windows:

Listing 2-4 UNIX UBBCONFIG KAUTHSVR Configuration

*RESOURCES
IPCKEY                  66666
MASTER                  SITE1
MODEL                   MP

SECURITY       MANDATORY_ACL

*SERVERS

KAUTHSVR SRVGRP=SECGRP SRVID=100 GRACE=0 MAXGEN=2 CLOPT="-A -- -k /etc/krbauth.kt -p krbauth@host.yourcomany.com"

Notes: The -k option allows you to provide the KAUTHSVR Kerberos key table file location.

The -p option indicates KAUTHSVR principal name.

KAUTHSVR running on UNIX platforms must use the GSS format.

Listing 2-5 Windows UBBCONFIG KAUTHSVR Configuration

*RESOURCES
IPCKEY                  66666
MASTER                  SITE1
MODEL                   MP

SECURITY       MANDATORY_ACL

*SERVERS

KAUTHSVR SRVGRP=GROUP3 SRVID=100 GRACE=0 MAXGEN=2
SEC_PRINCIPAL_NAME="kauthsvc" SEC_PRINCIPAL_PASSVAR=test CLOPT="-A -- -p
krbauth/host.yourcomany.com@REALM"

Notes: The -p option indicates KAUTHSVR principal name.

Instead of using the -k option, Windows platforms must use the following two arguments:

• SEC_PRINCIPAL_NAME represents KAUTHSVR, it does not represent the server principal name (which is represented by the -p option).
• SEC_PRINCIPAL_PASSVAR is the internal password variable. It is not the true password that is required when tmloadcf creates the TUXCONFIG file. The tmloadcf password input must be same as the KAUTHSVR account password in a Windows domain.

KAUTHSVR running on Windows platform must use the complete Kerberos realm name.

Configure Tuxedo Native Client

To use the Tuxedo native client with Kerberos enabled, you must first obtain a valid TGT from the KDC using kinit or other similar commands.

No programming APIs are required. Also, if USER_AUTH is specified, the Tuxedo user name is not required in the tpusr file. However, a user name is required for ACL and MANDATORY_ACL security level.

Limitations

• Kerberos Plug-In only works on systems where the plug-in is installed and registered to Tuxedo through epif* commands. If the Tuxedo administrator does not register the libkrb5atn to Tuxedo, the default plug-in still works and the default Tuxedo security mechanism takes effect. KAUTHSVR supports full function of AUTHSVR in addition to Kerberos authentication.
• Even if the Kerberos plug-in is configured on a system running WSH, the workstation clients connected to this system use the Tuxedo default security mechanism. This is because the protocol between workstation client and WSH is not affected using this feature.
• Although CORBA native clients can take advantage of Kerberos support, we do not support CORBA remote clients using Kerberos. ISH will report an error when the Kerberos plug-in is installed.

Note: Authentication between the security protocols of Tuxedo workstation client and workstation handler, authentication between two domain gateways and CORBA components are not supported.

See Also

• KAUTHSVR(5)
• Kerberos Introduction from MIT (tap://web.mit.edu/kerberos/wow/)
• Microsoft White Papers and Guide for Kerberos (tap://www.microsoft.com/windows2000/technologies/security/kerberos/default.asp)
• RFC 1510, Kerberos protocol (tap://www.ietf.org/raft/rfc1510.txt)
• RFC 2743, GSSAPI (tap://www.ietf.org/raft/rfc2743.txt)
• RFC 1509, GSSAPI, c-bindings.(http://www.ietf.org/raft/rfc1509.txt)

 

---

Using the Cert-C PKI Encryption Plug-in

The Cert-C based PKI (public key infrastructure) plug-in utilizes the public key encryption algorithm to provide you with the ability to:

• sign - assign a signature to a Tuxedo typed buffer
• seal - encrypt a Tuxedo typed buffer, and
• envelope - provide access to the user signature and encryption information associated with the Tuxedo typed buffer

The following sections describe the Cert-C PKI encryption feature included in Tuxedo:

• Cert-C PKI Encryption Plug-In
• Cert-C PKI Encryption Plug-In Pre-configuration
• Cert-C PKI Encryption Plug-In Configuration

 

---

Cert-C PKI Encryption Plug-In

The Tuxedo Cert-C PKI encryption plug-in plug-in uses LDAP version 2 or higher as the storage mechanism for the publicly accessible user certificates. LDAP is a commonly used and deployed network directory service.

 

---

Cert-C PKI Encryption Plug-In Pre-configuration

To use the Tuxedo Cert-C PKI encryption plug-in, you must make sure of the following system requirements:

• Access to a configured LDAP server
• User certificates stored in the LDAP are entered in the following format: cn=user name

 

---

Cert-C PKI Encryption Plug-In Configuration

To use this plug-in, you must run a command script to configure Tuxedo in order to use this plug-in as the default PKI plug-in.

The Tuxedo Cert-C plug-in utilizes four interface groups in the Tuxedo Security PIF and is configured using PIF registry commands. The required interface groups are:

• Configure Certificate Lookup
• Configure Key Management
• Configure Certificate Parsing
• Configure Certificate Validation

In the Tuxedo environment, only user names are available in the plug-in at runtime. In order to get the proper search information, it assumes that a certificate stored in the LDAP with a cn=user name entry is a Tuxedo user name.

Configure Certificate Lookup

This interface group expects a user certificate to be located on an LDAP server and it has access permission to read these certificates. The certificate lookup interface has four parameters that must be configured. The parameters are described as follows:

ldapUserCertificate

LDAP server configuration parameter that identifies where the plug-in can obtain user certificates. The network address for the LDAP host is specified in this parameter as a string variable. It also contains the TCP LDAP port number. The syntax of this parameter is LDAP:URL. For example:

ldapUserCertificate=ldap://sagamore:389

This example tells the Cert-C plug-in that the LDAP server is located on a machine called "sagamore", and it is listening on port 389.

ldapBaseObject

LDAP server configuration parameter that identifies the base DN where the LDAP search should start. For example:

ldapBaseObject="ou=Engineer Test,o=ABC Company,c=US"

This example initiates a search from the directory information tree "ou=Engineer Test, o=ABC Company, c=US"

ldapFilterAttribute

LDAP server configuration parameter that identifies the search filter used in an LDAP search when retrieving a certificate by subject name. This parameter is a string variable and follows the same syntax as ldapBaseDNAttribute. For example:

ldapFilterAttribute="cn"

This example tells the Cert-C plug-in to use "cn" as a filter.

ldapBaseDNAttribute

LDAP server configuration parameter that is used in an LDAP search to build the base DN. This parameter is a string variable consisting of a comma-separated list of DN attributes, such as c, o. An optional blank space can follow the commas. For example:

ldapBaseDNAttribute="c, o, ou, cn"

This example tells the Cert-C plug-in to use the "c", "o", "ou", "cn" attributes when constructing the DN for a search.

Configure Key Management

The location of the private key is the only configuration parameter that must be specified for key management interface.

decPassword

Optional parameter. It is a string variable that gives the Cert-C PKI encryption plug-in the password to decrypt the private key wrapped in encrypted private key information format. For example:

decPassword="abc123"

The plug-in assumes the private key information file follows the "<subject_name>.epk" naming scheme.

Note: decPassword and privateKeyDir can be overridden by using the tpkey_open(3c) identity_proof and location parameters.

privateKeyDir

A string variable parameter in file URL format. It indicates the default location of the private key. For example:

privateKeyDir=file:///c:\home\certs\

This example tells the Cert-C PKI encryption plug-in to look for a private key in the c:\home\certs directory. The private key can be a binary file that conforms with PKCS #8. It must have a .pvt or .epk extension.

If the password is given in the "decPassword" path or tpkey_open(..., identity_proof, ...), then the .epk file will be searched first, if not found then it will try .pvt file. If the password is not given in the "decPassword" path or tpkey_open(..., identity_proof, ...), then only .pvt file is searched.

Configure Certificate Parsing

No special configuration parameter is needed to utilize the certificate parsing interface. It is initialized automatically.

Note: Certificates must be X.509-compatible in DER format.

Configure Certificate Validation

This interface group allows the Cert-C PKI encryption plug-in to examine a certificate and to determine its validity based on trusted certificate authorities, chains of trust, certificate revocation list. There are two configuration parameters associated wither certificate validation:

caCertificateFile

A string variable configuration parameter in file URL format. It points to a single certificate whose public key is trusted by the user. The certificate can be self-signed. If the certificate chain validates this trusted certificate the certificate is deemed a "good" certificate.For example:

Note: There is only one certificate validation chain level. That is, all user certificates are issued directly by the root CA configured in caCertificateFile.

caCertificateFile=file:///c:\home\certs\root.cer

This example indicates that the trusted root certificate is located at directory called c:\home\certs and is named root.cer.

crlFile

A string variable configuration parameter in file URL format. It points to a single CRL that is to be used to verify the resulting certificate path; in another word, it determines whether the certificate in question is being revoked by its issuer or not. For example:

crlFile=file:///c:\home\certs\revoke.crl

This example indicates which CRL is used to determine if the certificate has not been revoked by its issuer.

Sample Registry Command File

The following is a sample command for modifying the Tuxedo registry database on a Windows platform using the Cert-C PKI encryption plug-in.

Note: On a UNIX platform, you must:

• use the file name libcertctux plus your platform specific dynamic library extension instead of certctux.dll used in Windows. For example:
  
  Solaris: libcertctux.so.71
HP-UX: libcertctux.sl
• change the file URL to UNIX format

Listing 2-6 Sample Command for Modifying Tuxedo Registry Database on Windows

REM **********************************************************
REM ** Modify Validation Interface **
REM **********************************************************
epifreg -r -p bea/cert-c/certificate_validation -i engine/security/certificate_validation -v 1.0 -f certctux.dll -e _ep_dl_certc_validate_certificate -u caCertificateFile=file:///c:\home\certs\root.cer -u crlFile=file:///c:\home\certs\revoke.crl

epifreg -s -k SYSTEM/impl/bea/valfile -a InterceptionSeq=bea/cert-c/certification_validation

epifregedt -s -k SYSTEM/interfaces/engine/security/certificate_validation -a DefaultImpl=bea/valfile

REM **********************************************************
REM ** Modify Lookup Interface **
REM **********************************************************

epifreg -r -p bea/cert-c/certificate_lookup -i engine/security/certificate_lookup -v 1.0 -f certctux.dll -e _ep_dl_certc_certificate_lookup -u ldapUserCertificate=ldap://sagamore:389 -u ldapBaseObject="ou=Engineer Test,o=ABC Company,c=US" -u ldapFilterAttribute="cn" -u ldapBaseDNAttribue="c,o,ou,cn"

epifregedt -s -k SYSTEM/interfaces/engine/security/certificate_lookup -a DefaultImpl=bea/cert-c/certificate_lookup

REM **********************************************************
REM ** Modify Key Management Interface **
REM **********************************************************

epifreg -r -p bea/cert-c/key_management -i engine/security/key_management -v 1.0 -f certctux.dll -e _ep_dl_certc_key_management -u privateKeyDir=file:///c:\home\certs\

epifregedt -s -k SYSTEM/interfaces/engine/security/key_management -a DefaultImpl=bea/cert-c/key_management

REM **********************************************************
REM ** Modify Certificate Parsing Interfaces **
REM **********************************************************

epifreg -r -p bea/cert-c/certificate_parsing -i engine/security/certificate_parsing -v 1.0 -f certctux.dll -e _ep_dl_certc_certificate_parsing

epifregedt -s -k SYSTEM/interfaces/engine/security/certificate_parsing -a DefaultImpl=bea/cert-c/certificate_parsing

Limitations

• The "cn" attribute of distinguished name is used as key for certificate lookup, so the DN must contains the "cn=" attribute.
• There are two possible places to put a name in an X.509 v3 KC:
• One is the subject field in the base PKC, often called the Distinguished Name or DN field.
• The other is the subjectAltName extension. This plug-in does not support subjectAltName extension.

Note: Wildcards used in a name are not supported. Empty subject fields are not allowed.

• The following tpkey_getinfo() attributes cannot retrieve ENCRYPT_ALG, ENCRYPT_BITS, SIGNATURE_ALG, or SIGNATURE_BITS information using the Cert-C PKI encryption plug-in:
• TPKEY_SIGNATURE: cannot retrieve ENCRYPT_ALG, ENCRYPT_BITS
• TPKEY_ENCRYPT: cannot retrieve SIGNATURE_BITS
• TPKEY_AUTOSIGN: cannot retrieve ENCRYPT_ALG, ENCRYPT_BITS
• TPKEY_AUTOENCRYPT: cannot retrieve SIGNATURE_BITS

Note: TPKEY_DECRYPT: can retrieve ENCRYPT_ALG, ENCRYPT_BITS, SIGNATURE_ALG, or SIGNATURE_BITS information

TPKEY_AUTOSIGN|TPKEY_DECRYPT: can retrieve ENCRYPT_ALG, ENCRYPT_BITS, SIGNATURE_ALG, or SIGNATURE_BITS information

See Also

tpkey_open(3c)

Contact BEA |  Feedback |  Privacy  |