FastSSR is a high-speed, secure file transfer system for IBM mainframes. It can run standalone or as an enhancement to SSR Server. SSR Server for TSO & VTAM (ASISSR) is a fully supported program product from Applied Software, Inc. which functions as an enhanced replacement for IBM’s IND$FILE program. While adding many features, it is still based on 3270 packet transmissions to transfer data between a Windows client and the LPAR (an Endpoint).

FastSSR z/OS implements all the features of ASISSR but re-engineers the data transfer mechanism to use direct TCPIP protocols and TLS encryption. In most instances, this improves transfer speeds up to 900 times faster than emulator-based transfers.

FastSSR for z/OS runs as a multi-tasking job on each z/OS LPAR (Endpoint) where data access is required. The job executes a load module called FSSRMAIN. It is comprised of mix of z/OS programs written in COBOL, C, and High-Level Assembler (HLASM). The decisions on programming languages were primarily made to support the underlying technologies required for FastSSR and where the internet offered more examples of that technology. In particular:

• FastSSR transfers occur under the context of the credentials supplied on the transfer. The SAF authorization calls, and JES integration features, require the FastSSR load library be APF authorized and placed into the Link Pack Area (LPA) during IPL or console command.
• The z/OS Client Web Enablement Toolkit (HWTH), needed for web services, requires the z/OS Language Environment (LE).
• This led to using COBOL for the programs implementing the HWTH APIs.
• Since COBOL does not have support for attaching subtasks, FSSRMAIN calls a C program to create subtasks using pthread_create.
• By creating the subtask using C (and thus, LE), the subtask HLASM programs, that do all the transfer processing, have runtime LE support to call a COBOL program which issues HWTH APIs to send transfer status to the database server.

The programming decisions described above require specific z/OS components are installed and at certain levels. These components come standard as part of a typical z/OS installation.

Component	Version	Notes
Enterprise COBOL	6.3	Requires z/OS 2.2 or later.
z/OS XL C	2.4	Version matches z/OS release.
Language Environment	2.4	Version matches z/OS release.
Web Enablement Toolkit	N/A	Requires z/OS 2.2 or later. With AT-TLS support, z/OS 2.3 or later.
AT-TLS	N/A	Requires setup if TLS support is required.

The image below diagrams the main program processing with the FSSRMAIN load module. Its basic functionality is to act as a data transfer server that creates a new subtask for each transfer request. Of special note, SVC Call 40 – SAF Authorization, is newly created to switch the authorization context of a subtask to that of the FastSSR PC user when accessing Endpoint data. This prohibits users from transferring data they are not authorized to access

The z/OS client web enablement toolkit (HWTH) provides a set of lightweight application programming interfaces (APIs) to enable traditional, native z/OS programs to participate in modern web services applications. The toolkit is included in the base of z/OS operating system so there is nothing to install.

Pieces of the toolkit:

• A z/OS HTTP/HTTPS protocol enabler to externalize HTTP and HTTPS client functions in an easy-to-use generic fashion.
• A z/OS JSON parser which parses and modifies JSON coming from any source.

Application Transparent –TLS (AT-TLS) is a stack-based TLS performed in the TCP layer (via System SSL) without requiring any change to existing TCPIP applications (transparent). AT-TLS policy specifies which TCP traffic is to be TLS protected based on a variety of criteria:

• Local address, port.
• Remote address, port.
• z/OS username, jobname.

This gives network administrators greater control over the security requirements of network applications rather than individual applications. The alternative is for each application (including FastSSR), to code all the TLS/SSL instructions necessary to handle certificates, key exchanges, key negotiation, and encryption/decryption duties for both web services and TCPIP sockets. For FastSSR, it is an easy decision to use AT-TLS since the z/OS web enablement toolkit supports it and it requires no change to the current FastSSR for z/OS TCPIP code. More information regarding AT-TLS can be found HERE.

AT-TLS Setup

We will not document all the AT-TLS considerations here but will detail the primary setup steps used to enable AT-TLS in our environment.

