If you try to create a trust store with a format of Java Key Store you get a message saying you should not be using a propriety format. After some digging around, I have found out how to create a database with a format of pkcs12 (or .p12 as it is also known).

To make a PKCS12 keystore (including the private key)

You can use open ssl to create the two parts, (public and private), and get the public part signed.

You can then create a .p12entry using

password=”-passout file:password.file -passin file:password.file”
name=”colincert”
ca=”-CAfile capem -chain “

openssl pkcs12 -export -inkey $name.key.pem -in $name.pem -out $name.p12  -name $name  $password $ca

To make a key store, importing the .p12s with the private keys,  use

rm mykey.p12
ks=” -importkeystore -destkeystore mytrust.p12″
dest=”-deststoretype pkcs12 -deststorepass password”
src=”-srcstoretype PKCS12 -srcstorepass password”

keytool $ks $src $dest -srckeystore ecec.p12 
keytool $ks $src $dest -srckeystore ss.p12
keytool -list -v -keystore mykey.p12 -storepass password

By default it uses the alias from the -name in the openssl command.

Using the -list command without the verbose option (-v) gives

keytool -list -keystore mykey.p12 -storepass password

Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains … entries

ecec, 21-Jan-2021, PrivateKeyEntry,
Certificate fingerprint (SHA1): C3:3D:98:D1:45:DF:44:F0:13:FE:87:D9:3E:CC:22:33:A8:D6:24:91
mqweb, 21-Jan-2021, PrivateKeyEntry, 
…

So we can see this is a PKCS12 keystore with entries with a Private Key in them.

To make a trust store

A trust store only has the public parts, it does not have the private key, so creating an intermediate .p12 file does not work, you have to use the public .pem files.

rm mytrust.p12
ks=” -import -keystore mytrust.p12 -deststoretype pkcs12″
password=“-storepass:file password.file”

keytool $ks $password -file ecec.pem -alias ecec
keytool $ks  $password -file ss.pem -alias ss

keytool -list -v -keystore mytrust.p12 $password

This example uses the password stored in the file password.file, rather than specifying it in the command.

You have to supply the -alias, as it defaults to “mykey”.  If you add multiple entries with the default, you only get one entry in the keystore.

Using the -list command without the verbose option (-v) gives

keytool -list -keystore mytrust.p12 -storepass:file password.file
Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains 2 entries

ecec, 21-Jan-2021, trustedCertEntry,
Certificate fingerprint (SHA1): C3:3D:98:D1:45:DF:44:F0:13:FE:87:D9:3E:CC:22:33:A8:D6:24:91
ss, 21-Jan-2021, trustedCertEntry,
Certificate fingerprint (SHA1): E9:D1:69:49:5B:D3:B4:3C:E8:44:5A:C1:2C:A2:D6:5D:FB:47:61:E7

So we can see this is a PKCS12 keystore, and has the expected entries which are Trusted Certificate Entries.

With my first, (and second) reading of the RACF documentation it looked like z/OS could not act as my corporate Certificate Authority.  I was written up a blog post saying how to do it using Linux as my CA, when I found a couple of hints to show that z/OS could be used as a certificate authority.

The short answer on how to do it.

Create a end user certificate on z/OS

//IBMRACF JOB 1,MSGCLASS=H 
//S1 EXEC PGM=IKJEFT01,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD * 
RACDCERT ID(START1) GENCERT - 
  SUBJECTSDN(CN('MYCERT') - 
             O('SS') - 
             OU('SS')) - 
   ALTNAME(IP(10.1.1.2) - 
           DOMAIN('WWW.ME.COM') )- 
   SIZE(4096) - 
   SIGNWITH (CERTAUTH LABEL('MY-CA1')) - 
   RSA - 
   WITHLABEL('MYCERT')

This creates a certificate START1.MYCERT signed by CERTAUTH.MY-CA1

How to process a certificate created on Linux

I created a certificate on Linux in a script (so I could use a variable as part of the file name).

name=”ec2″
passwords=“-passin file:password.file -passout file:password.file”
# generate a private key in rsa format
openssl genrsa -out $name.key.pem 2048
# make a certificate request to send off to get it signed
openssl req -config mqwebserver.config -new -key $name.key.pem -out $name.csr -outform PEM -subj “/C=GB/O=cpwebuser/CN=mqwebec”  $passwords

This creates a Certificate Server Request file ec2.csr, and a private key in ec2.key.pem.

I FTP’d the .csr file to z/OS.   This is a text file, where the first line is —–BEGIN CERTIFICATE REQUEST—– so you need to FTP in text format.

With RACF you can generate a certificate by passing the information in a data set, or by specifying it on the RACDCERT GENCERT command.

