Configuring PAGENT for AT-TLS.

I covered the initial set up of PAGNET here.

What does TLS need?

When setting up TLS you need to make decisions, for example

Once you decide on the classification you need to decide which attributes are to be used for example

• Is TLS to be used or not?
• What levels of SSL and TLS will be supported?
• Which keyring is to be used on the z/OS end?
• Does the server need the client to authenticate and send its certificate?
• Should there be any constraints on the TLS parameters, such as Cipher Spec, key size etc?
• The preferred order of cipher specs to be used?
• Any GSK specific parameters?
• Should parameters be retrieved from LDAP?
• Should OCSP be used to validate a certificate?

You can configure PAGENT to map sessions to TLS definitions, by giving rules and configuration data.

You need to create rules to match between the users, and the TLS configuration they get.

You can create rules based on

• Input port numbers
• Input IP addresses
• Output port numbers
• Output IP addresses
• Jobnames (on z/OS)
• Userids (on z/OS)

The starting point for the configuration is a TTLSRULE entry for example.

Some simple rules and associated definitions

TTLSRule TLS1414
{
   LocalPortRange 1414
   TTLSGroupActionRef GrpActOn2
   TTLSEnvironmentActionRef        TNCP3-GrpEnvAct  
}
TTLSRule TLSGRPA
{
   LocalPortRangeRef  MYPORTS
   TTLSGroupActionRef GrpActOn2
   TTLSEnvironmentActionRef        TNCP3-GrpEnvAct  
}
TTLSGroupAction                   GrpActOn2             
{                                                       
  TTLSEnabled                     On
}                                                       
PortRange MYPORTS
{
  Port 2141 2151
}
TTLSGroupAction
{
  TLSKeyringParms...
  Handshake...such as ServerWithClientAuth
  TLSCipherParms...
  Trace...
}

This example shows

• You can have multiple rules – each with a unique name.
• You can specify information inline – for example LocalPortRange 1414
• You can point to a (shared) definition LocalPortRangeRef MYPORTS -> PortRange MYPORTS.
• Every TTLSRULe needs a group action, and is pointed to by a TTLSGroupActionRef statement
• A definition group has { } at the start of the line

If you use the pasearch -p TCPIP2 1>a unix command you get can display the configuration for the TCPIP instance, and get output like

policyRule:             TLS1414 
  Rule Type:            TTLS 
  Version:              3                 Status:            Active 
  Weight:               1                 ForLoadDist:       False 
  Priority:             1                 Sequence Actions:  Don't Care 
  No. Policy Action:    2 
  policyAction:         GA1 
   ActionType:          TTLS Group 
   Action Sequence:     0 
  policyAction:         TNCP3-GrpEnvAct 
   ActionType:          TTLS Environment 
   Action Sequence:     0 
  Time Periods: 
     ...
  TTLS Condition Summary:                 NegativeIndicator: Off 
   Local Address: 
    FromAddr:           All 
    ToAddr:             All 
   Remote Address: 
    FromAddr:           All 
    ToAddr:             All 
   LocalPortFrom:       1414              LocalPortTo:       1414 
   RemotePortFrom:      0                 RemotePortTo:      0 
   JobName:                               UserId: 
   ServiceDirection:    Inbound 
  Policy created: Tue May 24 11:01:04 2022 
  Policy updated: Tue May 24 11:01:04 2022
... 
                                                                                                           

Within this output is

TTLS Action:                  GA1 
  Version:                    3 
  Status:                     Active 
  Scope:                      Group 
   TTLSEnabled:                On 
   CtraceClearText:            Off 
   Trace:                      2 
   FIPS140:                    Off 
   TTLSGroupAdvancedParms: 
    SecondaryMap:              Off 
    SyslogFacility:            Daemon 
   Policy created: Tue May 24 11:01:04 2022 
   Policy updated: Tue May 24 11:01:04 2022 

TTLS Action:                  TNCP3-GrpEnvAct 
  Version:                    3 
  Status:                     Active 
  Scope:                      Environment 
    HandshakeRole:              Server 
    SuiteBProfile:              Off 
    TTLSKeyringParms: 
     Keyring:                   TNCP4.TTLS 
...

Where

• Scope: Group is for the TTLSGroupAction GA1 {} definition
• Scope: Environment is for the TTLSEnvironmentAction {} definition
• The keyring is INCP4.TTLS

Changing the configuration

If you change the configuration files you can use the F PAGNET,REFRESH to reprocess the configuration files. You can configure PAGNET to check to see if Unix files have been changed, and do an automatic refresh.

If you have a mistake with your definitions, then the new definitions are not activated. If you stop and restart PAGENT while the configuration has errors, then you will get no AT-TLS definitions!