SYS1.TCPPARMS(stackname)
AT-TLS must be enabled for z/OS TCPIP by adding the TTLS option to the TCPCONFIG statement to the TCPIP parameters dataset.

TCPCONFIG TTLS

SYS1.PROCLIB(PAGENTX)
AT-TLS policies are enabled and enforced by running the Policy Agent procedure (PAGENTX). This procedure is provided by IBM.

//PAGENTX  PROC                                                          
//*                                                                      
//* IBM Communications Server for z/OS                                   
//* SMP/E distribution name: EZAPAGSP                                    
//*                                                                      
//* 5650-ZOS Copyright IBM Corp. 1998, 2013                              
//* Licensed Materials - Property of IBM                                 
//* "Restricted Materials of IBM"                                        
//* Status = CSV2R1                                                      
//*                                                                      
//PAGENTX  EXEC PGM=PAGENT,REGION=0K,TIME=NOLIMIT,                       
//       PARM=('ENVAR("TZ=EST5EDT")/-c //''SYS1.PARMLIB(PAGENTX)'' -l  
//             /tmp/pagent.log')                                         

The important part here is the PARM statement which points to the dataset that contains the Policy Agent parameter file, VENDOR.PARMLIB(PAGENTX).

SYS1.PARMLIB(PAGENTX)
For each TCPIP stack, a TTLSConfig parameter is needed to define the actual policy rules and action statements.

TTLSConfig //'SYS1.PARMLIB(FSSRTTLS)'                                         

FSSRTTLS is the member name with the policy rules and actions.

SYS1.PARMLIB(FSSRTTLS)
The policy rules and action statements for FastSSR z/OS are as follows. These statements can reside in their own member or added to your current policy statements member.

