RACDCERT EXPORT (Export certificate package)

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 function
Format	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

Related commands

To list a certificate, see RACDCERT LIST (List 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 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.