2 Administering Security
The following sections explain how to set security policies for an Oracle Tuxedo ATMI application:
- What Administering Security Means
- Security Administration Tasks
- Setting the Oracle Tuxedo Registry
- Configuring an ATMI Application for Security
- Setting Up the Administration Environment
- Administering Authentication
- Specifying Principal Names
- Mandating Interoperability Policy
- Establishing a Link Between Domains
- Setting ACL Policy
- Setting Credential Policy
- Administering Authorization
- Administering Link-Level Encryption
- Administering SSL Encryption
- Administering Public Key Security
- Administering Default Authentication and Authorization
- How to Enable Application Password Security
- How to Enable User-Level Authentication Security
- Enabling Access Control Security
- 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
2.1 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 Oracle Tuxedo system upon which the ATMI application is built enforces those policies.
The Oracle Tuxedo system offers the following ATMI security capabilities:
- Authentication
- Authorization
- Auditing
- Link-level encryption
- SSL 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
![Administering ATMI Security Diagram Administering ATMI Security Diagram](img/secadm-2.1.01.jpg)
Parent topic: Administering Security
2.2 Security Administration Tasks
Security administration consists of the following tasks:
- Setting the Oracle 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 SSL Encryption
- Administering Public Key Security
- Administering Default Authentication and Authorization
Parent topic: Administering Security
2.3 Setting the Oracle Tuxedo Registry
The application administrator needs to know about the Oracle 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 Oracle Tuxedo registry does not need to be changed.
The Oracle 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.
2.3.1 Purpose of the Oracle Tuxedo Registry
Most Oracle 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 Oracle Tuxedo registry, which is a set of binary files that stores information about active plug-ins. There is one registry per Oracle Tuxedo installation.
- On a UNIX host machine, the Oracle Tuxedo registry is in the
$TUXDIR/udataobj
directory. - On a Windows 2003 host machine, the Oracle 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.
Parent topic: Setting the Oracle Tuxedo Registry
2.3.2 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 Oracle 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 unregistered 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 Oracle Tuxedo registry to access the custom plug-ins.
For more information about security plug-ins, including installation and configuration procedures, see your Oracle account executive.
Parent topic: Setting the Oracle Tuxedo Registry
2.4 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 Oracle 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
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.
2.4.1 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 Oracle 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 and Creating the Configuration File in Setting Up an Oracle Tuxedo Application.
Parent topic: Configuring an ATMI Application for Security
2.4.2 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 Oracle 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 Oracle Tuxedo MIBs, start with MIB(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference. Also, see Introducing Oracle Tuxedo ATMI.
Parent topic: Configuring an ATMI Application for Security
2.5 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 Oracle 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 an Oracle Tuxedo Application at Run Time.
2.5.1 Administering Operating System (OS) Security
In addition to the security features in the ATMI environment of the Oracle 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.
2.5.1.1 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.
Parent topic: Administering Operating System (OS) Security
2.6 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 Oracle 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
![Mutual Authentication in the Delegated Trust Authentication Model Diagram Mutual Authentication in the Delegated Trust Authentication Model Diagram](img/secadm-2.1.02.jpg)
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.
See Also:
- Authentication
- Default Authentication and Authorization
- Administering Default Authentication and Authorization
- Security Administration Tasks
- Security Interoperability
- Security Compatibility
- Oracle Tuxedo Domains (Multiple-Domain) Servers in Introducing Oracle Tuxedo ATMI
Parent topic: Administering Security
2.7 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 Oracle Tuxedo software.
Parameter Name | Description | Setting |
---|---|---|
SEC_PRINCIPAL_NAME in UBBCONFIG (TA_SEC_PRINCIPAL_NAME in TM_MIB )
|
During application booting, each WSH, domain gateway, and server process in the ATMI application calls the authentication plug-in to acquire security credentials for the security principal name specified inSEC_PRINCIPAL_NAME.*
|
1 - 511 characters. If not specified at any level in the configuration hierarchy, the security principal name defaults to theDOMAINID string specified in the UBBCONFIG file.
|
CONNECTION_PRINCIPAL_NAME for local domain access point in DMCONFIG (TA_DMCONNPRINCIPALNAME for LACCESSPOINT in DM_MIB )
|
During application booting, each domain gateway process in the ATMI application calls the authentication plug-in a second time to acquire security credentials for the connection principal name specified in CONNECTION_PRINCIPAL_NAME.*
|
1 - 511 characters. If not specified, the connection principal name defaults to theACCESSPOINTID ** string for the local domain access point specified in the DMCONFIG file.
|
* The topics that follow explain how the system processes acquire credentials and why they require them. ** . The ACCESSPOINTID parameter is also known as DOMAINID .
|
SEC_PRINCIPAL_NAME
is specified any of the following four levels in the configuration hierarchy:
-
RESOURCES
section inUBBCONFIG
orT_DOMAIN
class inTM_MIB
-
MACHINES
section inUBBCONFIG
orT_MACHINE
class inTM_MIB
-
GROUPS
section inUBBCONFIG
orT_GROUP
class inTM_MIB
-
SERVERS
section inUBBCONFIG
orT_SERVER
class inTM_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
exceptserv1
processes useterri
as a principal name. - All
serv1
processes usejohn
as a principal name.
Note:
Security principal information must be specified for all machines in a networked application (MP mode) configuration. If a boot failure occurs, examine the ULOG files on both sides of the connection where the failure occurred for more information about the cause of the failure.- How System Processes Acquire Credentials
- Why System Processes Need Credentials
- Example UBBCONFIG Entries for Principal Names
Parent topic: Administering Security
2.7.1 How System Processes Acquire Credentials
- to acquire security credentials
- get authorization and auditing tokens for itself
Figure 2-3 Acquiring Credentials and Tokens During Application Booting
![Acquiring Credentials and Tokens During Application Booting Diagram Acquiring Credentials and Tokens During Application Booting Diagram](img/secadm-2.1.03.jpg)
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.
Parent topic: Specifying Principal Names
2.7.2 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 Oracle 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.Parent topic: Specifying Principal Names
2.7.3 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"
Parent topic: Specifying Principal Names
2.8 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 Oracle 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 Oracle 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
![WSH Operating with Older Workstation Client Diagram WSH Operating with Older Workstation Client Diagram](img/secadm-2.1.04.jpg)
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
![Older WSH Operating with Workstation Client Diagram Older WSH Operating with Workstation Client Diagram](img/secadm-2.1.05.jpg)
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
![Server Interoperating with Older ATMI Application Diagram Server Interoperating with Older ATMI Application Diagram](img/secadm-2.1.06.jpg)
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 Oracle Tuxedo Systems
![Server Interoperating with Older Oracle Tuxedo Systems Diagram Server Interoperating with Older Oracle Tuxedo Systems Diagram](img/secadm-2.1.07.jpg)
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
- Summarizing How the CLOPT -t Option Works
- Example UBBCONFIG Entries for Interoperability
Parent topic: Administering Security
2.8.1 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
![Obtaining Authorization and Auditing Tokens for an Older Client Diagram Obtaining Authorization and Auditing Tokens for an Older Client Diagram](img/secadm-2.1.08.jpg)
- How the WSH Establishes an Identity for an Older Client
- How the Domain Gateway Establishes an Identity for an Older Client
- How the Server Establishes an Identity for an Older Client
Parent topic: Mandating Interoperability Policy
2.8.1.1 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.
Parent topic: Establishing an Identity for an Older Client
2.8.1.2 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.
Parent topic: Establishing an Identity for an Older Client
2.8.1.3 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.
Parent topic: Establishing an Identity for an Older Client
2.8.2 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.
Table 2-1 Functionality of WSH, Domain Gateway, and Server Processes When Interoperability Is and Is Not Allowed
Process | Interoperability Allowed (CLOPT -t) | Interoperability Not Allowed |
---|---|---|
Workstation Handler (WSH) | If the WSH receives a request from a pre-release 7.1 Workstation client to join the application, the WSH authenticates the client using a pre-release 7.1 authentication protocol and calls the impersonate user function to get authorization and auditing tokens for the client based on the user name given in the request. When the WSH receives a service request from the authenticated Workstation client, it attaches the tokens to the client request and forwards the request to the destination server. | If the WSH receives a request from a pre-release 7.1 Workstation client to join the application, the WSH rejects the request. No communication is possible between the newer WSH and the older Workstation client. |
Domain gateway (GWTDOMAIN) | When the domain gateway sets up a connection to a pre-release 7.1 remote domain gateway, it authenticates the remote domain gateway using a pre-release 7.1 authentication protocol and then sets up the network connection. When the domain gateway receives a client request from the older domain, the domain gateway calls the impersonate user function to get authorization and auditing tokens for the client based on the LOCAL_PRINCIPAL_NAME (defaults to ACCESSPOINTID ) identity configured for the remote domain access point, attaches the tokens to the client request, and then forwards the request to the destination server. The client has the same access permissions as the LOCAL_PRINCIPAL_NAME identity. For any outbound client request, the domain gateway strips the tokens from the request before sending the request along with the client’s application key to the older domain.
|
The domain gateway does not set up a connection to a pre-release 7.1 remote domain gateway. No communication is possible between the newer and older domains. |
System or application server | If the server receives a request from a remote client running Oracle Tuxedo pre-release 7.1 software, the server calls the impersonate user function to get authorization and auditing tokens for the client based on the client’s assigned application key, and then performs the client request assuming the client passes any authorization checks. | If the server receives a request from a remote client running Oracle Tuxedo pre-release 7.1 software, the server rejects the client request. No communication is possible between the newer server and the older client. |
Parent topic: Mandating Interoperability Policy
2.8.3 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 ... "
Note:
- Specifying Principal Names
- Establishing a Link Between Domains
- Setting ACL Policy
- Security Administration Tasks
- Security Interoperability
- Setting Up Security in a Domains Configuration and Setting Up Connections in a Domains Configuration in Using the Oracle Tuxedo Domains Component
Parent topic: Mandating Interoperability Policy
2.9 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 SSL or link-level encryption (LLE) min-max values to be used to set up SSL or LLE on the link between the gateways. If SSL is being used, the initiator and target domain gateways also authenticate each other through the use of SSL certificates. LLE is described in Link-Level Encryption. SSL is described in SSL Encryption.
- The initiator and target domain gateways authenticate one another through the exchange of security tokens assuming that both gateways are running Oracle Tuxedo release 7.1 or later software.
If one or both of the domain gateways are running Oracle 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 Oracle Tuxedo release 7.1 or later software.
Parameter Name | Description | Setting |
---|---|---|
CONNECTION_PRINCIPAL_NAME in DMCONFIG (TA_DM CONNPRINCIPALNAME in DM_MIB) |
When this parameter appears in the DM_LOCAL section* of the DMCONFIG file, its value becomes the principal name of the local domain access point when setting up a connection with a remote domain access point. For default authentication plug-ins, if a value is assigned to CONNECTION_PRINCIPAL_NAME for the local domain access point, it must be the same as the value assigned to the ACCESSPOINTID parameter* for the local domain access point. If these values do not match, the local domain gateway process will not boot, and the system will generate the following userlog(3c) message: ERROR: Unable to acquire credentials.
|
1-511 characters. If not specified, the principal name defaults to the ACCESSPOINTID string for the local domain access point.
|
When this parameter appears in the DM_REMOTE section* of the DMCONFIG file for a particular remote domain access point, its value becomes the principal name of the remote domain access point when setting up a connection with the local domain access point. For default authentication plug-ins, if a value is assigned to CONNECTION_PRINCIPAL_NAME for a remote domain access point, it must be the same as the value assigned to the ACCESSPOINTID parameter* for the remote domain access point. If these values do not match, any attempt to set up a connection between the local domain gateway and the remote domain gateway fails, and the system generates the following userlog(3c) message: ERROR: Unable to initialize administration key for domain domain_name .
|
1-511 characters. If not specified, the principal name defaults to the ACCESSPOINTID string for the remote domain access point. | |
*The DM_LOCAL section is also known as DM_LOCAL_DOMAINS ; the DM_REMOTE section is also known as DM_REMOTE_DOMAINS ; and the ACCESSPOINTID parameter is also known as DOMAINID .
|
Figure 2-9 Establishing a Link Between Domains Using Default Authentication
![Establishing a Link Between Domains Using Default Authentication Establishing a Link Between Domains Using Default Authentication](img/secadm-2.1.09.jpg)
Note:
The “Credentials” shown in the preceding figure were acquired by each domain gateway process at application booting using theCONNECTION_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.
2.9.1 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"
Note:
- Specifying Principal Names
- Mandating Interoperability Policy
- Setting ACL Policy
- Security Administration Tasks
- Setting Up Security in a Domains Configuration in Using the Oracle Tuxedo Domains Component
Parent topic: Establishing a Link Between Domains
2.10 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 Oracle Tuxedo release 7.1 or later software.
Parameter Name | Description | Setting |
---|---|---|
ACL_POLICY in DMCONFIG (TA_DMACLPOLICY in DM_MIB )
|
May appear in the DM_REMOTE section of the DMCONFIG file for each remote domain access point. Its value for a particular remote domain access point determines whether or not the local domain gateway modifies the credential (identity) of service requests received from the remote domain. | LOCAL or GLOBAL. Default is LOCAL. LOCAL means replace credential of any service request received from remote domain, and GLOBAL means pass service requests with no change. |
LOCAL_PRINCIPAL_NAME in DMCONFIG (TA_DMLOCALPRINCIPALNAME in DM_MIB )
|
May appear in the DM_REMOTE section of the DMCONFIG file for each remote domain access point. If the ACL_POLICY parameter is set (or defaulted) to LOCAL for a particular remote domain access point, the local domain gateway replaces the credential of any service request received from the remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME parameter for this remote domain access point. | 1-511 characters. If not specified, the principal name defaults to the ACCESSPOINTID string for the remote domain access point. |
The following three figures illustrates how the ACL_POLICY
configuration affects the operation of local domain gateway (GWTDOMAIN
) processes.
Figure 2-10 Establishing a Local ACL Policy
![Establishing a Local ACL Policy Diagram Establishing a Local ACL Policy Diagram](img/secadm-2.1.10.jpg)
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 Oracle Tuxedo pre-release 7.1 software except that the system uses theACCESSPOINTID
identity configured for the remote domain access point. Essentially, the local ACL policy is hardcoded in Oracle Tuxedo release 6.5 or earlier software.
Figure 2-11 Establishing a Global ACL Policy
![Establishing a Global ACL Policy Diagram Establishing a Global ACL Policy Diagram](img/secadm-2.1.11.jpg)
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
![Establishing a One-way Local and One-way Global ACL Policy Diagram Establishing a One-way Local and One-way Global ACL Policy Diagram](img/secadm-2.1.12.jpg)
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.
- 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 - an ACL database containing entries for users in its own domain as well as users in ATMI application 1.
Parent topic: Administering Security
2.10.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.
Parent topic: Setting ACL Policy
2.10.2 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"
Parent topic: Setting ACL Policy
2.11 Setting Credential Policy
As the administrator, you use the following configuration parameter to set and control the credential policy between ATMI applications running Oracle Tuxedo release 8.0 or later software.
Parameter Name | Description | Setting |
---|---|---|
CREDENTIAL_POLICY in DMCONFIG (TA_DMCREDENTIALPOLICY in DM_MIB )
|
May appear in the DM_REMOTE section of the DMCONFIG file for each remote domain access point. Its value for a particular remote domain access point determines whether or not the local domain gateway removes the credential (identity) from a local service request destined for this remote domain access point.
Note: The CREDENTIAL_POLICY parameter controls whether or not the local domain gateway removes the credential from a local service request before sending the request to a remote domain. The ACL_POLICY parameter controls whether or not the local domain gateway replaces the credential of a service request received from a remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME parameter. |
LOCAL or GLOBAL. Default is LOCAL. LOCAL means remove the credential from a local service request destined for this remote domain access point, and GLOBAL means do not remove the credential from a local service request destined for this remote domain access point. |
Parent topic: Administering Security
2.12 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.
Parent topic: Administering Security
2.13 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, and 128-bit.
LLE applies to the following types of ATMI links:
- Workstation client to workstation handler (WSH)
- Bridge-to-Bridge
- Administrative utility (such as
tmboot
) totlisten
- Domain gateway to domain gateway
- Understanding LLE min and max Values
- How to Configure LLE on Workstation Client Links
- How to Configure LLE on Bridge Links
- How to Configure LLE on tlisten Links
- How to Configure LLE on Domain Gateway Links
Parent topic: Administering Security
2.13.1 Understanding LLE 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
LLE when the license file specifies STRENGTH=128 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.
Parent topic: Administering Link-Level Encryption
2.13.2 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 LLE 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 theSERVERS
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 parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
variable.
In the preceding example, when tmloadcf(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 Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information.
Parent topic: Administering Link-Level Encryption
2.13.3 How to Configure LLE on Bridge Links
The Oracle Tuxedo system architecture optimizes network communications by establishing a multiplexed channel among the machines in a multiple-machine application. Oracle 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 LLE 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 theNETWORK
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 theBRIDGE
parameter. - Load the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
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 Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information.
Parent topic: Administering Link-Level Encryption
2.13.4 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 Oracle Tuxedo Command Reference, and TM_MIB(5) and UBBCONFIG(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information.
Parent topic: Administering Link-Level Encryption
2.13.5 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 Oracle 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 to 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 LLE 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 theDM_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)
. Thedmloadcf
command parsesDMCONFIG
and loads the binaryBDMCONFIG
file to the location referenced by theBDMCONFIG
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 Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information. Also, see Setting Up Security in a Domains Configuration in Using the Oracle Tuxedo Domains Component.
2.14 Administering SSL Encryption
SSL encryption establishes data privacy for messages moving between the machines in an ATMI application. The industry-standard TLS 1.0 protocol is used for SSL encryption. Customers can used 256-bit, 128-bit, and 56-bit SSL ciphers.
- Understanding SSL min and max Values
- How to Configure SSL on Workstation Client Links
- How to Configure SSL on Bridge Links
- How to Configure SSL on tlisten Links
- How to Configure SSL on Domain Gateway Links
- Development Process for the SSL Protocol
- Creating an Oracle Wallet
- Runtime Creation of an Oracle Wallet
- Use of the TUXCREATEWALLET Environment Variable
- Debugging SSL Connection Problems
Parent topic: Administering Security
2.14.1 Understanding SSL min and max Values
Before you can configure SSL for your ATMI application, you need to be familiar with the SSL 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 SSL version
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 the SSL Protocol Works and Encryption Key Size Negotiation.
Parent topic: Administering SSL Encryption
2.14.2 How to Configure SSL on Workstation Client Links
To configure SSL on Workstation client links, follow these steps:
- Ensure that you are working on the ATMI application
MASTER
machine and that the application is inactive. SEC_PRINCIPAL_NAME
,SEC_PRINCIPAL_LOCATION
, andSEC_PRINCIPAL_PASSVAR
parameters must be specified. This may be done in the*RESOURCES
,*MACHINES
,*GROUPS
, or*SERVERS
sections.Note:
In general, it is recommended to specify these parameters at the highest level possible to avoid duplicating information in theUBBCONFIG
and to avoid multiple password prompts if runningtmloadcf
interactively.- Open
UBBCONFIG
with a text editor and add the following lines to theSERVERS
sections:*SERVERS WSL SRVGRP="group_name" SRVID=server_number ... CLOPT="-A -- -z min -Z max -n <network_address> -S <secure port> [-a] [-R <renegotiation_interval>] ..."
If the secure port is set to the same port used in the network address then the WSL will accept only SSL connections; if different ports are used, the same WSL can accept both non-SSL and SSL connections.
The WSC must set the
SEC_PRINCIPAL_LOCATION
,SEC_PRINCIPAL_NAME
and/orSEC_PRINCIPAL_PASSWORD
environment variables as appropriate.All workstation clients using SSL must specify the list of trusted certificate(s) used to verify the credentials presented by the WSH. When using legacy security credentials, the location is specified via the plugin framework
certificate_validation
interface and does not require setting any environment variables. When the Oracle Wallet is used for security credentials, the trusted certificates are contained in the Oracle Wallet. TheSEC_PRINCIPAL_LOCATION
andSEC_PRINCIPAL_NAME
environment variables are used to locate the wallet as described in Runtime Creation of an Oracle Wallet. TheSEC_PRINCIPAL_PASSWORD
environment variable is used to open the wallet.Note:
- It is possible for
SEC_PRINCIPAL_NAME
to be unset, in which case it will be interpreted as a 0-length string. - If legacy security credentials for 1-way SSL are converted to an Oracle Wallet at runtime and the
SEC_PRINCIPAL_PASSWORD
environment variable is not set at the time of creation, then a default passwordTrustedCertsOnlyNoPWNeeded
is used to create the wallet. Such a wallet can be subsequently accessed without setting theSEC_PRINCIPAL_PASSWORD
environment variable.
If the WSL -a (mutual authentication) option is being used then the WSC must also specify the location of its own certificate and private key. Regardless of whether legacy security credentials or the Oracle Wallet are being used, the
SEC_PRINCIPAL_LOCATION
,SEC_PRINCIPAL_NAME
, andSEC_PRINCIPAL_PASSWORD
environment variables must be set to access these credentials.It is possible for
SEC_PRINCIPAL_NAME
to be unset, in which case it will be interpreted as a 0-length string. - It is possible for
- Load the configuration by running
tmloadcf(1)
. Thetmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
variable.
Parent topic: Administering SSL Encryption
2.14.3 How to Configure SSL on Bridge Links
To configure SSL 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 theRESOURCES
andNETWORK
sections:*RESOURCES OPTIONS SSL,LAN SSL_RENEGOTIATION (optional) [value] *NETWORK LMID NADDR="bridge_network_address" BRIDGE="bridge_device" NLSADDR="listen_network_address" MINENCRYPTBITS=min MAXENCRYPTBITS=max
SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION
, andSEC_PRINCIPAL_PASSVAR
must be specified in the*RESOURCES
and/or*MACHINES
sections.LMID
is the logical machine where the Bridge server resides; it has direct access to the network device specified in theBRIDGE
parameter. - Load the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
variable.
Parent topic: Administering SSL Encryption
2.14.4 How to Configure SSL on tlisten Links
To configure SSL on tlisten
links, follow the steps given in the previous topic, How to Configure SSL on Bridge Links. You must enter the following command:
tlisten -l nlsaddr [-z min -Z
max][-s][-c <sec_principal_location>][-n
<sec_principal_name>][-p
<sec_principal_passvar>]
Note:
The-s
option specifies an SSL connection instead of an LLE connection.
The -c, -n, and -p options specify SSL security principal information and must match the values specified for the SEC_PRINCIPAL_NAME
, SEC_PRINCIPAL_LOCATION
, and SEC_PRINCIPAL PASSVAR
in the UBBCONFIG
file.
Parent topic: Administering SSL Encryption
2.14.5 How to Configure SSL on Domain Gateway Links
To configure SSL 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 theDM_TDOMAIN
section:*DM_TDOMAIN # SSL DEFAULT: NWPROTOCOL={SSL|SSL_ONE_WAY} SSL_RENEGOTIATION =
[value]
# 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.
- SEC_PRINCIPAL_NAME,
SEC_PRINCIPAL_LOCATION
SEC_PRINCIPAL_PASSWORD
- Load the configuration by running dmloadcf(1) . The
dmloadcf
command parsesDMCONFIG
BDMCONFIG
file to the location referenced by theBDMCONFIG
variable.
Parent topic: Administering SSL Encryption
2.14.6 Development Process for the SSL Protocol
Using the SSL protocol in a Tuxedo application is primarily an administration process. The following table describes the administration steps required to set up the infrastructure required to use the SSL protocol and configure the servers and clients in your application to use SSL.
For a detailed description of the administration steps, see Managing Public Key Security and Configuring the SSL Protocol in Using Security in CORBA Applications.
Once the administration steps are complete, you can use either password authentication or certificate authentication in your Tuxedo application. The steps are similar for CORBA application authentication. For more information, see Writing a CORBA Application That Implements Security in Using Security in CORBA Applications.
Note:
If you are using the Oracle CORBA C++ ORB as a server application, the ORB can also be configured to use the SSL protocol. For more information, see Configuring the SSL Protocol in Using Security in CORBA Applications.Table 2-2 Administration Steps for the SSL Protocol
Step | Description |
---|---|
1 | Set up an LAP-enabled directory service. You will be prompted for the name of the LDAP server during the installation of the Oracle Tuxedo product. |
2 | Install the license for the SSL protocol. |
3 | Obtain a digital certificate and private key for the Oracle Tuxedo application from a certificate authority. |
4 | Publish the digital certificates for the Oracle Tuxedo application and the certificate authority in the LAP-enabled directory service. |
5 | Define the SEC_PRINCIPAL_NAME , SEC_PRINCIPAL_LOCATION , and SEC_PRINCIPAL_PASSVAR parameters for the Tuxedo server process in the UBBCONFIG file.
|
6 | Change to "Set the UBBCONFIG parameters, DMCONFIG parameters, WSL CLOPT, JSL CLOPT, or ISL CLOPT so that SSL is turned on. |
7 | Define a port for SSL communication in the appropriate configuration file or server CLOPT. |
8 | Create a Trusted Certificate Authority file (trust_ca.cer ) that defines the certificate authorities trusted by the Oracle Tuxedo application.
|
9 | Change to "Use the tmloadcf and/or dmloadcf commands to load the appropriate configuration file(s).
|
10 | Optionally, create a Peer Rules file (peer_val.rul ) for the Oracle Tuxedo product.
|
11 | Optionally, modify the LDAP Search filter file to reflect the directory hierarchy in place in your enterprise. |
If you use the SSL protocol with password authentication, you need to set the SECURITY
parameter in the UBBCONFIG
file to desired level of authentication and if appropriate, configure the Authentication Server (AUTHSRV
). For information about the administration steps for password authentication, see “Password Authentication” in Using Security in ATMI Applications..
The following figure illustrates the configuration of a Tuxedo application that uses the SSL protocol.
Figure 2-13 Configuration for Using the SSL Protocol in a Tuxedo Application
![Configuration for Using the SSL Protocol in a Tuxedo Application Diagram Configuration for Using the SSL Protocol in a Tuxedo Application Diagram](img/clientss_2.png)
Parent topic: Administering SSL Encryption
2.14.7 Creating an Oracle Wallet
An Oracle Wallet can be created in any of the following ways:
- Using the owm graphical tool for those customers who have installed Oracle Database
- Using the orapki command line tool for those customers who have installed Oracle Database
- Using openssl or another third party tool
- Automatically at execution time by conversion of security credentials used in Tuxedo 11g or earlier releases.
Parent topic: Administering SSL Encryption
2.14.7.1 Creating an Oracle Wallet with orapki
For information about how to create an Oracle Wallet using orapki, see the orapki Utility in Oracle Database Advanced Security Administrator's Guide.
Oracle Tuxedo wallets require a password, so the Auto
Login option should not be used. orapki
and
owm
can be used to generate wallet with a new private
key and certificate, but current versions of these tools cannot
import a previously used private key and certificate into a wallet.
If it is necessary to import a preexisting private key and
certificate pair into a wallet, use runtime conversion, openssl, or
another third party tool.
Parent topic: Creating an Oracle Wallet
2.14.7.2 Creating an Oracle Wallet with openssl
An example of an openssl
command that can be used
to create an Oracle Wallet is as follows:
Listing 2‑1 Example of Creating an Oracle Wallet with openssl
openssl pkcs12 \
-export \
-chain \
-inkey private_key_file.pem \
-in certificate_file.pem \
-CAfile trusted_certificate_file.pem \
-out ewallet.p12 \
-passin Spass:private_key_password \
-passout pass:wallet_password \
Where,
-
-export
: indicates that a PKCS 12 file is being created. -
-chain
: specifies that an attempt is made to include the entire certificate chain of the user certificate. -
-inkey:
specifies the private key file. -
-in
: specifies the file that contains the user certificate and any other certificates in the certificate chain.Note:
If the private key and the certificate chain are in the same file, the-inkey
and-in
parameters can specify the same file.
-
-CAfile
: specifies a file containing trusted certificates. -
-out
: specifies the output file name, which must be ewallet.p12 for an Oracle Wallet. -
-passin
: specifies the password for the private key file. -
-passout
: specifies the password for the newly created wallet.
Note:
- If there is any concern about other users executing "
ps
" whileopenssl
is running, then the-passin
and-passout
parameters should be omitted andopenssl
will prompt for the passwords. - When you create an Oracle Wallet with
openssl
, the "-passin
" parameter must have the same value as the "-passout
" parameter, for Oracle Wallet does not distinguish wallet password from private key password.
Parent topic: Creating an Oracle Wallet
2.14.8 Runtime Creation of an Oracle Wallet
When the SEC_PRINCIPAL_LOCATION
configuration
parameter or the workstation client
SEC_PRINCIPAL_LOCATION
environment variable does not
point to an Oracle Wallet, Tuxedo looks for legacy security
credentials and attempts to create an Oracle Wallet as follows:
- As in previous releases,
SEC_PRINCIPAL_LOCATION
points to the private key file for the process. A private key file is mandatory for processes that will be on the server side of an SSL connection or that will be on the client side of the connection when mutual authentication is used. It is optional for processes that will be on the client side of a one-way SSL connection. The value of theSEC_PRINCIPAL_PASSVAR
configuration file environment variable (or the workstation clientSEC_PRINCIPAL_PASSWORD
environment variable) will be used to decrypt the private key. - The certificate chain for the process is obtained via the
plugin framework passing the value of
SEC_PRINCIPAL_NAME
as input (In the default plugin framework implementation this uses LDAP). A certificate chain is mandatory for processes that will be on the server side of an SSL connection or that will be on the client side of the connection when mutual authentication is used. It is optional for processes that will be on the client side of a one-way SSL connection. - The trusted certificates for the process are contained in the
file specified as the
caCertificateFile
parameter of the plugin frameworkcertificate_validation
interface. The defaultcaCertificateFile
is$TUXDIR/udataobj/security/certs/trust_ca.cer
. Trusted certificates need to exist for SSL servers and SSL clients.
A PKCS12 wallet file is created using the process' private key (if any) and user certificate (if any) as well as the other certificates in the chain and the trusted certificates.
During Oracle wallet runtime creation,
SEC_PRINCIPAL_LOCATION
is used to specify the location
of the newly created wallet; it must be defined as either server's
or client's own private key.
For example, if there is a private key file
"ISH_tuxqa.pem"
in "/home/tuxedo/myapp"
,
you should define
SEC_PRINCIPAL_LOCATION="/home/tuxedo/myapp/ISH_tuxqa.pem"
.
In this way, the wallet is created at
/home/tuxedo/myapp/wallet.ISH_tuxqa.pem/ewallet.p12
.
Note:
- If you want to create the wallet manually with the method mentioned in Creating an Oracle Wallet, you must follow the same rules as above to create your wallet at a proper directory; otherwise, the wallet cannot be found.
- Exceptionally, when creating the wallet manually, besides defining the
SEC_PRINCIPAL_LOCATION
as a private key file, you can also define it as a directory. In this way, bothSEC_PRICIPAL_LOCATION
andSEC_PRINCIPAL_NAME
will be used to locate the wallet. - For example, if you define
SEC_PRINCIPAL_LOCATION="/home/tuxedo/myapp"
andSEC_PRINCIPAL_NAME="ISH_tuxqa"
, you should copy your manually created wallet to/home/tuxedo/myapp/wallet.ISH_tuxqa/ewallet.p12
; otherwise, it cannot be found.
Parent topic: Administering SSL Encryption
2.14.9 Use of the TUXCREATEWALLET Environment Variable
The conversion of legacy security credentials to the Oracle
Wallet format is affected by the TUXCREATEWALLET
environment variable, which may have the following settings:
-
TUXCREATEWALLET=KEEP
orTUXCREATEWALLET=YES
orTUXCREATEWALLET
unset: If a wallet does not exist but old-style security credentials do exist then convert the legacy security credentials to a wallet. This is the default behavior. The directory where the wallet is created will have 700 permissions and the ewallet.p12 file will have 600 permissions. The user must have proper permissions to read any existing wallet or to create a wallet. IfULOG_SSLINFO=y
is set then the following message will be logged:LIBTUX_CAT:6908: INFO: Security credentials for principal name have been converted to Oracle Wallet wallet_directory
On subsequent process invocations the newly created wallet will be used so that the legacy security credentials do not need to be recreated.
-
TUXCREATEWALLET=TEMP
: If a wallet does not exist but old-style security credentials do exist create a wallet in a temporary directory and then remove the temporary file wallet once it is open.No LIBTUX_CAT:6908
message will be logged when using this option. The TEMP option is less efficient but is needed if:- Old-style security credentials gotten from the plugin framework could change dynamically, or
- The application does not want to store wallets on a local file system for security reasons or for any other reason, or
-
SEC_PRINCIPAL_LOCATION
is located on a read-only file system.
-
TUXCREATEWALLET=NO
orTUXCREATEWALLET=anyothervalue
: If a wallet does not exist report an error and do not look at old-style security credentials.The values KEEP or TEMP may be in any case but must be those 4 characters. The values
YES
orNO
may be in the local language as is true for many otherYes/No
environment variables in Tuxedo.
Parent topic: Administering SSL Encryption
2.14.10 Debugging SSL Connection Problems
- Enabling NZ Tracing
- Connection Establishment Log Message
- Displaying the Contents of an Oracle Wallet
- Obtaining NZ Error Code Information
Parent topic: Administering SSL Encryption
2.14.10.1 Enabling NZ Tracing
If the environment variable TUXNZTRACE=8191
is set,
Tuxedo will output an SSL trace for the process to a file named
trace-process_id.log
. The trace output will contain
information sent across the SSL handshake process as well as
encrypted application data. This trace can be very helpful in
determining why a particular certificate chain is not considered
valid or why there is some other error in the SSL handshake
process.
Parent topic: Debugging SSL Connection Problems
2.14.10.2 Connection Establishment Log Message
If the environment variable ULOG_SSLINFO=yes
is set, then Tuxedo will write a message to the userlog each time an SSL connection is established which includes the name of the negotiated cipher.
Parent topic: Debugging SSL Connection Problems
2.14.10.3 Displaying the Contents of an Oracle Wallet
Various tools can be used to display information about an Oracle Wallet, which is a PKCS12 file.
Openssl is available as part of the OS distribution on some operating systems and can be downloaded and compiled from source on other operating systems.
The following openssl command displays the certificates and private keys in an Oracle Wallet:
openssl pkcs12 -in ewallet.p12
openssl
will prompt for a password to be used to open the wallet. (The option
-password pass:password
can be used to avoid the prompt but using this
option could allow the password to be seen by another user on the machine who is executing the
ps
command.)
openssl
will also prompt for a password to be used to encrypt the decrypted
private key when displaying it on the terminal. The option -nodes can be used to avoid this
prompt and to display the private key in unencrypted format.
Any of the certificates contained in the output of openss pkcs12
can be copied into another file and the following command displays the fields in the certificate:
openssl x509 -in certificatefile -text -noout
Users who have Oracle Database software installed can also use the orapki command or the owm graphical command to display information about a wallet. The orapki command to display wallet information looks like this:
orapki wallet display -wallet wallet_location
Parent topic: Debugging SSL Connection Problems
2.14.10.4 Obtaining NZ Error Code Information
Many SSL error messages include an error code number returned by the Oracle NZ security layer. In some but not all error messages this is followed by a short text description of the NZ error number. For those error messages where no text description of the NZ error code is included, this information can be obtained by looking in the file.
$TUXDIR/locale/C/ORACLE.text
Users who have Oracle Database software installed can also use the oerr command to determine the string associated with a particular error number
Note:
- SSL Encryption
- Security Administration Tasks
-
UBBCONFIG(5)
Resources Section DM_MIB(5)
T_DM_TDOMAIN
Class-
DMCONFIG(5)
DM_TDOMAIN
section -
WS_MIB(5)
T_WSL
Class - Using Security in CORBA Applications
Parent topic: Debugging SSL Connection Problems
2.15 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
- Assigning Public-Private Key Pairs
- Setting Digital Signature Policy
- Setting Encryption Policy
- Initializing Decryption Keys Through the Plug-ins
- Failure Reporting and Auditing
Parent topic: Administering Security
2.15.1 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.
Parent topic: Administering Public Key Security
2.15.2 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.
Parent topic: Administering Public Key Security
2.15.3 Setting Digital Signature Policy
As the administrator, you use the following configuration parameters to set the digital signature policy for your ATMI application.
Parameter Name | Description | Setting |
---|---|---|
SIGNATURE_AHEAD in UBBCONFIG (TA_SIGNATURE_AHEAD in TM_MIB )
|
Maximum permissible time difference between (1) the timestamp value attached to a digitally signed message buffer and (2) the time at which the message buffer is received. If the signature timestamp is too far into the future, the receiving process rejects the message buffer. | 1-2147483647 seconds. Default is 3600 seconds (one hour). |
SIGNATURE_BEHIND in UBBCONFIG (TA_SIGNATURE_BEHIND in TM_MIB )
|
Maximum permissible time difference between (1) the time at which a digitally signed message buffer is received and (2) the timestamp value attached to the message buffer. If the signature timestamp is too far into the past, the receiving process rejects the message buffer. | 1-2147483647 seconds. Default is 604800 seconds (one week). |
SIGNATURE_REQUIRED in UBBCONFIG (TA_SIGNATURE_REQUIRED in TM_MIB )
|
Determines whether a receiving process will accept only message buffers that are digitally signed. | Y (yes—digital signature is required) or N (no—digital signature is not required). Default is N .
|
- Setting a Postdated Limit for Signature Timestamps
- Setting a Predated Limit for Signature Timestamps
- Enforcing the Signature Policy for Incoming Messages
- How the EventBroker Signature Policy Is Enforced
- How the /Q Signature Policy Is Enforced
- How the Remote Client Signature Policy Is Enforced
Parent topic: Administering Public Key Security
2.15.3.1 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.
2.15.3.1.1 Example UBBCONFIG Entries for Postdated Limit
*RESOURCES
SIGNATURE_AHEAD 2400
Parent topic: Setting a Postdated Limit for Signature Timestamps
2.15.3.2 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.
2.15.3.2.1 Example UBBCONFIG Entries for Predated Limit
*RESOURCES
SIGNATURE_BEHIND 300000
Parent topic: Setting a Predated Limit for Signature Timestamps
2.15.3.3 Enforcing the Signature Policy for Incoming Messages
SIGNATURE_REQUIRED
may be specified any of the
following four levels in the configuration hierarchy:
-
RESOURCES
section inUBBCONFIG
orT_DOMAIN
class inTM_MIB
-
MACHINES
section inUBBCONFIG
orT_MACHINE
class inTM_MIB
-
GROUPS
section inUBBCONFIG
orT_GROUP
class inTM_MIB
-
SERVICES
section inUBBCONFIG
orT_SERVICE
class inTM_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 orT_DOMAIN
class), this parameter covers all application services advertised within the domain, including those advertised by gateway processes. The default isN
. - Set at the machine level (
MACHINES
section orT_MACHINE
class), this parameter covers all application services advertised on a particular machine, including those advertised by gateway processes. The default isN
. - Set at the group level (
GROUPS
section orT_GROUP
N
. - Set at the service level (
SERVICES
sectionT_SERVICE
class), this parameter covers all instances of a particular service advertised within the domain, including those advertised by gateway processes. The default isN
.
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
.
Parent topic: Setting Digital Signature Policy
2.15.3.3.1 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.
Parent topic: Enforcing the Signature Policy for Incoming Messages
2.15.3.3.2 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 theMACHINES
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 parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
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
- 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.
Parent topic: Enforcing the Signature Policy for Incoming Messages
2.15.3.4 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 theTMUSREVT(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.
Parent topic: Setting Digital Signature Policy
2.15.3.5 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.
Parent topic: Setting Digital Signature Policy
2.15.3.6 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.
Parent topic: Setting Digital Signature Policy
2.15.4 Setting Encryption Policy
As the administrator, you use the following configuration parameter to set the encryption policy for your ATMI application.
Parameter Name | Description | Setting |
---|---|---|
ENCRYPTION_REQUIRED in UBBCONFIG (TA_ENCRYPTION_REQUIRED in TM_MIB )
|
Determines whether a receiving process will accept only message buffers that are encrypted. | Y (yes—encryption is required) or N (no—encryption is not required). Default is N .
|
- Enforcing the Encryption Policy for Incoming Messages
- How the EventBroker Encryption Policy Is Enforced
- How the /Q Encryption Policy Is Enforced
- How the Remote Client Encryption Policy Is Enforced
Parent topic: Administering Public Key Security
2.15.4.1 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 inUBBCONFIG
orT_DOMAIN
class inTM_MIB
-
MACHINES
section inUBBCONFIG
orT_MACHINE
class inTM_MIB
-
GROUPS
section inUBBCONFIG
orT_GROUP
class inTM_MIB
-
SERVICES
section inUBBCONFIG
orT_SERVICE
class inTM_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 orT_DOMAIN
class), this parameter covers all application services advertised within the domain, including those advertised by gateway processes. The default isN
. - Set at the machine level (
MACHINES
section orT_MACHINE
class), this parameter covers all application services advertised on a particular machine, including those advertised by gateway processes. The default isN
. - Set at the group level (
GROUPS
section orT_GROUP
class), this parameter covers all application services advertised by a particular group, including those advertised by gateway processes. The default isN
. - Set at the group level (
GROUPS
section orT_GROUP
class), this parameter covers all application services advertised by a particular group, including those advertised by gateway processes. The default isN
. - Set at the service level (
SERVICES
sectionT_SERVICE
class), this parameter covers all instances of a particular service advertised within the domain, including those advertised by gateway processes. The default isN
.
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
.
Parent topic: Setting Encryption Policy
2.15.4.1.1 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.
Parent topic: Enforcing the Encryption Policy for Incoming Messages
2.15.4.1.2 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 theGROUPS
section:*GROUPS STDGRP LMID="machine_logical_name" GRPNO="server_group_number" ENCRYPTION_REQUIRED=Y
- Load the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
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.Parent topic: Enforcing the Encryption Policy for Incoming Messages
2.15.4.2 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.
Parent topic: Setting Encryption Policy
2.15.4.3 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.
Parent topic: Setting Encryption Policy
2.15.4.4 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.
Parent topic: Setting Encryption Policy
2.15.5 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.
Parameter Name | Description | Setting |
---|---|---|
SEC_PRINCIPAL_NAME in UBBCONFIG (TA_SEC_PRINCIPAL_NAME in TM_MIB )
|
The name of the target principal, which becomes the identity of one or more system processes. | 1-511 characters. |
SEC_PRINCIPAL_LOCATION in UBBCONFIG (TA_SEC_PRINCIPAL_LOCATION in TM_MIB )
|
The location of the file or device where the decryption (private) key for the target principal resides. | 0-1023 characters. If not specified, defaults to a NULL (zero length) string.
|
SEC_PRINCIPAL_PASSVAR in UBBCONFIG (SEC_PRINCIPAL_PASSVAR in TM_MIB )
|
The variable in which the password for the target principal is stored. | 0-31 characters. If not specified, defaults to a NULL (zero length) string.
|
This trio of configuration parameters can be specified at any of the following four levels in the configuration hierarchy:
-
RESOURCES
section inUBBCONFIG
orT_DOMAIN
class inTM_MIB
-
MACHINES
section inUBBCONFIG
orT_MACHINE
class inTM_MIB
-
GROUPS
section inUBBCONFIG
orT_GROUP
class inTM_MIB
-
SERVERS
section inUBBCONFIG
orT_SERVER
class inTM_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
exceptserv1
processes use the decryption key assigned tomach1
to decrypt any received message buffer that is encrypted. - All
serv1
processes use the decryption key assigned toserv1
to decrypt any received message buffer that is encrypted.
Configured decryption keys are automatically opened when an ATMI application is booted. The following figure illustrates how the process works.
Figure 2-14 How a Decryption Key Is Initialized Example
![How a Decryption Key Is Initialized Example Diagram How a Decryption Key Is Initialized Example Diagram](img/secadm-2.1.14.jpg)
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
, andSEC_PRINCIPAL_PASSVAR
at a particular level in the ATMI application’sUBBCONFIG
file. - The administrator loads the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
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 readsSEC_PRINCIPAL_NAME
,SEC_PRINCIPAL_LOCATION
, andSEC_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 inSEC_PRINCIPAL_NAME
, themap_proof
plug-in passes the name, location, and password of the principal to thePKi_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.
Parent topic: Administering Public Key Security
2.15.5.1 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"
Parent topic: Initializing Decryption Keys Through the Plug-ins
2.15.6 Failure Reporting and Auditing
This topic explains how the system manages errors found through digital signatures and message encryption.
Parent topic: Administering Public Key Security
2.15.6.1 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(3c) 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
orTPSIGN_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(3c) message (severity
WARN
) - Discards the buffer as if it were never received by the process
Parent topic: Failure Reporting and Auditing
2.15.6.2 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(3c) message (severity
ERROR
) - Discards the buffer as if it were never received by the process
Parent topic: Failure Reporting and Auditing
2.16 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 Oracle 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.
Parent topic: Administering Security
2.16.1 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
.
- Establishing Security by Editing the Configuration File
- Establishing Security by Changing the TM_MIB
Parent topic: Administering Default Authentication and Authorization
2.16.1.1 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.
Parent topic: Designating a Security Level
2.16.1.2 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).
Parent topic: Designating a Security Level
2.16.2 Configuring the Authentication Server
The Oracle 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 aboutLAUTHSVR
and single point security administration with WebLogic Server, refer to Implementing Single Point Security Administration. - To use the LDAP repository as your security database to authenticate and authorize Tuxedo users, you must implement extensible security administration using
XAUTHSVR
as your authentication and authorization server. For information aboutXAUTHSVR
and extensible security administration, refer toXAUTHSVR(5)
in File Formats, Data Descriptions, MIBs, and System Processes Reference.
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 Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference
Parent topic: Administering Default Authentication and Authorization
2.17 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 theRESOURCES
section of theUBBCONFIG
file toAPP_PW
. - Load the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
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 oftmadmin
. - Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.
Parent topic: Administering Security
2.18 How to Enable User-Level Authentication Security
Default authentication offers an 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.
Parent topic: Administering Security
2.18.1 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
andSERVERS
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"
) toAUTHSVR
whentmboot
starts the ATMI application. By default,AUTHSVR
uses the client user information in a file namedtpusr
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’sAPPDIR
variable. - Load the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
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 oftmadmin
. - Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.
Parent topic: How to Enable User-Level Authentication Security
2.18.2 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.
Figure 2-15 tpusr Sample Entry
![Sample Entry Diagram Sample Entry Diagram](img/secadm-2.1.15.jpg)
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 tpusradd(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.
Figure 2-16 tpgrp Sample Entry
![tpgrp Sample Entry Diagram tpgrp Sample Entry Diagram](img/secadm-2.1.16.jpg)
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 Oracle Tuxedo User and Group Files
- Adding, Modifying, or Deleting Users and Groups
Parent topic: How to Enable User-Level Authentication Security
2.18.2.1 Converting System Security Data Files to Oracle 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 Oracle 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 Oracle Tuxedo system, enter the following command.tpaclcvt -u /etc/password
This command creates the
tpusr
file and stores the converted data in it. If thetpusr
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 Oracle Tuxedo system, enter the following command.tpaclcvt -g /etc/group
This command creates thetpgrp
file and stores the converted data in it. If thetpgrp
file already exists,tpaclcvt
adds the converted data to the file, but it does not add duplicate group information to the file.
Parent topic: Setting Up the User and Group Files
2.18.2.2 Adding, Modifying, or Deleting Users and Groups
The Oracle 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
- Changing Entries for Users and Groups Through the ACL_MIB
Parent topic: Setting Up the User and Group Files
2.18.2.2.1 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.
Run . . . | To . . . | An Entry in This File |
---|---|---|
tpusradd(1) |
Add | tpusr |
tpusrmod(1) |
Modify | |
tpusrdel(1)
|
Delete | |
tpgrpadd(1)
|
Add | tpgrp |
tpgrpmod(1) |
Modify | |
tpgrpdel(1)
|
Delete |
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 Oracle Tuxedo Command Reference.
Parent topic: Adding, Modifying, or Deleting Users and Groups
2.18.2.2.2 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.
Parent topic: Adding, Modifying, or Deleting Users and Groups
2.19 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
- How to Enable Mandatory ACL Security
- How to Enable Generic LDAP Based Security
- How to Enable Security Service for OES
Parent topic: Administering Security
2.19.1 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.
Parent topic: Enabling Access Control Security
2.19.1.1 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 theRESOURCES
andSERVERS
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"
) toAUTHSVR
whentmboot
starts the ATMI application. By default,AUTHSVR
uses the client user information in a file namedtpusr
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’sAPPDIR
variable. - Load the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
variable. - Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.
Parent topic: How to Enable Optional ACL Security
2.19.1.2 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.
Figure 2-17 tpacl Sample Entry
![tpacl Sample Entry Diagram tpacl Sample Entry Diagram](img/secadm-2.1.17.jpg)
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
.
Parent topic: How to Enable Optional ACL Security
2.19.1.2.1 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.
Run . . . | To . . . |
---|---|
tpacladd(1) |
Add an entry |
tpaclmod(1) |
Modify an entry |
tpacldel(1) |
Delete an entry |
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 Oracle Tuxedo Command Reference.
Parent topic: Setting Up the ACL File
2.19.1.2.2 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.
Parent topic: Setting Up the ACL File
2.19.2 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.
Parent topic: Enabling Access Control Security
2.19.2.1 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 theRESOURCES
andSERVERS
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") toAUTHSVR
whentmboot
starts the ATMI application. By default,AUTHSVR
uses the client user information in a file namedtpusr
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’sAPPDIR
variable. - Load the configuration by running tmloadcf(1). The
tmloadcf
command parsesUBBCONFIG
and loads the binaryTUXCONFIG
file to the location referenced by theTUXCONFIG
variable. - Distribute the application password to authorized users of the ATMI application through an offline means such as telephone or letter.
Parent topic: How to Enable Mandatory ACL Security
2.19.2.2 Setting Up the ACL File
See Also:
Setting Up the ACL File.Parent topic: How to Enable Mandatory ACL Security
2.19.3 How to Enable Generic LDAP Based Security
Generic LDAP based security includes the user-level authentication and access control security.
With this security mechanism, authentication and authorization
are performed by invoking TUXEDO "..ATNSVC"
and
"..ATZSVC"
administrative services. It provides
flexibility for Oracle Tuxedo user to store their security
information in independent repository and access these security
information from the "..ATNSVC"
and
"..ATZSVC"
services. Oracle Tuxedo supplies a default
implementation of XAUTHSVR
server which advertises
these two administrative services. With this implementation, the
security information, including Tuxedo user ID, password, and
service access privilege, are stored in LDAP repositories.
Each client must provide a valid user name and user-specific password, to join the ATMI application. The user password must match the password stored in LDAP repositories. Each client must be granted with proper privilege before it can access Tuxedo services successfully.
To enable the LDAP based security with default
XAUTHSVR
implementation, follow these steps:
- Setting Up the UBBCONFIG File
- Setting Up the XAUTHSVR Server Configuration File
- Setting Up the LDAP Repository
- Setting Up the Authorization Cache
Instructions for these steps are provided in the following topics.
- Setting Up the UBBCONFIG File
- Setting Up the XAUTHSVR Server Configuration File
- Setting Up the LDAP Repository
- Setting Up the Authorization Cache
Parent topic: Enabling Access Control Security
2.19.3.1 Setting Up the UBBCONFIG File
- Open
UBBCONFIG
with a text editor. - In the
RESOURCES
section, do the following:- Set the SECURITY parameter to one of these values:
USER_AUTH
,ACL
orMANDATORY_ACL
. - Set the
OPTIONS
parameter toEXT_AA
. - Do one of the following:
- If the
SECURITY
parameter is set toACL
orMANDATORY_ACLAUTHSVC
, setAUTHSVC
to..AUTHSVC
, which is the service name advertised by theXAUTHSVR
server. - If the SECURITY parameter is set to
USER_AUTH
, setAUTHSVC
toAUTHSVC
, which is the service name advertised by theXAUTHSVR
server.
- If the
- Set the SECURITY parameter to one of these values:
-
Set up
XAUTHSVR
in theSERVERS
section.* RESOURCES SECURITY ACL AUTHSVC ..AUTHSVC OPTIONS EXT_AA *SERVERS XAUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y
Parent topic: How to Enable Generic LDAP Based Security
2.19.3.2 Setting Up the XAUTHSVR Server Configuration File
XAUTHSVR
server configuration file is used for
XAUTHSVR
to locate the LDAP repository. By default,
the configuration file named tpldap.xauth
resides in
$TUXDIR/udataobj
directory. You can specify a
customized location with "-f" option to XAUTHSVR
server. XAUTHSVR
server allows you to store your
authentication and authorization information in separate LDAP
repositories. You can specify an ATN configuration file with "-n"
option and "-z" option respectively. All these configuration files
share the same format.
The following table describes the XAUTHSVR
configuration file keywords.
Table 2-3 XAUTHSVR Configuration File Keywords
Keyword | Value Type | Usage |
---|---|---|
FILE_VERSION
|
numeric | The configuration file version. The default is 1. This should remains in 1. |
LDAP_VERSION
|
numeric | The LDAP protocol version. Valid values are 2 and 3. The default is 3. |
BINDDN
|
string | The DN used to bind to an LDAP server. Usually the DN represents a LDAP administrator. The default is " cn=Admin ". The tpldapconf command can be used to create BINDDN .
|
BASE
|
string | LDAP search base. The default is " ou=people,ou=aa,dc=mydomain ", where mydomain is the root node of the authentication or authorization security repository.
|
PASSWORD
|
string | The password for bind DN. This is a required keyword and the password is encrypted in clear text. The tpldapconf command can be used to create the encrypted password.
|
LDAP_ADDR
|
string | A comma-separated list of LDAP address containing hostnames and ports. The syntax is [//]hostname[:port] . The default value for port is 7001. If LDAP_ADDR is not specified, XAUTHSVR regards localhost:7001 as the location to contact the LDAP server.
|
UID_KW
|
string | The keyword used in user unique identification search in the authentication security repository. The default value is " uid ".
|
PWD_KW
|
string | The keyword used in user password search in the authentication security repository. The default value is "userPassword ".
|
MEMBEROF_KW
|
string | The keyword used in group membership search. The default value is "memberof ". Different LDAP servers use different key name to identify the user's group membership. When using OVD with virtual member plugin enabled, the keyword is "memberof ".
|
Parent topic: How to Enable Generic LDAP Based Security
2.19.3.3 Setting Up the LDAP Repository
The security information in the LDAP repository follows below schema:
-
inetOrgPerson: This object class holds the entries that
represent people. The definition follows RFC 4519 & 2798
standard except that the attribute "
uid
" length is limited to up to 30 characters. Each Oracle Tuxedo user is saved as an entry in this class. The information including user identification and user password is used for user-level authentication. - groupOfUniqueNames: This object classes holds the entries that represents a set of named objects including the information relevant to purpose or maintenance of the set. The definition follows RFC 4519 standard. This class groups a list of users that can be granted with certain sort of permissions. Groups can be nested. The permission granted to a parent group also applies to its child groups.
- Orcljaznpermission: This object class holds the tuxedo permission object consisting of the attributes shown in the following table. This object consists of two parts. One is the permission, which describes the resource types, target resource, and actions on the target resource. The other is the assigned groups or users, which are granted with this permission.
The following table describes the orcljaznpermission
class attributes.
Table 2-4 orcljaznpermission Class Attributes
Attribute | Type | Constraints | Description |
---|---|---|---|
Cn
|
String: | Single-valued, unique, required | Permission name |
Displayname
|
String: | String: | Display name |
Description
|
String: | String: | Description |
OrclJpsResourceTypeName
|
String: | Single valued | Type name of the resource to be protected. To define a Tuxedo service, this attribute should be specified to " SERVICE ".
|
Orcljaznpermissiontarget
|
String: | Single valued | Name of the resource to be protected. To define a Tuxedo service, this attribute should be specified as the service name. |
Orcljaznpermissionactions
|
String: | Single valued | List of the assigned actions, separated by comma. To define a Tuxedo service, this attribute should be specified to "EXECUTE ".
|
Parent topic: How to Enable Generic LDAP Based Security
2.19.3.4 Setting Up the Authorization Cache
In order to improve ATZ performance, the new ATZ mechanism introduces a roll-up cache, in which privileges of specific user identifiers are stored, to every Tuxedo server. To meet various ATZ requirements, the cache is configurable and flexible at each Tuxedo server level.
Three environment variables control the basic behaviors of the
cache. After defining an ENVFILE
parameter for a
specific server entry in TUXCONFIG
, these environment
variables can be defined for each Tuxedo server entry in the
SERVERS
section in UBBCONFIG
.
- TMATZPRIVILEGEMAX
- It specifies the maximum number of privileges entries. When the privileges number in the cache reaches this threshold, the new entry replaces an old one. Remaining time-to-live of privileges is evaluated for Tuxedo to choose the " most useless" entry in the ATZ cache. If this environment variable is set to 0, ATZ cache in Tuxedo server is disabled and all ATZ requests are dispatched to ATZ service. If this environment variable is not defined explicitly, the default value is 100. The valid value range is from 0 to 32767. The size of one privilege entry in the ATZ cache is 50 bytes or so.
- TMATZRESOURCEMAX
- It specifies the maximum number of resource entries which can be allocated for a specific Tuxedo Server. When the resource number in the cache reaches this threshold, both the resource and new privilege are not added into the cache and the subsequent access requests to the resource are routed to the ATZ server until an available resource slot is found. Tuxedo keeps a reference number to each resource entry occupied by the cached privileges. When no privilege occupies the specific resource entry, it will be cleared from the cache.
- TMATZEXP
- It specifies the maximum lifetime of a specific privilege in minutes. When the lifetime of a privilege reaches this threshold, the privilege is removed from the cache. If this environment variable of a Tuxedo server is set to 0, all privileges stored in the Tuxedo server have infinite lifetime and never expire. If this environment variable is not defined explicitly, the default value is 10. The valid value range is from 0 to 525600. 525600 indicates the privilege life in cache is 1 year.
Parent topic: How to Enable Generic LDAP Based Security
2.19.4 How to Enable Security Service for OES
- Install OES server and client (security module).
Note:
Oracle Entitlement Server (OES) client 11.1.2.0 is certified for use. - Configure OES java client to connect OES server.
- Create an application in OES server; create resource type, resource, and policy to specify authorization. Note: Users are allowed to authorize different types of resources having the same name by defining different policies on OES side, each of which authorizes only one resource type. For example, in order to authorize a service named OES and a /Q queue named OES, users can define two policies on OES side to authorize them respectively.
- Configure authorization template file (configure the
application name in the configured OES server and the full path
name of
jps-config.xml
to be precise) to indicate what you have configured in OES. - Configure
EAUTHSVR
server:- Run
tux.env
to set uplibjvm.so
in your library path. - Set
oes-client.jar
inCLASSPATH
.
- Run
- Configure authentication server:
Configure EXT_AA
in OPTIONS
and
..AUTHSVC
in UBBCONFIG RESOURCES
to
authenticate service you use.
For more information, please refer to Installation Guide for Oracle Identity and Access Management.
Parent topic: Enabling Access Control Security
2.20 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 following See Also section for more information about Kerberos.
The following sections describe the Kerberos authentication plug-in feature included in Tuxedo:
Parent topic: Administering Security
2.21 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.
2.21.1 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
Parent topic: Kerberos Plug-In
2.21.2 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.
Parent topic: Kerberos Plug-In
2.22 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.
Parent topic: Administering Security
2.23 Kerberos Plug-In Configuration
This section provides configuration information to get the Kerberos plug-in set up and running.
Each of these steps are explained in more detail in the subsections that follow.
Parent topic: Administering Security
2.23.1 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 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 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
Note:
On a Windows platform, the plug-inKRB5_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 Windows Tuxedo client always uses the complete Kerberos realm name to access
KAUTHSVR
.KAUTHSVRPRINC
can also be set as an environment variable.
Parent topic: Kerberos Plug-In Configuration
2.23.1.1 Restore Default Plug-in
The following commands restore the plug-in to its default state.
Listing 2‑4 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 the above listing,libtux.so
is used as an example. You must use the file name libtux
plus your platform specific dynamic library extension.
Parent topic: Configure the Kerberos Plug-in
2.23.2 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 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"
Note:
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 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"
Note:
The-p
option indicates KAUTHSVR
principal name.
Instead of using the -k
option, Windows platforms
must use the following two arguments:
Instead of using the -k
option, Windows platforms
must use the following two arguments:
-
SEC_PRINCIPAL_NAME
representsKAUTHSVR
, 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 whentmloadcf
creates theTUXCONFIG
file. Thetmloadcf
password input must be same as theKAUTHSVR
account password in a Windows domain.
KAUTHSVR
running on Windows platform must use the
complete
Kerberos realm name.
Parent topic: Kerberos Plug-In Configuration
2.23.3 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.
Parent topic: Kerberos Plug-In Configuration
2.23.4 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 thelibkrb5atn
to Tuxedo, the default plug-in still works and the default Tuxedo security mechanism takes effect.KAUTHSVR
supports full function ofAUTHSVR
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 unsupported.
Note:
- 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)
Parent topic: Kerberos Plug-In Configuration
2.24 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:
Parent topic: Administering Security
2.25 Cert-C PKI Encryption Plug-In
The Tuxedo Cert-C PKI encryption 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.
Parent topic: Administering Security
2.26 Cert-C PKI Encryption Plug-In Pre-configuration
To use the Tuxedo Cert-C PKI encryption plug-in, you must ensure to follow the system requirements:
- Access to a configured LDAP server
- User certificates stored in the LDAP are entered in the
following format:
cn=user name
Parent topic: Administering Security
2.27 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
- Configure Key Management
- Configure Certificate Parsing
- Configure Certificate Validation
- Sample Registry Command File
- Limitations
Parent topic: Administering Security
2.27.1 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
-
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"
-
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"
2.27.1.1 OpenLDAP for X.509 Certificate Lookup
To enable OpenLDAP for X.509 certificate lookup, execute the command shown in the following Listing modifies Tuxedo PKI plug-in information:
Listing OpenLDAP Command
epifreg -r -p security/BEA/certificate_lookup -i engine/security/certificate_lookup -v 1.0 -f 'libplugin.<suffix>' -e _ep_dl_certlookup -u
userCertificateLdap=ldap:/<ldap_host_name>:<ldap_port>/-u ldapBaseObject='<your_ldap_base>' -u binaryCertificate='YES'.
Where:
-
<suffix>
is the proper suffix for the shared library ( for example,libplugin.dll
for Windows, andlibplugin.so.71
for Solaris). -
ldap_host_name
is the name of the host where the LDAP server is running -
ldap_port
is the LDAP server port number (for example,userCertificateLdap=ldap:/cerebrum:389/)
. -
your_ldap_base
is the base of your LDAP DIT (for example,ldapBaseObject='ou=Accounting,o=ABC Company,c=US')
Note:
You may also need to modify thebea_ldap_filter.dat
file which is located in$TUXDIR/udataobj/security
.
Listing Filter Example
"BEA_person_lookup"
".*' " " "(&(objectClass=inetOrgPerson)(cn=%v))" "username"
"(&(objectClass=inetOrgPerson)(cn=%v*))" "start of
username"
"BEA_issuer_lookup"
".*" " "
"(&(objectClass=certificationAuthority)(cn=%v)(sn=%v))" "exact match on
sn, cn"
Parent topic: Configure Certificate Lookup
2.27.2 Configure Key Management
The location of the private key is the only configuration parameter that must be specified for key management interface.
2.27.2.1 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.
Parent topic: Configure Key Management
2.27.2.2 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.
Parent topic: Configure Key Management
2.27.3 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.Parent topic: Cert-C PKI Encryption Plug-In Configuration
2.27.4 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:
2.27.4.1 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 rootCA
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
.
Parent topic: Configure Certificate Validation
2.27.4.2 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.
Parent topic: Configure Certificate Validation
2.27.5 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 ofcertctux.dll
used in Windows. For example:Solaris:
HP-UX:libcertctux.so.71
libcertctux.sl
- change the file
URL
to UNIX format
Listing 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
Parent topic: Cert-C PKI Encryption Plug-In Configuration
2.27.6 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 supportsubjectAltName
extension.
Note:
Wildcards used in a name are not supported. Empty subject fields are not allowed. - The following
tpkey_getinfo()
attributes cannot retrieveENCRYPT_ALG
,ENCRYPT_BITS
,SIGNATURE_ALG
, orSIGNATURE_BITS
information using the Cert-C PKI encryption plug-in:-
TPKEY_SIGNATURE:
cannot retrieveENCRYPT_ALG
,ENCRYPT_BITS
-
TPKEY_ENCRYPT:
cannot retrieveSIGNATURE_BITS
-
TPKEY_AUTOSIGN:
cannot retrieveENCRYPT_ALG
,ENCRYPT_BITS
-
TPKEY_AUTOENCRYPT:
cannot retrieveSIGNATURE_BITS
Note:
TPKEY_DECRYPT:
can retrieveENCRYPT_ALG
,ENCRYPT_BITS
,SIGNATURE_ALG
, orSIGNATURE_BITS
informationTPKEY_AUTOSIGN|TPKEY_DECRYPT:
can retrieveENCRYPT_ALG
,ENCRYPT_BITS
,SIGNATURE_ALG
, orSIGNATURE_BITS
information -
See Also:
tpkey_open(3c)Parent topic: Cert-C PKI Encryption Plug-In Configuration