TTLSRule                     FastSSRProxyRule
{
      RemotePortRange                   9100-9199
      Direction                         Outbound
      TTLSGroupActionRef                FastSSRGroup
      TTLSEnvironmentActionRef          FastSSRProxyEnv
      Priority                          200
}
TTLSRule                     FastSSRApiRule
{
      Jobname                           FASTSSR
      Direction                         Outbound
      TTLSGroupActionRef                FastSSRGroup
      TTLSEnvironmentActionRef          FastSSRApiEnv
      Priority                          100
}
TTLSGroupAction              FastSSRGroup
{
      TTLSEnabled                       On
}
TTLSEnvironmentAction        FastSSRProxyEnv
{
      TTLSKeyRingParms
      {
          Keyring                       SCOTT/FastSSRProxy
      }
      HandshakeRole                     CLIENT
      Trace                             3
      TTLSCipherParmsRef                FastSSREncryption
      TTLSEnvironmentAdvancedParms
      {
          TLSv1.2                       On
          TLSv1.3                       On
      }
}
TTLSEnvironmentAction        FastSSRApiEnv
{
      TTLSKeyRingParms
      {
          Keyring                       *AUTH*/*
      }
      HandshakeRole                     CLIENT
      Trace                             3
      TTLSCipherParmsRef                FastSSREncryption
      TTLSEnvironmentAdvancedParms
      {
          TLSv1.2                       On
          TLSv1.3                       On
      }
}
# Set of TLS ciphers for FastSSR encryption
TTLSCipherParms FastSSREncryption
{
    #TLSv1.2 with option for no data encryption
    V3CipherSuites TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
    V3CipherSuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
    V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    V3CipherSuites TLS_RSA_WITH_NULL_SHA256
    #TLSv1.3
    V3CipherSuites TLS_AES_256_GCM_SHA384
    V3CipherSuites TLS_CHACHA20_POLY1305_SHA256
    V3CipherSuites TLS_AES_128_GCM_SHA256
}                                  

There is much to unpack here. First note that we have two (2) TTLSRule definitions, one for the Proxy Agent (i.e., the TCPIP transfers) and one for the web services APIs. This due to using two (2) different RACF keyrings for two (2) different secure certificates. We could, just as easily, use the same certificate for both forms of traffic and only have one TTLSRule.

As mentioned previously, AT-TLS filters traffic and applies policies based on different attributes. The FastSSRProxyRule states any TCPIP traffic occurring over ports 9100-9199 will have its actions applied. The FastSSRApiRule states any TCPIP traffic coming from job FASTSSR will have its actions applied.

Interestingly, the TCPIP traffic and web services traffic both come from the FASTSSR job! Which rule will apply? The Priority attribute directs the Policy Agent to apply the FastSSRProxyRule first, then the FastSSRApiRule.

Each rule specifies an TTLSEnvironmentActionRef statement. The TTLSEnvironmentAction action defines which certificate keyring is used for TLS/SSL processing. Think of a keyring as a certificate store. When TLS negotiation occurs between the FastSSR Proxy Agent and the AT-TLS, AT-TLS will search this keyring for the public keys the Proxy Agent is requesting. The TTLSEnvironmentAdvancedParms statement defines which versions of TLS are supported and the TTLSCipherParms define which encryption algorithms are supported

There are two (2) forms of TCPIP traffic within the FastSSR system, web services traffic and data transfer traffic. To secure this traffic a secure certificate, and if needed, its intermediate certificates are needed. For both forms of traffic, FastSSR PC and the FastSSR for z/OS are considered “client” ends of TLS/SSL processing and require the public keys of the certificate and intermediate certificates. The FastSSR web services server and the FastSSR Proxy Agent server are considered the “server” ends for web services and data transfers respectfully and require the private key of the certificate and the public keys of any required intermediate certificates.

As with most TLS/SSL enabled applications, 3rd party certificates from a known certificate authority such as GoDaddy can be used in FastSSR. This is highly recommended for both web services and data transfer, as they are easier to implement and offer a higher level of trust. However, it is sometimes difficult to obtain 3rd party certificates due to costs and other corporate hinderances. In this case, FastSSR supports self-signed certificates, and, optionally, turning off TLS/SSL support for an Endpoint (TLS/SSL processing is always required for FastSSR PC clients)

Certificates on the PC

Most 3rd party certificates, including GoDaddy, come preinstalled with Windows, so if you host your own Proxy Agent and it uses a 3rd party certificate from a popular certification authority (CA), you should be ok on the PC side. If using a self-signed certificate for either the web service host or proxy agent, the public key of the self-signed certificate must be imported to the PC and stored as a Trusted Authority within the Windows Computer Certificate Store.

Certificates on z/OS

You can use z/OS RACF to create, register, store, and administer digital certificates and their associated private keys. You can also use RACF to manage key rings of stored digital certificates. From a FastSSR perspective, the z/OS endpoint, if using a 3rd party certificate from a central authority, must hold the public keys of the intermediate/root certificates of the web service host and proxy agent. If using a self-signed certificate for either the web service host or proxy agent, the public key of the self-signed certificate must be installed on the endpoint.

For example, here are the steps we performed on our test system:

1. Download the GoDaddy G2 root and intermediate certificates.
2. Using emulator transfer, upload GoDaddy root and intermediate certs into datasets (RECFM=VB, LRECL=255) with names: ES.FSSRV01.GDROOT.CRT, ES.FSSRV01.GDIMMD.CRT.
3. In ISPF > R (RACF) > 1 (Digital Certificate Functions) > 5 (Add certificate).
4. Enter option 1 at the top.
5. Select Certificate Authority.
6. Enter the dataset name of certificate (first root certificate, then intermediate certificate).
7. Enter 'Go Daddy Root Certificate G2' for root, or 'Go Daddy Secure Certificate G2' (include single quotes) for intermediate into Label field
8. Enter T for Trust.
9. Press the Enter key.
10. At the TSO READY prompt:
    • RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
    • PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(GROUP2) ACCESS(READ), where GROUP2 is the group of username associated with FastSSR job.
    • SETROPTS RACLIST(FACILITY) REFRESH
11. Within the FSSRTTLS parameter file, find the TTLSKeyRingParms parameter and specify:

    Keyring      *AUTH*/*

For details on TLS/SSL in z/OS, click HERE. For details on RACF certificate management click HERE.

The image below shows how certificates are handled and deployed for FastSSR.