Access x.509 Public and Private Key Certificates
7 CRYPTOGRAPHIC FACILITY UTILITY PKCRYUTL
The SecureZIP for z/OS IBM Cryptographic Facilities Integration feature enables the selection of locally activated IBM cryptographic facilities to complete cryptographic service requests for data encryption and digital signature processing. (See “SecureZIP ICSF Operations” in the “System Requirements” section of chapter 1.)
Cryptographic Facility Categories
SecureZIP for z/OS automatically determines which facilities are available for use when a
cryptographic service is required. It also selects which facility to use based on configurable preference lists specified through either the defaults module or a command.
Facilities are organized into sets of similar cryptographic functionality. For example, all
symmetric data encryption methods, such as DES and AES, fall into the ENCRYPTDATA facility category. Digital signature creation or authentication requires a cryptographic HASH facility. (See also the FACILITY_ENCRYPTDATA, FACILITY_HASH, and FACILITY_RANDOM commands in the SecureZIP for z/OS User’s Guide).
Assessing a System’s Cryptographic Capabilities with PKCRYUTL
Available ICSF APIs and underlying facilities (hardware or software emulation) vary across system configurations (see the table “ICSF feature/facility requirements” in chapter 1). The PKCRYUTL utility program provided with the product can help the administrator or user select the most appropriate facility settings when planning to employ cryptographic features of
SecureZIP for z/OS.
The simplest choice for facility settings is to allow SecureZIP to choose a facility based on the default settings distributed with product. As distributed, SecureZIP gives preference first to ICSF hardware services, then to ICSF software emulation, and finally to software
cryptographic facilities native to the SecureZIP product. This order of precedence generally provides the best performance when used in conjunction with the default
ENCRYPTION_METHOD and SIGN_HASHALG algorithm settings and ensures that at least one facility can be selected to complete the processing request.
PKCRYUTL can also be used to verify that alternative facility preference or algorithm settings will run on a target system.
PKCRYUTL Execution
The SecureZIP product provides sample batch JCL in INSTLIB(PKCRYUTL) that will execute a report step for each cryptographic category.
The SecureZIP Administration Services ISPF dialog has a “Cryptographic Services Utility” selection that provides an options panel for foreground execution. Online help is also accessible in the dialog.
PKCRYUTL Reporting
The utility is intended to be run once for a facility category to be assessed. Multiple processing phases are performed by the utility during the run to:
Report on the basic operating environment
Report active ICSF facilities
Report which API facilities are available for SecureZIP to use
Run timing tests for available facilities
Report throughput rates for various algorithm/facility combinations
Indicate which facility would be selected for a properly licensed SecureZIP product
PKCRYUTL Sample Report
ZPEN350I PKCRYUTL 1.4 Cryptographic API Review Utility
ZPEN350I Copyright (C) 1989-2006 PKWARE, Inc. All rights reserved. ZPEN350I Program and Output used by permission only. PKWARE, Inc. ZPEN378I Testing with 1048571 Bytes Active
ZPEN336I CSRSI Query IBM Type(2066) Mod(0A2) #(000000000001824A) ZPEN300I OSname<z/OS> OS Ver(01) Rel(06) Mod( ) HWclass<Z/X00 > ZPEN307I ICSF is Active/CCVTACT
ZPEN308I ICSF is at a proper level for CSFIQF ZPEN309I z/Architecture Hardware Available -Z/X00
ZPEN313I CSNBSYE (AES) System Capable with ICSF when available. ZPEN314I AES Software Only Available -Z/X00
ZPEN320I CryptoAPI Facilities HW SW SecureZIP ZPEN321I 96 Bit Encryption --- --- PKW ZPEN321I AES 128 Encryption --- SYE BSAFE ZPEN321I AES 192 Encryption --- SYE BSAFE ZPEN321I AES 256 Encryption --- SYE BSAFE ZPEN321I 3DES Encryption ENC --- BSAFE ZPEN321I DES Encryption ENC --- BSAFE ZPEN321I RC4 Encryption --- --- BSAFE ZPEN321I CRC32 Hashing --- --- PKW ZPEN321I SHA1 Hashing OWH --- BSAFE ZPEN321I MD5 Hashing --- OWH BSAFE ZPEN321I SHA256 Hashing --- --- --- ZPEN321I Random Data Gen RNG --- PKW
ZPEN322I Facility Encryptdata Seq: IBMHW(1) IBMSW(2) PKW(3) ZPEN322I Facility Hash (Signature) Seq: IBMHW(1) IBMSW(2) PKW(3) ZPEN322I Facility Randomdata Seq: IBMHW(1) IBMSW(2) PKW(3)
ZPEN340I /---Encryptdata Matrix (01) ---/ ZPEN341I 0001(96 Bit Encryption ) Select (10/10) SecureZIP ZPEN342I Status-IBMHW(-NotCap-) IBMSW(-NotCap-) PKW( PKW )
ZPEN341I 6801(RC4 Encryption ) Select (10/10) SecureZIP ZPEN342I Status-IBMHW(-NotCap-) IBMSW(-NotCap-) PKW( BSAFE )
ZPEN341I 660E(AES 128 Encryption) Select (20/70) IBM Software ZPEN342I Status-IBMHW( -NoAPI-) IBMSW(SYE/SYD ) PKW( BSAFE )
ZPEN341I 660F(AES 192 Encryption) Select (20/70) IBM Software ZPEN342I Status-IBMHW( -NoAPI-) IBMSW(SYE/SYD ) PKW( BSAFE )
ZPEN341I 6610(AES 256 Encryption) Select (20/70) IBM Software ZPEN342I Status-IBMHW( -NoAPI-) IBMSW(SYE/SYD ) PKW( BSAFE )
ZPEN341I 6603(3DES Encryption ) Select (40/70) IBM Hardware ZPEN342I Status-IBMHW(ENC/DEC ) IBMSW( -NoAPI-) PKW( BSAFE )
ZPEN341I 6601(DES Encryption ) Select (40/70) IBM Hardware ZPEN342I Status-IBMHW(ENC/DEC ) IBMSW( -NoAPI-) PKW( BSAFE )
********************************************** ZPEN370I *************Start of Testing***************** *************Nbr of Bytes=1048571************* *************Nbr of MEG= 1********************
Test Summary Results CPU Usage
ZPEN383I Crypto Facilities HW SW BSAFE/PKW ZPEN384I 96 Bit Encryption N/A N/A N/A ZPEN384I AES 128 Encryption --- 0.113* 0.167 ZPEN384I AES 192 Encryption --- 0.132* 0.191 ZPEN384I AES 256 Encryption --- 0.150* 0.218 ZPEN384I 3DES Encryption 0.058* --- 1.102 ZPEN384I DES Encryption 0.042* --- 0.378 ZPEN384I RC4 Encryption --- --- 0.072*
Test Summary Results Megabytes/CP Second
ZPEN383I Crypto Facilities HW SW BSAFE/PKW ZPEN384I 96 Bit Encryption N/A N/A N/A ZPEN384I AES 128 Encryption --- 8.83* 5.98 ZPEN384I AES 192 Encryption --- 7.58* 5.23 ZPEN384I AES 256 Encryption --- 6.68* 4.60 ZPEN384I 3DES Encryption 17.19* --- 0.91 ZPEN384I DES Encryption 23.74* --- 2.65 ZPEN384I RC4 Encryption --- --- 13.85*
ZPEN385I-Testing Completed Total CPU Seconds(2.625) Total Elapsed Seconds(3) ZPEN374I-Completing with rc=0 ---
PKCRYUTL Interpretation
Report lines are generated in standard SecureZIP message format. This section includes basic explanatory information for the majority of the messages. Additional information for each message, including system and user response, can be found in the SecureZIP Messages Guide as well as in the online Message section of the SecureZIP ISPF Dialog.
ZPEN300I OSname<oooo> OS Ver(vv) Rel(rr) Mod(mm) HWclass<cccccccc>
A request was made to report on the available cryptographic facilities for the current operating
environment.
The operating system level and hardware platform govern which cryptographic facilities may be available for use.
Classification of hardware.
S/390 Pre-zArchitecture, possibly with G5/G6 Z/X00 zArchitecture z800/z900, possibly with CCF Z/X90 zArchitecture z890/z990, with CPACF
Z9 zArchitecture z9-109 or equivalent, with CPACF
ZPEN301E-AMUTCQRY Error Occurred:
A request was made to report on the available cryptographic facilities for the current operating environment.
An attempt was made to determine what cryptographic facilities are available through ICSF, but required ICSF and/or hardware facilities are not operative.
ZPEN320I The CCVT is not built by ICSF.
The Cryptographic Communications Vector Table is the major control block used in the operating system to govern ICSF service requests.
It appears that ICSF has not been started in the operating environment.
ZPEN303I Either ICSF is not up, or it is up in PCF mode.
It appears that ICSF is not currently running, or an older PCF service is running.
ZPEN304I There are no valid cryptographic units ACTIVE.
Although ICSF is operating, there are no active hardware cryptographic components in the system.
Although one or more may show as ONLINE, they are not usable by ICSF due to configuration settings.
ZPEN305E-Unknown ICSF Error Code: +2+H+
A request was made to report on the available cryptographic facilities for the current operating environment.
An attempt was made to determine what cryptographic facilities are available through ICSF, but required ICSF and/or hardware facilities are not operative.
ZPEN306I State Error Found <State=%02X/Error=%02X>
The Cryptographic Communications Vector Table is the major control block used in the operating system to govern ICSF service requests.
When ICSF environmental conditions are determined to be inappropriate to ICSF operations through SecureZIP this message may be issued.
State Flags:
x'80' - An error has been detected (See Error Flags) x'40' - ICSF is active in the system
x'20' - The ICSF level supports CSFIQF x'10' - z/Architecture hardware is present x'08' - CPACF Crypto Assist Hardware is present x'04' - CSNBSYE/CSNBSYD API services are available
Error Flags:
x'80' - The CCVT has never been initialized by ICSF x'40' - ICSF is not up in an appropriate mode
x'20' - There are no hardware crypto devices available
Sample State/Error codes:
State=80/Error=80 - ICSF was never started.
No other info is available (no CCVT) State=B4/Error=40 - ICSF is in the process of starting but has not completed initialization. State=B4/Error=60 - ICSF has been shut down.
ZPEN307I ICSF is [not] Active/CCVTACT
A request was made to report on the available cryptographic facilities for the current operating environment.
ICSF (which is required for IBMHARDWARE and IBMSOFTWARE cryptographic facility use) is active in the system.
ZPEN308I ICSF is [not] at a proper level for CSFIQF
A request was made to report on the available cryptographic facilities for the current operating environment.
ICSF (which is required for IBMHARDWARE and IBMSOFTWARE cryptographic facility use) is at a release level that supports the ICSF Query Facility CSFIQF. This is
necessary to determine whether more advanced cryptographic services (such as Hardware-based AES) are available for use.
ZPEN309I z/Architecture Hardware Available %s
The Cryptographic Communications Vector Table is the major control block used in the operating system to govern ICSF service requests.
The hardware classification is also shown. - CCF (Cryptographic Coprocessor Feature) may be available with Z/X00 or S/390 systems.
- CPACF (CP Assist for Cryptographic Functions) may be active on Z/X90 or Z9 systems
ZPEN310I CP Assist For Cryptographic Functions Available
The Cryptographic Communications Vector Table is the major control block used in the operating system to govern ICSF service requests.
CPACF hardware acceleration is available for select service requests.
ZPEN313I CSNBSYE (AES) System capable with ICSF when available.
ICSF AES symmetric data encryption can be performed on this system if the IBM Hardware Cryptographic feature is enabled. The CSNBSYE API will be used to access the IBMSOFTWARE or IBMHARDWARE facility depending on the system hardware available.
ZPEN314I AES Software Only Available [system_classification]
Some systems (hardware) do not support hardware-based AES processing. ICSF will provide CSNBSYE API software emulation.
Classification of hardware.
S/390 Pre-zArchitecture, possibly with G5/G6 Z/X00 zArchitecture z800/z900, possibly with CCF Z/X90 zArchitecture z890/z990, with CPACF
Z9 zArchitecture z9-109 or equivalent, with CPACF
ZPEN320I Crypto Facilities HW SW SecureZIP
A request was made to report on the available cryptographic facilities for the current operating environment. A list of supported cryptographic algorithms follows indicating which API facilities are available for use by SecureZIP.
The cryptographic API facilities are categorized into one of the following groups:
HW - IBM Cryptographic Hardware SW - IBM Cryptographic Software SecureZIP - Software algorithms
ZPEN321I [crypto_algorithm] [hw_API] [sw_API] [SecureZIP_API]
A request was made to report on the available cryptographic facilities for the current operating environment. A separate report line is listed for each algorithm to indicate which (if any) API is
available for use by SecureZIP before dynamic evaluation. A subsequent check of each algorithm will be performed based on run-time options and environmental
characteristics.
[crypto_algorithm]
The [crypto_algorithm] name will also identify the use type for the algorithm.
Symmetric Data Encryption algorithms: 96 Bit Encryption AES 128 Encryption AES 192 Encryption AES 256 Encryption 3DES Encryption DES Encryption
RC4 Encryption
Data Integrity and Digital Signature algorithms: CRC32 Hashing SHA1 Hashing MD5 Hashing SHA256 Hashing [hw_API] [sw_API]
The IBM Cryptographic facilities are accessed through one if the following ICSF APIs (hardware and software).
ENC- CSNBENC/CSNBDEC Encipher/Decipher
SYE- CSNBSYE/CSNBSYD Symmetric Key Encrypt/Decrypt OWH- CSNBOWH One way hash
RNG- CSNBRNG Random Number Generation
[SecureZIP_API]
SecureZIP provides software algorithms using one of the following services.
BSAFE-RSA BSAFE CryptoC PKW -PKWARE internal routine
"---" indicates that no service facility could be identified under the API service category for the algorithm.
ZPEN322I [Facility Category] Seq: IBMHW(x) IBMSW(x) PKW(x)
As part of the CryptoAPI report (see also ZPEN320I), the specified FACILITY sequence is displayed.
[x] - The preferred facility order of choice. 0 - Not included in the FACILITY list 1 - First selection if available for use 2 - Second selection if available for use 3 - Third selection if available for use
[Facility Category] Encryptdata
Algorithms associated with symmetric data encryption.
HASH (Signature)
Algorithms associated with hashing.
Uses include digital signature creation and authentication.
RandomData
Algorithms associated with creating random data for encryption extensions (such as Cipher Block Chaining)
ZPEN340I /---[Facility_Category] Matrix ([type_code]) ---/
A request was made to report on the available cryptographic facilities for the current operating environment.
A separate report is listed for each category of cryptographic service. All associated algorithms are included in the report along with resulting selection results.
Encryptdata
Algorithms associated with symmetric data encryption.
HASH (Signature)
Algorithms associated with hashing.
Uses include digital signature creation and authentication.
ZPEN341I [alg_id]([algorithm_name]) Select ([code]) [Facility Category]
A request was made to report on the available cryptographic facilities for the current operating environment.
A separate report line is listed for each algorithm to indicate which (if any) API is selected for use by PKWARE after dynamic evaluation.
Each algorithm is validated against requested FACILITY settings, licensing and facilities reported by ICSF.
[Facility Category]
The final facility chosen is shown.
NONE FOUND
No viable facility could be identified for use. This algorithm cannot be serviced with the current configuration.
IBM Hardware
The CryptoAPI identified in ZPEN321I (HW) will be used
IBM Software
The CryptoAPI identified in ZPEN321I (SW) will be used
SecureZIP
The CryptoAPI identified in ZPEN321I (PKW) will be used
ZPEN342I Status-IBMHW([APIstate]) IBMSW([APIstate]) PKW([APIstate])
A request was made to report on the available cryptographic facilities for the current operating environment.
A separate report line is listed for each algorithm to indicate which (if any) API is available for use by SecureZIP after dynamic evaluation.
Each algorithm is validated against requested FACILITY settings, licensing and facilities reported by ICSF.
[APIstate]
The state of each facility type is reported for the algorithm reported in the preceding ZPEN341I message.
State definitions are as follows:
-NotCap-
The facility category is not capable of servicing this algorithm, and is therefore not available for use.
-NoAPI-
No API could be identified as being available for use in the current run-time environment.
-NoFacil-
This facility was not listed in the associated FACILITY setting, and is not available for use.
-NoLic-
The product does not have the appropriate SecureZIP feature license code enabled to make use of this facility category.
-NotSup-
This algorithm is not supported under the current release of SecureZIP.
BSAFE
BSAFE(r) CryptoC routines included with the SecureZIP product has been identified as being viable for use.
ENC/DEC
For the system platform being executed on, the ICSF CSNBENC(encipher) and CSNBDEC(decipher) API calls were identified as viable for use.
SYE/SYD
For the system platform being executed on, the ICSF CSNBSYE(symmetric key encipher) and CSNBSYD(symmetric key decipher) API calls were identified as viable for use.
PKW
A PKWARE proprietary routine was identified as viable for use.
OWH
For the system platform being executed on, the ICSF CSNBOWH(One Way Hash) API call was identified as viable for use.
ZPEN383I Crypto Facilities HW SW SecureZIP
A request was made to produce a timing report for supported cryptographic facilities in the current operating environment. A list of supported
cryptographic algorithms follows indicating which API facilities are available for use by SecureZIP.
A list of supported cryptographic algorithms follows showing timing test values for each.
A preceding header line will indicate whether this report is for raw TCB CPU time, or a computed throughput rate in megabytes per CP Second.
ZPEN384I [crypto_algorithm] [hw_API] [sw_API] [SecureZIP_API]
A request was made to produce a timing report for supported cryptographic facilities in the current operating environment.
A value will be listed for each facility category associated with the correlated facility API listed in ZPEN321I.
An "*" following a timing value indicates that the corresponding API will be selected based on the facility preference list shown in ZPEN322I.
is for raw TCB CPU time, or a computed throughput rate in megabytes per CP Second.
Note: The "96 bit encryption" algorithm will not have timings run. The SecureZIP(PKW) facility API will always be selected for use when