RACDCERT REKEY (Rekey certificate)
Purpose
Use the RACDCERT REKEY command to replicate (rekey) a digital certificate with a new public/private key pair. In general, after you rekey a certificate, issue the RACDCERT ROLLOVER command to supersede the old certificate with the new rekeyed certificate and retire the old private key. For sample procedures, see "Renewing a certificate with a new private key (rekeying)" in z/OS Security Server RACF Security Administrator's Guide.
During rekeying, the subject's distinguished name, key usage, and subject alternate name are copied from the original certificate to the replicated certificate. The replicated certificate is then self-signed and stored as a new certificate associated with the same user ID, CERTAUTH, or SITE. The original certificate is not changed by this operation.
If the rekeyed certificate needs to be signed by another certificate in RACF® or another certificate authority, issue the RACDCERT GENREQ command to create a PKCS #10 request from the replicated certificate. Use the resulting request as input to RACDCERT GENCERT to sign the replicated certificate with another certificate in RACF or sent to the external certificate authority for fulfillment. Perform signing (if needed) before issuing the RACDCERT ROLLOVER command.
Use the RACDCERT GENCERT command instead of REKEY when you want to change the subject's distinguished name or supported extensions in addition to creating a new key pair.
See UTF-8 and BMP character restrictions for information about how UTF-8 and BMP characters in certificate names and labels are processed by RACDCERT functions.
Issuing options
As a RACF TSO command? | As a RACF operator command? | With command direction? | With automatic command direction? | From the RACF parameter library? |
---|---|---|---|---|
Yes | No | No. (See rules.) | No. (See rules.) | No |
- The RACDCERT command cannot be directed to a remote system using the AT or ONLYAT keyword.
- The updates made to the RACF database by RACDCERT are eligible for propagation with automatic direction of application updates based on the RRSFDATA profiles AUTODIRECT.target-node.DIGTCERT.APPL and AUTODIRECT.target-node.DIGTRING.APPL, where target-node is the remote node to which the update is to be propagated.
Authorization required
- The SPECIAL attribute, or
- Sufficient authority to the IRR.DIGTCERT.REKEY resource in the FACILITY class for your intended purpose, as shown in Table 1, or
- Sufficient authority to the appropriate resources in the RDATALIB class, as shown in Table 2, if Granular Authority Checking has been enabled by defining the IRR.RACDCERT.GRANULAR resource in the RDATALIB class.
- When you specify RSA(PKDS) or PCICC, you must have READ authority to the CSFDSG, CSFIQF, CSFPKG, CSFPKRC, and CSFPKX resources.
- When you specify RSA(TOKEN(token-name)), you must have READ authority to the CSF1GAV, CSF1GKP, CSF1TRD, CSFDSG, and CSFIQF resources.
- When you specify RSA and omit PKDS or TOKEN, you must have READ authority to the CSFIQF resource.
- When you specify ICSF, you must have READ authority to the CSFIQF, CSFPKI, and CSFPKRC resources.
- When you specify NISTECC(PKDS) or BPECC(PKDS), you must have READ access to the CSFDSG, CSFDSV, CSFOWH, CSFPKG, CSFPKRC, and CSFPKX resources.
- When you specify NISTECC(TOKEN(token-name)) or BPECC(TOKEN(token-name)), you must have READ access to the CSF1GAV, CSF1GKP, CSF1PKV, CSF1TRC, CSF1TRD, CSFDSG, and CSFOWH resources.
- When you specify NISTECC or BPECC and omit PKDS or TOKEN, you must have READ access to the CSF1GAV, CSF1GKP, CSF1PKS, CSF1PKV, CSF1TRC, CSF1TRD, and CSFOWH resources.
- When you omit key type, RACF rekeys the private key using with the characteristics of the original key, including how it is stored. Therefore, you must have access authority to the appropriate resources based on the characteristics of the original key even when you omit the key types shown in this list.
For details about the CSFSERV resources, see z/OS Cryptographic Services ICSF Administrator's Guide.
Access level | Purpose |
---|---|
READ | Rekey your own certificate. |
UPDATE | Rekey another user's certificate. |
CONTROL | Rekey a SITE or CERTAUTH certificate. |
READ access to the resource based on cert owner and cert label * | Purpose |
---|---|
IRR.DIGTCERT.<cert owner>.<source cert label>.UPD.REKEY, |
Replicate (rekey) a certificate under <cert owner> with <source cert label> to a new certificate with <target cert label> |
IRR.DIGTCERT.<cert owner>.<source cert label>.UPD.REKEY, |
Replicate (rekey) a certificate under <cert owner> with <source cert label> to a new certificate with a system generated label |
Activating your changes
If the DIGTCERT class is RACLISTed, refresh the class to activate your changes.
SETROPTS RACLIST(DIGTCERT) REFRESH
Related commands
- To rollover an expiring certificate to a rekeyed certificate, see RACDCERT ROLLOVER (Rollover certificate).
- To generate a certificate, see RACDCERT GENCERT (Generate certificate).
Syntax
For the key to the symbols used in the command syntax diagrams, see Syntax of RACF commands and operands. The complete syntax of the RACDCERT REKEY command is:
RACDCERT REKEY(LABEL('existing-label-name')) |
|
If you specify more than one RACDCERT function, only the last specified function is processed. Extraneous keywords that are not related to the function being performed are ignored.
If you do not specify a RACDCERT function, LIST is the default function.
For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.
Parameters
- REKEY(LABEL('existing-label-name'))
-
Specifies the label of the existing certificate to be replicated during RACDCERT REKEY processing. This keyword is required and identities an existing certificate owned by ID(certificate-owner), SITE, or CERTAUTH. The certificate identified by the LABEL keyword must be associated with the must have a private key associated with it otherwise an error message is issued and the command ends.
If the private key associated with the certificate is an ECC key, the ICSF subsystem must be operational and configured for PKCS #11 operations.
Restriction: When ICSF is operating in FIPS mode, you cannot rekey a certificate that has an associated Brainpool ECC private key.
- ID(certificate-owner) | SITE | CERTAUTH
- Specifies that the certificate to replicate is either a user certificate associated with the specified user ID, a site certificate, or a certificate-authority certificate. If you do not specify ID, SITE, or CERTAUTH, the default is ID, and certificate-owner defaults to the user ID of the command issuer. If more than one keyword is specified, the last specified keyword is processed and the others are ignored by TSO command parse processing.
- SIZE(key-size)
- Specifies
the size of the new private key expressed in decimal bits.
If SIZE is omitted, it defaults to the size of the private key associated with the original certificate.
For NISTECC keys, valid key sizes are 192, 224, 256, 384, and 521 bits. For BPECC keys, valid key sizes are 160, 192, 224, 256, 320, 384, and 512 bits.
For DSA keys, the minimum key size is 512.
For RSA keys, the minimum key size for clear keys and secure keys in the PKDS (PKA key data set) is 512; the minimum key size for secure keys in the TKDS (token key data set) is 1024 and the size must be a multiple of 256.
- The maximum key size for RSA and DSA keys is determined by United States export regulations and is controlled by RACF and non-RACF code in z/OS. Depending on the installation, non-RACF code may enforce a lower maximum size.
- Rounding up to the next appropriate key size might occur. Therefore, the key size of the generated key might be longer than the value you specify with SIZE but the generated key is never shorter than requested.
Maximum key sizes: The maximum key size for a private key depends on key type, as follows:Private key type Maximum key size RSA key stored in the RACF database 4096 bits RSA key stored in the ICSF PKDS as a CRT key token 4096 bits RSA key stored in the ICSF PKDS as an ME key token 1024 bits NISTECC key 521 bits BPECC key 512 bits Note: To generate an RSA key that is longer than 1024 bits and is to be stored in the RACF database, the CP Assist for Cryptographic Function (CPACF) must be enabled.
Standard RSA key sizes: Currently, standard key sizes for RSA keys are as follows:
Key size Key strength 512 bits Low-strength key 1024 bits Medium-strength key 2048 bits High-strength key 4096 bits Very high-strength key Key strength considerations: Shorter keys of the ECC type, which are generated when you specify NISTECC or BPECC, achieve comparable key strengths when compared with longer RSA keys.
RSA, NISTECC, and BPECC keys of the following sizes are comparable in strength:RSA key size NISTECC key size BPECC key size 1024 bits 192 bits 160 or 192 bits 2048 bits 224 bits 224 bits 3072 bits 256 bits 256 or 320 bits 7680 bits 384 bits 384 bits 15360 bits 521 bits 512 bits Hashing algorithm used for signing: With PTF UA80493 for APAR OA49085, RACF signs certificates using a set of secure hash algorithms based on the SHA-1 or SHA-2 hash functions. When the signing key is a DSA type, there are two options depending on the presence of the IRR.DSA.SHA256 profile in the FACILITY class. If the profile is not defined, the SHA-1 algorithm is used for keys of all sizes. If it is defined, just like RSA, NISTECC, and BPECC type, the size of the signing key determines the hashing algorithm used for signing, as follows:Hashing algorithm
used for signingSigning key size RSA / DSA NISTECC BPECC SHA-1 Less than 2048 bits — — SHA-256 2048 bits or
longer192, 224,
or 256 bits160, 192, 224,
256, or 320 bitsSHA-384 — 384 bits 384 bits SHA-512 — 521 bits 512 bits - NOTBEFORE(DATE(yyyy-mm-dd) TIME(hh:mm:ss))
- Specifies
the local date and time from which the certificate is valid. If DATE
is not specified, it defaults to the current local date. If TIME is
not specified, it defaults to TIME(00:00:00).
If DATE is specified, the value of yyyy must be 1950 - 9997.
Note that the use of the date format yyyy-mm-dd is valid. However, to aid installations familiar with the RACF date format, the value can be specified in the format yyyy/mm/dd.
The time and date values are stored in the certificate as a universal time coordinated (UTC) value. The calculated UTC value might be incorrect if the date and time values for NOTBEFORE and NOTAFTER represent a time that has a different local offset from UTC.
- NOTAFTER(DATE(yyyy-mm-dd) TIME(hh:mm:ss))
- Specifies
the local date and time after which the certificate is no longer valid.
If DATE is not specified, it defaults to one year from the NOTBEFORE
date value. If TIME is not specified, it defaults to TIME(23:59:59).
If DATE is specified, the value of yyyy must be 1950 - 9997. If DATE is defaulted, the value must be 1951 - 9998.
The NOTBEFORE value must be earlier than the NOTAFTER value or an informational message is issued.
Note the use of the date format yyyy-mm-dd is valid. However, to aid installations familiar with the RACF date format, the value can be specified as yyyy/mm/dd.
The time and date values are stored in the certificate as a universal time coordinated (UTC) value. The calculated UTC value might be incorrect if the date and time values for NOTBEFORE and NOTAFTER represent a time that has a different local offset from UTC.
- RSA | PCICC | ICSF | NISTECC | BPECC
- Specifies
how RACF should generate the
new key pair and how the private key should be stored for
future use.
When you omit the RSA, PCICC, ICSF, NISTECC, and BPECC operands, RACF rekeys using the key type and key size of the private key associated with the original certificate. The new key will have all the characteristics of the original key, including how it is stored. For example, if the original key is stored in the ICSF PKDS, the new key is also stored in the PKDS but with a new system-generated key label.
To specify a PKDS label for the new key, you must specify key type with the PKDS suboperand and a pkds-label value or an asterisk (*). When you specify PKDS with a pkds-label value, the new key is stored in the PKDS (if all required conditions are met) regardless of whether the original key was stored in the PKDS. Conversely, if the original key is stored in PKDS and you specify key type without the PKDS suboperand, the new key is not stored in the PKDS unless the following condition occurs. When the specified key type is incompatible with the original key, the key-type keyword is ignored. (For example, you cannot specify BPECC to rekey a certificate with an RSA key.) If the key-type operand is ignored, the new key is stored in the PKDS if the original key was stored in the PKDS.
For details about specifying or allowing RACF to generate the PKDS label, see PKDS label considerations.
For the hardware requirements for storing or accessing a key in the ICSF PKA key data set (PKDS), see Hardware requirements.
- RSA
- Specifies that the key pair is to be generated using software
with the RSA algorithm and the private key is to be stored in the RACF database as an RSA key.
When you specify RSA without the PKDS option, the CP Assist for Cryptographic Function (CPACF) must be enabled to generate a key that is longer than 1024 bits.
- PKDS[(pkds-label | *)]
- Specifies that the key pair is to be generated using a CCA cryptographic coprocessor. The resulting private key is generated with the RSA algorithm and stored in the ICSF PKA key data set (PKDS) as an RSA Chinese Remainder Theorem (CRT) key token with either a system-generated label, a label specified by pkds-label, or a label copied from the certificate label.
- TOKEN(token-name)
- Specifies that the key pair is to be generated using an Enterprise PKCS#11 cryptographic coprocessor. The resulting private key is stored in the specified existing token-name token in the ICSF token key data set (TKDS) as an RSA Chinese Remainder Theorem (CRT) key token.
- PCICC[(pkds-label | *)]
- Specifies the same function as the PKDS suboperand of the RSA operand. See the RSA operand of REKEY for details.
- ICSF[(pkds-label | *)]
- Specifies that the key pair is to be generated using software. The resulting private key is generated with the RSA algorithm and stored in the ICSF PKA key data set (PKDS) as an RSA Modulus-Exponent (ME) key token.
- NISTECC
- Specifies that the key pair is to be generated using software ,
if clear key is not restricted in the system, with the elliptic
curve cryptography (ECC) algorithm in accordance with the standard
proposed by the National Institute of Standards and Technology (NIST).
The resulting private key is stored in the RACF database as an ECC
key.
You can specify NISTECC to rekey only an ECC key pair.
When specifying NISTECC, the ICSF subsystem must be operational and configured for PKCS #11 operations.
- PKDS[(pkds-label | *)]
- Specifies that the key pair is to be generated using a CCA cryptographic coprocessor. The resulting private key is stored in the ICSF PKA data set (PKDS) as an ECC key in the PKA token with either a system-generated label, a label specified by pkds-label, or a label copied from the certificate label.
- TOKEN(token-name)
- Specifies that the key pair is to be generated using an Enterprise PKCS#11 cryptographic coprocessor. The resulting private key is stored in the specified existing token-name token in the ICSF token key data set (TKDS).
- BPECC
- Specifies that the key pair is to be generated using software,
if clear key is not restricted in the system, with the elliptic
curve cryptography (ECC) algorithm in accordance with the standard
proposed by the ECC Brainpool working group of the Internet Engineering
Task Force (IETF). The resulting private key is stored in the RACF
database as an ECC key.
You can specify BPECC to rekey only an ECC key pair.
When specifying BPECC, the ICSF subsystem must be operational and configured for PKCS #11 operations.
Restriction: When ICSF is operating in FIPS mode, you cannot generate a Brainpool ECC key.
- PKDS[(pkds-label | *)]
- Specifies that the key pair is to be generated using a CCA cryptographic coprocessor. The resulting private key is stored in the ICSF PKA data set (PKDS) as an ECC key in the PKA token with either a system-generated label, a label specified by pkds-label, or a label copied from the certificate label.
- TOKEN(token-name)
- Specifies that the key pair is to be generated using an Enterprise PKCS#11 cryptographic coprocessor. The resulting private key is stored in the specified existing token-name token in the ICSF token key data set (TKDS).
- WITHLABEL('to-be-created-label-name')
- Specifies
the label assigned to the new certificate. If specified, this must
be unique to the user ID with which the certificate is associated.
If not specified, it defaults in the same manner as the WITHLABEL
keyword on the RACDCERT ADD command.
The label-name value is stripped of leading and trailing blanks. If a single quotation mark is intended to be part of the label-name, use two single quotation marks together for each single quotation mark within the string, and enclose the entire string within single quotation marks.
See the WITHLABEL keyword for RACDCERT ADD for information on label rules.
Examples
Example 1 | Operation | User RACFADM has an expiring CERTAUTH certificate labeled 'Local PKI CA' and wants to renew it and rekey the private key. The new, rekeyed certificate will be labeled 'Local PKI CA-2'. The PCI cryptographic coprocessor will to be used to generate the new key pair. The size of the new private key will be 1024 bits (RACF default size). After issuing the RACDCERT REKEY command, the user RACFADM will issue the RACDCERT ROLLOVER command to retire and replace the expiring certificate. |
---|---|---|
Known | User RACFADM has CONTROL access to the IRR.DIGTCERT.REKEY resource in the FACILITY class. | |
Command |
|
|
Output | None. |