Tag: keyring

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

Why did my certificate mapping go wrong?

I had a working mapping for a Linux generated certificate to a z/OS userid. And then it wasn’t working. It took me 2 days before I had enlightenment. Although I had undone all of the changes I had made – well all but one.

I had defined

//IBMRACF  JOB 1,MSGCLASS=H 
//S1  EXEC PGM=IKJEFT01,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD * 
RACDCERT DELMAP(LABEL('colinpaice'))ID(IBMUSER) 
RACDCERT MAP ID(IBMUSER)  - 
   WITHLABEL('colinpaice') - 
   SDNFILTER('CN=colinpaice.O=cpwebuser.C=GB') 
SETROPTS RACLIST(DIGTNMAP, DIGTCRIT) REFRESH 
racdcert listMAP id(IBMUSER) 
/*

Which says it the certificate with Subject: C = GB, O = cpwebuser, CN = colinpaice come in, then it maps to IBMUSER. Yes, the terms are in a different order, and there are “.” instead of “.” but it worked.

I started working with JSON Web Tokens (JWT), and it stopped working. The userid was coming out as IZUSVR – which is the userid of z/OSMF. I struggled with traces, and wrote my own little program to map the certificate to a userid – but still it was IZUSVR.

The enlightenment.

With JWT they are signed by a private key, and the public key is used to check the signature (that is check the checksum of the data is valid). To do this, the keyring needs the certificate in the keyring.
I was lazy and used the same certificate to sign the JWT, as I used to do certificate logon to z/OSMF.

To put the certificate in the keyring you need to import the certificate. I copied the certificate from Linux, using cut and paste and imported it

I used

//IBMRACF2 JOB 1,MSGCLASS=H 
//S1  EXEC PGM=IKJEFT01,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD * 
RACDCERT CHECKCERT('COLIN.COLIN.PAICE.PEM') 
RACDCERT DELETE  (LABEL('COLINPAICE')) ID(IZUSVR) 
RACDCERT ADD('COLIN.COLIN.PAICE.PEM')  - 
   ID(IZUSVR)  WITHLABEL('COLINPAICE') TRUST 
                                                             
                                                             
RACDCERT ID(IZUSVR) CONNECT(RING(CCPKeyring.IZUDFLT)  - 
                            USAGE(CERTAUTH)  - 
                            LABEL('COLINPAICE') - 
                              id(IZUSVR)) 
                                                             
SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh 
/*

This imports the certificate and associates it with the specified userid, ID(IZUSVR).
Now, when the certificate arrives as part of the certificate logon to z/OSMF, it checks to see if it is in the RACF data base – yes it is – under userid IZUSVR. It does not use the RACDCERT MAP option.

I reran this job with userid ADCDB – and the JWT had ADCDB in the definition.

To make it more complex, the Liberty Web Server within z/OSMF caches some information, and this complicated the diagnosis. In the evening it worked – next morning after IPL – it didn’t!

Lesson learned

Use one certificate for certificate logon, and another certificate for JWT.

Secure store aren’t

Applications such as Zowe can store secure information on the end user’s machine. This is not very secure! It is built into the operating systems. It is a bit like securing a door with a bit of string. Joshua Waters pointed out

The fact of the matter is that regardless of whether or not you are storing your credentials on a machine, if there is a virus or malicious actor on it, your credentials are up for grabs while the user is logged in. The only time they wouldn’t be up for grabs is if you were using an application that either require some master key to access the credentials store for it, or every authed request to the server requires user to re-enter credentials.

On Linux

The information is in the gnome-keyring ~/.local/share/keyrings/login.keyring .

You can use the Linux command seahorse to display the contents of the gnome-keyring. The user’s password is used to decrypt the store.
The following python code display the keyring contents

import secretstorage
conn = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(conn)
for item in collection.get_all_items():
    print('='*30)
    print('label:', item.get_label())
    print('attributes:')
    for k,v in item.get_attributes().items():
        print('\t%-12s: %s' % (k,v))
    print('secret:',item.get_secret())

This gave

label: Zowe/secure_config_props
attributes:
	account     : secure_config_props
	service     : Zowe
	xdg:schema  : org.freedesktop.Secret.Generic
secret: b'eyIva...9fQ=='

The secret is based64 encoded. You can decode it (on Linux) with

base64 -d <<<"eyIva...9fQ=="

This gave

{"/home/colinpaice/ssl/ssl2/zowe.config.json":
  {"profiles.project_base.properties.user":"colin",
  "profiles.project_base.properties.password":"password"
  }
}

Where /home/colinpaice/ssl/ssl2/zowe.config.json is the name of the configuration file it applies to.

You can delete an entry using

import secretstorage
conn = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(conn)
for item in collection.get_all_items():
    print('='*30)
    print('label:', item.get_label())
    if item.get_label() == "Zowe/secure_config_props":
        item.delete()
        print("delete")
        continue

This deletes all of the entries for that component – so all the Zowe data.

Who can see the contents of the store?

Your gnome-keyring is encrypted with your password, so you can access it. Someone one else would need your password to be able to decrypt it and see the contents.

What happens on other platforms?

On Windows and Mac’s it is essentially the same. There is a secure disk, and you need to be running as the owner to access it.

If your machine is infected with a virus, which runs under your userid, it can access the key stores and so get userid and password information store in the “secure store”.

Solving certificate problems in Java on z/OS

I spent many any hour trying to understand why z/OSMF was getting a message saying certificate not found in keyring, when it was always there when I checked it.

I tried Java trace options but they did not help. I have my own Java program, and that gave me a message from IRRSDL00 (the callable service to access keyrings). But when I did a RACF GTF trace to get see what was going on I got no entries in the trace. Weird. Once I solved the problems, the solution was obvious.

My Java program reported

java.io.IOException: The private key of NEWTECCTEST is not available or no authority to access the private key

z/OSMF report

[ERROR ] CWPKI0024E: The NISTECCTEST certificate alias specified by the attribute serverKeyAlias is either not found in KeyStore safkeyring://START1/MQRING or it is invalid.

The problem and the solution

The message The private key … is not available or no authority to access the private key. Has a hint as to the problem. The documentation is hidden away. It was not as bad as

It was on display in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying ‘Beware of the Leopard.”

but it is not easy to find. It says

Applications can call the R_datalib callable service (IRRSDL00) to extract the private keys from certain certificates after they have access to the key ring. A private key is returned only when the following conditions are met:

  1. For RACF real key rings:
    • User certificates An application can extract the private key from a user certificate if the following conditions are met:
      • The certificate is connected to the key ring with the PERSONAL usage option.
      • One of the following two conditions is true:
        • The caller’s user ID is the user ID associated with the certificate if the access to the key ring is through the checking on IRR.DIGTCERT.LISTRING in the FACILITY CLASS, or
        • The caller’s user ID has READ or UPDATE authority to the <ringOwner>.<ringName>.LST resource in the RDATALIB class. READ access enables retrieving one’s own private key, UPDATE access enables retrieving other’s.

I had a keyring START1.MQRING and the start task userid had read access to it. Within the keyring was the certificate NISTECCTEST owner by userid START1. The started task userid needs UPDATE access to the keyring to be able to access the private key belonging to a different userid.

Reasons for “not found” reason code

Under the covers the callable server IRRSDL00 is called. The reason code are documented here. You might get SAF return code 8, RACF return code 8, RACF reason code 44.

  • The certificate was not in the keyring
  • It was NOTRUST
  • It had expired
  • The CA for the certificate was not in the keyring,
  • The userid did not have update access to the keyring when there are private certificates from other userids.