When doing key and cert management, IBMZSecurity can been seen as a wrapper for Resource Access Control Facility (RACF®). Additionally, it also provides some conveniences and quality of life. The biggest difference is that the zseckeytool can be used in the unix-like environment of UNIX System Services (USS) without ever having to interact with Time Sharing Option/Extensions (TSO/E). This is handy if new z/OS users are coming from a Linux environment and want to use the same commands that they are used to.

Generating certificates

In RACF you would typically generate a certificate like so:

RACDCERT gencert subjectsdn(cn('mycert') ou('Server Group') o('IBM') l('Poughkeepsie') sp('NY') c('USA')) withLABEL('serviceTest')

While relatively straightforward, it might be unclear to a new z/OS user what all of these options mean and what they equate to within the certificate. The syntax might also be a little strange to a Linux user with the amount of parentheses being used.

Also, if you would like to add that certificate to a keyring, you will need to issue more commands.

RACDCERT addring("serviceTestRing")

RACDCERT connect(LABEL('serviceTest') ring("serviceTestRing") USAGE(PERSONAL))

In the above, the first command creates the keyring, and the second command connects the certificate to the keyring.

In comparison, generating a certificate using zseckeytool looks like this:

zseckeytool -J-Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider -genkeypair -keyalg RSA -storetype JCERACFKS -v -alias "serviceTest" -keystore safkeyring://IBMUSER/serviceTestRing -dname "CN=mycert, OU=Server Group, O=IBM, C=US" -sigalg SHA1withRSA

Syntactically, this is much more intuitive to someone with Linux experience, and it provides a clearer picture in regards to all of the arguments that make up the certificate. Also note that we can create the keyring and store the certificate inside that keyring in the same command. So this has the added benefit of running three RACF commands with a single command.

Listing certificates

A popular usage of zseckeytool is to list a certificate inside of a RACF keystore which will give some information as to if IBMZSecurity is configured correctly.

To list a certificate in RACF, it would look like this:

RACDCERT LIST(LABEL('serviceTest')) ID(IBMUSER)

This is more straightforward than generating a certificate, but there is also some nuance. This command requires nested parentheses, LABEL() inside of LIST(). Once again, this is not intuitive to someone used to Linux syntax and can be confusing while also being more prone to making a mistake.

To a list a certificate in zseckeytool, it is very similar to the syntax of generating a certificate.

zseckeytool -J-Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider -list -alias serviceTest -keystore safkeyring://IBMUSER/serviceTestRing -storetype JCERACFKS

A nice thing about zseckeytool in general is that the syntax is consistent and has a lot of overlap with the other commands. However, you will notice that the keystore must be specified as well. An advantage that calling RACF directly has is that it can list certificates without specifying the keyring it is associated with.

Although a caveat of that is RACF has a separate command for listing keyrings. For example:

RACDCERT LISTRING(serviceTestRing) ID(IBMUSER)

This is treated as a separate command and has it's own syntax versus the LIST command. For zseckeytool, you just need to remove the alias argument in order to list all of the certificates in the keystore.

zseckeytool -J-Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider -list -keystore safkeyring://IBMUSER/serviceTestRing -storetype JCERACFKS

Exporting certificates

Perhaps the biggest advantage that the zseckeytool has is that it can export certificates to a USS file. It also has support for multiple certificate formats such as PEM and DER. This allows the certificate file to easily be moved to other filesystems and machines. RACF can only export the certificate to a data set. It also uses confusing, non-standard format names. It uses CERTDER for DER encoded files, and CERTB64 for PEM encoded files.

To do this in RACF, it would look like this:

RACDCERT EXPORT(LABEL('serviceTest')) DSN(EXAMPLE.DSN.NAME)

The default format is CERTB64/PEM.

For zseckeytool, the command looks like this:

zseckeytool -J-Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider -export -keystore safkeyring://IBMUSER/serviceTestRing -alias serviceTest -file cert.der

This will export the serviceTest certificate to the cert.der USS file in the local directory where the command is run. It will be DER encoded by default. If you want to use PEM encoding, then all you have to do is add the -rfc argument:

zseckeytool -J-Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider -export -keystore safkeyring://IBMUSER/serviceTestRing -alias serviceTest -rfc -file cert.pem

You can then use any SFTP or SCP client to easily transfer the certificate somewhere else.

References:

USS - https://www.ibm.com/docs/en/zos/3.1.0?topic=zos-unix-system-services

RACF - https://www.ibm.com/products/resource-access-control-facility