 |
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 The following table identifies
the eligible options for issuing the RACDCERT REKEY command: | 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 |
Rules: The
following rules apply when issuing this command. - 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 To
issue the RACDCERT REKEY command, you must have 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.
When your installation
controls access to ICSF services and the CSFSERV class is active,
additional access to CSFSERV resources might be required as follows: - 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.
Table 1. Authority required for the RACDCERT REKEY function| IRR.DIGTCERT.REKEY |
|---|
| Access level |
Purpose |
|---|
| READ |
Rekey your own certificate. |
| UPDATE |
Rekey another user's certificate. |
| CONTROL |
Rekey a SITE or CERTAUTH certificate. |
Activating your changes If the DIGTCERT
class is RACLISTed, refresh the class to activate your changes.
Example: SETROPTS RACLIST(DIGTCERT) REFRESH
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')) |
| [ ID(certificate-owner) | SITE | CERTAUTH ]
[ SIZE(key-size) ]
[ NOTBEFORE( [ DATE(yyyy-mm-dd) ] [ TIME(hh:mm:ss) ] ) ]
[ NOTAFTER( [ DATE(yyyy-mm-dd) ] [ TIME(hh:mm:ss) ] ) ]
[ { RSA [ (PKDS [ (pkds-label | * ) ] | TOKEN(token-name) ) ]
| NISTECC [ (PKDS [ (pkds-label | * ) ] | TOKEN(token-name) ) ]
| BPECC [ (PKDS [ (pkds-label | * ) ] | TOKEN(token-name) ) ]
| PCICC [ (pkds-label | * ) ]
| ICSF [ (pkds-label | * ) ] } ]
[ WITHLABEL('to-be-created-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: 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, the SHA-1
algorithm is used for keys of all sizes. When the signing key is an
RSA, NISTECC, or BPECC type, the size of the signing key determines
the hashing algorithm used for signing, as follows: | Hashing algorithm
used for signing
|
Signing key
size |
|---|
| RSA |
NISTECC |
BPECC |
|---|
| SHA-1 |
Less than 2048 bits |
— |
— |
| SHA-256 |
2048 bits or
longer
|
192, 224,
or 256 bits
|
160, 192, 224,
256, or 320 bits
|
| SHA-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 |
RACDCERT REKEY(LABEL(’Local PKI CA’))
CERTAUTH
WITHLABEL(’Local PKI CA-2’)
RSA(PKDS)
|
| Output |
None. |
|
z/OS Security Server RACF Command Language Reference
Copyright IBM Corporation 1990, 2014