There is a lot of configuration needed when setting up TLS(SSL) between a server and a client. There are many options and it is easy to misconfigure. The diagnostic information you get when the TLS handshake fails is usually insufficient to identify any problems.
You need the following on z/OS:
- One or more Certificate Authority certificates. You can create and use your own for testing. If you want to work with external sites you’ll need a proper (external) CA, but for validation and proof of concept you can create your own CA. You could set up a top level CA CN=CA,O=MYORG, and another one (signed by CA=CA,O=MYORG), called CN=CA,OU=TEST,O=MYORG. Either or both of the public CA certificates will need to be sent to the clients in imported into their keystore.
- A private/public key, signed by a CA, (such as signed by CA=CA,OU=TEST,O=MYORG).
- The private key is associated with a userid.
- The signing operation takes the data (the public key), does a hash sum calculation on the data, encrypts this hash sum, and stores the encrypted hash value, and CA public certificate with the original data. To check the signature, the receiving application compares the CA with its local copy, if that matches, does the same checksum calculation, decodes the encrypted hash sum – and checks the decrypted and locally calculated values match.
- A certificate is created using one from a list of algorithms. (For example, Elliptic Curve, RSA). When the certificate is sent to the client, the client needs to support the algorithm. Either end can be configured, for example, to support Elliptic Curve, but not RSA.
- A keyring to contain your private key(s) – this can also contain CA public certificates of the partners (clients or servers).
- A “site” keyring (public keystore, or trust ring) which holds the public CA certificates of all the other sites you work with. If you have only one keyring per user or application, you need to update each of them if you need to an a new CA to your environment. Many applications are only designed to work with one keyring. Java applications tend to have a key store(for the private key) and a trust store for the CAs.
- Some applications can support more than one private certificate on a keyring. The certificate needs to match what the client can support.
- For certificates which are sent to your server, you need a copy of the CA(s) used to sign the incoming certificate. If you have a copy of the CA, then you can validate any certificate that the CA signed. This means you do not have to have a copy of the public certificate of every client. You just need the CA.
- Some application need access to just one CA in the chain, other applications need access to all certificates in the CA chain.
- As part of the TLS handshake
- the client sends up a list of the valid cipher specs it supports (which algorithms, and size of key)
- the server sends down a subset of the list of cipher spec to use (from the client’s list)
- the server can also send down its certificate, which contains information such as the distinguished name CN=zSERVER, OU=TEST, O= MYORG, and host name.
- the client can validate these names – to make sure the host name in the certificate matches the host, and what it was expecting.
- if requested, the client can send up its certificate for identification. The server can validate the certificate, and can optionally map it to a userid on the server.
- A userid can be given permission to read certificate in another user’s keyring. A userid needs a higher level of authority to be able to access the private key in another id’s keyring.
Create the Certificate Authority
//IBMRACF JOB 1,MSGCLASS=H
//S1 EXEC PGM=IKJEFT01,REGION=0M
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT certauth LIST(label('DOCZOSCA'))
RACDCERT CERTAUTH DELETE(LABEL('DOCZOSCA'))
RACDCERT GENCERT -
CERTAUTH -
SUBJECTSDN(CN('DocZosCA')-
O('COLIN') -
OU('CA')) -
NOTAFTER( DATE(2027-07-02 ))-
KEYUSAGE( CERTSIGN ) -
SIZE(2048) -
WITHLABEL('DOCZOSCA')
/*
//
This certificate is created against “user” CERTAUTH. Keyusage CERTSIGN means it can be used to sign certificates. “user” CERTAUTH is often displayed internally as “irrcerta”.
Once it has been created the certificate should be connected to every ring that may use it, see below.
Export the CA certificate to a file so, clients can access it
RACDCERT CERTAUTH EXPORT(LABEL('DOCZOSCA')) -
DSN('IBMUSER.CERT.DOC.CA.PEM') -
FORMAT(CERTB64) -
PASSWORD('password')
The file looks like
-----BEGIN CERTIFICATE----- MIIDYDCCAkigAwIBAgIBADANBgkqhkiG9w0BAQsFADAwMQ4wDAYDVQQKEwVDT0xJ TjELMAkGA1UECxMCQ0ExETAPBgNVBAMTCERvY1pvc0NBMB4XDTIyMTAwOTAwMDAw ...
This can be sent to the clients, so they can validate certificates sent from the server. This file could be sent using cut and paste, or FTP.
Create the keyring for user START1.
The instructions below lists the ring first – in case you need to know what it was before you deleted it”
RACDCERT LISTRING(TN3270) ID(START1) RACDCERT DELRING(TN3270) ID(START1) RACDCERT ADDRING(TN3270) ID(START1) RACDCERT LISTRING(TN3270) ID(START1) SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh
Connect the CA to every keyring that needs to use it
RACDCERT ID(START1) CONNECT(RING(TN3270) -
CERTAUTH LABEL('DOCZOSCA'))
Create a user certificate and sign it on z/OS
This creates a certificate and gets is signed – as one operation. You can create a certificate, export it, sent it off to a remote CA, import it, and add it to a userid.
RACDCERT ID(START1) DELETE(LABEL('NISTECC521'))
RACDCERT ID(START1) GENCERT -
SUBJECTSDN(CN('10.1.1.2') -
O('NISTECC521') -
OU('SSS')) -
ALTNAME(IP(10.1.1.2))-
NISTECC -
KEYUSAGE(HANDSHAKE) -
SIZE(521) -
SIGNWITH (CERTAUTH LABEL('DOCZOSCA')) -
WITHLABEL('NISTECC521') -
RACDCERT id(START1) ALTER(LABEL('NISTECC521'))TRUST
RACDCERT ID(START1) CONNECT(RING(TN3270) -
ID(START1) -
DEFAULT -
LABEL('NISTECC521') )
SETROPTS RACLIST(DIGTCERT,DIGTRING ) refresh
RACDCERT LIST(LABEL('NISTECC521' )) ID(START1)
RACDCERT LISTRING(TN3270) ID(START1)
This creates a certificate with type Elliptic Curve (NISTECC) with a key size of 521. It is signed with the CA certificate created above.
The ALTNAME, is a field the client can verify that the Source Name in the certificate matches the IP address of the connection.
It is connected to the user’s keyring as the DEFAULT. The default certificate is used if the label of a certificate is not specified when using the keyring.
Give a user access to the keyring
PERMIT START1.TN3270.LST CLASS(RDATALIB) -
ID(COLIN ) ACCESS(UPDATE )
SETROPTS RACLIST(RDATALIB) refresh
- Update access give userid COLIN access to the private key.
- Read access only gives access to the public keys in the ring.
You would typically give a group of userids access, not just to individual userids.
Import the client’s CA’s used to sign the client certificates
This is the opposite to Export the CA certificate to a file so clients can access it above.
Copy the certificate to z/OS. This can be done using FTP or cut and paste.
Use it!
I used it in AT-TLS
TTLSConnectionAdvancedParms TNCOonAdvParms
{
ServerCertificateLabel NISTECC521
...
}
TTLSSignatureParms TNESigParms
{
CLientECurves Any
}
TTLSEnvironmentAction TNEA
{
HandshakeRole ServerWithClientAuth
TTLSKeyringParms
{
Keyring start1/TN3270
}
...
}
ColinPaice 