How do I get my client talking to the server with a signed certificate

Signed certificates are very common, but I was asked how I connected my laptop to my server, in the scenario “one up” from a trivial example.

Basic concepts

• A private/public key pair are generated on a machine. The private stays on the machine (securely). The public key can be sent anywhere.
• A certificate has ( amongst other stuff)
  • Your name
  • Address
  • Public key
  • Validity dates

Getting a signed certificate

When you create a certificate: it does a checksum of the contents of the certificate, encrypts the checksum with your private key, and attaches this encrypted value to the certificate.

Conceptually, you go to your favourite Certificate Authority (UKCA) building and they Sign it

• They check your passport and gas bill with the details of your certificate.
• They attach the UKCA public key to your certificate.
• They do a checksum of the combined documents.
• They encrypt the checksum with the the UKCA private key, and stick this on the combined document.

You now have a signed certificate, which you can send it to anyone who cares.

Using it

When I receive it, and use it

• my system compares my copy of the UKCA public certificate with the one in your certificate – it matches!
• Using (either) UKCA public certificate – decrypt the encrypted checksum
• Do the same checksum calculation – and the two values should match.
• If they match I know I can trust the information in the certificate.

This means the checking of the certificate requires the CA certificate that signed it.

To use a (Linux) certificate on z/OS you either need to

• issue the RACF GENCERT command on the Linux .csr file, export it, then download it to Linux. The certificate will contain the z/OS CA’s certificate.
• import the Linux CA certificate into RACF (This is the easy, do once solution.)

then

• connect the CA certificate to your keyring, and usually restart your server.

Setting up my system

If the CA certificate is not on your system, you need to import it from a dataset.

You can use FTP, or use cut and paste to the dataset.

Once you have the CA certificate in your RACF database you can connect it to your keyring.

• Creating my Linux CA and copying it to z/OS
• Getting my Linux certificate signed by z/OS

Create my Linux CA and copy it to z/OS

CA="docca256"
casubj=" -subj /C=GB/O=DOC/OU=CA/CN=LINUXDOCCA2564"
days="-days 1095"
rm $CA.pem $CA.key.pem

openssl ecparam -name prime256v1 -genkey -noout -out $CA.key.pem

openssl req -x509 -sha384 -config caca.config -key $CA.key.pem -keyform pem -nodes $casubj -out $CA.pem -outform PEM  $days

openssl x509 -in $CA.pem -text -noout|less

Where my caca.config has

####################################################################
[ req ]
distinguished_name = ca_distinguished_name
x509_extensions    = ca_extensions
prompt             = no

authorityKeyIdentifier = keyid:always,issuer:always

[ca_distinguished_name ]
[ ca_extensions ]

subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always 
basicConstraints       = critical,CA:TRUE, pathlen:0
keyUsage               = keyCertSign, digitalSignature,cRLSign

Running the command gave

Certificate:
    Data:
        ...
        Issuer: C = GB, O = DOC, OU = CA, CN = LINUXDOCCA256
        ...
        Subject: C = GB, O = DOC, OU = CA, CN = LINUXDOCCA256
        ...
        X509v3 extensions:
           ...
            X509v3 Basic Constraints: critical
                CA:TRUE, pathlen:0
            X509v3 Key Usage:
               Digital Signature, Certificate Sign, CRL Sign
            ...

Where it has CA:TRUE and X509v3 Key Usage:Certificate Sign

Which allows this to be used to sign certificates.

Installing the CA certificate on z/OS

You need to copy the docca256.pem file from Linux to a z/OS dataset (Fixed block, lrecl 80, blksize 80) you can use FTP or cut and paste. I used dataset COLIN.DOCCA256.PEM.

Import it into z/OS, and connect it to the START1.MYRING keyring as a CERTAUTH.

//COLRACF  JOB 1,MSGCLASS=H 
//S1  EXEC PGM=IKJEFT01,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD * 
RACDCERT CHECKCERT('COLIN.DOCCA256.PEM') 
                                                             
 *RACDCERT DELETE  (LABEL('LINUXDOCA256'))    CERTAUTH 
