Purpose
Use
the RACDCERT EXPORT command to write a digital certificate to a data
set.
Restriction: The private key of the exported certificate
must not be stored in the ICSF PKA key data set (PKDS) or command
processing stops and an error message is displayed.
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 EXPORT 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 EXPORT command, you must have the SPECIAL attribute,
or sufficient authority to the IRR.DIGTCERT.EXPORT or IRR.DIGTCERT.EXPORTKEY
resource in the FACILITY class based on the certificate owner and
format of the exported certificate package, 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:
- If one or more certificates in the certificate chain you are exporting
has an ECC key, you must have READ access to the CSF1PKV, CSF1TRC,
CSF1TRD, CSFDSV, and CSFOWH resources.
Exception: When the
Crypto Express3 coprocessor (CEX3C), or later, is operational, no
access to CSF1PKV, CSF1TRC, or CSF1TRD is required.
For details about the CSFSERV resources, see z/OS Cryptographic Services ICSF Administrator's Guide.
Table 1. Authority required for
the RACDCERT EXPORT functionFormat |
Your own certificate |
Another user's certificate |
SITE or CERTAUTH certificate |
---|
Export in CERT format |
Export your own certificate: READ authority
to IRR.DIGTCERT.EXPORT |
Export another user's certificate: UPDATE
authority to IRR.DIGTCERT.EXPORT |
Export SITE or CERTAUTH certificates: CONTROL
authority to IRR.DIGTCERT.EXPORT |
Export in PKCS #7 format |
Export your own certificate, but not the parent
CA chain: READ authority to IRR.DIGTCERT.EXPORT |
Export another user's certificate, but not
the parent CA chain: UPDATE authority to IRR.DIGTCERT.EXPORT |
Export SITE or CERTAUTH certificates and/or
the entire parent CA chain: CONTROL authority to IRR.DIGTCERT.EXPORT |
Export in PKCS #12 format |
Export your own certificate and the
private key: READ authority to IRR.DIGTCERT.EXPORTKEY |
Export another user's certificate and the
private key: CONTROL authority to IRR.DIGTCERT.EXPORTKEY |
Export SITE or CERTAUTH certificate and
the private key: CONTROL authority to IRR.DIGTCERT.EXPORTKEY |
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
EXPORT command is:
|
---|
RACDCERT EXPORT(LABEL('label-name')) |
[ID(certificate-owner) | SITE | CERTAUTH]
DSN(output-data-set-name)
[FORMAT(
CERTDER
| CERTB64
| PKCS7DER
| PKCS7B64
| PKCS12DER
| PKCS12B64
)]
[PASSWORD('pkcs12-password')]
|
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
- EXPORT(LABEL('label-name'))
- The label-name value
identifies the certificate that is being exported. Depending on which
keyword you specify, you can export a certificate, a certificate and
its CA chain, or a certificate and private key.
Restriction: When
ICSF is operating in FIPS mode, you cannot export the certificate
if one or more certificates in the certificate chain has a Brainpool
ECC key.
- ID(certificate-owner)
| SITE | CERTAUTH
- Specifies that the specified certificate 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.
- DSN(output-data-set-name)
- Specifies
the data set that is to contain the certificate. The data set output-data-set-name is
deleted and reallocated if it exists. If EXPORT is specified, DSN
must be specified.
- FORMAT
- Specifies
the format of the exported certificate package. Valid values for FORMAT
are:
- CERTB64 - specifies
a DER encoded X.509 certificate that has been encoded using Base64.
- CERTDER - specifies
a DER encoded X.509 certificate.
- PKCS7B64 - specifies
a DER encoded PKCS #7 package that has been encoded using Base64.
- PKCS7DER - specifies
a DER encoded PKCS #7 package.
- PKCS12B64 - specifies
a DER encoded PKCS #12 package that has been encoded using Base64.
- PKCS12DER - specifies
a DER encoded PKCS #12 package.
Note: - PKCS12DER is the default if PASSWORD is specified; otherwise,
CERTB64 is the default.
- The PKCS12B64 format might not be supported by non-IBM applications.
These applications often issue messages indicating incorrect passwords.
In this case, reissue the command specifying a format supported by
the application.
The CERT keywords indicate that only a certificate
is to be exported.
The PKCS #7 keywords indicate to export
a certificate and its CA chain. If the command issuer is authorized
to export CERTAUTH certificates PKCS #7 processing will attempt to
package any certificate authority certificate necessary to complete
the basing chain to the exported certificate. If a certificate in
the chain cannot be found under CERTAUTH or is expired or the command
issuer is not authorize to export CERTAUTH certificates, an informational
message will be issued. Processing continues creating an incomplete
PKCS #7 package. An incomplete PKCS #7 package can still be processed
by RACF but might or might
not be useful for OEM products.
The PKCS #12 keywords indicate
to export the certificate and the private key (which must exist and
must not be stored in the ICSF PKDS). The package produced by specifying
one of the PKCS #12 keywords is encrypted using the password specified
according to the PKCS #12 standard.
PKCS #12 processing requires
a software private key. If the private key is stored in the ICSF PKDS,
the PKCS #12 package cannot be created, and processing stops.
PKCS
#12 processing will attempt to package any certificate-authority certificate
necessary to complete the basing chain to the exported certificate.
If a certificate in the chain cannot be found under CERTAUTH, an informational
message will be issued. Processing continues and an incomplete PKCS
#12 package is created that can still be processed by RACF but might or might not be useful for OEM
products.
- PASSWORD('pkcs12-password')
- Specifies
the password to use for PKCS #12 package encryption. The string is
converted before being used, so any characters entered must be translatable
to 7-bit ASCII. However, RACF does not enforce this.
Note: RACF assumes the current host code page is IBM®-1047 and translates to ASCII
accordingly.
Examples
|
|
|
---|
Example 1 |
Operation |
User WENTING wants to export a certificate and
send it to her business partner Yun. |
Known |
The exported certificate does not contain the
private key so the data set Wen Ting transmits to Yun need not
be protected in any way. |
Commands |
RACDCERT EXPORT(LABEL('Wen Ting''s certificate'))
DSN(FOR.YUN.CRT)
|
Output |
None. |