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.

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.

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.

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.

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.

• Recommended Practices for OS Security
  

Figure 2-3 Acquiring Credentials and Tokens During Application Booting

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

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.

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" 

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

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

• How the WSH Establishes an Identity for an Older Client
  
• How the Domain Gateway Establishes an Identity for an Older Client
  
• How the Server Establishes an Identity for an Older Client
  

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.

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 ... "

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"

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:

1. 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.
2. Uses these tokens to overwrite the tokens already attached to the client request.
3. Forwards the request to the destination server.

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

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"

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.

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.

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

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

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

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

In the preceding example, when 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.

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:

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

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

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

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

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

See TM_MIB(5) and UBBCONFIG(5) in the 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.

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.

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:

1. Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
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

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

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

See DMCONFIG(5) in 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.

Before you can configure TLS for your ATMI application, you need to be familiar with the TLS 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 TLS 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.

To configure TLS on Workstation client links, follow these steps:

1. Ensure that you are working on the ATMI application MASTER machine and that the application is inactive.
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.

   Note:

   In general, it is recommended to specify these parameters at the highest level possible to avoid duplicating information in the UBBCONFIG and to avoid multiple password prompts if running tmloadcf interactively.
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>] ..."

   If the secure port is set to the same port used in the network address then the WSL will accept only TLS connections; if different ports are used, the same WSL can accept both non-TLS and TLS connections.

   The WSC must set the SEC_PRINCIPAL_LOCATION, SEC_PRINCIPAL_NAME and/or SEC_PRINCIPAL_PASSWORD environment variables as appropriate.

   All workstation clients using TLS 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. The SEC_PRINCIPAL_LOCATION and SEC_PRINCIPAL_NAME environment variables are used to locate the wallet as described in Runtime Creation of an Oracle Wallet. The SEC_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 TLS 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 password TrustedCertsOnlyNoPWNeeded is used to create the wallet. Such a wallet can be subsequently accessed without setting the SEC_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, and SEC_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.

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

To configure TLS on Bridge links, follow these steps:

1. Ensure that you are working on the ATMI application MASTER machine and that the application is inactive.
2. Open UBBCONFIG with a text editor and add the following lines to the RESOURCES and NETWORK 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, and SEC_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 the BRIDGE parameter.

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

To configure TLS 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>]

The -c, -n, and -p options specify TLS 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.

To configure TLS on domain gateway links, follow these steps:

1. Ensure that you are working on the ATMI application MASTER machine and that the ATMI application is inactive.
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.
4. Load the configuration by running dmloadcf(1) . The dmloadcf command parses DMCONFIG and loads the binary BDMCONFIG file to the location referenced by the BDMCONFIG variable.

Using the TLS 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 TLS protocol and configure the servers and clients in your application to use TLS.

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.

If you use the TLS 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 TLS protocol.

Figure 2-13 Configuration for Using the TLS Protocol in a Tuxedo Application

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.

• Creating an Oracle Wallet with orapki
  
• Creating an Oracle Wallet with openssl
  

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 TLS 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 TLS 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.
• 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 TLS 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 TLS connection.
• The trusted certificates for the process are contained in the file specified as the caCertificateFile parameter of the plugin framework certificate_validation interface. The default caCertificateFile is $TUXDIR/udataobj/security/certs/trust_ca.cer. Trusted certificates need to exist for TLS servers and TLS 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.

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 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:

  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 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.

• Enabling NZ Tracing
  
• Connection Establishment Log Message
  
• Displaying the Contents of an Oracle Wallet
  
• Obtaining NZ Error Code Information
  

• 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.

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.

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

• Setting a Postdated Limit for Signature Timestamps
  
• 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
  

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

• Enforcing the Encryption Policy for Incoming Messages
  
• How the EventBroker Encryption Policy Is Enforced
  
• How the /Q Encryption Policy Is Enforced
  
• How the Remote Client Encryption Policy Is Enforced
  

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

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

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

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

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

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

Figure 2-14 How a Decryption Key Is Initialized Example

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

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.
2. The administrator loads the configuration by running tmloadcf(1). The tmloadcf command parses UBBCONFIG and loads the binary TUXCONFIG file to the location referenced by the TUXCONFIG variable.
3. When prompted, the administrator enters and then re-enters the password for the target principal.
4. The administrator enters the tmboot(1) command to boot the ATMI application.
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:

tmloadcf -y ubbconfig_name < /dev/null

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

• Example UBBCONFIG Entries for Principal Names and Decryption Keys
  

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

• Digital Signature Error Handling
  
• Encryption Error Handling
  

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
  

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"

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

   *RESOURCES SECURITY
            USER_AUTH AUTHSVC    AUTHSVC
            .      .
            . *SERVERS AUTHSVR
            SRVGRP="group_name" SRVID=1 RESTART=Y GRACE=600 MAXGEN=2
            CLOPT="-A"

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

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

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

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

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
  

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:

1. Set up the UBBCONFIG file.
2. Set up the ACL file.

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

• Setting Up the UBBCONFIG File
  
• Setting Up the ACL File
  

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:

1. Set up the UBBCONFIG file.
2. Set up the ACL file.

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

• Setting Up the UBBCONFIG File
  
• Setting Up the ACL File
  

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:

1. Setting Up the UBBCONFIG File
2. Setting Up the XAUTHSVR Server Configuration File
3. Setting Up the LDAP Repository
4. 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
  

1. Install OES server and client (security module).

   Note:

   Oracle Entitlement Server (OES) client 11.1.2.0 is certified for use.
2. Configure OES java client to connect OES server.
3. 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.
4. 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.
5. Configure EAUTHSVR server:
   • Run tux.env to set up libjvm.so in your library path.
   • Set oes-client.jar in CLASSPATH.
6. 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.

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

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.

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

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.

• Restore Default Plug-in
  

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"

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"

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 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.

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.

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

  Note:

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

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

ldapUserCertificate

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

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

ldapBaseObject

LDAP server configuration parameter that identifies the base DN where the LDAP search should start. For example: ldapBaseObject="ou=Engineer Test,o=ABC Company,c=US"

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

ldapFilterAttribute

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

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

ldapBaseDNAttribute

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

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

• OpenLDAP for X.509 Certificate Lookup
  

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

• decPassword
  
• privateKeyDir
  

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

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

• caCertificateFile
  
• crlFile
  

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

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

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

  Note:

  Wildcards used in a name are not supported. Empty subject fields are not allowed.
• The following tpkey_getinfo() attributes cannot retrieve ENCRYPT_ALG, ENCRYPT_BITS, SIGNATURE_ALG, or SIGNATURE_BITS information using the Cert-C PKI encryption plug-in:
  • TPKEY_SIGNATURE: cannot retrieve ENCRYPT_ALG, ENCRYPT_BITS
  • TPKEY_ENCRYPT: cannot retrieve SIGNATURE_BITS
  • TPKEY_AUTOSIGN: cannot retrieve ENCRYPT_ALG, ENCRYPT_BITS
  • TPKEY_AUTOENCRYPT: cannot retrieve SIGNATURE_BITS

  Note:

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