System SSL: Ensure ICSF is available when running System SSL in FIPS 140-2 mode

Description

In z/OS V2R1, System SSL, when running in FIPS 140-2 mode, uses ICSF's random number generation and Diffie-Hellman support. Before running System SSL in FIPS 140-2 mode you must ensure that ICSF is running and that all user IDs that start SSL applications in FIPS 140-2 mode, invoke the gskkyman utility to manage FIPS 140-2 key database files, or invoke the GSKSRVR started task in FIPS mode have access to certain CSFSERV classes.

When it is running in non-FIPS mode, System SSL uses its own implementation of Diffie-Hellman and does not require ICSF. In non-FIPS 140-2 mode, however, System SSL attempts to use ICSF's random number generation as it would when running in FIPS 140-2 mode. If ICSF or the required resource is unavailable, System SSL uses its own random number generation capabilities as in earlier releases.

Table 1 provides more details about this migration action. Use this information to plan your changes to the system.

Table 1. Information about this migration action
Element or feature: Cryptographic Services.
When change was introduced: z/OS V2R1.
Applies to migration from: z/OS V1R13.
Timing: Before the first IPL of z/OS V2R2.
Is the migration action required? Yes, if your installation runs System SSL in FIPS mode.
Target system hardware requirements: None.
Target system software requirements: None.
Other system (coexistence or fallback) requirements: None.
Restrictions: None.
System impacts: None.
Related IBM Health Checker for z/OS check: None

Steps to take

To run System SSL in FIPS 140-2 mode, you must now make sure that ICSF is running and that all user IDs that start SSL applications in FIPS 140-2 mode, invoke the GSKSRVR started task in FIPS 140-2 mode, or invoke the gskkyman utility to manage FIPS 140-2 key database files can access the necessary ICSF callable services.

  1. Make sure that ICSF is running. Assuming CSF is the name of the ICSF started task, you would enter:
    DISPLAY A,CSF*
    To display status about all started tasks, you would enter:
    DISPLAY A,ALL

    In z/OS V1R13, System SSL is providing capability to identify System SSL applications that are running in FIPS 140-2 mode, which are started before ICSF is available. Identification of these applications is done by using the System SSL started task (GSKSRVR) and the z/OS tracking facility. This migration assistance support is delivered in APAR OA40816. See Brief overview of APAR OA40816 for more information.

  2. System SSL applications that are running in FIPS 140-2 mode, the GSKSRVR started task that is running in FIPS 140-2 mode, and the gskkyman utility (if managing FIPS 140-2 key database files) must be able to access ICSF's PKCS #11 pseudo-random function callable service for random number generation. In addition, applications and the gskkyman utility must access the following callable services to use ICSF's Diffie-Hellman capabilities:
    • PKCS #11 Token record create
    • PKCS #11 Derive key
    • PKCS #11 Generate key pair
    • PKCS #11 Generate secret key
    • PKCS #11 Get attribute value
    • PKCS #11 Token record delete
    To ensure that RACF user IDs have access to the necessary services:
    1. Determine if the CSFSERV class is active. If active, this class restricts access to the ICSF programming interface. If it is not active, access to the ICSF programming interface (and the necessary callable services) is unrestricted. No configuration is necessary.

      To determine which RACF classes are currently active, enter the SETROPTS command with the LIST parameter specified.SETROPTS LIST

    2. If the SETROPTS LIST command shows that the CSFSERV class is active, identify the profile or profiles that cover the following resources:
      • CSFRNG (which represents the PKCS #11 Pseudo-random function callable service)
      • CSF1TRC (which represents the PKCS #11 Token record create callable service)
      • CSF1DVK (which represents the PKCS #11 Derive key callable service)
      • CSF1GKP (which represents the PKCS #11 Generate key pair callable service)
      • CSF1GSK (which represents the PKCS #11 Generate secret key callable service)
      • CSF1GAV (which represents the PKCS #11 Get attribute value callable service)
      • CSF1TRD (which represents the PKCS #11 Token record delete callable service)
      Each of these resources can be covered by a discrete profile or, if generic profile checking is activated, a generic profile. You can use the RLIST command to determine if a profile is defined to protect each resource. For example, to determine if a profile is defined to protect the CSFRNG resource, enter the following RLIST command: RLIST CSFSERV CSFRNG. When you enter this command, RACF lists information for the discrete profile CSFRNG. If there is no matching discrete profile, RACF lists the generic profile that most closely matches the resource name.
    3. If the RLIST command output reveals that there is a discrete or generic profile that covers the resource, examine the command output to ensure that all RACF user IDs that might start System SSL applications in FIPS 140-2 mode have at least READ access to the resource. If necessary, use the PERMIT command to give the appropriate users or groups access. For example, if a discrete profile CSFRNG exists, the following command would give the user JASMINE access:
      PERMIT CSFRNG CLASS(CSFSERV) ID(JASMINE) ACCESS(READ)
      If you do make changes, refresh the in-storage RACF profiles for the CSFSERV class: SETROPTS RACLIST(CSFSERV) REFRESH

Overview of APAR OA40816: In z/OS V1R13, System SSL is providing capability to identify System SSL applications that are running in FIPS 140-2 mode that have been started before ICSF was available. Identification of these applications is done by using the System SSL started task (GSKSRVR) and the z/OS tracking facility. See z/OS MVS Planning: Operations for more information about the z/OS tracking facility.

When the System SSL started task is enabled to write to the tracking facility, the started task will get notified of any SSL applications that are running in FIPS 140-2 mode before ICSF was available. The messages in the z/OS tracking facility can be monitored by issuing a DISPLAY OPDATA,TRACKING command to see which System SSL applications are running in FIPS 140-2 mode before ICSF being available. The following example shows output from the DISPLAY OPDATA,TRACKING command: 
12.43.50           d o,tr                                                
12.43.50           CNZ1001I 12.43.50 TRACKING DISPLAY 788             
STATUS=ON       NUM=4    MAX=1000 MEM=n/a EXCL=0     REJECT=0         
---- TRACKING INFORMATION---- -VALUE-- JOBNAME   PROGNAME+OFF-- ASID NUM
GSK01058I No ICSF for FIPS.         00 GSKSRVR   GSKSRVR   D9D6   48   1
GSK01059I SSLAPP1 no ICSF.          00 GSKSRVR   GSKSRVR   DAB0   48   5
GSK01059I SSLAPP2 no ICSF.          00 GSKSRVR   GSKSRVR   DAB0   48   2
GSK01059I SUIMGVD9 no ICSF.         00 GSKSRVR   GSKSRVR   DAB0   48   1  
------------------------------------------------------------------------  .
From the tracking information in this example:
  1. The GSK01058I message is the generic message that is written to the z/OS tracking facility once for the life of the System SSL started task. This message is issued the first time when either the System SSL started task or a System SSL application is running in FIPS 140-2 mode before ICSF being available.
  2. The SSLAPP1 job was started or submitted 5 times
  3. The SSLAPP2 job was started or submitted 2 times.
  4. The SUIMGVD9 job was started or submitted just 1 time.
For more information about the support in APAR OA40816, see the documentation updates in OA40816.

Reference information

For more information, see the following references:
Parent topic: Cryptographic Services actions to perform before the first IPL of z/OS V2R2