Enable Client Certificate Authentication in z/VM SSL
APAR Identifier ...... PM52716 Last Changed ........ 12/11/20
ENABLE CLIENT CERTIFICATE AUTHENTICATION IN Z/VM SSL
Symptom ...... IN INCORROUT Status ........... CLOSED PER
Severity ................... 3 Date Closed ......... 12/02/27
Component .......... 5735FAL00 Duplicate of ........
Reported Release ......... 610 Fixed Release ............ 999
Component Name TCP/IP V2 FOR V Special Notice
Current Target Date .. Flags
SCP ...................
Platform ............
Status Detail: SHIPMENT - Packaged solution is available for
shipment.
PE PTF List:
PTF List:
Release 610 : UK74833 available 12/02/27 (1201 )
Release 620 : UK74834 available 12/02/27 (1202 )
Parent APAR:
Child APAR list:
ERROR DESCRIPTION:
The z/VM SSL server allows for server-certificate validation
today, but it does not currently support client-certificate
validation during handshaking. The lack of this support
prevents a client from presenting a certificate to SSLSERV, thus
denying the client the ability to identify itself through its
certificate. This SSL support is required for z/VM to comply
with Common Criteria evaluation requirements.
LOCAL FIX:
PROBLEM SUMMARY:
****************************************************************
* USERS AFFECTED: All users of secured Telnet on z/VM. *
****************************************************************
* PROBLEM DESCRIPTION: *
****************************************************************
* RECOMMENDATION: APPLY PTF *
****************************************************************
Existing exploitation of z/VM SSL by the Telnet server allowed
for the use of only a server certificate in the handshaking
process. This means that a connecting client's certificate
cannot be validated by the z/VM SSL Server. This
functionality is part of the standard defined in RFC 4346.
PROBLEM CONCLUSION:
z/VM Telnet and the SSL Server have been updated to allow
for the validation of a client's digital certificate during
the creation of dynamic (or, explicitly negotiated) SSL
connections. This is accomplished through the addition of
a new INTERNALCLIENTPARMS statement, CLIENTCERTCHECK, which
can be specified in the TCP/IP server configuration file.
CLIENTCERTCHECK may accept one of two values: 'NONE' (the
default) or 'FULL'.
CLIENTCERTCHECK FULL
All dynamically secure TELNET connections must present a
client certificate for validation by the SSL Server. This
option cannot be specified in conjunction with
SECURECONNECTION NEVER.
CLIENTCERTCHECK NONE
No client certificate validation will be performed for
secure TELNET connections. This is the default behavior.
If CLIENTCERTCHECK is enabled, then a client must present an
appropriate certificate during the handshaking process. This
certificate is validated against the contents of the z/VM SSL
database resident in the Byte File System. If the certificate
does not pass validation, then the connection is rejected.
The revised information that follows will be included in any
future updates to the following publications:
===============================================================
GC24-6201-02 -- z/VM Migration Guide
Section: Summary of Changes
New text:
V6.2 APAR: Client Certificate Validation for z/VM SSL Server
With the PTFs for APAR PM57216, z/VM provides enhancements
to the SSL Server to accommodate client certificate
validation as a part of handshaking for dynamic SSL
connections. This provides a means for TLS handshaking to
incorporate mutual authentication of certificates before
the establishment of a secure connection.
For more information, see:
- z/VM Secure Configuration Guide
- z/VM TCP/IP Planning and Customization
- z/VM TCP/IP User's Guide
===============================================================
SC24-6238-00 -- z/VM: TCP/IP Level 610 Planning and
Customization
Chapter 21: Configuring the TCP/IP Server
Section: 'INTERNALCLIENTPARMS Statement'
The diagram for INTERNALCLIENTPARMS will be adjusted to include
CLIENTCERTCHECK, as follows:
.- CLIENTCERTCHECK NONE -.
|-----+------------------------+----|
'- CLIENTCERTCHECK FULL -'
The operand list will be updated to include the description of
CLIENTCERTCHECK, as follows:
CLIENTCERTCHECK FULL
All dynamically secure TELNET connections must present a
client certificate for validation by the SSL Server. This
option cannot be specified in conjunction with
SECURECONNECTION NEVER.
CLIENTCERTCHECK NONE
No client certificate validation will be performed for
secure TELNET connections. This is the default behavior.
The INTERNALCLIENTPARMS Usage Note list will be updated as
follows:
The SECURECONNECTION, CLIENTCERTCHECK and TLSLABEL options
may be modified by an INTERNALCLIENTPARMS statement using the
NETSTAT OBEY or OBEYFILE commands.
================================================================
GC24-6235-00 -- z/VM: TCP/IP Level 610 Diagnosis Guide
Chapter 14: SSL Server Diagnosis
Heading: "Trace Connections NODATA"
Subheading: "SSL Server Console"
New trace output will be displayed.
The Explanation section will be modified as follows -
New text for list item (4):
The client's certificate has been presented and validated by
the SSL server. This always follows the validation of the
server certificate and would not appear if handshaking had
failed. If the client certificate had been rejected, that
would have been indicated by this trace entry. The
certificate is identified by the Common Name, per X.509
format standards.
The entry currently labeled (4) will be relabeled to (5).
Chapter 14: SSL Server Diagnosis
Heading: "Trace Connections DATA"
Subheading: "SSL Server Console"
New trace output will be displayed.
The Explanation section will be modified as follows -
New text for list item (3):
Identifies that the SSL server is processing handshake
operations and may be requesting the client to present a
valid certificate. Data is being sent in cleartext because
handshaking has not yet been completed.
New text for list item (5):
The client's certificate has been presented and validated
by the SSL server. This always follows the validation of
the server certificate and would not appear if handshaking
had failed. If the client certificate had been rejected,
that would have been indicated by this trace entry. The
certificate is identified by the Common Name, per X.509
format standards.
Text currently labeled (3) should be relabeled to (4).
Text currently labeled (4) should be relabeled to (6).
Text currently labeled (5) should be relabeled to (7). The
reference to (4) should be updated to (6).
Text currently labeled (6) should be relabeled to (8).
Text currently labeled (7) should be relabeled to (9). The
references to (6) should be changed to (8).
Text currently labeled (8) should be relabeled to (10). The
references to (4), (5), (6), (7) should be changed to (6).
(7), (8), and (9) respectively.
===============================================================
SC24-6240-00 -- z/VM: TCP/IP Level 610 User's Guide
Chapter 6: Monitoring the TCP/IP Network
Section: Examples
Subsection: CONFIG Statement
The output of NETSTAT CONFIG PARMS will be adjusted to display
the Client Cert Check field.
netstat config parms
VM TCP/IP Netstat Level 610 TCP/IP Server Name: TCPIP
Assorted Parameters
Check Consistency: No CLAW Double NOP: No
CP Dump: No VM Dump: No
Ignore Redirects: No IPv6 Ignore Redirects: No
ACB Cushion: Yes Forwarding Enabled: Yes
Warn on Level Mismatch: Yes RFC1323 Support Yes
UDP Queue Limit: Yes IPv4 PMTU Default Enabled: No
Permitted Users Only: No Proxy ARP: No
Restrict Low Ports: No Secure Local: No
Source VIPA: No IPv6 Source VIPA: No
Stop On CLAW Error: No
Internal Client Settings
Asynchronous Input: No CCS Terminal Name: TCPIP
Connection Exit: <none> EOJ Time Out: 120
Go Aheads Disabled: No Ignore EAU Data: No
Inactivity Timeout: 0 LDev Range: 0000 -
Scan Interval: 60 Timemark Timeout: 0
TN3270E Enabled: Yes Use SC Exit for TN3270E: No
TN3270E Exit: <none> Transform: No
Secure Connection: Allowed TLS Label: ZVMCER
Client Cert Check: None
Port(s): 23 623
===============================================================
GC24-6237-00 -- z/VM: TCP/IP Level 610 Messages and Codes
Chapter 19, 'TCP/IP Server Messages'
Section 'Numbered Messages'
The following new messages will be added:
DTCSTM360E Telnet server: Invalid or missing value for
CLIENTCERTCHECK. Using CLIENTCERTCHECK NONE.
Explanation: An INTERNALCLIENTPARMS statement contained an
invalid or missing parameter for CLIENTCERTCHECK. The default
parameter NONE will be used.
System Action: The Telnet server will not validate clients'
certificates for secure connections.
User Response: If validation of clients' certificates for
secure connections is desired, add or correct the
CLIENTCERTCHECK parameter by issuing NETSTAT OBEY or OBEYFILE
with the appropriate INTERNALCLIENTPARMS statement. Otherwise
specify the CLIENTCERTCHECK parameter NONE on the
INTERNALCLIENTPARMS statement.
DTCSTM363W Telnet server: Using CLIENTCERTCHECK FULL, but
cleartext connections are <state>.
Explanation: SECURECONNECTION parameter ALLOWED or PREFERRED
was specified. While this requires clients connecting through
a secure connection to present a certificate that can be
validated against the certificate database which provides extra
security for secure connections, the Telnet server still allows
cleartext connections without any restrictions. This
configuration is useful in test installations only and should
be avoided in production systems.
System Action: The Telnet server continues processing.
User Response: If you want to allow only validated clients to
connect, change the SECURECONNECTION parameter to REQUIRED by
issuing NETSTAT OBEY or OBEYFILE with an appropriate
INTERNALCLIENTPARMS statement. If you do not want to validate
clients at all, remove CLIENTCERTCHECK from
INTERNALCLIENTPARMS. Otherwise no further action is required.
DTCSTM364E Telnet server: Using CLIENTCERTCHECK FULL, but
secure connections are disabled. Internal Client will not
start.
Explanation: SECURECONNECTION was missing or parameter NEVER
was specified along with CLIENTCERTCHECK FULL in the
INTERNALCLIENTPARMS statement. This combination of options
is disallowed.
System Action: The Telnet server will not start.
User Response: To correct, issue NETSTAT OBEY or OBEYFILE with
a corrected INTERNALCLIENTPARMS statement: If you do not want
to support secure connections, remove the CLIENTCERTCHECK
option. If you want to allow secure connections, add or
correct the SECURECONNECTION parameter to a value other than
NEVER.
DTCSTM365E Telnet server: Using CLIENTCERTCHECK FULL, but
secure connections are disabled. Settings remain unmodified.
Explanation: An attempt to modify the Telnet server
configuration failed: SECURECONNECTION was missing or parameter
NEVER was specified along with CLIENTCERTCHECK FULL in the
INTERNALCLIENTPARMS statement. This combination of options is
disallowed.
System Action: The Telnet server continues processing. None of
the options in the INTERNALCLIENTPARMS statement were applied.
User Response: To correct, issue NETSTAT OBEY or OBEYFILE with
a corrected INTERNALCLIENTPARMS statement: If you do not want
to support secure connections, remove the CLIENTCERTCHECK
option. If you want to allow secure connections, add or correct
the SECURECONNECTION parameter to a value other than NEVER.
DTCSTM366E Telnet server: Invalid option <value> to parameter
CLIENTCERTCHECK. Internal Client will not start.
Explanation: An attempt to modify the Telnet server
configuration failed. The specified option to the
CLIENTCERTCHECK parameter in the INTERNALCLIENTPARMS statement
was not recognized.
System Action: The Telnet server will not start.
User Response: To correct, issue NETSTAT OBEY or OBEYFILE with
a corrected INTERNALCLIENTPARMS statement, specifying one of
the valid options to the CLIENTCERTCHECK parameter: NONE or
FULL.
DTCSTM367E Telnet server: Invalid option <value> to parameter
CLIENTCERTCHECK. Settings remain unmodified.
Explanation: An attempt to modify the Telnet server
configuration failed. The specified option to the
CLIENTCERTCHECK parameter in the INTERNALCLIENTPARMS statement
was not recognized.
System Action: The Telnet server continues processing. None
of the options in the INTERNALCLIENTPARMS statement were
applied.
User Response: To correct, issue NETSTAT OBEY or OBEYFILE
with a corrected INTERNALCLIENTPARMS statement, specifying
one of the valid options to the CLIENTCERTCHECK parameter:
NONE or FULL.
TEMPORARY FIX:
COMMENTS:
MODULES/MACROS: CMCOMM CMNETST DTCINMNX MSNETSTA MSTCP
PROFILE SSLADMIN SSLADMIO SSLADMNP SSLCACHE SSLCIPHS SSLCTLIO
SSLDPUMP SSLDSPTC SSLGSKCF SSLMNTOR SSLREPRT SSLSCBEX SSLSTART
SSLTOOLS SSLTRACE SSLTRSIT TCMIB TCPARSE TCPEXITS TCPIP
TCPIPIN TCPREQU TCUTIL TNSTMAS
SRLS: NONE
RTN CODES:
CIRCUMVENTION:
None
MESSAGE TO SUBMITTER: