SMP/E Internet Service Retrieval shared and non-shared certificates

Document ID : KB000009794
Last Modified Date : 14/02/2018
Show Technical Document Details
Introduction:

A user digital certificate is needed by the SMP/E RECEIVE ORDER command to uniquely identify a user to the IBM Automated Service Delivery server. 

Prior to setting up the required digital certificates as described in this informational solution, a site needs to obtain the User Certificate and the Certificate Authority Certificate as described in the IBM SMP/E for z/OS User's Guide in the chapter on Preparing to Use Internet Service Retrieval. 

A site can establish certificates for each user or share a user certificate among multiple user-ids. 

    A) To share a user certificate among multiple users follow the steps under SMP/E Internet Service Retrieval Shared Certificates. 

    B) To establish certificates for each user follow the steps under SMP/E Internet Service Retrieval Non-Shared Certificates. 

 Note: Ensure to have the following IBM Java 1.4.2 PTF applied: UK00802.

Instructions:

A)  SMP/E Internet Service Retrieval Shared Certificates 

This examples assumes two user-ids, user1 and user2, will share a single user certificate. 

1) Create a CA Top Secret keyring. 

   TSS ADD(user1) KEYRING(SMPRING) LABLRING(SMPE_USER_KEYRING) 

Note: The KEYRING and LABLRING fields are case sensitive. ‘SMPRING’ can be changed to something else, however, the value on the KEYRING must match the value specified in steps 5 and 10. ‘SMPE_USER_KEYRING’ can also be changed to something else, however, the value on the LABLRING must match the value specified in step 12. 

2) Obtain a user certificate from ShopzSeries.

   http://www.ibm.com/software/shopzseries 

3) After downloading the certificate file to your workstation, you need to upload it as a binary file to a dataset on your z/OS system. 

4) Add the user certificate to the eTrust CA Top Secret database. 

   TSS ADD(user1) DIGICERT(digicertname) LABLCERT(cert_label) -

   DCDSN('mvs.dataset.name') PKCSPASS(ppppppp) TRUST

   Where:

  ‘digicertname’ is the name of the digital certificate. This needs to be the same wherever you see ‘digicertname’ in other steps (ie step 5 has RINGDATA(user1,digicertname) ). 

  ‘cert_label’ specifies a label associated with the certificate. You choose this value. Up to 32 case-sensitive-characters can be specified for the label name. Spaces are allowed if you use single quotes. 

  ‘mvs.dataset.name’ is the name of the dataset where the certificate was uploaded in step 3. 

  ‘ppppppp’ is the password associated with a PKCS#12-formatted digital certificate. A password is required if the data set contains a PKCS#12-format certificate that is password protected.  The password can be up to 255 characters, is case sensitive, and can contain blanks. 

  The LABLCERT and PKCSPASS fields are case sensitive.  The DIGICERT and DCDSN fields are not case sensitive. 

  Note: 'pppppppp' is the password specified when generating the user certificate. It cannot be added to the security data base if it is not specified.  It is the responsibility of the individual who generated the user certificate to know it. 

  If you receive:

  TSS1573I THE CERTIFICATE <digicertname> SIGNER NOT FOUND. ADDING CERTIFICATE  WITH NOTRUST STATUS 

  Issue:

  TSS REPLACE(user1) DIGICERT(digicertname) TRUST 

5) Connect the user1 certificate to your keyring. 

  TSS ADD(user1) KEYRING(SMPRING) RINGDATA(user1,digicertname) -

  USAGE(CERTAUTH) 

  The 'digicertname' specified above should match the user1 certificate specified on the CA Top Secret 'TSS ADD' command in step 4. 

6) The KEYRING specified above should match the keyring specified on the CA Top Secret 'TSS ADD' command in step 1. 

7) Download to your workstation the DER encoded form of the Equifax Secure Certificate Authority root CA certificate. The certificate name is 'Root 1 - Equifax Secure Certificate Authority' and can be found at : 

https://knowledge.rapidssl.com/support/ssl-certificate-support/index?page=content&actp=CROSSLINK&id=SO5761 

Note: IBM mentioned that a change will be made to their SMP/E documentation stating that the "GeoTrust Global CA" certificate (serial number 02:34:56) will be recommended to be used instead of the Equifax certificate as the preferred root. 

The "Equifax Secure Certificate Authority" certificate (serial number 35:DE:F4:CF) identified in the SMP/E book (designated as a "retired root" on the GeoTrust website) will continue to be honored. (It has a 2018 supported date) 

8) Upload the CA certificate as ASCII and store it as a sequential data set on your z/OS system. 

9) Once you have stored the certificate in a sequential data set, add the GeoTrust CA certificate to the CA Top Secret database. This is the CA Certificate Authority Certificate as mentioned above. 

   TSS ADD(CERTAUTH) DIGICERT(GEOTRUST) LABLCERT(CERTAUTH.GEOTRUST) -

   DCDSN('mvs.dataset.name') TRUST 

   Where: 

  ‘user1’ is the acid the keyring should be added to. 

  ‘mvs.dataset.name’ is the dataset containing the uploaded CA certificate in step 8. 

  You can call the GEOTRUST digicertname whatever you want (1-8 characters).  This needs to be the same wherever you see ‘GEOTRUST’ in other steps (ie step 10 has RINGDATA(CERTAUTH,GEOTRUST’) ). 

10) Connect the GeoTrust CA certificate to your keyring. 

  TSS ADD(user1) KEYRING(SMPRING) RINGDATA(CERTAUTH,GEOTRUST) -

  USAGE(CERTAUTH) 

  The KEYRING specified above should match the keyring specified on the CA Top Secret 'TSS ADD' command in step 1. 

11) Give user2 permission to read other users' keyrings and certificates as shown in this example: 

  TSS PER(user2) IBMFAC(IRR.DIGTCERT.LIST) ACC(CONTROL)

  TSS PER(user2) IBMFAC(IRR.DIGTCERT.LISTRING) ACC(CONTROL) 

12) Ensure that SMP/E finds the certificate in the correct keyring when executing the RECEIVE ORDER command. To do this, user2 must specify not only the keyring name, but also the userid associated with the keyring, USER1, on the keyring attribute in the ORDERSERVER data set (within SMP/E Internet Service Retrieval) as follows: 

   keyring="user1/SMPE_USER_KEYRING" 

Note: The above ringname must match(case as well) the LABLRING specified in the CA Top Secret 'TSS ADD' command from step 1. 

13) Repeat steps 10 and 11 for additional users.

 

B)  SMP/E Internet Service Retrieval Non-Shared Certificates 

1) Create a CA Top Secret keyring for user1. 

   TSS ADD(user1) KEYRING(SMPRING) LABLRING(SMPE_USER_KEYRING) 

Note: The KEYRING and LABLRING fields are case sensitive. ‘SMPRING’ can be changed to something else, however, the value on the KEYRING must match the value specified in steps 5 and 10. ‘SMPE_USER_KEYRING’ can also be changed to something else, however, the value on the LABLRING must match the value specified in step 12. 

2) Obtain a user certificate from ShopzSeries.

   http://www.ibm.com/software/shopzseries 

3) After downloading the certificate file to your workstation, you need to upload it as a binary file to a dataset on your z/OS system. 

4) Once you have stored the certificate in a sequential data set, add the user1 certificate to the CA Top Secret database. 

   TSS ADD(user1) DIGICERT(digicertname) LABLCERT(cert_label) -

   DCDSN('mvs.dataset.name') PKCSPASS(ppppppp) TRUST 

  Where: 

  ‘digicertname’ is the name of the digital certificate. This needs to be the same wherever you see ‘digicertname’ in other steps (ie step 5 has RINGDATA(user1,digicertname) ). 

  ‘cert_label’ specifies a label associated with the certificate. You choose this value. Up to 32 case-sensitive-characters can be specified for the label name. Spaces are allowed if you use single quotes. 

  ‘mvs.dataset.name’ is the name of the dataset where the certificate was uploaded in step 3. 

  ‘ppppppp’ is the password associated with a PKCS#12-formatted digital certificate. A password is   required if the data set contains a PKCS#12-format certificate that is password protected. The password can be up to 255 characters, is case sensitive, and can contain blanks. 

  The LABLCERT and PKCSPASS fields are case sensitive. The DIGICERT and DCDSN fields are not case   sensitive. 

Note: 'pppppppp' is the password specified when generating the user certificate. It cannot be added to the security data base if it is not specified. It is the responsibility of the individual who generated the user certificate to know it. 

If you receive:

TSS1573I THE CERTIFICATE <digicertname> SIGNER NOT FOUND. ADDING CERTIFICATE WITH NOTRUST STATUS 

Issue:

TSS REPLACE(user1) DIGICERT(digicertname) TRUST 

5) Connect the user1 certificate to your keyring. 

   TSS ADD(user1) KEYRING(SMPRING) RINGDATA(user1,digicertname) -

   USAGE(PERSONAL) 

   The 'digicertname' specified above should match the user1 certificate specified on the CA Top Secret 'TSS ADD' command in step 4. 

   The KEYRING specified above should match the keyring specified on the CA Top Secret 'TSS ADD' command in step 1. 

6) Download to your workstation the DER encoded form of the Equifax Secure Certificate Authority root CA certificate.  The certificate name is 'Root 1 - Equifax Secure Certificate Authority' and can be found at : 

  https://knowledge.rapidssl.com/support/ssl-certificate-support/index?page=content&actp=CROSSLINK&id=SO5761 

Note: IBM mentioned that a change will be made to their SMP/E documentation stating that the "GeoTrust Global CA" certificate (serial number 02:34:56) will be recommended to be used instead of the Equifax certificate as the preferred root. 

The "Equifax Secure Certificate Authority" certificate (serial number 35:DE:F4:CF) identified in the SMP/E book (designated as a "retired root" on the GeoTrust website) will continue to be honored. (It has a 2018 supported date) 

7) Upload the CA certificate as ASCII file and store it as a sequential data set on your z/OS system. 

8) Add the GeoTrust CA certificate to the CA Top Secret database. This is the Certificate Authority Certificate as mentioned above. 

   TSS ADD(CERTAUTH) DIGICERT(GEOTRUST) LABLCERT(CERTAUTH.GEOTRUST) -

   DCDSN('mvs.dataset.name') TRUST

   You can call the GEOTRUST digicertname whatever you want (1-8 characters). This needs to be the same wherever you see ‘GEOTRUST’ in other steps (ie step 9 has RINGDATA(CERTAUTH, GEOTRUST’) 

9) Connect the GeoTrust CA certificate to your keyring. 

   TSS ADD(user1) KEYRING(SMPRING) RINGDATA(CERTAUTH,GEOTRUST) -

   USAGE(CERTAUTH) 

  The DIGICERT specified above should match the CA certificate specified on the CA Top Secret 'TSS ADD' command in step 5. 

  The KEYRING specified above should match the keyring specified on the CA Top Secret 'TSS ADD' command in step 1. 

10) Give user1 permission to read keyrings and certificates as shown in this example: 

    TSS PER(user1) IBMFAC(IRR.DIGTCERT.LIST) ACC(READ)

    TSS PER(user1) IBMFAC(IRR.DIGTCERT.LISTRING) ACC(READ) 

11) Repeat all of the above steps for each additional user certificate. Each user will have a keyring with their user certificate and the CA certificate. 

12) Ensure that SMP/E finds the certificate in the correct keyring when executing the RECEIVE ORDER command. To do this, the keyring attribute attribute in the ORDERSERVER data set as follows: 

    keyring="SMPE_USER_KEYRING" 

 

Note: The above ringname must match(case as well) the keyring name specified in the TSS ADD command from step 1.