NEW FUNCTION - ADD PKCS #12 CERTIFICATE/KEY STORE SUPPORT FOR
SSL/TLS ENVIRONMENT
APAR Identifier ...... PI29130 Last Changed ........ 15/09/22
NEW FUNCTION - ADD PKCS #12 CERTIFICATE/KEY STORE SUPPORT FOR
SSL/TLS ENVIRONMENT
Symptom ...... NF NF Status ........... CLOSED UR1
Severity ................... 4 Date Closed ......... 15/01/22
Component .......... 5735FAL00 Duplicate of ........
Reported Release ......... 630 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 630 : UI25021 available 15/09/22 (1502 )
Parent APAR: OA45216
Child APAR list:
ERROR DESCRIPTION:
NEED PKCS #12 CERTIFICATE/KEY STORE SUPPORT FOR SSL/TLS
ENVIRONMENT
LOCAL FIX:
PROBLEM SUMMARY:
****************************************************************
* USERS AFFECTED: Users of z/VM System SSL. *
****************************************************************
* PROBLEM DESCRIPTION: System SSL has been enhanced to support *
* the utilization of a PKCS #12 file as a *
* certificate/key store when defining a *
* SSL/TLS environment. *
****************************************************************
* RECOMMENDATION: APPLY PTF *
****************************************************************
System SSL has been enhanced to support SSL/TLS
environments using a PKCS #12 file as the certificate/key
store.
PROBLEM CONCLUSION:
TEMPORARY FIX:
COMMENTS:
System SSL has been updated to add support to read and utilize
PKCS #12 certificate/key stores when establishing SSL/TLS
environments.
Use System SSL environment variables GSK_KEYRING_FILE and
GSK_KEYRING_PW to define the file name and password for the
the PKCS #12 certificate/key store.
To display the contents of a PKCS #12 certificate/key store use
the System SSL GSKKYMAN command line function -dc or -dcv with
option -p12 filename.
The following documentation updates are made for this APAR:
Title: z/VM TCP/IP User's Guide
Document Number: SC24-6240-XX
Make the following changes to "Chapter 7. SSL Certificate/Key
Management and SSL Tracing Information".
In section "SSL Certificate Management", replace the third
paragraph, which begins with "SSL uses the GSK_KEYRING_FILE",
with the following paragraphs:
SSL also uses PKCS #12 standard files created according to
PKCS #12 V3.0. These files must be created as binary format
files whose fully qualified file name does not exceed 251
characters in length and does not end with .kdb, .rdb, or
.sth.
SSL supports PKCS #12 certificate and private key objects
types. Any other object types within the file are ignored.
All certificates within the file are treated as trusted
certificates and no certificate can be identified as a default
certificate.
The PKCS #12 file is protected by a password and the integrity
of the file is ensured by a SHA-1 message authentication
value.
When the certificates from a PKCS #12 file are read into
storage they are assigned a label using either the PKCS #12
friendly name, if one exists, or the certificate's subject
distinguished name. When the friendly name or the subject
distinguished name value is greater than 127 characters, only
the first 127 characters are used. If multiple certificates
have the same friendly name value, the first encountered
certificate is read into storage. Any other certificate with
that friendly name is ignored. If a certificate is encountered
that does not contain a friendly name and the subject
distinguished name is empty, the processing of the PKCS #12
file fails. As with key database files, the label is case
sensitive.
SSL uses the GSK_KEYRING_FILE environment variable to specify
the locations of the PKI private keys and certificates. The
key database file name or the PKCS #12 file name is passed in
this environment variable.
In section "GSKKYMAN Command Line Mode Syntax", add the
following option to the -dc and -dcv functions in the syntax
diagram:
-p12 filename
Under "Options", change the first paragraph of the description
of the -k option to the following:
Specifies the name (fn) of the key database. This option is
mutually exclusive with the -p12 option. You will be prompted
for the key database file name if neither this option nor the
-p12 option is specified. The length of the fully qualified
file name cannot exceed 251 characters. If the file name does
not end with an extension of 1-3 characters, the length of the
fully qualified file name cannot exceed 247 characters.
Finally, the key database name cannot end with .rdb or
.sth
Under "Options", add the following description for the -p12
option:
Specifies the name of the PKCS #12 file containing the
certificates to be displayed. This option is mutually
exclusive with the -k option. The length of the fully
qualified file name cannot exceed 251 characters. If the file
name does not end with an extension of 1-3 characters, the
length of the fully qualified file name cannot exceed 247
characters. Lastly, the PKCS #12 file cannot end with .kdb,
.rdb or .sth.
Under "Usage", change the first paragraph to the following:
The GSKKYMAN command is used to manage a key database and its
associated request database, or to list the contents of a PKCS
#12 file. Interactive menus are displayed if no command
options are specified. Otherwise, the requested database/PKCS
#12 file function is performed and the GSKKYMAN command exits.
and add the following after the first paragraph:
Note: The ability to display the contents of a PKCS #12 file
is not supported through the interactive menu-driven
interface.
If the -p12 (PKCS #12 file) option is specified with the -dc
or -dcv functions, and the -l option is also specified, the
certificate with the matching label is displayed. If the -l
option is not specified, all certificates within the file are
displayed.
If the command does not specify the -p12 option, then it is
assumed that the function is to be performed for a key
database. If neither the -k nor the -p12 option is specified,
the user is prompted for a key database file name.
If both the -k and -p12 options are specified, the command is
rejected and an error message is displayed.
MODULES/MACROS: GSKCMS31 GSKC31 GSKC31F GSKKYMAN GSKMSGA
GSKMSGS GSKSSL GSKSUS31 GSKS31 GSKS31F GSKTRACE
SRLS: SC246240XX
RTN CODES:
CIRCUMVENTION:
MESSAGE TO SUBMITTER: