Table of Contents

Search

  1. Preface
  2. Introduction to PowerExchange
  3. DBMOVER Configuration File
  4. Netport Jobs
  5. PowerExchange Message Logs and Destination Overrides
  6. SMF Statistics Logging and Reporting
  7. PowerExchange Security
  8. Secure Sockets Layer Support
  9. PowerExchange Alternative Network Security
  10. PowerExchange Nonrelational SQL
  11. PowerExchange Globalization
  12. Using the PowerExchange ODBC Drivers
  13. PowerExchange Datatypes and Conversion Matrix
  14. Appendix A: DTL__CAPXTIMESTAMP Time Stamps
  15. Appendix B: PowerExchange Glossary

Creating a Certificate By Using the z/OS RACDCERT Command

Creating a Certificate By Using the z/OS RACDCERT Command

  1. 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
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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
  7. Perform a binary FTP of the PKCSK23DER to the Windows or Unix machine.
  8. 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.
  9. 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
  10. 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.
  11. Optionally, configure for verification.
    To use verification, perform the following steps:
    1. Export the z/OS CA certificate to PKCSK23DER format. You need extra RACF permission for this.
    2. Perform a binary FTP of the exported certificate.
    3. Convert the certificate to a PEM file.
    4. Create a merged file from the outputs of step 9 and the new CA PEM file.
    5. Insert the new file name into the KEY parameter of the SSL statement in the DBMOVER configuration file:
      SSL=(KEY=
    6. Insert the new CA PEM file name into the CALIST parameter of the SSL statement in the DBMOVER configuration file:
      SSL=(CALIST=