ENABLE SSL/TLS SERVER FOR PKCS #12 USAGE USING V1.13 SYSTEM SSL
APAR Identifier ...... PI31202 Last Changed ........ 15/02/13
ENABLE SSL/TLS SERVER FOR PKCS #12 USAGE USING V1.13 SYSTEM SSL
Symptom ...... NF NEWFUNCTION Status ........... CLOSED UR1
Severity ................... 4 Date Closed ......... 15/02/12
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 : UI25144 available 15/02/13 (1502 )
Parent APAR:
Child APAR list:
ERROR DESCRIPTION:
System SSL V1.13 (used by z/VM 6.3) now supports the
use of PKCS #12 formatted files as certificate and key
repositories. PKCS #12 is a common file format used by
cryptographic libraries today. Enabling
System SSL for this functionality allows for greater
interoperability between environments.
LOCAL FIX:
PROBLEM SUMMARY:
****************************************************************
* USERS AFFECTED: Users of the z/VM SSL Server *
****************************************************************
* PROBLEM DESCRIPTION: *
****************************************************************
* RECOMMENDATION: APPLY PTF *
****************************************************************
System SSL V1.13 (used by z/VM 6.3) now supports the
use of PKCS #12 formatted files as certificate and key
repositories. PKCS #12 is a common file format used by
cryptographic libraries today. Enabling
System SSL for this functionality allows for greater
interoperability between environments.
PROBLEM CONCLUSION:
TEMPORARY FIX:
COMMENTS:
The SSL Server will operate as follows when opening a
key database or PKCS #12 file:
(1) if the database has a file extension of .kdb, it is a
standard key database. The database password must be in a file
with an extension of .sth, and the password file name must
be the same as the database file name.
(2) if the database has a file extension of .p12 or .pfx, it is
a PKCS #12 file. Its default password must be stored in a
user-created file with an extension of .p12pw, and the password
file name must be the same as the PKCS#12 file name.
(3) if the database filetype does not match either, it is
unsupported database type, an error message will be displayed
and the SSL server will not initialize.
Two new configuration variables will be added:
one to store the PKCS #12 password file, the other to store the
PKCS #12 password. The new parameters will be used to initialize
the the PKCS #12 database.
------------------------------------------------------------
The following documentation updates are made for this APAR:
Title: z/VM TCP/IP User's Guide
Document Number: SC24-6240-05
Page 227:
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 by convention, has a file extension
of .p12 or .pfx.
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.
gskkyman Overview
gskkyman is a program that creates, fills in, and manages a
file that contains PKI private keys, certificate requests, and
certificates. This file is called a key database and, has a
file extension of .kdb. gskkyman can also export a certificate
with its private key from a key database file to form a
PKCS #12 file. This can be accomplished through the
Key Management menu of the gskkyman utility (see below),
using the following sequence of selections:
1 - Manage keys and certificates
7 - Export certificate and key to a file
3 - Binary PKCS #12 Version 3
Page 228:
In section "Key Database Files", change the section name to
"Key Database Files and PKCS #12 Files". And replace all the
string "key database files" with the string "key database files
and PKCS #12 files", replace all the string "key database file"
with the string "key database file and PKCS #12 file".
Besides, after the fifth paragraph, which begins with "A key
database that is created as a FIPS mode database", add a new
paragraph as foolows:
To use a PKCS #12 file in FIPS mode, the file must be protected
using TDES, which means when creating a PKCS #12 file from
certificates within a key database file, using the gskkyman
utility, the key database must be a FIPS key database. Such a
database, however, may be opened as read-only when executing
in non-FIPS mode. PKCS #12 file created while in non-FIPS
mode cannot be opened when executing in FIPS mode.
Page 271:
In section "GSKKYMAN Command Line Mode Syntax", add the
following option to the -dc and -dcv functions in the syntax
diagram:
-p12 fn -l lbl
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.
------------------------------------------------------------
The following documentation updates are made for this APAR:
Title: z/VM TCP/IP Planning and Customization
Document Number: SC24-6238-06
Page 534
In section "Step 5: Update the DTCPARMS File for the SSL Server
Pool", Under "Note", change the sixth and seventh items to
the following:
Require the SSL certificate database file space to be
different from /../VMBFS:VMSYS:GSKSSLDB/ or require the mount
point for this file space to be other than /etc/gskadm.
Require the SSL certificate database pathname to be different
from /etc/gskadm/Database.kdb.
Page 536:
In section "VMSSL Command", change the description for
"KEYFILE pathname" under "Operands" as follows:
specifies the name of the certificate database (key database
file or PKCS #12 file) that is to be used by the SSL server.
The file name is case sensitive, and can be specified as an
absolute or as a relative pathname. The default key database
file name is /etc/gskadm/Database.kdb
Under "Usage Notes", replace the fourth note, which begins
with "For information about trace output", with the
following notes:
4. To use a PKCS #12 file in FIPS mode, the file must be
protected using TDES. When creating a PKCS #12 file from
certificates within a key database file, using the gskkyman
utility, the key database must be a FIPS key database.
5. For information about trace output, see the z/VM: TCP/IP
Diagnosis Guide.
Page 542:
In section "Step 6: Set Up the Certificate (Key) Database",
replace the statement "Use the steps that follow to create and
prepare the certificate database" with the following statements:
Only two kinds of certificate database are allowed as SSL
certificate database, one is the standard key database file
which has a file extension of .kdb, another is the PKCS #12
certificate store which has a file extension of .p12 or .pfx.
SSL server will not support the other certificate database
file name.
Use the steps that follow to create and prepare the key
database file:
Page 544:
Add a new paragraph after the last paragraph on page 544:
The PKCS #12 file could be created through the Key
Management menu of the gskkyman utility and is placed in the
BFS directory, it will be introduced below. Besides, a
password file which has a file extension of .p12pw need to be
created to store the password of the
PKCS #12 file and is placed in the same BFS directory.
OPENVM PERMIT command should be used to grant read access
to them to allow the SSL server to access them.
MODULES/MACROS: SSLADMIO SSLADMNP SSLCIPHS SSLCTLIO SSLDPUMP
SSLGSKCF SSLMNTOR SSLPARGS SSLSTART SSLTRACE SSLTRSIT VMSSL
SRLS: SC24623806 SC24624005
RTN CODES:
CIRCUMVENTION:
MESSAGE TO SUBMITTER: