Using code signing on z/OS

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.

Signing load modules on z/OS

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!

This blog post describes how to set up your environment to sign load modules. I’ve documented Using code signing on z/OS

I hit various problems. The return code from the program signing function are documented here.

Create RACF profiles

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 specify 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 uses the default key in the keyring.

How to sign a load module

You sign a module at bind time, by specifying the binder options SIGN=YES.

I added SIGN=YES to the binder JCL

When it failed, there were messages like

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 00000098.

These are from the R_PgmSignVer (IRRSPS00): Program Sign and Verify callable service. See the return codes. The return codes in the messages are in hex; in the documentation they are in decimal. 0x98 is decimal 152. 152 is CA or signing certificate is expired or not yet active. This was true – my signing certificate had expired.

Create a certificate to sign load modules.

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.

Code signing – error messages

The messages I received were from R_PgmSignVer (IRRSPS00 or IRRSPS64): Program Sign and Verify

Return code hex 64, decimal 100 (CA) certificate missing from the keyring used to verify.
Return code hex 70, decimal 112 use the correct keyring, ensure it has a valid default certificate.
Return code hex 88, decimal 136 fix the keyusage().
Return code hex 90, decimal 144 keytype not RSA.

Return code hex 70, decimal 112

ICH440I Program signature error 0x10/0x00000070 for program IRRPVERS in library SYS1.SIEALNKE.
The program was not loaded.
ICH442I The digital signature appears to be valid but the root signer is not trusted.
ICH451I RACF encountered an error while attempting to load the program verification module. Operation code = X’06’.
Return code X’00000306′ and Reason code X’00000040′.
Supplemental diagnostic code 1 = X’00000000′.
Supplemental diagnostic code 2 = X’00000000′.
Supplemental diagnostic code 3 = X’00000000′.
Supplemental diagnostic code 4 = X’00000000′.
Supplemental diagnostic code 5 = X’00000000′.

The certificate CERTAUTH LABEL(‘STG Code Signing CA – G2’) was not trusted.

R_PgmSignVer return codes code 0x70 is 112. Key ring or token does not exist or does not contain a default certificate.

I had mis typed the certificate name.

Action:

The the name of the keyring, there is a default certificate, and the certificate has not expired.

Return code hex 64, decimal 100

At execution time I got.

ICH440I Program signature error 0x10/0x00000064 for program ZZZDATA in library COLIN.ZWIRESHA.LOAD. The program was not loaded. ICH442I The digital signature appears to be valid but the root signer is not trusted.

code 0x64 is decimal 100 which is

The program appears to be correctly signed but one of the following conditions exists:

The root CA certificate in the zOSSignatureInfo structure of the program object is not connected to the signature-verification key ring.
The root CA certificate is marked NOTRUST.

The CA of the signing code was not in the verify keyring at execution time.

Action:

Connect the certificate or its CA to the verify keyring.

Return code hex 88, decimal 136

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 00000088.

The default certificate in the key ring or token does not have code signing capability.

When Num_parms = 10, the keyUsage extension is optional. If the extension is present, the digitalSignature bit must be set.
When Num_parms = 11, the keyUsage extension must be present and the digitalSignature bit must be set.

The real reason is “HANDSHAKE” or “DOCSIGN” was missing from the KEYUSAGE().

Action:

Fix the keyusage field.

Return code hex 90, decimal 144

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 00000090.

The key type of one or more certificates in the key ring or token is not supported. This reason code is also issued for the following conditions:

When Num_parms = 11, the signing key can be stored in ICSF, but it must be a 521-bits NIST Elliptic Curve Cryptography (ECC) key. Also, the key size of any other certificates in the key ring or token must be at least 2048 bits for RSA keys, or 224 bits for NIST ECC and Brainpool ECC keys.
When Num_parms = 10 and an RSA CA certificate in the chain has a key size less than 2048 bits.

This was caused by using a key with

NISTECC -
SIZE(521 ) -

using the followin

RSA
SIZE(2048) -

Works.

Action:

Use RSA key with size 2048;

First steps in using system ssl

System SSL also known as GS kit provides an API for doing

TLS handshakes
Keyring manipulation
Encryption and signing of data

This blog post covers background information for using GSKit. I wrote it because I could not find useful samples to get me started.

Introduction

It took me some time to understand how System SSL has been written. Now I understand it, I think it is a good API. They can be more than one way of doing something, so working out what you want to to can be hard.

Use of structures

It took me a while to understand the structures. I thought they were a little complex, and started designing my own equivalent, but I then found my “improved” definition were very similar to the original ones.

For example, I want to process some application data. It has an address and a length.
With my simplistic view I would define

char * pBuffer;
int lBuffer;

You could the use these in your application.

GSKIT provides the same files in a structure.

			
gsk_buffer mybuffer;
mybuffer.data = "ABCD";  // data is a void * pointing to the data
mybuffer.length = 4;     //

I can then do

			
gsk_buffer in;
gsk_buffer out;
in.data = ...
in.length = ...
gsk_rc gsk_copy_buffer(*in,*out)

		

For gsk_buffers that are output from a GSKIT call you need to free the contents.

gsk_free_buffer(&in);

This will release any storage which had been allocated to the structure, and set the values to 0.

Do not use this for gsk_buffers you created, because it will free the storage the data is using.

Arrays of objects

Some API functions take one certificate, and others take an array of certificates.

You define one certificate-key

 pkcs_cert_key cert_key;

For an array of certificate keys you use

			
// Define the array (of 2)
pkcs_cert_key cert_key[2]; 
// Initialise it
cert_key[0].certificate =  cert; 
cert_key[0].privateKey  =  pRecord -> privateKey;
cert_key[1].certificate =  cert1; 
cert_key[1].privateKey  =  pRecord1 -> privateKey;
// Define the structure of array of keys
pkcs_cert_keys cert_keys; 
cert_keys.count = 2; 
cert_keys.certKeys = &cert_key[0]; 

		

Processing arrays of objects

			
void print_certs(pkcs_certificates * pcs)
{
  // pkcs_certificate has a count and array of certs
  // iterate over them all
  int i;
  pkcs_certificate * pc = & pcs-> certificates[0];
  for (i = 1; i <= pcs-> count;i++)
  {
    printf("Certificate %i\n",i);
    printf("==========\n");
    print_cert(pc);
    pc ++;
    printf(" \n");
  }  
                  
}

		

Where print_cert() is the program I wrote which prints information about one certificate.

Useful functions

Most gskit functions return a gsk_status. You can print the interpretation of this using

			
if ( gskrc != 0)
  printf("Error return: %s\n" gsk_strerror(gskrc));

Definitions are in

/usr/include/gsktypes
/usr/include/gskcms.h

First steps in using system ssl: compiling a program

System SSL also known as GS kit provides an API for doing

TLS handshakes
Keyring manipulation
Encryption and signing of data

See First steps in using system ssl gives some introductions to gskit.

The blog post provides the script I used to compile my programs. Not everything may be relevant.

			
name=main 
export _C89_CCMODE=1 
p5="-I.  -I/usr/include " 
p7="-Wc,DLL " 
p8="-Wc,LIST(c.lst),SOURCE,XREX,SHOWINC" 
p8=" "  # no listing
/bin/xlc $p5  $p7 $p8  -c $name.c -o $name.o 
l1="-Wl,LIST=ALL,MAP,XREF         " 
bind=" /usr/lib/GSKCMS31.x /usr/lib/GSKSSL.x " 
/bin/xlc $name.o ${bind}  -o $name -v $l1 1>bind.lst 

		

The output from the C compile goes into c.lst, and from the bind it goes into bind.lst

The gsk includes are in /usr/include.

For the bind you need /usr/lib/GSKCMS31.x /usr/lib/GSKSSL.x

Example of system ssl to display keyring information

System SSL also known as GS kit provides an API for doing

TLS handshakes
Keyring manipulation
Encryption and signing of data

This blog post covers how to access a keyring and use the information in it. I wrote it because I could not find useful samples to get me started.

Introduction

First steps in using system ssl gives some introductions to gskit.
Compiling a gsk program
Example of using system ssl to print certificate information.
Example of using system ssl to sign some data.

