How to Renew Digital Certificates with ACF2
search cancel

How to Renew Digital Certificates with ACF2

book

Article ID: 220869

calendar_today

Updated On:

Products

ACF2 ACF2 - MISC ACF2 - z/OS

Issue/Introduction

This article explains how to renew digital certificates in ACF2 and provides sample renewal commands for each use case. It also provides more information on the REKEY/ROLLOVER process if a new private key is desired.

Resolution

Table of Contents


Renew Certificates Signed by an Internal CA

The RENEW subcommand allows you to renew a certificate that is signed by an internal Certificate Authority (CA) in a single step. The certificate must exist in the CA ACF2 database and must have a private key. The new EXPIRE date must fall before the EXPIRE date of the signing CERTAUTH certificate. The private key of CERTAUTH certificate signing the renewed certificate must also be in the CA ACF2 database. If SIGNWITH is not specified, the RENEW subcommand finds the original signing certificate, and signs the renewed certificate with the original signing certificate if the original signing certificate has a private key. In this process the original public/private key pair is retained.

The following outlines the process to renew a certificate signed by an internal CA:

  1. CHKCERT of the certificate to be renewed and note the EXPIRE.

  2. RENEW certificate with a new expire date.

  3. CHKCERT CHAIN the certificate after the RENEW and verify the changed EXPIRE date with the complete signing chain.

Sample ACF2 Commands: 

ACF
CHKCERT userid.cert1
RENEW userid.cert1 EXPIRE(12/31/2030)
CHKCERT userid.cert1 CHAIN

Relevant Error Codes and Possible Causes:

ACF0A005 RECORD(S) NOT FOUND
The certificate specified on the RENEW command does not exist in the ACF2 database. Verify the information used to identify the certificate is correct.

ACF68037 This certificate does not have a private key
The certificate specified on the RENEW command does not have a private key and is unable to be renewed.

ACF68073 The SIGNWITH PRIVATE KEY cannot be found. The certificate cannot be renewed using the RENEW command
The signing certificate for the certificate being renewed does not have a private key and cannot be used to renew the certificate. A different signing certificate that contains a private key will need to be specified.                                            

More details on the RENEW command can be found in the CA ACF2 Documentation in section "RENEW Subcommand".

Renew Certificates Signed by External CA

The following process documents the replacement of an expiring user certificate that has been signed by a third-party Certificate Authority (CA) or by a company CERTAUTH that is not maintained locally (a CHKCERT of the CERTAUTH on the keyring does not show a private key). These expiring certificates have to be sent off to the Certificate Authority to be renewed. 

The following outlines the process to renew a certificate signed by an external CA:

  1. CHKCERT the certificate to be renewed. Save the output for future reference.

  2. EXPORT the certificate to a dataset to have a backup copy.

    • If the private key is non-ICSF, use PKCS#12 format to save the certificate and its public/private key pair.

    • If the private key is stored in ICSF, consider using the IBM freeware utility called KEYXFER to back up the private key. This can be used in conjunction with a non-PKCS#12 format (CERTDER) used to back up the certificate and public key that are stored in the ACF2 database.

  3. Issue a GENREQ against the existing CERTDATA record for the expiring certificate. Output will contain the Subject DN and the public key. An ACF68068 message will appear indicating the certificate request has been placed in the designated dataset.

  4. Send the output to the CA to be renewed.

  5. When it is returned, issue CHKCERT against the dataset to verify the new certificate looks valid. Things to look for include:

    • Has the 'not valid after' date been extended?

    • How does the output compare to the initial CHKCERT output?

  6. INSERT the renewed certificate from the dataset using the same certdata record name as the GENREQed certificate in Step 3 above. This will replace the existing CERTDATA record.

  7. Issue CHKCERT CHAIN against the CERTDATA record to verify the replacement certificate looks like the output of the original CHKCERT---except that the 'not valid after' date has been extended. There should be a private key. It should have TRUST. The CHAIN parameter will allow you to verify that the signing chain is complete.

  8. Issue F ACF2,REBUILD(USR),CLASS(P)

  9. Issue F ACF2,OMVS

  10. Bounce any address spaces that reference the keyrings to which a replaced certificate is connected.

Sample ACF2 Commands:

CHKCERT userid.cert1
EXPORT userid.cert1 DSN('saved.userid.cert1') FORMAT(PKCS12DER) PASSWORD(pkcs12 password)
GENREQ userid.cert1 DSN('userid.cert1.req')

** Send to Certificate Authority. Certificate Authority will send back a certificate package. **

CHKCERT DSN('renewed.userid.cert1')
SET PROFILE(USER) DIV(CERTDATA)
INSERT userid.cert1 DSN('renewed.userid.cert1') TRUST
CHKCERT userid.cert1 CHAIN
F ACF2,REBUILD(USR),CLASS(P)
F ACF2,OMVS

