PKI Services for z/OS

Overview: Frequently Asked Questions [FAQs]

Most browsers will soon withdraw support for non-root certificates signed with a SHA1 based signature. What do I need to do with my existing PKI Services instances?

You need to update your PKI Services configuration to use a new signature algorithm. If you have several levels of certificate authorities, you may need to change the configurations for each instance PKI Services in those levels in the correct order. Depending on the strength of the keys used by the CA certificate, you may have to renew or rekey the CA certificate as part of this process.

The instructions below can help you decide how to update PKI Services and what steps to take.

First, determine how many certificate authorities are involved in your case.

You may have several levels of certificate authorities, where one acts as a root CA and others act as intermediate CAs. Consider this example of such a structure:

root CA → intermediate CA 1 → intermediate CA 2

To properly update all the PKI Services instances in this example, start from the head of the chain and work towards the end. Make your updates to root CA first, intermediate CA 1 next, and intermediate CA 2 last.

Next, determine if you need to renew or rekey the CA certificate for each PKI Services instance.

You can skip this part:

  • For the root CA, so long as the root CA is not issuing end-entity certificates, since trust in the root CA is not based on the hash used in its signature.
  • If the CA certificate used by a PKI Services instance already has a SHA2 based signature.

For any other case, you will need to either renew or rekey the CA certificate. Which action you take should depend upon the CA certificate's validity period and its key strength.

  • If the certificate's key pair uses a strong key size, and less than half of the certificate's validity period has yet to pass, renew may be the better option for you. You will not need to distribute the new CA certificate to applications that validate certificates issued from this CA, because their copies of the original CA certificate will validate both old and new certificates issued from that CA.
  • Otherwise, rekey is your best option. This option gives you the chance to use a key pair with a stronger size, but it will require you to distribute the new CA certificate to all the applications that need to validate its newly issued certificates. These applications will still need to retain the original CA certificate so that older certificates that were issued by it can still be validated.

To renew a CA certificate:

For an Intermediate CA For a Root CA
Create a certificate request (CSR) for the issuing CA using the RACF RACDCERT GENREQ command:

RACDCERT CERTAUTH GENREQ(LABEL('CA-cert-label')) DSN(output-dataset)

The CSR will be stored in output-dataset.
Check to make sure that this instance of PKI Services has issued certificates for all approved certificate requests.
Send this CSR to the certificate authority that issued your original CA certificate, requesting that the certificate be signed with a SHA2 based signature. Shut down the PKI Services instance for that CA.
Once you receive the renewed CA issuing certificate, store the new certificate in a dataset. Create a certificate request (CSR) for the issuing CA using the RACF RACDCERT GENREQ command:

RACDCERT CERTAUTH GENREQ(LABEL('CA-cert-label')) DSN(output-dataset)

The CSR will be stored in output-dataset.
Check to make sure that this instance of PKI Services has issued certificates for all approved certificate requests. Generate the new certificate signed by itself:

RACDCERT CERTAUTH GENCERT(output-dataset) SIGNWITH(CERTAUTH LABEL('CA-cert-label')) NOTBEFORE(DATE(original start date)) NOTAFTER(DATE(original-end-date or new-end-date))
Shut down the PKI Services instance for that CA.  
Add the new certificate to RACF with the RACF RACDCERT ADD command. The certificate is to be added without a label:

RACDCERT CERTAUTH ADD(dataset_with_new_CA_cert)
 

To rekey a CA Certificate:

For an Intermediate CA For a Root CA
Generate a temporary, self-signed certificate for the issuing CA certificate using the RACF RACDCERT REKEY command:

RACDCERT CERTAUTH REKEY(LABEL('current-CA-cert-label')) WITHLABEL('new-CA-cert-label')
Check to make sure that this instance of PKI Services has issued certificates for all approved certificate requests.
Create a certificate request (CSR) for the temporary issuing CA certificate using the RACF RACDCERT GENREQ command:

RACDCERT CERTAUTH GENREQ(LABEL('new-CA-cert-label')) DSN(output-dataset)

The CSR will be stored in output-dataset.
Shut down the PKI Services instance for that CA.
Send this CSR to the certificate authority that issued your original CA certificate, requesting that the certificate be signed with a SHA2 based signature. Create a certificate request (CSR) for the issuing CA using the RACF RACDCERT GENREQ command:

RACDCERT CERTAUTH GENREQ(LABEL('CA-cert-label')) DSN(output-dataset)

The CSR will be stored in output-dataset.
Once you receive the renewed CA certificate, store the new certificate in a dataset. Generate the new certificate signed by itself:

RACDCERT CERTAUTH GENCERT(output-dataset) SIGNWITH(CERTAUTH LABEL('CA-cert-label')) SIZE(2048 or above) NOTBEFORE(DATE(original start date)) NOTAFTER(DATE(original-end-date or new-end-date))
Check to make sure that this instance of PKI Services has issued certificates for all approved certificate requests.  
Shut down the PKI Services instance for that CA.  
Add the new certificate to RACF with the RACDCERT ADD command. The certificate is to be added without a label, and will replace the temporary self-signed certificate:

