Reference Manual

10.4.0 HotFix 1
- 10.5.5
- 10.5.4
- 10.5.3
- 10.5.2
- 10.5.1
- 10.5
- 10.4.1
- 10.4.0

Back Next

Creating a Certificate By Using the z/OS RACDCERT Command

Choose a z/OS user ID under which to process certificates.

There is no correlation between z/OS user IDs and Linux, Unix and Windows clients.

The certificate produced will be in PKCS12DER format. This format exports both the certificate and the private key, which must be stored

List existing certificate information.

List existing certificate labels on the user key rings by using the TSO command RACDCERT LISTRING.

You can also use the PWXUGSK utility to list existing certificates. For more information, see the

PowerExchange Utilities Guide

Use JCL statements such as the following ones:


//**
//RINGL  EXEC PGM=IKJEFT01
//SYSTSPRT  DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//SYSUDUMP  DD SYSOUT=*
//SYSTSIN   DD *
    RACDCERT LISTRING(*) ID(certificate_owner)
    END
/*

List the details of existing certificates for the user by using the TSO command RACDCERT LIST.

Use JCL statements such as the following ones:


//**
//CERTUSR   EXEC PGM=IKJEFT01
//SYSTSPRT  DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//SYSUDUMP  DD SYSOUT=*
//SYSTSIN   DD *
    RACDCERT LIST ID(certificate_owner)
    END
/*

If the certificate you want already exists, you can skip step 3.

Looking at existing certificates gives an idea about what to put into new certificates.

Run the TSO RACDCERT GENCERT command to create the certificate.

Use JCL statements such as the following ones:


//**
//CERTAUTH  EXEC PGM=IKJEFT01
//SYSTSPRT  DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//SYSUDUMP  DD SYSOUT=*
//SYSTSIN   DD *
  RACDCERT ID(certificate_owner) GENCERT -                     
    SUBJECTSDN ( -                               
      O('YourOrganization') -                         
      CN('certificate_owner.servername.yourdomain.com') -       
      OU('zOS.Admin') -                          
      C('GB') -                                  
            )          -                       
    WITHLABEL('CERTUSRPCCert')-                       
    SIGNWITH(CERTAUTH LABEL('LOCALCA'))          
  
/*

The following table shows the mapping of the general certificate attributes to RACDCERT GENCERT parameters:

Attribute	RACDCERT GENCERT Parameter and Notes
Key size in bits	SIZE Default is 1024. Setting a value higher than 1024 might be prevented by RACF or United States export regulations.
Distinguished name	SUBJECTSDN ( - O('myorganization') - CN('userid.machine.myorganization.com') - OU('myorganizationunit') C('GB') -
Message digest	default is sha1.
Expiration date	NOTAFTER( `yyyy`-`mm`-`dd` ) Default is 12 months from the current date.
Certificate Authority	If the certificate is signed by a recognized CA, the label reflects the name of the CA. SIGNWITH(CERTAUTH LABEL(('LOCALCA'))

The following table shows z/OS-specific RACDCERT GENCERT parameters:

RACDCERT GENCERT Parameter	Usage
WITHLABEL	Used during the export of the certificate to DER format. Will be available in the PEM certificate under " Bag Attributes - friendlyName: "
SIGNWITH	Specifies the certificate with a private key that is signing the certificate. The default is to sign with the private key of the certificate being generated, thus creating a self-certified certificate. This default is appropriate for certificate authority certificates but not useful with personal certificates.

Using the z/OS TSO command RCADCERT GETCERT, the key type can be affected by the parameters PCICC, ICSF or DSA.

Use the TSO command RACDCERT LIST to check the details of the new personal certificate.

The RACDCERT GENCERT command causes the warning message to be issued:

 IRRD175I The new profile for DIGTCERT will not be in effect until a SETROPTS REFRESH has been issued.

To refresh the RACF definitions, issue a TSO SETROPTS command such as the following one:

 SETROPTS RACLIST(DIGTCERT,DIGTNMAP) REFRESH "

You need specific RACF permission to use this command.

You might omit this command if AT-TLS is not going to use the new certificate, that is, if you are generating the certificate only for use by a PowerExchange client on Linux, Unix, or Windows.

Issue a TSO RACDCERT CONNECT command to connect the certificate to a key ring.

You might omit this command if AT-TLS is not going to use the new certificate, that is, if you are generating the certificate only for use by a PowerExchange client on Linux, Unix or Windows.

To export the certificate file to a PKCSK23DER format flat file, issue the TSO RACDCERT EXPORT command.

Use JCL statements such as the following ones:


//**
//CERTAUTH  EXEC PGM=IKJEFT01
//SYSTSPRT  DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//SYSUDUMP  DD SYSOUT=*
//SYSTSIN   DD *
    RACDCERT EXPORT(LABEL('CERTUSRPCCert1'))  -
             DSN('certificate_owner.PCCERT1.DER.P12') -
             PASSWORD('USRPWD')                -
             FORMAT(PKCS12DER)
    END
/*

The following table describes the command parameters:

Parameter	Description
LABEL	Identifies the certificate. Must match the WITHLABEL parameter in the RACDCERT GENCERT command.
DSN	Identifies the output data set name in PKCS12 DER format. The data set will be dynamically allocated DCB values RECFM=VB, LRECL=84. The data set does not need to be deleted or pre-allocated.
PASSWORD	Temporary password that needs to be remembered and input to the openssl pkcs12 -clcerts command that you issue in step 8.
FORMAT	PKCS12DER

Perform a binary FTP of the PKCSK23DER to the Windows or Unix machine.

Use one of the following methods do convert the PKCSK23DER certificate to the PEM format used on the Windows or Unix machine:

Use the PWXUSSL utility to convert the certificate to PEM format:

pwxussl cmd=CONVERT_CERT_PKCS12_PEM verbose=Y INFILE=E:\_MYDETAIL\SSLCerts\Exported\certificate_owner.PCCERT1.DER.P12 pwd=pwd OUT_FILE=E:\_MYDETAIL\SSLCerts\Exported\RACFEXPkey.pem

The utility issues progress and success messages:

PWX-37129 MONITOR statistics switched off for process PWXUSSL

Processing console program. pwxussl cmd=CONVERT_CERT_PKCS12_PEM verbose=Y INFILE=E:\_MYDETAIL\SSLCerts\Exported\certificate_owner.PCCERT1.DER.P12 PWD=pwd OUT_FILE=E:\_MYDETAIL\SSLCerts\Exported\RACFEXPkey.pem

Importing PKCS12 file into memory X509 objects
----------------------------------------------
Opening file 'E:\_MYDETAIL\SSLCerts\Exported\SSL.RACFEXP.STQA.CERT1.DER.PKCS12'
Calling d2i_PKCS12_fp()
Closing input file
Calling PKCS12_parse()
PKCS12 contains 1 CA certificates

Exporting X509 objects to PEM file
----------------------------------
Opening output file 'E:\_MYDETAIL\SSLCerts\Exported\RACFEXPkey.pem'
Writing subject identification certificate
Writing Encrypted Private Key
Encoding private key using input password
Writing CA certificate 1
Closing output file

CONVERT_CERT_PKCS12_PEM ended OK

Use OpenSSL to convert the certificate to PEM format:

c:\openSSL\bin\openssl.exe pkcs12  -clcerts -in K:\sslCertificates\abc890_2\PCCert1\certificate_owner.PCCERT1.DER.P12 -out K:\sslCertificates\abc890_2\PCCert1\RACFEXPkey.pem

Enter Import Password:

At the Enter Import Password prompt, enter the password that you specified in the TSO RACDCERT EXPORT command in step 6.

xxxxxx
MAC verified OK
Enter PEM pass phrase:

At this prompt specify the permanent password for the certificate and private key file. This password must be specified in the PASS= parameter on the SSL statement in the DBMOVER configuration file.

Verifying - Enter PEM pass phrase:

Re-enter the permanent password.

This creates the file named in the -out parameter.

Enter the following parameters into the SSL statement in the DBMOVER configuration file:

SSL Parameter	Value
KEY	Output file from step 8
PASS	Permanent password from step 8

Test basic connectivity:

DTLREXE PROG=PING LOC=NODE1SSL
=>
PWX-00750 DTLREXE Input LOC=NODE1SSL, PROG=PING, PARMS=<null>, UID=<>.
PWX-00755 DTLREXE Command OK!

Note that with a single personal certificate in the file, it is not possible to enable verification. If verification is attempted, error messages result.

Example error messages on the PowerExchange Listener machine:

PWX-00591 Tasks now active = 1.
PWX-00656 Port 16495 is running in SSL mode
PWX-00652 [127.0.0.1]:1501 : TCP/IP SSL Error, rc=-1, reason <SSL_Socket_Open fa
iled: 1239336>
PWX-31023 Open secure socket failed
PWX-31045 Certificate 1 does not verify. rc=21 "X509_V_ERR_UNABLE_TO_VERIFY_LEAF
_SIGNATURE".
PWX-31045 Certificate 1 does not verify. rc=27 "X509_V_ERR_CERT_UNTRUSTED".
PWX-31045 Certificate 1 does not verify. rc=20 "X509_V_ERR_UNABLE_TO_GET_ISSUER_
CERT_LOCALLY".
PWX-31044 Certificate 1.  Machine 'Local Client'. Type 'CA3: Self-signed X509 V1'. Start '2014-12-11 18:37:49 GMT'. End '2042-04-27 18:37:49 GMT'. Subject '/emailAddress=myuid1@machine1'. Issuer '/emailAddress=myuid1@machine1'.
PWX-00591 Tasks now active = 0.

Example error message on the client machine:

DTLREXE PROG=PING LOC=pccertSSL
=>
PWX-00750 DTLREXE Input LOC=pccertSSL, PROG=PING, PARMS=<null>, UID=<>.
PWX-00752 DTLREXE Startup Error <Failed Client Connect RCs=1217/0/0>.
PWX-00652 [127.0.0.1]:1516 : TCP/IP SSL Error, rc=31045, reason <SSL_Socket_Open fa
iled: 31045>
PWX-31045 Certificate 1 does not verify. rc=21 "X509_V_ERR_UNABLE_TO_VERIFY_LEAF
_SIGNATURE".
PWX-31045 Certificate 1 does not verify. rc=27 "X509_V_ERR_CERT_UNTRUSTED".
PWX-31045 Certificate 1 does not verify. rc=20 "X509_V_ERR_UNABLE_TO_GET_ISSUER_
CERT_LOCALLY".
PWX-31044 Certificate 1. Machine z390a Type CA3: Self-signed X509 V1 Start date 100811000000Z. End date 110811235959Z. Subje
ct /C=GB/O=INFORMATICA/OU=DEVELOPMENT/CN=certificate_owner.GBW170701.INFORMATICA.COM. Issuer
/C=GB/O=Informatica/OU=zOS.Admin/CN=irrcerta.z390a.informatica.com.

Optionally, configure for verification.

To use verification, perform the following steps:

Export the z/OS CA certificate to PKCSK23DER format. You need extra RACF permission for this.

Perform a binary FTP of the exported certificate.

Convert the certificate to a PEM file.

Create a merged file from the outputs of step 9 and the new CA PEM file.

Insert the new file name into the KEY parameter of the SSL statement in the DBMOVER configuration file:

SSL=(KEY=

Insert the new CA PEM file name into the CALIST parameter of the SSL statement in the DBMOVER configuration file:

SSL=(CALIST=

Rename Saved Search

Table of Contents

Reference Manual

Reference Manual

Creating a Certificate By Using the z/OS RACDCERT Command

Creating a Certificate By Using the z/OS RACDCERT Command