z/OS Communications Server: IP Programmer's Guide and Reference
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Interfacing with the DCAS: Defining the format for request and response specifications

z/OS Communications Server: IP Programmer's Guide and Reference
SC27-3659-02

Table 1 contains format 1 request information.

Table 1. Format 1 request
Field byte offset Field name Field description
0 opcode 01 = request
1 Format 01 = request user ID and PassTicket
2-5 Correlator User-defined value
6-25 Appl ID Application for which the PassTicket is generated. This must have the same name as the PassTicket data profile that is defined for the application using the RACF® PTKTDATA class.1 (EBCDIC).
26-27 reserved not used
28-31 Certificate Length Input certificate length. Maximum length is 32 767 bytes. This field is a binary integer.
32-n Certificate Base-64 encoded certificate

1 The application ID required in the DCAS Format 1 and Format 2 requests must match the name of a valid PassTicket data profile defined in RACF using the PTKTDATA class. See z/OS Security Server RACF Security Administrator's Guide for information about defining PTKTDATA for applications.

Table 2 contains format 1 response information.

Table 2. Format 1 response
Field byte offset Field name Field description
0 opcode 02 = response
1 Format 01 = request user ID and PassTicket
2-5 Correlator User-defined value that matches the value of the request.
6-7 Return Code 1 If nonzero, examine the extended return codes: Return Code 2, Return Code 3, Return Code 4
8-11 Return Code 2 Extended (see Table 4)
12-15 Return Code 3 Extended (see Table 4)
16-19 Return Code 4 Extended (see Table 4)
20-28 User ID If Return Code 1 is 0, a user ID is returned (EBCDIC)
29 reserved null
30-37 Passticket If Return Code 1 is 0, a PassTicket is returned.

Table 3 contains format 2 request information.

Table 3. Format 2 request
Field byte offset Field name Field description
0 opcode 02 = request
1 Format 02 = request PassTicket
2-5 Correlator User-defined value
6-25 Appl ID Application for which the PassTicket is generated. Must have the same name as the PassTicket data profile that is defined for the application using the RACF PTKTDATA class.1 (EBCDIC)
26-27 reserved Not used
28-31 User ID Length Length of the input user ID (binary integer)
32-n User ID Input user ID (EBCDIC)

1 The response to a Format 2 request is a Format 1 Response. The application ID required in the DCAS Format 1 and Format 2 requests must match the name of a valid PassTicket data profile defined in RACF using the PTKTDATA class. See z/OS Security Server RACF Security Administrator's Guide for information about defining PTKTDATA for applications.

Table 4. Understanding return codes in the response
Return Code 1 Return Code 2 Return Code 3 Return Code 4 Comments
0 Not Set Not Set Not Set The response indicates that the request completed successfully.
248 Not Set Not Set Not Set If the DCAS uses AT-TLS policies, you must do the following configuration:
  • Set the TTLSEnvironmentActions statement HandshakeRole parameter to ServerWithClientAuth.
  • Set the TTLSEnvironmentActions -> TTLSEnvironmentAdvancedParms statement ClientAuthType parameter to SAFCHECK or Required.
Tip: For more information about AT-TLS policies setup, see Customizing DCAS for TLS/SSL in z/OS Communications Server: IP Configuration Guide and Diagnosing problems with Express® Logon in z/OS Communications Server: IP Diagnosis Guide.
249 Not Set Not Set Not Set DCAS AT-TLS handshake failed or the connection is not secure. Check the AT-TLS configuration and DCAS log file for details.
Tip: For more information about AT-TLS policies setup, see Customizing DCAS for TLS/SSL in z/OS Communications Server: IP Configuration Guide and Diagnosing problems with Express Logon in z/OS Communications Server: IP Diagnosis Guide.
250 Not Set Not Set Not Set An internal error occurred on the DCAS server. Request that the system operator obtain a DCAS trace. See z/OS Communications Server: IP Diagnosis Guide for instructions.
251 Not Set Not Set Not Set PassTicket generation failed. The most likely cause is that the application ID in the DCAS Format 1 or 2 request does not match a valid PassTicket data profile name defined in the RACF PTKTDATA class.1
252 8 8 36 – Certificate is not valid.

40 – Certificate is not mapped to a valid user ID.

 For a Format 1 type request, RACF has determined that the input certificate is in error or has not been mapped to a valid RACF user ID. For return codes other than the ones described, see z/OS Communications Server: IP Diagnosis Guide.
253 10 – Format 1 request has a certificate length that is not valid.

11 – The request format is incorrect.

12 – The opcode that us specified in the request is not valid.

 Not Set Not Set The input format 1 or 2 request is incorrect. Examine Return Code 2 for details.

Verify that the input request to DCAS matches the defined format specifications.

Verify that DCAS is configured with a SERVERTYPE in the DCAS profile that is consistent with the input request format.
254 8 8 36 – Certificate is not valid.

40 – Certificate is not mapped to a valid user ID.

 DCAS failed to authenticate the client.

The DCAS server has been configured with AUTHTYPE LOCAL2. This requires that the certificate of the DCAS client (as a result of the SSL handshake) be mapped to a defined and valid user ID in RACF. The user ID must be permitted to the following SERVAUTH class profile: EZA.DCAS.cvtsysname. If the DCAS client receives this error, then the user ID is not permitted to the defined SERVAUTH class profile.

Tip: The DCAS can call System SSL or use AT-TLS for TLS/SSL. See Customizing DCAS for TLS/SSL in z/OS Communications Server: IP Configuration Guide. If the DCAS uses AT-TLS policies, configure TTLSEnvironmentAction-> TTLSEnvironmentAdvancedParms ClientAuthType SAFCHECK in the policy configuration file.

For return codes other than the ones described, see the Diagnosing problems with Express Logon information in z/OS Communications Server: IP Diagnosis Guide for diagnosing the DCAS.
255 8 8 36 – Certificate is not valid.

40 – Certificate is not mapped to a valid user ID.

 DCAS failed to authenticate the client.

The DCAS server has been configured with AUTHTYPE LOCAL2. This requires that the certificate of the DCAS client (as a result of the SSL handshake) be mapped to a defined and valid user ID in RACF. If the DCAS client receives this error, then the certificate does not map to a valid user ID.

Tip: DCAS can call System SSL or use AT-TLS for TLS/SSL. See Customizing DCAS for TLS/SSL in z/OS Communications Server: IP Configuration Guide. If the DCAS uses AT-TLS policies, do the following configuration in the policy configuration file:
  • Set the TTLSEnvironmentActions statement HandshakeRole parameter to ServerWithClientAuth.
  • Set the TTLSEnvironmentActions -> TTLSEnvironmentAdvancedParms statement ClientAuthType parameter to SAFCHECK.

1 The application ID required in the DCAS Format 1 and Format 2 requests must match the name of a valid PassTicket data profile defined in RACF using the PTKTDATA class. See z/OS Security Server RACF Security Administrator's Guide for information about defining PTKTDATA for applications.

Parent topic: Interfacing with the Digital Certificate Access Server (DCAS)

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014