List the certificates in a keyring

			
// #include <gskssl.h>  // only used for TLS and SSL
#include <gskcms.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
#include <errno.h> 
#include <printhex.h>
int main(int argc, char * argv[]) { 
 int rc; 
 gsk_status gskrc; 
 gsk_handle hRing ; 
 int        count = 0;// the number of certs is put here
 char * ring = "START1/TN3270";
 printf("Open keyring %s\n",ring);
 gskrc=  gsk_open_keyring (ring, 
                &hRing, 
                &count ); 
 if (gskrc != 0)
 {
   printf("gsk_open_keyring %s\n",  gsk_strerror(gskrc)); 
   return 8;
 }
 printf("Number of certs in the ring %i\n",count); 
 //
 // Get the default label (if it exists)
 // 
 char * default_label;
 gskrc = gsk_get_default_label(hRing,&default_label);
    
 if (gskrc != 0)
 { 
   else printf("gsk_get_default_label error %s\n",gsk_strerror(gskrc));
   return 8;
 }
 printf("gsk_get_default_label %s\n",default_label);
 // 
 // now get the record with this label (or by number)
 //
 gskdb_record * pRecord = 0;
 gskrc =  gsk_get_record_by_label(hRing,default_label,&pRecord);   
 //gskrc = gsk_get_record_by_id(hRing,4,&pRecord); // by number
 if (gskrc != 0)
 {
    printf("gsk_get_record_by_label worked %s\n",gsk_strerror(gskrc));
    return 8;
 }  
 // The value is a half work enum
 printf("Record Type %hi\n",pRecord ->recordType);
 #include <readLabels.h> 
 #include <listall.>
 gskrc = gsk_close_database(&hRing); 
 return 0 ;
}

		

ReadLabels

With gsk_get_record_labels you can request those with private keys (1) or those without private keys(0)

If you want all certificates on the ring use without private_keys(0).

			
gskrc = gsk_get_default_label ( hRing,&default_label);
if (gskrc == 0)
    printf("gsk_get_default_label %s\n",default_label);
else printf("gsk_get_default_label error %s\n",gsk_strerror(gskrc));
char ** pl = 0;
int countL = 0;int whichRecords = 0;
printf("/nGet records with no private key (%i)\n",whichRecords);
gskrc = gsk_get_record_labels (hRing, 
           whichRecords, // those with public keys only
                  //  1 for this with private key 
           &countL, // How many returned
           &pl);  // char *** labels
if ( gskrc != 0)
{
  printf("gsk_get_record_labels%s\n",gsk_strerror(gskrc));
  return 8
}  
for (int j = 0; j<countL ;j++)
   {
     printf("Label %i,%s\n",j,*pl);
     pl++;
   }
    
printf("============\n");

		

It took me some time to get the list of labels printed out. The value is a char ***;

If you had char * p; p is a pointer to a string so is a char *.
char * q[10]; pl = &q[0]
pl is a pointer to the elements in the array. pl is addr(a char * ) so char **;
the address of pl is passed to the function, so it is addr( a char **) so is a char ***
In the loop we get what pl points to (*pl). This is a pointer to a string. so we have printf(“…”,*pl);

Listall

			
printf("Number of records %i\n",count);
for (int j = 1 ; j<count+1 ;j++) // starts at 1
    {
       gskrc = gsk_get_record_by_index(hRing,j,&pRecord);
       printf("Record %i:n",j);
       printRecord(pRecord);    
    }
    
printf("============\n");

		

printRecord

			
void printRecord( gskdb_record * pRecord)
{
  printf("Record Type %hi\n",pRecord ->recordType);
  printf("Record Flags %2.2x\n",pRecord ->recordFlags);
  printf("Record ID %i\n",pRecord ->recordId);
  printf("Record Issuer ID %i\n",pRecord ->issuerRecordId );
  printf("Record Label %s\n",pRecord ->recordLabel);
  printf("============\n");
}

		

Output

The program printed out

Open keyring START1/TN3270
Number of certs in the ring 9
gsk_get_default_label NISTEC256
gsk_get_record_by_label worked
precrd 2  20a2e6e0
Sizeof gskdb_record_type 2
gsk_get_default_label NISTEC256

Get records with no private key (0)

Label 0,DOCZOSCA
Label 1,JUN24CA
Label 2,DocZosCADSA
Label 3,CA256

============
Number of records 9
Record 1:
Record Type 2
Record Flags 80
Record ID 1
Record Issuer ID 1
Record Label DOCZOSCA
...

Record 9:
Record Type 3
Record Flags c0
Record ID 9
Record Issuer ID 1
Record Label NISTEC256
============

The value of Record 1 type gskdb_rectype_certificate = 2, /* Certificate */
Flags is
- GSKDB_RECFLAG_TRUSTED = The certificate is trusted ( 0x80);
- GSKDB_RECFLAG_DEFAULT = This is the default key
ID 1 – record 1
Issuer ID 1 – it is self signed
Label DOCZOSCA

Record 9:
Record Type 3
Record Flags c0
Record ID 9
Record Issuer ID 1
Record Label NISTEC256

The record type is 3 gskdb_rectype_certKey = 3, /* Certificate with key */
Flags is
- GSKDB_RECFLAG_TRUSTED = The certificate is trusted.
- GSKDB_RECFLAG_DEFAULT = This is the default key
ID 9 – it is record 9 in the keyring
Issuer ID 1- it was signed by the certificate with position 1 (DOCZOSCA)
Its label is NISTEC256

Example of using system ssl to print certificate information

The structure containing information about a certificate has a very deep nesting of structures and arrays. Fortunately for the most common information, gskit provides an interface.

There is a standards document giving the layout of the certificate, and what the fields mean.

First steps in using system ssl give some introductions to gskit.
Compiling a gsk program
Example of system ssl to display keyring information
Example of using system ssl to sign some data.

The structures are in /usr/include/gskcms.h. Some of the data types are in /usr/include/gsktypes.h .

The certificate structure

The structure pkcs_certificate>s has an array of pkcs_certificate and a count of the elements.
The structure pkcs_certificate has a certificate type and an x509_certificate.
The structure x509_certificate has
- a tbsCertificate
- signature algorithm
The x509_tbs_certificate structure (tbs from To Be Signed) has
- the certificate version
- the certificate serial number
- the signature algorithm of the certificate
- the issuer
- the validity period
- the subject.

The fields

The certificate serial number. This a hexadecimal value. The definition has a pointer to the data, and a length of the data. The length is at least one.
The signature algorithm of the certificate. This includes
- The signature type. This is a C enum, such as x509_alg_sha256WithRsaEncryption = 25
The issuer is a complex nest of structure. Fortunately gskit provide a function gsk_name_to_dn(structure,name). The output “name” is a printable EBCDIC string like CN=DocZosCA,OU=CA,O=COLIN
The validity period. This structure contains two time-value fields, not before, and not after.
- You can format a time value field using
  - char dest[18];
  - strftime(dest,18,”%y/%m/%d %H:%M:%S”,timeval);
The subject is like the issuer. Use the function gsk_name_to_dn to convert it to printable EBCDIC. For example CN=10.1.1.2,OU=SSS,O=NISTECC521

Printing the structures

I have some functions like

			
void print_certs(pkcs_certificates * pcs)
{
  // pkcs_certificate has a count and array of certs
  // iterate over them all
  int i;
  pkcs_certificate * pc = & pcs-> certificates[0];
  for (i = 1; i <= pcs-> count;i++)
  {
    printf("Certificate %i\n",i);
    printf("==========\n");
    print_cert(pc);
    pc ++;
    printf(" \n");
  }  
                  
}

		

