System SSL requires Security Level 3 FMID (JCPT411) 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 form the FIPS 140-2 cryptographic boundary
are signed using an IBM® key
during the build process. Once System SSL is installed, additional
steps are required before 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 certificate. This
certificate is shipped as a default CERTAUTH certificate in the RACF database under the label 'STG
Code Signing CA'.
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:
- Mark the IBM root CA as
TRUSTed if not already TRUSTed
RACDCERT CERTAUTH LIST(LABEL('STG Code Signing CA'))
RACDCERT CERTAUTH ALTER (LABEL('STG Code Signing CA')) TRUST
- Create a key ring to hold the STG Code Signing CA 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') 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') USAGE(CERTAUTH))
- 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')
- Activate your profile changes in the FACILITY, DIGTCERT and/or
DIGTRING classes if active and RACLISTed.
SETROPTS RACLIST(FACILITY) REFRESH
SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
- 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.
- 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))
- Refresh the PROGRAM class.
SETROPTS WHEN(PROGRAM) REFRESH
- Contact your system programmer to complete this step.
- 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.
- 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.
- Do not define PROGRAM profiles for the System SSL modules
until IRRVERLD executes successfully.
- 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))
- Refresh the PROGRAM class.
SETROPTS WHEN(PROGRAM) REFRESH