I used the following job to sign the certificate using Certificate Authority DAN-CA1, passing the information in from the .CSR data set I had previously uploaded.

//S1 EXEC PGM=IKJEFT01,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD * 
RACDCERT ID(START1) GENCERT('IBMUSER.IBMUSER.EC2.CSR') - 
   SIGNWITH (CERTAUTH LABEL('MY-CA1')) - 
   WITHLABEL('MYCERT3') 

RACDCERT LIST(LABEL('MYCERT3')) ID(START1)
 
RACDCERT ID(START1) EXPORT(LABEL('MYCERT3'))- 
   DSN('IBMUSER.CERT.MYCERT3.PEM') - 
   FORMAT(CERTB64) 

SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh 

This reads the data set specified in the GENCERT() command, and takes all of the certificate parameters from it.  It is signed by the CERTAUTH with label(‘MY-CA1’) and stored in the RACF database under id(START1) with label(MYCERT3).

THE EXPORT command exports the signed certificate to a dataset.

I then FTP’d the exported data set IBMUSER.CERT.MYCERT3.PEM back to Linux.

I merged the two parts back together to create a .p12 combined file with

openssl pkcs12 -export -inkey ec2.key.pem -in dancert3.pem -out mycert3.p12 -name mycert3 -passout file:password.file -passin file:password.file

and displayed the .p12 file with

pk12util -l mycert3.p12

This gave me

Certificate(has private key):
Data:
  Version: 3 (0x2)
  Serial Number: 4 (0x4)
  Signature Algorithm: PKCS #1 SHA-256 With RSA Encryption
  Issuer: "CN=MYCA1,OU=SSS,O=SSS"
  Validity:
    Not Before: Sun Jan 17 00:00:00 2021
    Not After : Mon Jan 17 23:59:59 2022
  Subject: "CN=mqwebec,O=cpwebuser,C=GB"
  Subject Public Key Info:
    Public Key Algorithm: PKCS #1 RSA Encryption
    RSA Public Key:
    Modulus:...

    Exponent: 65537 (0x10001)
  Signed Extensions:
    Name: Certificate Comment
      Comment: "Generated by the Security Server for z/OS (RACF)"

    Name: Certificate Subject Alt Name
      DNS name: "localhost"
      IP Address: 127.0.0.1

  Name: Certificate Key Usage
    Critical: True
    Usages: Digital Signature
    Non-Repudiation
    Key Encipherment

  Name: Certificate Subject Key ID
    Data:...

  Name: Certificate Authority Key Identifier
    Key ID:...

  Signature Algorithm: PKCS #1 SHA-256 With RSA Encryption
    Signature:...
    Fingerprint (SHA-256):...
    Fingerprint (SHA1):...Friendly Name: dancert3

  Key(shrouded):
  Friendly Name: mycert3

  Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC

Note: I tried exporting the file on z/OS using FORMAT(PKCS7B64) instead of FORMAT(CERTB64).
The openssl pkcs12 -export command failed with

unable to load certificates
error:0D0680A8:asn1 encoding routines:asn1_check_tlen:wrong tag:../crypto/asn1/tasn_dec.c:1149:
error:0D07803A:asn1 encoding routines:asn1_item_embed_d2i:nested asn1 error:../crypto/asn1/tasn_dec.c:309:Type=X509_CINF
error:0D08303A:asn1 encoding routines:asn1_template_noexp_d2i:nested asn1 error:../crypto/asn1/tasn_dec.c:646:Field=cert_info, Type=X509
:error:0907400D:PEM routines:PEM_X509_INFO_read_bio:ASN1 lib:../crypto/pem/pem_info.c:196:

If you get these messages download it in the proper format.

The longer answer…

When setting up certificates you have several options

1. Use a Self Signed certificate.  This offers very little security, as anyone can create a certificate one.   This should only be used for testing, though I think you should never use them, as you need to test with signed certificates because of the additional work that needs to be done.  Imagine conversation with your manager “Did you test this?”  “No, I tested something else”.
2. Get a certificate from recognised authority.   You pay for each certificate you get.  As the authority’s certificate is generally available you can use your certificate as soon as you get it.
3. Set up your own authority you create your own high level certificate such as CN=TOPLEVELCA O=MYORG, which in turn creates other certificates such as CN=TESTCA, O=MYORG, and CN=PRODUCTIONCA O=MYORG.  You can create as many certificate as you wish for example using the TESTCA for certificates that can be used in test.
4. A combination of both, you get a High level Certificate Authority certificate signed by a recognised authority, and then used that  to set up your own certificates.

What does a “certificate” contain?

There are two parts

1. The certificate identified the “who”, along with the public key.
2. The private key used in encryption.

What does “signing”  mean?

You take a block of data, and do a calculation on it, for example a checksum.  The signer takes the checksum and encrypts it using its private key.  The original block of data then has the encrypted checksum, and the signers public key appended to it.

