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.
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.
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.
SEC_PRINCIPAL_NAME may be specified any of the following four levels in the configuration hierarchy:
•
|
RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
|
•
|
MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
|
•
|
GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
|
•
|
SERVERS section in UBBCONFIG or T_SERVER class in TM_MIB
|
•
|
All serv1 processes use john as a principal name.
|
*RESOURCES
SEC_PRINCIPAL_NAME "Tommy"
.
.
.
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.
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” on page 1‑48 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.
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.
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” on page 3‑7.) The WSH includes the user name as the principal name when calling the impersonate user function.
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.
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.
*SERVERS
WSL SRVGRP="group_name" SRVID=
server_number ...
CLOPT="-A -t
..."
•
|
“Setting Up Security in a Domains Configuration” and “Setting Up Connections in a Domains Configuration” in Using the Oracle Tuxedo Domains Component
|
When a domain gateway (GWTDOMAIN) attempts to establish a network link with another domain gateway, the following major events occur.
1.
|
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.
|
|
|
|
CONNECTION_PRINCIPAL_NAME in DMCONFIG ( TA_DMCONNPRINCIPALNAME 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.
|
|
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 will fail, and the system will generate the following userlog(3c) message: ERROR: Unable to initialize administration key for domain domain_name.
|
|
*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 demonstrates how a link is established between domains using default authentication plug-ins.
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.
*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"
|
|
|
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.
|
|
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 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.
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.
*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"
|
|
|
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 that 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.
|
•
|
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.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the SERVERS section:
|
In the preceding example, when tmboot(1) starts the ATMI application, it passes the
"-A -- -z min -Z max" command-line options to the WSL server. When establishing a network link between a Workstation client and the WSH, the Workstation client and WSL negotiate the key size until they agree on the largest key size supported by both.
See WSL(5),
WS_MIB(5), and
UBBCONFIG(5) in the
Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference for additional information.
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” on page 2‑35 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.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the NETWORK section:
|
LMID is the logical machine where the Bridge server resides; it has direct access to the network device specified in the
BRIDGE parameter.
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.
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.
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.
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.
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” on page 2‑35 for details.) Of course, domain-to-domain link-level encryption is possible only if LLE is installed on the machines where the domains reside.
2.
|
Open DMCONFIG with a text editor and add the following lines to the DM_TDOMAIN section:
|
*DM_TDOMAIN
# Local network addresses
LDOM NWADDR="
local_domain_network_address"
NWDEVICE="
local_domain_device"
MINENCRYPTBITS=
min
MAXENCRYPTBITS=
max
.
.
.
# Remote network addresses
RDOM NWADDR="
remote_domain_network_address"
NWDEVICE="
remote_domain_device"
MINENCRYPTBITS=
min
MAXENCRYPTBITS=
max
.
.
.
# TDomain network addresses
RDOM NWADDR="
remote_domain_network_address"
NWDEVICE="
remote_domain_device"
CONNECTION_POLICY=ON_START
LACCESSPOINT="
local_domain_access_point_identifier"
FAILOVERSEQ=100
MINENCRYPTBITS=
min
MAXENCRYPTBITS=
max
LDOM is replaced with a local domain access point identifier, and
RDOM is replaced with a remote domain access point identifier.
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.
•
|
For max: Number of bits that indicates the highest level of encryption possible for the installed SSL version
|
2.
|
SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR parameters must be specified. This may be done in the *RESOURCES, *MACHINES, *GROUPS, or *SERVERS sections.
|
3.
|
Open UBBCONFIG with a text editor and add the following lines to the SERVERS 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>] ..."
The WSC must set the SEC_PRINCIPAL_LOCATION,
SEC_PRINCIPAL_NAME and/or
SEC_PRINCIPAL_PASSWORD enviornment variables as appropriate.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and NETWORK sections:
|
SEC_PRINCIPAL_NAME,
SEC_PRINCIPAL_LOCATION, and
SEC_PRINCIPAL_PASSVAR must be specifed 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 the
BRIDGE parameter.
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.
|
2.
|
Open DMCONFIG with a text editor and add the following lines to the DM_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.
3.
|
SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSWORD must be specified in the UBBCONFIG file.
|
Figure 2‑13 illustrates the configuration of a Tuxedo application that uses the SSL protocol.
•
|
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
|
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.
An example of an openssl command that can be used to create an Oracle Wallet is as follows:
•
|
-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.
|
•
|
-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.
|
•
|
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.
|
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 the SEC_PRINCIPAL_PASSVAR configuration file environment variable (or the workstation client SEC_PRINCIPAL_PASSWORD environment variable) will be used to decrypt the 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 will be created at
/home/tuxedo/myapp/wallet.ISH_tuxqa.pem/ewallet.p12.
For example, if you define SEC_PRINCIPAL_LOCATION="/home/tuxedo/myapp" and
SEC_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.
•
|
TUXCREATEWALLET=KEEP or TUXCREATEWALLET=YES or TUXCREATEWALLET 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. If ULOG_SSLINFO=y is set then the following message will be logged:
|
•
|
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:
|
•
|
TUXCREATEWALLET=NO or TUXCREATEWALLET=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 or
NO may be in the local language as is true for many other
Yes/No environment variables in Tuxedo.
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.
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 will include the name of the negotiated cipher.
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.
|
|
|
SIGNATURE_AHEAD in UBBCONFIG ( TA_SIGNATURE_AHEAD in TM_MIB)
|
|
|
SIGNATURE_BEHIND in UBBCONFIG ( TA_SIGNATURE_BEHIND in TM_MIB)
|
|
|
SIGNATURE_REQUIRED in UBBCONFIG ( TA_SIGNATURE_REQUIRED in TM_MIB)
|
|
Y (yes—digital signature is required) or N (no—digital signature is not required). Default is N.
|
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).
*RESOURCES
SIGNATURE_AHEAD 2400
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).
*RESOURCES
SIGNATURE_BEHIND 300000
SIGNATURE_REQUIRED may be specified any of the following four levels in the configuration hierarchy:
•
|
RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
|
•
|
MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
|
•
|
GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
|
•
|
SERVICES section in UBBCONFIG or T_SERVICE class in TM_MIB
|
Setting SIGNATURE_REQUIRED to
Y (yes) at a particular level means that signatures are required for all processes running at that level or below. For example, setting
SIGNATURE_REQUIRED to
Y for a machine named
mach1 means that all processes running on
mach1 will accept only incoming messages that are digitally signed.
•
|
Set at the domain-wide level (RESOURCES section or T_DOMAIN class), this parameter covers all application services advertised within the domain, including those advertised by gateway processes. The default is N.
|
•
|
Set at the machine level (MACHINES section or T_MACHINE class), this parameter covers all application services advertised on a particular machine, including those advertised by gateway processes. The default is N.
|
•
|
Set at the group level (GROUPS section or T_GROUP class), this parameter covers all application services advertised by a particular group, including those advertised by gateway processes. The default is N.
|
•
|
Set at the service level (SERVICES section T_SERVICE class), this parameter covers all instances of a particular service advertised within the domain, including those advertised by gateway processes. The default is N.
|
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.
To configure SIGNATURE_REQUIRED for a machine named
mach1, follow these steps.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the MACHINES section:
|
*MACHINES
mach1 LMID="machine_logical_name"
TUXCONFIG="
absolute_path_name_to_tuxconfig_file"
TUXDIR="
absolute_path_name_to_BEA_Tuxedo_directory"
APPDIR="
absolute_path_name_to_application_directory"
SIGNATURE_REQUIRED=Y
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:
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.
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” on page 3‑53. 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.
|
|
|
ENCRYPTION_REQUIRED in UBBCONFIG ( TA_ENCRYPTION_REQUIRED in TM_MIB)
|
|
Y (yes—encryption is required) or N (no—encryption is not required). Default is N.
|
ENCRYPTION_REQUIRED may be specified at any of the following four levels in the configuration hierarchy:
•
|
RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
|
•
|
MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
|
•
|
GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
|
•
|
SERVICES section in UBBCONFIG or T_SERVICE class in TM_MIB
|
Setting ENCRYPTION_REQUIRED to
Y (yes) at a particular level means that encryption is required for all processes running at that level or below. For example, setting
ENCRYPTION_REQUIRED to
Y for a machine named
mach1 means that all processes running on
mach1 will accept only incoming messages that are encrypted.
•
|
Set at the domain-wide level (RESOURCES section or T_DOMAIN class), this parameter covers all application services advertised within the domain, including those advertised by gateway processes. The default is N.
|
•
|
Set at the machine level (MACHINES section or T_MACHINE class), this parameter covers all application services advertised on a particular machine, including those advertised by gateway processes. The default is N.
|
•
|
Set at the group level (GROUPS section or T_GROUP class), this parameter covers all application services advertised by a particular group, including those advertised by gateway processes. The default is N.
|
•
|
Set at the service level (SERVICES section T_SERVICE class), this parameter covers all instances of a particular service advertised within the domain, including those advertised by gateway processes. The default is N.
|
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.
To configure ENCRYPTION_REQUIRED for a server group named
STDGRP, follow these steps.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the GROUPS section:
|
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:
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.
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.
•
|
RESOURCES section in UBBCONFIG or T_DOMAIN class in TM_MIB
|
•
|
MACHINES section in UBBCONFIG or T_MACHINE class in TM_MIB
|
•
|
GROUPS section in UBBCONFIG or T_GROUP class in TM_MIB
|
•
|
SERVERS section in UBBCONFIG or T_SERVER class in TM_MIB
|
•
|
All processes on mach1 except serv1 processes use the decryption key assigned to mach1 to decrypt any received message buffer that is encrypted.
|
•
|
All serv1 processes use the decryption key assigned to serv1 to decrypt any received message buffer that is encrypted.
|
1.
|
The administrator defines SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR at a particular level in the ATMI application’s UBBCONFIG file.
|
5.
|
During the boot process, the map_proof plug-in reads SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR, analyzes their values, and then determines whether the calling process has proven its right to access the requested decryption key. (Having access to a decryption key, or private key, is equivalent to possessing the principal’s identity.)
|
6.
|
If the password associated with SEC_PRINCIPAL_PASSVAR matches the assigned password for the principal specified in SEC_PRINCIPAL_NAME, the map_proof plug-in passes the name, location, and password of the principal to the PKi_init plug-in.
|
7.
|
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:
*RESOURCES
SEC_PRINCIPAL_NAME "Tommy"
SEC_PRINCIPAL_LOCATION "/home/jhn/secsapp/cert/tommy.pvk"
SEC_PRINCIPAL_PASSVAR "TOMMY_VAR"
.
.
.
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.
In your UBBCONFIG file, set the
SECURITY parameter to the appropriate value:
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.
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).
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:
*SERVERS
AUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"
*SERVERS
AUTHSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"
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.
*SERVERS
KERBEROSSVR SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2 CLOPT="-A"
•
|
AUTHSVR(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference
|
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.
2.
|
Set the SECURITY parameter in the RESOURCES section of the UBBCONFIG file to APP_PW.
|
Default authentication offers a user-level authentication security level that you invoke by specifying
SECURITY USER_AUTH in your configuration file. This security level requires that in addition to the application password, each client must provide a valid username and user-specific data, such as a password, to join the ATMI application. The per-user password must match the password associated with the combination user-client name stored in a file named
tpusr. The checking of per-user password against the password and user-client name in
tpusr is carried out by the authentication service
AUTHSVC, which is provided by the authentication server
AUTHSVR.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and SERVERS sections:
|
CLOPT="-A" causes
tmboot(1) to pass only the default command-line options (invoked by
"-A") to
AUTHSVR when
tmboot starts the ATMI application. By default,
AUTHSVR uses the client user information in a file named
tpusr to authenticate clients that want to join the ATMI application.
tpusr resides in the directory referenced by the first pathname defined in the ATMI application’s
APPDIR variable.
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.
AUTHSVR and the access control checking feature also require a group file named
tpgrp, which contains a list of groups associated with the client users allowed to join the ATMI application;
tpgrp is maintained by the application administrator using the
tpgrpadd(1),
tpgrpdel(1), and
tpgrpmod(1) commands.
AUTHSVC assigns an authenticated client user an
application key, which contains a user identifier and associated group identifier for the
USER_AUTH,
ACL, or
MANDATORY_ACL security level. (See
“Application Key” on page 1‑48 for more information about application keys.)
2.
|
To convert the /etc/password file into the format needed by the Oracle Tuxedo system, enter the following command.
|
This command creates the tpusr file and stores the converted data in it. If the
tpusr file already exists,
tpaclcvt adds the converted data to the file, but it does
not add duplicate user information to the file.
3.
|
To convert the /etc/group file into the format needed by the Oracle Tuxedo system, enter the following command.
|
This command creates the tpgrp file and stores the converted data in it. If the
tpgrp file already exists,
tpaclcvt adds the converted data to the file, but it does
not add duplicate group information to the file.
•
|
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.
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.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and SERVERS sections:
|
CLOPT="-A" causes
tmboot(1) to pass only the default command-line options (invoked by
"-A") to
AUTHSVR when
tmboot starts the ATMI application. By default,
AUTHSVR uses the client user information in a file named
tpusr to authenticate clients that want to join the ATMI application.
tpusr resides in the directory referenced by the first pathname defined in the ATMI application’s
APPDIR variable.
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.
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.
2.
|
Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and SERVERS sections:
|
CLOPT="-A" causes
tmboot(1) to pass only the default command-line options (invoked by
"-A") to
AUTHSVR when
tmboot starts the ATMI application. By default,
AUTHSVR uses the client user information in a file named
tpusr to authenticate clients that want to join the ATMI application.
tpusr resides in the directory referenced by the first pathname defined in the ATMI application’s
APPDIR variable.
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.
1.
|
Open UBBCONFIG with a text editor.
|
2.
|
In the RESOURCES section, do the following:
|
a.
|
Set the SECURITY parameter to one of these values: USER_AUTH, ACL or MANDATORY_ACL.
|
b.
|
Set the OPTIONS parameter to EXT_AA.
|
•
|
If the SECURITY parameter is set to ACL or MANDATORY_ACLAUTHSVC, set AUTHSVC to ..AUTHSVC, which is the service name advertised by the XAUTHSVR server.
|
•
|
If the SECURITY parameter is set to USER_AUTH, set AUTHSVC to AUTHSVC, which is the service name advertised by the XAUTHSVR server.
|
3.
|
Set up XAUTHSVR in the SERVERS section.
|
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.
Table 2‑3 defines the
XAUTHSVR configuration file keywords.
•
|
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 Table 2‑4. 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.
|
Table 2‑4 defines the
orcljaznpermission class attributes.
•
|
Run tux.env to set up libjvm.so in your library path.
|
•
|
Set oes-client.jar in CLASSPATH.
|
Configure EXT_AA in
OPTIONS and
..AUTHSVC in
UBBCONFIG RESOURCES to authenticate service you use.
Notes:
|
On a Windows platform, the plug-in KRB5_CONFIG and KRB5_KDC parameters are not required. These parameters are used on a UNIX platform to locate the Kerberos-related configuration files. KAUTHSVRPRINC specifies the principal name for the KAUTHSVR server and Tuxedo clients use it as the server principal name.
|
Note:
|
In Listing 2‑4, libtux.so is used as an example. You must use the file name libtux plus your platform specific dynamic library extension.
|
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.
Notes:
|
The -k option allows you to provide the KAUTHSVR Kerberos key table file location.
|
The -p option indicates
KAUTHSVR principal name.
KAUTHSVR running on UNIX platforms must use the GSS format.
Notes:
|
The -p option indicates KAUTHSVR principal name.
|
•
|
SEC_PRINCIPAL_NAME represents KAUTHSVR, it does not represent the server principal name (which is represented by the -p option).
|
•
|
SEC_PRINCIPAL_PASSVAR is the internal password variable. It is not the true password that is required when tmloadcf creates the TUXCONFIG file. The tmloadcf password input must be same as the KAUTHSVR account password in a Windows domain.
|
KAUTHSVR running on Windows platform must use the
complete Kerberos realm name.
•
|
<suffix> is the proper suffix for the shared library ( for example, libplugin.dll for Windows, and libplugin.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')
|
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.
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:
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:
•
|
use the file name libcertctux plus your platform specific dynamic library extension instead of certctux.dll used in Windows. For example: Solaris: libcertctux.so.71
HP-UX: libcertctux.sl
|
•
|
The "cn" attribute of distinguished name is used as key for certificate lookup, so the DN must contains the "cn=" attribute.
|
•
|
The other is the subjectAltName extension. This plug-in does not support subjectAltName extension.
|
•
|
The following tpkey_getinfo() attributes cannot retrieve ENCRYPT_ALG, ENCRYPT_BITS, SIGNATURE_ALG, or SIGNATURE_BITS information using the Cert-C PKI encryption plug-in:
|
Note:
|
TPKEY_DECRYPT: can retrieve ENCRYPT_ALG, ENCRYPT_BITS, SIGNATURE_ALG, or SIGNATURE_BITS information TPKEY_AUTOSIGN|TPKEY_DECRYPT: can retrieve ENCRYPT_ALG, ENCRYPT_BITS, SIGNATURE_ALG, or SIGNATURE_BITS information
|