which invokes

			
void print_cert(pkcs_certificate * pc )
{
    print_x509_algorithm_type(pc ->u.certificate. signatureAlgorithm
            .type,0);    
    // Serial number
    char output[60]; // into here
    // hexof is written by Colin Paice      
    printf("Serial number Hex     :%s\n",hexof(
        pc ->u.certificate.tbsCertificate.serialNumber.data,
        pc ->u.certificate.tbsCertificate.serialNumber.length,
        &output[0])    );
    
    // get the subject and issuer names
    gsk_status gskrc; 
    char * pName;   // returned here - must free it
    pName   = "Unknown"; 
    gskrc =  gsk_name_to_dn(
            & pc ->u.certificate.tbsCertificate.subject,
            &pName); 
  
    if (gskrc != 0)  
        printf("Subject gsk_name_to_dn  %s\n",  gsk_strerror(gskrc));
    
    printf("Subject name          :%s\n",pName);
    gsk_free_string(pName);           
    
  // extract the issuer,       
    pName   = "Unknown"; 
    gskrc =  gsk_name_to_dn (
        & pc ->u.certificate.tbsCertificate.issuer,
        &pName);      
    if (gskrc != 0) 
        printf("Issuer gsk_name_to_dn  %s\n,  gsk_strerror(gskrc)); 
    printf("Issuers name          :%s\n",pName); 
    gsk_free_string(pName); 
    
    // extract the valid times.
    char   buffer[18]; 
    printf("Not Before            :%s\n",         
        ccpformattime ( 
            & pc ->u.certificate.tbsCertificate.validity.notBefore, 
            &buffer[0]     ) );
     printf("Not After             :%s\n",
        ccpformattime ( 
            & pc ->u.certificate.tbsCertificate.validity.notAfter, 
            &buffer[0] ));
    
      print_x509_extensions(&pc -> 
             u.certificate.tbsCertificate.extensions);
} 

		

Process DER ASN.1

Some data is encoded in ASN.1 format.

This is of format

1 byte of type
1 or more bytes of length
Value, where value can be
- Integer data
- ASCII string data
- …
- A sequence of things ..

For example

16304765 6E657261… is

Type 16 is an ASCII string
of length 0x30
with value 0x4765… which translates to EBCDIC Genera…

30068704 0A010102

Type 30 is a sequence (it happens to be a sequence of one element)
Of length 6
- The value is a dotted decimal IP address of length 4
- with value 0A010102 – which is 10.1.1.2.

Certificate 2
==========
Certificate algorithm :x509_alg_sha256WithRsaEncryption
Serial number Hex     :68
Subject name          :CN=10.1.1.2,OU=SSS,O=NISTEC256
Issuers name          :CN=DocZosCA,OU=CA,O=COLIN
Not Before            :26/04/05 00:00:00
Not After             :27/04/05 23:59:59
Extension 1
============
Extension type:x509_ext_unknown
DER IA5String: Generated by the Security Server for z/OS (RACF)
 
Extension 2
============
Extension type:x509_ext_subjectAltName
DER Dotted address: 0x0A010102 
 
Extension 3
============
Extension type:x509_ext_keyUsage
DER BitString: 0x0780
Sample output

Extension 4
============
Extension type:x509_ext_subjectKeyIdentifier
DER Octet: 0xF421DD55 F00BEE6E E81B97D2 1D5556AB A671EC59 
 
Extension 5
============
Extension type:x509_ext_authorityKeyIdentifier
DER Context: 0xCAD12CE6 AACB598C 6E9595CD D812C90A C9C4C289

Example of using system ssl to sign some data

System SSL, also known as GS kit, provides an API for doing

TLS handshakes
Keyring manipulation
Encryption and signing of data

This blog post covers how to sign data. I wrote it because I could not find useful samples to get me started.

First steps in using system ssl gives some introductions to gskit.
Compiling a gsk program
Example of system ssl to display keyring information
Example of using system ssl to print certificate information.

Signing data

To digitally sign data, you

perform a check sum calculation on the data,
encrypt the checksum with a private key,
package up make the data, the encrypted checkum, and the originator’s public certificate.

The recipient

checks the validity of the certificate
extracts the public key
decrypts the encrypted checksum
does a checksum of the enclosed data
compares the two checksums.

The checksums should match.

How the defining structures work together

Reference to fields

The definition of a record read from a keyring is

			
typedef struct _gskdb_record { 
    gskdb_record_type           recordType; 
    gsk_octet                   recordFlags; 
    gsk_octet                   rsvd_1[1]; 
    gsk_int32                   recordId; 
    gsk_int32                   issuerRecordId; 
    char *                      recordLabel; 
    union { 
        x509_certificate        certificate; 
        pkcs_cert_request       request; 
    } u; 
    pkcs_private_key_info       privateKey; 
    gsk_octet                   rsvd_2[16]; 
} gskdb_record; 

		

This has information about certificate, and the private key.

If you have a variable pRecord as a pointer to this structure, you can refer to the private key as pRecord->privateKey.

Because this structure can be used for both a certificate and a certificate request to refer to a certificate you have to use pRecord->u.certificate to locate the certificate.

Arrays of objects

Some API functions take one certificate, and others take an array of certificates. See Arrays of objects.

To sign some data

			
printf("....SIGN the data\n");         
//  pRecord points to the default record 
gsk_buffer indata; 
gsk_buffer outdata; 
// Create the data to sign
indata.data = "ABCDEF"; 
indata.length = 6; 
outdata.data  ="OUTDATA "; // dummy data
outdata.length = 6 ;    
// Define the certificate(s) to be used
pkcs_certificate cert; 
cert.type = pkcs_certtype_certificate  ; 
cert.u. certificate = pRecord -> u.certificate;
pkcs_cert_key cert_key[1];
cert_key[0].certificate =  cert; 
cert_key[0].privateKey  =  pRecord -> privateKey; 
// create our structure of an array of keys
// Note the structure is pkcs_cert_key>s< which contains 
// one or more cert_key structures.
pkcs_cert_keys cert_keys; 
cert_keys.count = 1; 
cert_keys.certKeys = &cert_key[0]; 
  
// pkcs_certificates certs; 
                
gsk_process_option po; 
po.enforce_keyusage = 0; 
po.enforce_content_length = 0; 
po.enforce_keyparity = 0; 
po.create_detached_signature  = 0; 
gskrc =  gsk_make_signed_data_msg_extended 
        (po, // no options
         0, // version 
         x509_alg_sha1Digest, // algoritm 
         1, // include certs in the output
         &cert_keys, // the certs to use
         0, // no ca certs 
         &indata, 
         0, // no attrib signers 
         &outdata); 
          
if (gskrc == 0) 
   printf("gsk_make_signed_data_msg_extended worked\n"); 
else 
{ 
    printf("gsk_make_signed_data_msg_extended. %8.8x %s\n",
           gskrc,gsk_strerror(gskrc)); 
    return 8; 
} 
printf("Outdata length %i\n",outdata.length);
printHex(stdout,outdata.data,outdata.length);

		

This produced

00000000 : 3082048C 06092A86 4886F70D 010702A0  ................ .b.....f.f7..... 
00000010 : 82047D30 82047902 0100310B 30090605  ................ b.'.b.`......... 
00000020 : 2B0E0302 1A050030 1506092A 864886F7  ................ ............f.f7 
00000030 : 0D010701 A0080406 C1C2C3C4 C5C6A082  ................ ........ABCDEF.b 
00000040 : 03023082 02FE3082 01E6A003 02010202  ................ ...b...b.W...... 
00000050 : 0168300D 06092A86 4886F70D 01010B05  ................ .......f.f7..... 
00000060 : 00303031 0E300C06 0355040A 1305434F  ................ ...............| 
00000070 : 4C494E31 0B300906 0355040B 13024341  ................ <.+............. 
...
00000460 : B6CBA3F3 48B5C9CD 76063F2D 007840A7  ................ ..t3..I....... x 
00000470 : 0C8EF6FE 5442459E 47F6C1D0 12F1247E  ................ ..6......6A}.1.= 
00000480 : 0DC79B03 7723D129 078D1DB9 812F6EB9  ................ .G....J.....a.>.