To check the signature,

1. You compare the signers public key with your copy of it and check it matches.  If they match you decrypt the encrypted checksum.
2. You perform the same calculation on the original payload and check your calculation with the decrypted version.  If they match you know the data is good.

Signing a certificate is doing this with a certificate as the block of data.

If you have a corporate CA certificate, and a departmental CA certificate, the departmental certificate has been signed by the corporate CA.  When you sign a block of data, it will have the departmental certificate, and the corporate certificate appended.

How does a Certificate Authority work?

At the top of the Certificate Authority hierarchy is a generally available self signed certificate with its public key.

• I create a personal certificate with  “who” and the public key, and the private key.
• I send the personal certificate with  “who” and the public key, known as a Certificate Signing Request(CSR) to my security department, who sign it and return it.
• I merge the signed “who” and the public key, with the private key, and store it in my key store.

Although I disapprove of using self signed certificates, (it is like having a secure lock on one door, but you leave another door open).   Sometimes there is a need to use one on the journey to using signed certificates – just to get the environment working.

Create the certificate on Linux

On Linux, I set up a bash script to create the self signed certificate.  (I used a bash script so I can parametrize values, and “name” is used in many places.)

subj=’-subj /C=GB/O=SSS/CN=SS’
addext=’-addext keyUsage=keyCertSign,digitalSignature ‘
name=’ss’
passwords=”

#remove the old files for this cert
rm $name.pem $name.key.pem $name.p12

#create the  certificate and the private key
openssl req -x509 -newkey rsa:4096 -nodes -out $name.pem -keyout $name.key.pem $subj $addext

#Compine the two files into a p12 (PKCS12) file.
openssl pkcs12 -export -inkey $name.key.pem -in $name.pem -out $name.p12 -name $name $passwords

#display it
openssl x509 -in $name.pem -text -noout|less

This creates the certificate file, the key file and a .p12 file to be used by my application.

FTP the certificate file, ss.pem, to z/OS as text.  Once you have FTPed the file, check the first line is “—–BEGIN CERTIFICATE—–“

Add it to RACF

//IBMRACF JOB 1,MSGCLASS=H 
//S1 EXEC PGM=IKJEFT01,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSTSPRT DD SYSOUT=* 
//SYSTSIN DD * 
RACDCERT DELETE (LABEL('MYSS')) ID(START1) 
SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh 

RACDCERT ADD('IBMUSER.MY.SS.PEM') - 
  ID(START1) WITHLABEL('MYSS') 

/* connect it to START1.TRUSTRING
RACDCERT ID(START1) CONNECT(RING(TRUSTRING ) -
    USAGE(CERTAUTH)  - 
    ID(START1) LABEL('MYSS') )  

racdcert list (label('MYSS')) CERTAUTH 

racdcert listring(TRUSTRING) id(start1) 

SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh 
/* 

The list command gave

Digital certificate information for START1:
Label: MYSS 
  Certificate ID: 2QiJmZmDhZmjgcTB1eLi 
  Status: TRUST 
  Start Date: 2021/01/18 14:14:38 
  End Date: 2021/02/17 14:14:38 
  Serial Number: 
    >73CB2B49D0E56BBEAA95EC8EA01FCCC549A97BA8<   
Issuer's Name: 
  >CN=SS.O=SSS.C=GB< 
Subject's Name: 
  >CN=SS.O=SSS.C=GB< 
Signing Algorithm: sha256RSA 
Key Type: RSA 
Key Size: 4096 
Private Key: NO 
Ring Associations: 
  Ring Owner: START1 
  Ring: 
    >TRUSTRING< 

You can see this does not have the private key.   The issuer’s name matches the Subject’s name, so this shows it is self signed.

Restart your web server to pick up the changes to the trust keyring.

Change your client to point to the .p12 file, and specify the password.

-Djavax.net.ssl.keyStorePassword=password
-Djavax.net.ssl.keyStore=/home/colin/checkTLS/ss.p12
-Djavax.net.ssl.keyStoreType=pkcs12

Restart your client.

Other ways of creating your client certificate

Above I used

openssl req -x509 -newkey rsa:4096 -nodes -out $name.pem -keyout $name.key.pem $subj $addext

to create a request.   This is actually two operations

1. Create a private key
2. Create a certificate

For some combination of parameters it may be easier to do this in two steps

Create the private key.  This creates a private key using an elliptic curve.

openssl ecparam -name secp384r1 -genkey -noout -out $name.key.pem

Create the certificate using the private key

openssl req -config eccert.config -passin password -sha384 -new -key $name.key.pem -out $name.csr -outform PEM -subj “/C=GB/O=cpwebuser/CN=”$name $password