Tag: gsk_strerror

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

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.

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

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; 
}