More details on the GENREQ command can be found in the CA ACF2 Documentation in section "GENREQ Subcommand".

Relevant Error Codes and Possible Causes:

ACF0A026 RECORD ALREADY EXISTS
If a CERTDATA record is being inserted for renewal, the record ID and public keys of the certificates must match and one of the following criteria must be met:

  • The certificate to be inserted is an exact duplicate of the existing certificate. For example, the certificate has the same serial number, issuer's distinguished name, and label.
  • The certificate is not a duplicate, but there is a private key associated with the existing certificate in the database.

REKEY/ROLLOVER Process for new Private Key

The above renewal processes assume the existing key pair should be maintained. If a new private key is desired, the REKEY/ROLLOVER process can be used to rekey the expiring certificate (a new private key is created) and retire the old private key. This prevents a private key from being overused. Overuse of the private key leaves it more susceptible to being broken and used by an unintended party. This process is used in conjunction with one of the methods outlined above since the rekeyed certificate will be self-signed.

The following outlines the REKEY/ROLLOVER process to obtain a new private key:

  1. CHKCERT the certificate to be renewed. Save the output for future reference.

  2. EXPORT the certificate to be renewed to a dataset to have a backup copy.

    • If the private key is non-ICSF, use PKCS#12 format to save the certificate and its public/private key pair.

    • If the private key is stored in ICSF, consider using the IBM freeware utility called KEYXFER to back up the private key. This can be used in conjunction with a non-PKCS#12 format (CERTDER) used to back up the certificate and public key that are stored in the ACF2 database.

  3. Issue a REKEY command for the certificate specifying a new label (WITHLBL) and new suffix (WITHS) for the rekeyed certificate. This will create a self-signed copy of the original certificate with a new public/private key pair.

  4. Renew the new self-signed certificate using one of the methods above. If using the RENEW command, the SIGNWITH parameter containing the desired signing certificate will need to be specified if the original certificate wasn’t self-signed. The EXPIRE parameter will need to be specified on the RENEW command regardless of whether or not the EXPIRE parameter was used on the REKEY command. The new EXPIRE date must fall before the EXPIRE date of the signing CERTAUTH certificate.

  5. When ready to retire the old certificate, issue a ROLLOVER command.

  6. CHKCERT the old certificate to verify it no longer has a private key.

  7. CHKCERT CHAIN the new certificate to verify the certificate information is correct, the signing chain is complete, and that the new certificate is attached to the same keyrings as the old certificate.

  8. To double check that the old certificate has been replaced by the renewed rekeyed certificate on the keyring, LIST the keyring(s) that the old certificate was attached to.

  9. Issue F ACF2,REBUILD(USR),CLASS(P)

  10. Issue F ACF2,OMVS

Sample ACF2 Commands:

CHKCERT userid.cert1
EXPORT userid.cert1 DSN('saved.userid.cert1') FORMAT(PKCS12DER) PASSWORD(pkcs12 password)
REKEY userid.cert1 WITHLBL(USER1 Cert 2) WITHS(CERT2)

** Choose the appropriate renewal process from above. An example of an internal renewal is provided below. **
RENEW userid.CERT2 SIGNWITH(CERTAUTH LABEL(Test Signing Cert)) EXPIRE(12/30/2030)

ROLLOVER userid.cert1 NEWLABEL(USER1 Cert 2)

** Note the ROLLOVER command will not change the Certificate USAGE on the Keyring  when replacing the old certificate
    with the new certificate (as specified by the NEWLABEL keyword) in every key ring to which the old certificate is connected.

CHKCERT userid.cert1
CHKCERT userid.CERT2 CHAIN
SET P(USER) DIV(KEYRING)
LIST userid.RING    
F ACF2,REBUILD(USR),CLASS(P)
F ACF2,OMVS 

Relevant Error Codes and Possible Causes:

ACF68037 This certificate does not have a private key
The certificate specified in the REKEY command does not have a private key and is unable to be rekeyed.

ACF68091 Both certificates in the ROLLOVER command must have private keys
Either the old certificate or the new certificate specified in the REKEY/ROLLOVER command does not have a private key. This error will display which certificate is causing the error.

CAS20E3E Duplicate PKDS label. Key cannot be generated using the PCI Cryptographic Coprocessor
An attempt was made to generate a key pair for a digital certificate using ICSF and the PCI Cryptographic coprocessor. The PKDS label specified already exists within the PKDS. A different PKDS label will need to be specified.
 
More details on the REKEY and ROLLOVER commands can be found in the CA ACF2 Documentation in the "REKEY Subcommand" and “ROLLOVER Subcommand” sections.

Powered by Wolken Software