SMP/E Internet Service Retrieval for Shared and Non-shared Certificates in Top Secret
Article ID: 9794
Updated On:
Products
Issue/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 document, 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. Be sure to upload the certificates in BINary format with RECFM=VB.
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.
Environment
Component:
Resolution
A) SMP/E Internet Service Retrieval Shared Certificates
This example assumes two user-ids, user1 and user2, will share a single user certificate.
1) Create a 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 9. ‘SMPE_USER_KEYRING’ can also be changed to something else, however, the value on the LABLRING must match the value specified in step 11.
2) Download the Digicert Intermediate CA certificate:
Digicert Intermediate CA certificate
Note the location of the file on your workstation where the certificate was downloaded.
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 Top Secret database.
TSS ADD(CERTSITE) DIGICERT(usercert) LABLCERT('SMPE Client Certificate') -
DCDSN('mvs.dataset.name') PKCSPASS(ppppppp) TRUST
Where:
‘usercert’ is the name of the digital certificate. This needs to be the same wherever you see ‘usercert’ in other steps (ie step 5 has RINGDATA(user1,usercert) ).
‘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(CERTSITE) DIGICERT(usercert) TRUST
5) Connect the user1 certificate to your keyring.
TSS ADD(user1) KEYRING(SMPRING) RINGDATA(CERTSITE,usercert) -
USAGE(CERTAUTH)
The 'usercert' specified above should match the user1 certificate specified on the Top Secret 'TSS ADD' command in step 4.
The KEYRING specified above should match the keyring specified on the Top Secret 'TSS ADD' command in step 1.
6) Download to your workstation the root CA certificate. The certificate can be found at :
7) Upload the root CA certificate as ASCII and store it as a sequential data set on your z/OS system.
8) Once you have stored the certificate in a sequential data set, add the root CA certificate to the Top Secret database. This is the CA Certificate Authority Certificate as mentioned above.
TSS ADD(CERTAUTH) DIGICERT(digicert) LABLCERT('CERTAUTH.digicert') -
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 7.
You can call the 'digicert' name whatever you want (1-8 characters). This needs to be the same wherever you see ‘digicert’ in other steps (ie step 9 has RINGDATA(CERTAUTH,digicert) ).
9) Connect the root CA certificate to your keyring.
TSS ADD(user1) KEYRING(SMPRING) RINGDATA(CERTAUTH,digicert) -
USAGE(CERTAUTH)
The KEYRING specified above should match the keyring specified on the Top Secret 'TSS ADD' command in step 1.
10) 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)
11) 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 keyring lablring must match (case as well) the LABLRING specified in the Top Secret 'TSS ADD' command from step 1.
12) Repeat steps 9 and 10 for additional users.
B) SMP/E Internet Service Retrieval Non-Shared Certificates
1) Create a 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 9. ‘SMPE_USER_KEYRING’ can also be changed to something else, however, the value on the LABLRING must match the value specified in step 11.
2) Download the Digicert Intermediate CA certificate:
https://support.broadcom.com/cadocs/0/certs/digicert-old/Digi-Intermediate.crt
Note the location of the file on your workstation where the certificate was downloaded.
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 Top Secret database.
TSS ADD(user1) DIGICERT(usercert) LABLCERT('SMPE Client Certificate') -
DCDSN('mvs.dataset.name') PKCSPASS(ppppppp) TRUST
Where:
‘usercert’ is the name of the digital certificate. This needs to be the same wherever you see ‘usercert’ in other steps (ie step 5 has RINGDATA(user1,usercert) ).
‘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(usercert) TRUST
5) Connect the user1 certificate to your keyring.
TSS ADD(user1) KEYRING(SMPRING) RINGDATA(user1,usercert) -
USAGE(CERTAUTH)
The 'usercert' specified above should match the user1 certificate specified on the Top Secret 'TSS ADD' command in step 4.
The KEYRING specified above should match the keyring specified on the Top Secret 'TSS ADD' command in step 1.
6) Download to your workstation the root CA certificate. The certificate can be found at:
7) Upload the root CA certificate as ASCII and store it as a sequential data set on your z/OS system.
8) Once you have stored the certificate in a sequential data set, add the root CA certificate to the Top Secret database. This is the CA Certificate Authority Certificate as mentioned above.
TSS ADD(CERTAUTH) DIGICERT(digicert) LABLCERT(CERTAUTH.digicert) -
DCDSN('mvs.dataset.name') TRUST
You can call the digicert name whatever you want (1-8 characters). This needs to be the same wherever you see ‘digicert’ in other steps (ie step 9 has RINGDATA(CERTAUTH,digicert’)
9) Connect the root CA certificate to your keyring.
TSS ADD(user1) KEYRING(SMPRING) RINGDATA(CERTAUTH,digicert) -
USAGE(CERTAUTH)
The digicert specified above should match the root CA certificate specified on the Top Secret 'TSS ADD' command in step 8.
The KEYRING specified above should match the keyring specified on the 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(UPDATE)
TSS PER(user1) IBMFAC(IRR.DIGTCERT.LISTRING) ACC(UPDATE)
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, specify the keyring attribute in the ORDERSERVER data set as follows:
keyring="SMPE_USER_KEYRING"
Note: The above keyring lablring must match (case as well) the keyring name specified in the TSS ADD command from step 1.
Feedback
