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.

• Compiling a gsk program
• Example of system ssl to display keyring information
• Example of using system ssl to print certificate information
• Example of using system ssl to sign some data.

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