System SSL module verification setup

System SSL requires Security Level 3 FMID Start of changeJCPT451End of change to be installed in order for enabled applications to execute in FIPS mode. Application enablement requires applications to invoke the gsk_fips_state_set() API. For more information about the FIPS enablement API, see gsk_fips_state_set().

The System SSL modules that support FIPS 140-2 are signed using an IBM® key during the build process. If any of your installation's System SSL applications are enabled for FIPS and you intend on using System SSL functions in compliance with the FIPS 140-2 standard, then, in accordance with that standard, the integrity of each System SSL module when being loaded into storage must be verified. The verification of the modules requires additional configuration steps prior to the execution of a FIPS enabled System SSL application.

These steps involve:
  • Defining specific RACF® profiles to enable the verification of the System SSL module signature (added during the IBM module build process) when loaded by the z/OS® loader.
  • Defining specific RACF profiles and identifying which System SSL modules require signature verification.

Signature verification provides a method to ensure that the System SSL modules remain unchanged from the time they were built, installed onto the system, and loaded into storage to be used by a FIPS enabled System SSL application.

The IBM key used to sign the System SSL modules is an RSA private key that belongs to an X.509 certificate signed by the STG Code Signing CA - G2 certificate. This certificate is shipped as a default CERTAUTH certificate in the RACF database under the label 'STG Code Signing CA - G2'.

Note: A sample clist, GSKRACF, is shipped in pdsename.SGSKSAMP to assist you with the RACF commands needed to enable signature verification.
The following steps need to be followed by the system administrator to enable signature validation of the System SSL modules:
  1. Mark the IBM root CA as TRUSTed if not already TRUSTed
    RACDCERT CERTAUTH LIST(LABEL('STG Code Signing CA - G2'))
    RACDCERT CERTAUTH ALTER (LABEL('STG Code Signing CA - G2')) TRUST
  2. Create a key ring to hold the STG Code Signing CA - G2 certificate and connect the certificate to the key ring.

    The key ring needs to be owned by a valid RACF ID and the key ring must be defined in uppercase. Make sure that the ID is an ID of a security administrator. In our example the security administrator ID is RACFADM.

    There can only be one designated signature verification key ring active at one time. If already active, add the CA certificate to the key ring. If not already active create the key ring. The suggested key ring name is CODE.SIGNATURE.VERIFICATION.KEYRING.

    • Determine if signature verification key ring is already active:

      RLIST FACILITY IRR.PROGRAM.SIGNATURE.VERIFICATION

      The key ring is present in the APPLICATION DATA field

    • Create key ring if needed and connect CA certificate:

      RACDCERT ID(RACFADM) ADDRING(CODE.SIGNATURE.VERIFICATION.KEYRING)

      RACDCERT ID(RACFADM) CONNECT(RING(CODE.SIGNATURE.VERIFICATION.KEYRING) CERTAUTH LABEL('STG Code Signing CA - G2') USAGE(CERTAUTH))

    • If a key ring exists, verify that the CA certificate is connected to the key ring. If not connected, connect the certificate:

      RACDCERT ID(RACFADM) LISTRING(CODE.SIGNATURE.VERIFICATION.KEYRING)

      RACDCERT ID(RACFADM) CONNECT(RING(CODE.SIGNATURE.VERIFICATION.KEYRING) CERTAUTH LABEL('STG Code Signing CA - G2') USAGE(CERTAUTH))

  3. Create the FACILITY class profile that tells RACF the key ring to use for module signature verification if it is not already defined.
    Note: Because of space constraints, the second command example appears on two lines. However, the command should be entered completely (on one line) on your system.

    RLIST FACILITY IRR.PROGRAM.SIGNATURE.VERIFICATION

    RDEFINE FACILITY IRR.PROGRAM.SIGNATURE.VERIFICATION APPLDATA('RACFADM/CODE.SIGNATURE.VERIFICATION.KEYRING')

  4. Activate your profile changes in the FACILITY, DIGTCERT or DIGTRING class, or both the DIGTCERT and DIGTRING classes, if RACLISTed.
    SETROPTS RACLIST(FACILITY) REFRESH
    SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
  5. Activate PROGRAM control, if not already active.
    SETROPTS WHEN(PROGRAM)
    Note: Installations that have not previously turned on program control, may encounter problems after issuing SETROPTS WHEN(PROGRAM). Program control is necessary for signature verification, hence installations must evaluate the impact of enabling program control for the first time.
  6. Create the PROGRAM class profile that protects the program verification module IRRPVERS and specify its signature verification options.
    Note: Because of space constraints, the command appears on two lines. However, the command should be entered completely (on one line) on your system. 
    RDEFINE PROGRAM IRRPVERS ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))
  7. Refresh the PROGRAM class.
    SETROPTS WHEN(PROGRAM) REFRESH
  8. Contact your system programmer to complete this step.
    1. Notify your system programmer to initialize program signature verification by running the IRRVERLD program which loads and verifies the program verification module IRRPVERS. For programming information, see z/OS Security Server RACF System Programmer's Guide.
    2. Check with your system programmer to ensure that IRRVERLD executed successfully. If it did not execute successfully, work with your system programmer to check error messages. Correct any setup errors and retry.
    3. Do not define PROGRAM profiles for the System SSL modules until IRRVERLD executes successfully.
  9. Create the PROGRAM class profiles to indicate that the System SSL modules must be signed. The load should fail if the signature cannot be verified and auditing should occur for failure only. If your installation requires event logging for the signature verification, see the RALTER and RDEFINE commands in the z/OS Security Server RACF Command Language Reference for customizing the SIGAUDIT operand within the SIGVER segment.
    Note: Because of space constraints, the command examples appear on two lines. However, the command should be entered completely (on one line) on your system.
    RDEFINE PROGRAM GSKSSL ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKSSL64 ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKS31F ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKS64F ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKCMS31 ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKCMS64 ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKC31F ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKC64F ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKSRVR ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))  

    RDEFINE PROGRAM GSKKYMAN ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))

    RDEFINE PROGRAM GSKSRBRD ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))

    RDEFINE PROGRAM GSKSRBWT ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)
    SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))
  10. Refresh the PROGRAM class.
    SETROPTS WHEN(PROGRAM) REFRESH