RACDCERT CERTAUTH ADD(dataset_with_new_CA_cert)
 
Roll over the original issuing CA certificate to the new one that was added in the previous step using the RACF RACDCERT ROLLOVER command:

RACDCERT CERTAUTH ROLLOVER('current-CA-cert-label')) NEWLABEL('new-CA-cert-label')
 

After completing the renew or rekey, proceed to the next step.

Last, update the configuration for each instance of PKI Services

Check to make sure that this instance of PKI Services has issued certificates for all approved certificate requests.
Shut down the PKI Services instance for that CA, if it is not already shut down.
Update the PKI Services configuration file pkiserv.conf that is used by that CA to begin using a SHA2 based signing algorithm. This option is in the [CertPolicy] section of the configuration file. Change the SigAlg1 keyword value to sha-256WithRSAEncryption. For example, if your configuration file looked like this:

[CertPolicy]
 SigAlg1=sha-1WithRSAEncryption


It should now look like this:

[CertPolicy]
 SigAlg1=sha-256WithRSAEncryption
Restart the PKI Services instance for that CA.

Do not create a brand new instance of PKI Services and use a brand new issuing CA certificate in order to use a SHA2 based signature algorithm.

This is not an “easier” approach than reconfiguring your existing PKI Services instances, or easier than renewing or rekeying your existing issuing certificates. After you create this new instance, the old instance still needs to be active to create certificate revocation lists (CRLs) and to respond to OCSP requests. Instead of being a simple fix, you now have more PKI Services instances to administer and manage.

When should I consider using Elliptic Curve Cryptography (ECC) keys and RSA keys for certificates?

RSA is a long-established standard in asymmetric cryptography. Certificates using RSA keys are accepted by virtually all service providers and web browsers.

ECC is a newer standard and provides the equivalent security of large RSA keys with smaller key sizes. Larger ECC keys give a level of security that cannot be matched by the largest RSA keys. ECC is widely endorsed, but some service providers and web browsers have yet to provide support for this standard.

How do I choose between the hash algorithms that PKI Services supports for signing?

The choice of hash algorithm depends largely upon the size of the public key used in the CA certificate. The following chart offers some general guidance for picking an appropriate hash algorithm.

Size of ECC Key Size of RSA Key Suggested Hash Algorithm
  < 2048 bit SHA-1
160, 192, 224, 256, and 320 bit >= 2048 bit SHA-256
384 bit   SHA-384
512 and 521 bit   SHA-512

 

Why does PKI Services require me to start two instances of the HTTP server?

The two instances are required because two modes of SSL are required. (SSL without client authentication for requesting new certificates and SSL with client authentication for renewing or revoking existing certificates.) Unfortunately, you cannot have these two modes of SSL using only one instance of the HTTP server.

I've already purchased a certificate from a commercial certificate authority and have my z/OS HTTP server configured for SSL. Can I continue to use this webserver setup for PKI Services?

Absolutely. The setup exec (IKYSETUP) gives you an option for this.

I already have a CA certificate in RACF that I'm using to sign certificates. Can I continue to use that for PKI Services?

In most cases, yes. The setup exec (IKYSETUP) gives you an option for this. You just have to make sure that the subject's distinguished name you picked for your CA has a suffix that matches the LDAP suffix you are using.

Why does PKI Services require an LDAP directory? What is it used for?

PKI Services publishes information to an LDAP directory so that it may be retrieved by other distributed applications. This information includes the certificates issued by PKI Services, the PKI Services CA certificate, and certificate revocation information.

All I intend to use PKI Services for is to issue server certificates to be used within my intranet. Do I really need LDAP for this?

Yes. While you may not have a need to publish these certificates to LDAP, the revocation information still needs to be published.

I don't want to set up LDAP. Isn't there a way to configure PKI Services to not use LDAP?

While this is not recommended, the LDAP processing in PKI Services can be disabled by setting NumServers=0 in the [LDAP] section of the PKI Services configuration file. Understand that by doing so, you lose the ability to revoke certificates as the revocation information can no longer be published.

I successfully requested, retrieved, and revoked a test browser certificate as recommended before customization. Now I keep seeing message IKYP008E. What's that all about?

This is not a problem, at least not a serious one. The uncustomized certificate templates create certificates where the subject distinguished name suffix doesn't match the LDAP suffix you are using. Thus the certificate cannot be posted to LDAP. PKI Services will continue to attempt to post this certificate for one week before discarding it. If you wish to have this information discarded sooner, following the recommendations listed under message IKYP008E in the PKI Services Guide and Reference for setting RetryMissingSuffix=F.

When I request a server certificate, the web page expects me to supply a Base64 encoded PKCS#10 certificate request. Where do I get that?

The PKCS#10 certificate request contains the subject's name and subject's public key that will be used to create the server certificate. The certificate request is created by the server that is requesting the certificate. The procedure for creating and obtaining the certificate request varies from server to server and cannot be described here. Consult your server documentation for more information.

Contact IBM

Browse z/OS