In the data is

ABCDE – the original data
3082048c – I recognise this as ANS-1 encoding. (ASN.1) is a standard interface description language (IDL) for defining data structures that can be serialized and deserialized in a cross-platform way. It is broadly used in telecommunications and computer networking, and especially in cryptography.
- For example 048c is the length of data following

Once the signature has been obtained, it can be externalised (such as writing to a file) and sent to a remote site.

Because the data is in hexadecimal you may wish to convert it to EBCDIC for transport. You can use the

gsk_encode_base64 (gsk_buffer input_data,gsk_buffer_output_data);

to encode the data and use the gsk_decode_base64() to decode it.

Validate the data

The recipient can check that the signature and certificates are valid.

			
// Process the validation of the signature
// The list of input signatures 
pkcs_certificates certs; 
certs.count = 1;
certs.certificates = &cert;
gsk_attributes_signers as; 
gsk_buffer temp;  // process the data into temp.
printf("============READSIGNED======\n"); 
gsk_boolean ul; // were local certificates used?
gskrc = gsk_read_signed_data_msg_extended( 
         po, // no option 
         NULL,  // no local certificates provided / local_certificates, 
         &outdata,  // the signed data  
         &ul, // Set if certs were set locally or not 
         NULL, // returned cert not needed // msg_certificates 
         NULL, // signer_certificates 
         &as, // attrbute signers 
         &temp); 
     if (gskrc == 0) 
     { 
         printf("gsk_read_signed_data_msg_extended worked\n"); 
         printf("Use local certificates %i\n",ul);
         printHex(stdout,temp.data,temp.length); 
     } 
     else 
     { 
         printf("gsk_read_signed_data_msg_extended. %8.8x %s\n",
                gskrc,gsk_strerror(gskrc)); 
         return 8; 
     } 

		