RACDCERT ADD('COLIN.DOCCA256.PEM')        - 
   CERTAUTH  WITHLABEL('LINUXDOCA256') TRUST 

RACDCERT   CONNECT(CERTAUTH    LABEL('LINUXDOCA256') - 
  RING(MYRING) USAGE(CERTAUTH)) ID(START1) 

SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh 
/* 

Once you have connected the CA to the keyring, you need to get the server to reread the keyring, or restart the server.

Getting my Linux certificate signed by z/OS

This works, but is a bit tedious for a large number of certificates.

I created a certificate request file using

timeout="--connect-timeout 10"
enddate="-enddate 20290130164600Z" 

ext="-extensions end_user"

name="docec384Pass2"
key="$name.key.pem"
cert="$name.pem"
p12="$name.p12"
subj="-subj /C=GB/O=Doc3/CN="$name 
rm $name.key.pem
rm $name.csr
rm $name.pem
passin="-passin file:password.file"
passout="-passout file:password.file"
md="-md sha384"
policy="-policy signing_policy"
caconfig="-config ca2.config"
caextensions="-extensions clientServer"


openssl ecparam -name  secp384r1 -genkey -noout -out $name.key.pem 
openssl req -config openssl.config -new -key $key -out $name.csr -outform PEM -$subj $passin $passout

The certificate request file docec384Pass2.csr looks like

-----BEGIN CERTIFICATE REQUEST----- 
MIIBpzCCAS0CAQAwNDELMAkGA1UEBhMCR0IxDTALBgNVBAoMBERvYzMxFjAUBgNV 
...
Tmmvu/nqe0wTc/jJuC4c/QJt+BQ1SYMxz9LiYjBXZuOZkpDdUieZDbbEew== 
-----END CERTIFICATE REQUEST----- 

With words CERTIFICATE REQUEST in the header and trailer records.

Create a dataset(COLIN.DOCLCERT.CSR) with the contents. It needs to be a sequential FB, LRECL 80 dataset.

• Delete the old one
• Generate the certificate using the information in the .csr. Sign it with the z/OS CA certificate
• Export it to a dataset.

//IBMRACF2 JOB 1,MSGCLASS=H 
//S1  EXEC PGM=IKJEFT01,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD *                                                    

RACDCERT ID(COLIN ) DELETE(LABEL('LINUXCERT')) 
                                                                    
RACDCERT ID(COLIN) GENCERT('COLIN.DOCLCERT.CSR') - 
   SIGNWITH (CERTAUTH LABEL('DOCZOSCA')) - 
   WITHLABEL('LINUXCERT') 
                                                                    
RACDCERT ID(COLIN)   LIST(label('LINUXCERT')) 
RACDCERT EXPORT(label('LINUXCERT'))    - 
    id(COLIN)                          - 
    format(CERTB64 )  - 
    password('password')    - 
    DSN('COLIN.DOCLCERT.PEM' ) 

SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh 

Then you can download COLIN.DOCLCERT.PEM to a file on Linux and use it. I used cut and paste to create a file docec384Pass2.zpem

I used it like

set -x 
name="colinpaice"
name="colinpaice"
name="docec384Pass2"
insecure=" "
insecure="--insecure"
timeout="--connect-timeout 100"
url="https://10.1.1.2:10443" 
trace="--trace curl.trace.txt"	
 	
cert="--cert  ./$name.zpem:password"
key="--key $name.key.pem"

curl -v $cert $key $url --verbose $timeout $insecure --tlsv1.2  $trace

Using wireshark I can see CA certificates being send from z/OS, and the docec384Pass2.lpem used; signed by a z/OS CA certificate.

Using the certificate in the Chrome browser.

• In Chrome settings, search for cert.
• Click security
• Scroll down to Manage certificates, and select it
• Select customised
• Select import, and then select the file.
  • When I generated the file with the Linux CA it had a file type of .pem
  • When I signed it on z/OS, then downloaded it with a type of.zpem, I had to select all files (because the defaults are *.pem,*.csr,*.der..)