This question came up in an email exchange after someone had upgraded openssl from 1.1.1f to v3.
There are two format certificates – text, and binary.
Text certificate
The text certificate looks like
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 633 (0x279)
Signature Algorithm: ecdsa-with-SHA384
...
-----BEGIN CERTIFICATE-----
MIICgTCCAiegAwIBAgICAnkwCgYIKoZIzj0EAwMwOjELMAkGA1UEBhMCR0IxDDAK
BgNVBAoMA0RPQzELMAkGA1UECwwCQ0ExEDAOBgNVBAMMB1NTQ0EyNTYwHhcNMjMw
MzE5MTIzODA1WhcNMjQwMTMwMTY0NjAwWjAuMQswCQYDVQQGEwJHQjEMMAoGA1UE
CgwDRG9jMREwDwYDVQQDDAhkb2NlYzI1NjBZMBMGByqGSM49AgEGCCqGSM49AwEH
...
-----END CERTIFICATE-----
This has both a text version, and a base 64 encoded version within it.
On z/OS create a dataset with this file. Then use JCL like
//S1 EXEC PGM=IKJEFT01,REGION=0M
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT CHECKCERT('COLIN.DOCEC256.NEW.PEM')
This checks the file is usable, and you can check the contents before you install it on your system.
It produced output like
Certificate 1:
Start Date: 2023/03/19 12:38:05
End Date: 2024/01/30 16:46:00
Serial Number:
>0279<
Issuer's Name:
>CN=SSCA256.OU=CA.O=DOC.C=GB<
Subject's Name:
>CN=docec256.O=Doc.C=GB<
Subject's AltNames:
IP: 127.0.0.1
Domain: localhost
Signing Algorithm: sha384ECDSA
Key Usage: HANDSHAKE, DATAENCRYPT, DOCSIGN, KEYAGREE
Key Type: NIST ECC
Key Size: 256
...
It also gave me
Chain information: Chain contains 1 certificate(s), chain is incomplete
This message is because “A certificate chain is considered incomplete if RACF is unable to follow the chain back to a self-signed ‘root’ certificate”.
Which was true, RACF already had the CA in its database, and the CA certificate was not in the file.
When the file had already been imported I also got
Certificate 1: Digital certificate information for CERTAUTH: Label: Linux-CARSA
So I know it had already been imported into RACF.
I also got
Chain contains expired certificate(s)
So I could tell I needed to get a newer certicate.
Add it to the RACF key store
There is no add-replace, so you have to delete it, then add it
RACDCERT DELETE -
(LABEL('DOCEC256')) ID(COLIN)
RACDCERT ID(COLIN) ADD('COLIN.DOCEC256.NEW.PEM') -
WITHLABEL('DOCEC256')
SETROPTS RACLIST(DIGTNMAP, DIGTCRIT) REFRESH
The first time I ran this I got
RACDCERT DELETE (LABEL('DOCEC256')) ID(COLIN)
IRRD107I No matching certificate was found for this user.
READY
RACDCERT ID(COLIN) ADD('COLIN.DOCEC256.NEW.PEM') WITHLABEL('DOCEC256')
IRRD199I Certificate with label 'DOCEC256' is added for user COLIN.
IRRD175I The new profile for DIGTCERT will not be in effect until a SETROPTS REFRESH has been issued.
The second time I ran it I got
RACDCERT DELETE (LABEL('DOCEC256')) ID(COLIN)
IRRD176I RACLISTed profiles for DIGTCERT will not reflect the deletion(s) until a SETROPTS REFRESH is issued.
READY
RACDCERT ID(COLIN) ADD('COLIN.DOCEC256.NEW.PEM') WITHLABEL('DOCEC256')
IRRD199I Certificate with label 'DOCEC256' is added for user COLIN.
IRRD175I The new profile for DIGTCERT will not be in effect until a SETROPTS REFRESH has been issued.
Refresh the RACLISTed data
If the classes are RACLISTed (cached in memory), you need
SETROPTS RACLIST(DIGTNMAP, DIGTCRIT) REFRESH
What happens if it is already in the key store under a different userid?
I tried adding it for a different userid and got
RACDCERT ID(ADCDA) ADD('COLIN.DOCEC256.NEW.PEM') WITHLABEL('DOCEC256')
IRRD109I The certificate cannot be added. Profile 0279.CN=SSCA256.OU=CA.O=DOC.C=GB is already defined.
Unfortunately it does not tell you the id it has already been defined for.
The only way I found of finding this information is
- displaying all resources under class(DIGTCERT).
- find the resource with the matching name.
For example
//COLRACF JOB 1,MSGCLASS=H //S1 EXEC PGM=IKJEFT01,REGION=0M //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * RLIST DIGTCERT * /* //
gave me output like
CLASS NAME
----- ----
DIGTCERT 0279.CN=SSCA256.OU=CA.O=DOC.C=GB
...
APPLICATION DATA
----------------
ADCDF
the current owner is ADCDF.
The serial number of the certificate is 0279, and the components are separated with periods ‘.’.
If the name has a blank in it you will get a value like
COLIN4Certification¢Authority.OU=TEST.O=COLIN
where the blank is replaced with the cent sign(¢).
Binary certificate, PKCS12, .P12
You should be able to upload the .p12 file to z/OS as a binary file and import it using the same JCL as above.
However in openssl V3 the packaging of the certificate has changed, and RACF does not yet support it.
The easiest way of getting a certificate into z/OS is to use the .pem file (grin)
ColinPaice 