Step 2: Configure Policy Agent as a policy server

Define the port for clients to connect, and policy client matching statements to select the configuration files to be used for clients. Create user IDs on the server to match the user IDs of clients, and set up security.

Procedure

If you want to use the Policy Agent as a policy server, perform these steps:

Define the port to which policy clients will connect. If policy clients are to be used, the ClientConnection statement in the main configuration file provides the port that Policy Agent listens on for remote connections. You can use the default port (16310), but you must specify the ClientConnection statement to use Policy Agent as a policy server.
Guideline: Reserve the port specified on the ClientConnection statement using the PORT statement in the TCP/IP profile.

Restriction: The port value cannot match the port value that is configured on the ServicesConnection statement.

Define a set of policy client matching statements that select the configuration files to be used for policy clients. When a policy client connects to the policy server, the DynamicConfigPolicyLoad statements in the main configuration file are evaluated to determine whether there is a match. The names are case sensitive with regard to matching. When a matching statement is found, the parameters identify both common and image-specific configuration files to be used for the policy client. If no matching statement is found, a default image-specific file is used. A matching statement (or default values) is bound to a policy client for the life of that client, until one of the following events occur:

The policy client disconnects from the policy server.
The connection between the policy server and policy client ends.
The associated DynamicConfigPolicyLoad statement is removed. In this case, the policy client is bound to a different DynamicConfigPolicyLoad statement (or to default values).

You can use a regular expression for the policy client name on the DynamicConfigPolicyLoad statement to cause the statement to match multiple policy clients. For a description of supported regular expressions on the DynamicConfigPolicyLoad statement, see z/OS Communications Server: IP Configuration Reference.

For example, the expression (.+)_(.+) matches any client name composed of one or more characters, followed by an underscore, followed by one or more characters. The default client names configured on the PolicyServer statement on the policy client would match this expression.

You can use two different methods to substitute all or part of the client name in parts of the image-specific file name.

A single wildcard character (*) is replaced with the entire client name.
If you use a regular expression as the DynamicConfigPolicyLoad statement client name, you can use the symbolic replacement values $0 through $9 in the image-specific file name. The value $0 represents the entire portion of the client name that matched, while the values $1 through $9 represent portions of the client name that match corresponding parenthesized sub-expressions in the regular expression. Using the regular expression (.+)_(.+) as an example, and a policy client name of SYS123_TCPIP2, the values of the possible replacement variables are as follows:
- The value * is replaced with SYS123_TCPIP2
- The value $0 is replaced with SYS123_TCPIP2
- The value $1 is replaced with SYS123
- The value $2 is replaced with TCPIP2
In this example, the value $0 is the same as the value *, but this does not hold true for all regular expressions. If you want to use the entire client name as a replacement value, specify the value *.

The matching hierarchy used is as follows:

Exact match between the policy client name and the DynamicConfigPolicyLoad statement.
Regular expression match between the policy client name and the DynamicConfigPolicyLoad statement. The longest matching regular expression is chosen. If multiple statements match with the same length clientname parameter, the statement chosen is based on alphabetical order.
No matching statement. A default file is used based on the policy type, as follows:
Policy type

Default file

AT-TLS

/etc/pagent_remote.ttls

IDS

/etc/pagent_remote.ids

IPSec

/etc/pagent_remote.ipsec

QoS

/etc/pagent_remote.qos

Routing

/etc/pagent_remote.routing

The following example shows the DynamicConfigPolicyLoad statement matching by using a regular expression to simulate a simple wildcard, and the resulting configuration files that are used, using IPSec policies.

DynamicConfigPolicyLoad  Rem.*
{
  PolicyType             IPSec
  {
    CommonPolicyLoad     //'ETC.COMMON.IPSEC'
    PolicyLoad           //'ETC.IPSEC(*)'
  }
}

DynamicConfigPolicyLoad  Remote.*
{
  PolicyType             IPSec
  {
    PolicyLoad           /etc/*.ipsec
  }
}

DynamicConfigPolicyLoad  Remote5
{
  PolicyType             IPSec
  {
    CommonPolicyLoad     /user10/common_remote.ipsec
    PolicyLoad           /user10/pagent_remote5.ipsec
  }
}

The resulting configuration files used for a variety of policy clients are shown in Table 1:

Table 1. Configuration files used for various policy clients
Policy client name	Matching statement	Common IPSec configuration file	Image IPSec configuration file
Remote1	Remote.*	None	/etc/Remote1.ipsec
Remote5	Remote5	/user10/common_remote.ipsec	/user10/pagent_remote5.ipsec
Rem42	Rem.*	//'ETC.COMMON.IPSEC'	//'ETC.IPSEC(REM42)'
remote5	Not applicable	None	/etc/pagent_remote.ipsec

The following example shows the DynamicConfigPolicyLoad statement matching by using a more complex regular expression, and the resulting configuration files that are used, using IDS policies. The regular expression matches two strings separated by an underscore character. Each string must begin with an uppercase alphabetic character and end with a numeric character.

DynamicConfigPolicyLoad  ^([A-Z].+[0-9]+)_([A-Z].+[0-9]+)$
{
  PolicyType             IDS
  {
    CommonPolicyLoad     //'ETC.COMMON.IDS'
    PolicyLoad           //'ETC.$1($2)'
  }
}

The resulting configuration files used for a variety of policy clients are shown in Table 2:

Table 2. Configuration files used for various policy clients
Policy client name	Matching statement	Common IDS configuration file	Image IDS configuration file
SYS42_TCPIP2	^([A-Z].+[0-9]+)_([A-Z].+[0-9]+)$	//'ETC.COMMON.IDS'	//'ETC.SYS42(TCPIP2)'
Remote1_Image5	^([A-Z].+[0-9]+)_([A-Z].+[0-9]+)$	//'ETC.COMMON.IDS'	//'ETC.REMOTE1(IMAGE5)'
SYS123_TCPIP	Not applicable	None	/etc/pagent_remote.ids

Rule: The policy client names and DynamicConfigPolicyLoad statement names are case sensitive, but MVS™ data set names are not. Therefore, be careful when defining MVS data set configuration files that include a wildcard that is to be substituted with the policy client name. For example, the policy client names client42 and Client42, if used as a substitution variable in an MVS data set name, would result in the same configuration file being used for both policy clients.

Configure one or more user IDs on the policy server system to match the user IDs of the policy clients. Each policy client uses a unique client name, but also must present valid credentials to the policy server. Valid credentials include a user ID and password or a user ID and PassTicket (if secure signon is enabled).
Rule: The password defined for the user ID must match the password configured using the AuthBy Password parameter on the PolicyServer statement on the policy client.

A SAF user ID representing a policy client must be defined to the security product. The user ID must be defined with an OMVS segment. When RACF® is used as the security product, define the SAF user ID with the following command:
```
ADDUSER client PASSWORD(password) DFLTGRP(OMVSGRP) OMVS(UID(x) HOME('/home/client'))
```
Each policy client does not need to use a unique user ID, although that is a configuration option. The user ID is used for two purposes on the policy server:
- User authentication when the policy client connects to the policy server
- Access to SERVAUTH profiles to determine which policies the client can access
Permit Policy Agent to the BPX.DAEMON FACILITY class profile. For information about the use of the BPX.DAEMON profile, see BPX.DAEMON FACILITY class profile. If you decide to use this profile, permit the Policy Agent user ID to it. When RACF is used as the security product, permit the user ID with the following command:
```
PERMIT BPX.DAEMON CLASS(FACILITY) ID(userid) ACCESS(READ)
```
If you want to use PassTicket security for policy clients, configure PTKTDATA class profiles. Policy clients can be configured to use either a password or a PassTicket on the PolicyServer statement, used when they connect to the policy server. For information about the secured signon function and PassTickets, see z/OS Security Server RACF Security Administrator's Guide. If you choose to use PassTickets, define the appropriate profiles in the PTKTDATA class to contain the application key used to generate and validate the PassTicket. When RACF is used as the security product, define the profiles with the following command:
```
RDEFINE PTKTDATA profile SSIGNON(KEYMASKED(key)) UACC(UPDATE)
```
The application name used by Policy Agent is PAGENT, so you need to define a profile with this name. The application key defined in the profiles must be the same on the policy client and policy server.

If you want to use secure connections between policy clients and the policy server, configure AT-TLS rules on the policy server to enable SSL connections from the policy clients. If policy clients use SSL connections, you must define AT-TLS rules on the policy server for communications between the policy client and server to be secured using AT-TLS. AT-TLS processing for a stack is enabled by specifying the TTLS parameter on the TCPCONFIG statement in the TCP/IP profile. Specific AT-TLS policy is configured in Policy Agent configuration files. For details about enabling AT-TLS and configuring AT-TLS policy, see Application Transparent Transport Layer Security data protection.

Rules:

Define AT-TLS policy such that only cipher suites requiring TLS encryption are exchanged with policy clients. Failure to restrict the cipher suites to those requiring encryption might result in sensitive information flowing in the clear across an untrusted network.
Define AT-TLS policy for each stack through which policy server and policy client communication can flow.
If some policy clients use SSL and others do not use SSL, define AT-TLS policy to select only those policy clients that use SSL.

Result: If you choose not to use SSL for your policy client to policy server connections, sensitive information flows in the clear on the connections. Sensitive information includes, but is not limited to, the following information:

The password that is sent from the policy client to the policy server for authentication (if you are using password credentials)
Policy information that is sent from the policy server to the policy client, such as:
- Passwords
- Certificate labels
- IPSec keys for IKE tunnels that use pre-shared keys
- IPSec keys for manual tunnels

Requirement: The policy server acts as the server during an SSL handshake. To act in the server role of an SSL handshake, the policy server must have access to a private key and certificate verifying its ownership of that private key. For information about creating and managing keys and certificates for servers that use AT-TLS, see TLS/SSL security.

An example of the AT-TLS policy statements used to enable AT-TLS for the policy server is as follows:

TTLSRule                     PolicyServerRule                                    
{                                                                             
   LocalPortRange                     16310
   JobName                            PAGENT                              
   Direction                          Inbound                             
   TTLSGroupActionRef                 PolicyServerGroup                            
   TTLSEnvironmentActionRef           PolicyServerConn                
}  
          
TTLSGroupAction                       PolicyServerGroup                                         
{                                                                             
   TTLSEnabled                        On                                  
}   
                                                                          
TTLSEnvironmentAction                 PolicyServerConn                             
{                                                                             
   TTLSKeyRingParms                                                       
   {                                                                    
      Keyring                         PAGENT/keyring 
   }                                                                    
   TTLSCipherParmsRef                 RequireEncryption
   HandshakeRole                      SERVER                                                              
}                             

TTLSCipherParms                   RequireEncryption
{
   V3CipherSuites              TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA  
   V3CipherSuites              TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA  
   V3CipherSuites              TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA  
   V3CipherSuites              TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA  
   V3CipherSuites              TLS_RSA_WITH_3DES_EDE_CBC_SHA  
   V3CipherSuites              TLS_DHE_RSA_WITH_AES_256_CBC_SHA 
   V3CipherSuites              TLS_DHE_DSS_WITH_AES_256_CBC_SHA  
   V3CipherSuites              TLS_DH_RSA_WITH_AES_256_CBC_SHA  
   V3CipherSuites              TLS_DH_DSS_WITH_AES_256_CBC_SHA  
   V3CipherSuites              TLS_RSA_WITH_AES_256_CBC_SHA  
   V3CipherSuites              TLS_DHE_RSA_WITH_AES_128_CBC_SHA  
   V3CipherSuites              TLS_DHE_DSS_WITH_AES_128_CBC_SHA  
   V3CipherSuites              TLS_DH_RSA_WITH_AES_128_CBC_SHA 
   V3CipherSuites              TLS_DH_DSS_WITH_AES_128_CBC_SHA  
   V3CipherSuites              TLS_RSA_WITH_AES_128_CBC_SHA  
   V3CipherSuites              TLS_DHE_RSA_WITH_DES_CBC_SHA  
   V3CipherSuites              TLS_DHE_DSS_WITH_DES_CBC_SHA  
   V3CipherSuites              TLS_DH_RSA_WITH_DES_CBC_SHA  
   V3CipherSuites              TLS_DH_DSS_WITH_DES_CBC_SHA  
   V3CipherSuites              TLS_RSA_WITH_DES_CBC_SHA
   V3CipherSuites              TLS_RSA_WITH_RC4_128_SHA  
   V3CipherSuites              TLS_RSA_WITH_RC4_128_MD5  
   V3CipherSuites              TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5  
   V3CipherSuites              TLS_RSA_EXPORT_WITH_RC4_40_MD5  
}

Rule: The LocalPortRange value on the TTLSRule statement must include the value specified on the ClientConnection statement in the policy server main configuration file.

If you use secure connections between any policy clients and the policy server, permit Policy Agent to the EZB.INITSTACK.sysname.tcpname SERVAUTH class profile. Because AT-TLS policies are used to enable SSL connections from policy clients, Policy Agent must be permitted to the EZB.INITSTACK.sysname.tcpname SERVAUTH class profile if any policy clients use SSL. For more details, see TCP/IP stack initialization access control. When RACF is used as the security product, permit Policy Agent to the profile with the following command:
```
PERMIT EZB.INITSTACK.sysname.tcpname CLASS(SERVAUTH) ID(userid) ACCESS(READ)
```