There is an IBM document Task roadmap for program signing and signature verification, this provides some of the information, and some of the information is wrong!
I’ve documented Signing load modules on z/OS.
I hit various problems. The return code from the program signing function are documented here.
Using signed modules on your system
You have been sent some modules which have been signed, and you want to user the signature verification on these modules.
One-of system wide setup
Define the system wide keyring
For the validation of signed modules there is one system wide key ring. It needs to have the signing certificates (or the CA certificates) for all of the modules being used.
RACDCERT ADDRING(VERIFY) ID(COLIN )
* now the profile
RDEFINE RDATALIB COLIN.VERIFY.LST UACC(NONE)
PERMIT COLIN.VERIFY.LST CLASS(RDATALIB) ID(COLIN ) ACCESS(UPDATE)
SETROPTS RACLIST(RDATALIB) REFRESH
Connect the IBM CA to the keyring
You need to connect the IBM Provided Certificate authority, to be able to verify the signature of IBM provided modules. See Listing of RACF supplied certificates.
RACDCERT ID(COLIN )CONNECT(RING(VERIFY) -
CERTAUTH -
LABEL('STG Code Signing CA - G2')
RACDCERT LISTRING(VERIFY) ID(COLIN )
Note the lower case name.
Tell the certificate certificate facility which key ring to use.
RDEFINE FACILITY IRR.PROGRAM.SIGNATURE.VERIFICATION -
APPLDATA('COLIN/VERIFY')
This ring has the certificates needed to verify.
Define the program that does the signature validation.
RDEFINE PROGRAM IRRPVERS ADDMEM('SYS1.SIEALNKE'//NOPADCHK) UACC(READ)-
SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))
Run the IRRVELD job
I had to run this when setting up for the first time. When I next IPLed, I did not need to run it. I think that RACF checks to see if the above RACF profile exists – if so – loads the code.
See here.
//IRRVERLD JOB
//IRRVERLD EXEC PGM=IRRVERLD
When successful, this starts and ends with return code 0 and
ICH448I RACF program signature verification function is loaded. Program signature verification is available on this system.
Define your programs that need validation
RDEFINE PROGRAM ZZZDATA ADDMEM('COLIN.ZWIRESHA.LOAD'//NOPADCHK) -
UACC(READ) -
SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))
SETROPTS WHEN(PROGRAM) REFRESH
Where my program is called ZZZDATA and it is loaded from COLIN.ZWIRESHA.LOAD. The definition SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD)) says that signature is required, and if verification fails do not load the module, and write an audit record.
Each userid (or group) needs a RACF profile to specify which keyring to use to sign the programs
If you want to do IPL data signing for Validated Boot for z/OS you need the profile IRR.PROGRAM.V2.SIGNING…..
If you want to validate a general program you need the profile IRR.PROGRAM.SIGNING….
Where you can specif userid, group, or group and userid.
- IRR.PROGRAM.SIGNING.userid
- IRR.PROGRAM.SIGNING.goup
- IRR.PROGRAM.SIGNING.group.user
RDELETE FACILITY IRR.PROGRAM.SIGNING.COLIN
RDEFINE FACILITY IRR.PROGRAM.SIGNING.COLIN -
APPLDATA('SHA256 COLIN/SIGNING')
PERMIT IRR.PROGRAM.SIGNING.COLIN CLASS(FACILITY) -
ID(COLIN) ACCESS(CONTROL)
SETROPTS RACLIST(FACILITY) refresh
This says for userid COLIN use SHA256 and keyring COLIN/SIGNING. It will use the default key in the keyring.
You sign a module at bind time, by specifying the binder options SIGN=YES.
I added sign=yes to the binder JCL
Create a certificate to sign it
RACDCERT ID(COLIN) GENCERT -
SUBJECTSDN(CN('10.1.1.2') -
O('SIGNER521') -
OU('SSS')) -
ALTNAME(IP(10.1.1.2))-
SIZE(2048) -
NOTAFTER( DATE(2026-04-22) TIME(15:22:00) ) -
KEYUSAGE(HANDSHAKE DOCSIGN) -
SIGNWITH (CERTAUTH LABEL('SIGNCA')) -
WITHLABEL('SIGNER521')
RACDCERT id(COLIN) ALTER(LABEL('SIGNER521'))TRUST
SETROPTS RACLIST(DIGTCERT) REFRESH
RACDCERT ID(COLIN )CONNECT(RING(SIGNING) -
ID(COLIN) -
DEFAULT -
LABEL('SIGNER521') )
It seems to need KEYUSAGE HANDSHAKE and DOCSIGN.
It needed the default RSA size 2048. It did not work with an ECC algorithm.
It needs to be the default in the keyring.
Execute the program
When you come to execute the signed program, the system uses the keyring defined in the
IRR.PROGRAM.SIGNATURE.VERIFICATION CLASS(FACILITY) profile. I believe this has the certificates needed to verify the programs signature.
I used keyring COLIN/VERIFY.
IEW2494E 9116 A PROBLEM WAS ENCOUNTERED WITH THE SETUP OF THE DIGITAL CERTIFICATES REQUIRED FOR PROGRAM SIGNING. RACF RETURNED SAF RETURN CODE 8 RACF RETURN CODE 8 RACF REASON CODE 00000070.
R_PgmSign 70 Ver Key ring or token does not exist or does not contain a default certificate.
ColinPaice 