When this executed it produced

gsk_read_signed_data_msg_extended worked
Use local certificates 0
00000000 : C1C2C3C4 C5C6                        ......           ABCDEF

which matches the original input data.

With

			
gskrc = gsk_read_signed_data_msg_extended( 
         po, // no option 
         NULL,  // no local certificates provided / local_certificates, 
         ...

Only certificates in the data were used. “Use local certificates” was 0.

When

			
gskrc = gsk_read_signed_data_msg_extended( 
         po, // no option 
         &certs, // use local certificates provided
         ...

it used the certificate(s) from my keyring. “Use local certificates” was 1.

My final code was

			
pkcs_certificates msgcerts;
pkcs_certificates signercerts;
gsk_attributes_signers as; 
gskrc = gsk_read_signed_data_msg_extended( 
         po, // no option 
         &certs, // local_certificates, 
         &outdata,  // stread output
         &ul, // Set if certs were set locally or not 
         &msgcerts,  // returned msg_certificates 
         &signercerts, // signer_certificates 
         &as, // attrbute signers 
         &temp); 
if (gskrc == 0) 
{ 
    printf("gsk_read_signed_data_msg_extended worked\n"); 
    printf("Use local certificates %i\n",ul);
    printHex(stdout,temp.data,temp.length); 
    printf("====MSGCERTS+++\n");
    // print_pkcs_certificates(&msgcerts);
    print_certs(&msgcerts);
    printf("====Signers++\n");
    print_certs(&signercerts);
    // print_pkcs_certificates(&signercerts);
} 
else 
{ 
    printf("gsk_read_signed_data_msg_extended. %8.8x %s\n",
           gskrc,gsk_strerror(gskrc)); 
    return 8; 
}
  

		

An easy question: how do you print a long long nicely as hex?

I wanted to print a long long nicely, consistent with other lines of output. It took me a while to get working properly.

The code

printf("...  %20.16llx\n",ll);

The x means print as hexadecimal
ll means treat the value as a long long
20.16. The 20 is the the minimum number of characters printed. The second 16 specifies the number of characters to be output. In the past, I’ve used formatting to print numbers so they line up in a column.

Below is the formatting string, and the output

.%16.llx.    .              68.
.%16.16llx.  .0000000000000068.
.%.llx.      .68.
.%llx.       .68.

My final formatting string is

printf("Serial Number in hex:%llx\n",ll);

Serial Number in hex:68

It is another of the “it is always easy when you know the answer”.

My original problem was “how do you nicely print a variable length string”.

I solved it

			
char longChar[8];
char * pData;      // points to the data
int lData = ...  ; // length of the data
memset(&longChar[0],0,sizeof(longChar); // clear it to 0
memcpy(&longChar[8-lData],
       pdata, 
       lData
      ); 
long long ll;        
memcpy(&ll,&longChar,8);       
printf("Serial number Hex %llx\n",ll);

		

There may be better ways of doing it (please suggest a better way of doing it), but it works.

Why is the size of my enum larger than yours?

I’ve been doing some coding with GSK, system SSL, and had problems getting the data to match.

There are some definitions and my code

			
typedef enum { 
    gskdb_rectype_unknown       = 0, 
    gskdb_rectype_keyPair       = 1, /* Request key pair */ 
    gskdb_rectype_certificate   = 2, /* Certificate */ 
    gskdb_rectype_certKey       = 3, /* Certificate with key */ 
    gskdb_rectype_maximum       = 32767 
} gskdb_record_type; 
typedef struct _gskdb_record { 
    gskdb_record_type           recordType; 
    ....
} gskdb_record; 
...
gskdb_record ccp;
    
printf("Length %i\n",sizeof(ccp .recordType));

		

It prints out a length of 4.

If I display the data in the control block, the value of ccp.recordType is 0x0003C000.

This had me scratching my head. It needed a trip to the shops, and lunch before I spotted the problem

In the options section of the compiler list it had

 *ENUMSIZE(INT)

This says treat all enums as integer. The default is enums(SMALL).

The smallest size of gskdb_record_type is 2 bytes, but I had specified use 4 bytes. The true value of the field is 0x003 (Certificate with key) rather than an undefined 0003c000!

I removed the -qenum=int from my compiler switches.

When I recompiled, and reran the program – it all worked, giving the result 3 -> certificate with key!