Renew an Existing Certificate

Digital Certificates › General Rules › Renew an Existing Certificate

Renew an Existing Certificate

Valid on z/OS.

The RENEW command function renews a digital certificate. Use the RENEW command if a certificate is expiring and you want to continue to use the certificate. The RENEW command copies the information from an existing certificate and applies it to a certificate. This command can only renew certificates created by CA Top Secret, it cannot renew certificates from external certificate authorities. Certificates from external certificate authorities must be renewed manually using the PKCS 10 data set.

Notes:

Because the DIGICERT keyword indicates the name used in the digital certificate, specify a DIGICERT name as part of all RENEW functions.
You can enter additional keywords to modify the renewing certificate.
Use the NADATE keyword to specify an expiration date. If no date is specified, the certificate expires one year from the date that the certificate is renewed.
The keywords ICSF, PCICC, and LABLPKDS are only valid if the original certificate is NON-ICSF.
Before you renew a certificate, we recommend as a best practice that you export the certificate to a data set to save it, either using the RENEW command or manually.

Administrators must have:

ACID(MAINTAIN) and MISC4(CERTGEN) for users within their scope
MISC4(CERTSITE) for CERTSITE ACID
MISC4(CERTAUTH) for CERTAUTH ACID

This command function has the following format:

TSS RENEW {(CERTAUTH|CERTSITE|acid)}

DIGICERT(8-byte-name) 
[SUBJECTN('CN="common-name" T="title" OU="org-unit-name1,org-unit-name2" O="organizational-name" L="locality" ST="state-or-province" C="2—digit—only country code"')]
[NBDATE(mm/dd/yy) NBTIME(hh:mm:ss)]
[NADATE(mm/dd/yy) NATIME(hh:mm:ss)] 
[LABLCERT(label name)]
[ICSF|PCICC]
[SIGNWITH(acid,digicert)]
[KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN)]
[ALTNAME('IP=numeric-IP-address DOMAIN=internet-domain-name EMAIL=email-address URI=universal-resource-identifier')] 
[LABLPKDS]

CERTAUTH|CERTSITE|acid

Specifies the acid that will use the certificate.

CERTAUTH: Specifies the certificate as a certificate-authority certificate.
CERTSITE: Specifies the certificate as a site certificate.
acid: Specifies the user associated with the certificate.

DIGICERT(8-byte-name)

Specifies the keyword that identifies the digital certificate being renewed.

SUBJECTN('CN="common-name" T="title" OU="org-unit-name1,org-unit-name2" O="organizational-name" L="locality" ST="state-or-province" C="2—digit—only country code"')

(Optional) Specifies the distinguished name of the ACID. When you specify multiple parameters for SUBJECTN, surround the parameter list with single quotation marks. You can specify multiple values for OU=.

Default: The name field of the ACID

NBDATE/NBTIME Format(mm/dd/yy) Time(hh:mm:ss)

Indicates the date and time that the certificate becomes active. If no expire date is specified, the active year specified must be before 2048, because the expire date defaults to the active day and time plus one year.

Range: 1950 to 2049

Time Default: 000000

Date Default: Current day and time

NADATE/NATIME Format(mm/dd/yy) Time(hh:mm:ss)

(Optional) Indicates the date and time that the certificate expires.

Range: 1950 to 2049

Time Default: 000000

Date Default: The active day and time plus one year.

LABLCERT(label-name)

(Optional) Defines the label name of the certificate being renewed.

ICSF

(Optional) Indicates that the generated private key is placed in ICSF. If ICSF, PCICC, or LABLPKDS is not specified with ADD, the key is stored in the security file as a non-ICSF key. If the DSN parameter was also specified and an existing certificate is replaced, the existing certificate is also placed in ICSF. If ICSF is not active and configured for PKA operations, an error message is displayed when attempting to insert or use the private key.

PCICC

(Optional) Specifies that the key pair is generated using the PCI Cryptographic Coprocessor and that the private key is stored in ICSF. When PCICC is not specified, the key pair is generated using software. PCICC cannot be used with the DSA, DSN, or ICSF parameters.

If a PCI cryptographic coprocessor is not present or operational or if ICSF is not active or configured for PKA operations, an error message is displayed and processing terminates. If ICSF, PCICC, or LABLPKDS is not specified, the key pair is generated using software and stored in the security file as a non-ICSF key.

SIGNWITH(acid,digicert)

(Optional) Specifies the digital certificate signing the certificate. If not specified, the certificate is signed with the private key of the certificate being generated, creating a self-signed certificate.

KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN)

(Optional) Specifies the appropriate values for the KeyUsage certificate extension. If the KEYUSAGE data contains more than one value, place single quotation marks around the data.

Example: KEYUSAGE('HANDSHAKE DATAENCRYPT')

HANDSHAKE: (Optional) Facilitates identification and key exchange during security handshakes, such as SSL, which set the digitalSignature and keyEncipherment indicators. When the key pair is generated using the DSA algorithm, only the digitalSignature bit is set because the keys cannot be used for encryption.
DATAENCRYPT: (Optional) Encrypts data, which sets the dataEncipherment indicator. When the key pair is generated using the DSA algorithm, you cannot use the DATAENCRYPT keyword in the Keyusage parameter.
DOCSIGN: (Optional) Specifies a legally binding signature, which sets the nonRepudiation indicator.
CERTSIGN: (Optional) Specifies a signature for other digital certificates and CRLs, which sets the keyCertSign and cRLSign indicators.

ALTNAME ('IP=numeric-IP-address DOMAIN=internet-domain-name EMAIL=email-address URI=universal-resource-identifier')

(Optional) Specifies the appropriate values for the SubjectAltname extension. When you specify multiple parameters for ALTNAME, surround the parameter list with single quotation marks. Separate multiple parameters by a space.

Example: ALTNAME('IP=200.100.10.1 EMAIL=my.email@test.net')

LABLPKDS

(Optional) Specifies the PKDS label of the record created in the ICSF Public Key Data Set (PKDS). This field is used with the ICSF, PCICC, NISTECC, and BPECC keywords. If LABLPKDS is specified without ICSF or PCICC, the key is generated by the hardware and saved in CRT format in the ICSF PKDS. If NISTECC or BPECC is specified, the key is an ECC key; otherwise, the key is an RSA key.

Note: The PKDS label must conform to ICSF label syntax rules. The first character must be alphabetic or national.

To take the value from the LABLCERT keyword, include a LABLCERT specification in your syntax and specify the following syntax for LABLPKDS:

LABLPKDS(*)

Valid characters: Alphanumeric, national (@,#,$), or period(.).

Range: Up to 64 characters

Example: RENEW function

This example creates new certificate Locca4 for the existing certificate CERTAUTH.

TSS RENEW(CERTAUTH) DIGICERT(Locca4) NADATE(12/31/11)