Chapter 3. Principles of operation and hardware and software requirements
3.3 Exploitation of the z/OS integrated cryptography
3.3.2 Application programming interfaces exploited by the Encryption Facility
The z/OS integrated cryptographic functions are made available to applications through:
The ICSF API for all types of coprocessors. The z/OS Cryptographic Services
Integrated Cryptographic Service Facility Application Programmer’s Guide,
SA22-7522, describes all the ICSF cryptographic services that can be called by applications. Refer to this book for any detailed information about the ICSF services that we mention in this chapter.
“System z Assembler instructions for the CPACF” (z9, z990, and z890 only). These are problem state instructions that any application can use and are described in z/Architecture Principles of Operation, SA22-7832, as part of the z/Architecture Message-Security Assist (MSA).
Notes:
The PCICC “feature,” the book that is plugged into the system, contains two coprocessors or “card.” Beware of this somehow confusing terminology in the IBM documentation: By plugging in a “feature,” you are plugging in two “cards” at once.
The PCICC feature must be enabled by installing a Function Control Vector (FCV) diskette. See 3.3.3, “Cryptographic coprocessors administration considerations” on page 35.
Note: What follows can be considered as somehow advanced information
about the ICSF services exploited by the Encryption Facility for z/OS. At a higher level, this information can also be used to decide what profiles in the RACF CSFSERV class of resources have to be defined and protected in order to control access to the cryptographic services that the Encryption Facility calls.
Cryptographic services exploited on z9, z990, and z980
The Encryption Facility for z/OS invokes the following services:The ICSF callable service CSNBRNG (Random Number Generate) in order to get a high-quality random number for a dynamically generated symmetric key and a corresponding initialization vector.
The service is provided by a CEX2C/PCIXCC.
The ICSF callable service CSNBOWH (One Way Hash Generate) is called with the SHA-1 keyword for the Generation of a T-DES or AES-128 clear key derived from the optional password.
ICSF, in turn, uses the KIMD and KLMD instructions to invoke the CPACF. The ICSF callable service CSNBCKM (Multiple Clear Key Import).
Some of the ICSF callable services that the Encryption Facility for z/OS exploits operate only on T-DES keys already encrypted with the
coprocessor’s master key. CSNBCKM is a service that takes a clear T-DES data key value and returns it encrypted under the master key.
The service is provided by the CEX2C/PCIXCC.
The ICSF callable service CSNDSYX (Symmetric Key Export) to get a T-DES key encrypted with a designated RSA public key.
The T-DES key is presented to the service already encrypted under the coprocessor master key.
The service is provided by the CEX2C/PCIXCC.
The ICSF callable service CSNDSYI (Symmetric Key Import) to likewise decrypt with a designated RSA private key a T-DES key that was encrypted with the corresponding RSA public key.
The T-DES key is provided by the service encrypted with the coprocessor master key.
The service is provided by the CEX2C/PCIXCC.
The ICSF callable service CSNDPKE (PKA Encrypt). This service is called to encrypt a clear AES-128 key with a designated RSA public key.
The service is provided by the CEX2C/PCIXCC.
The ICSF callable service CSNDPKD (PKA Decrypt). This service is called to decrypt with a designated RSA private key a clear AES-128 key encrypted with the corresponding RSA public key.
Chapter 3. Principles of operation and hardware and software requirements for the Encryption Facility 33
The ICSF callable service CSNDSYG (Symmetric Key Generate). This service is used to produce directly inside the coprocessor a T-DES key that comes in two different output formats: One form is the T-DES key encrypted with the coprocessor master key and the other form is the same T-DES key encrypted with a designated RSA public key. This is the service used for the ENCTDES option, because the T-DES key is never seen in clear outside of the coprocessor.
The service is provided by the CEX2C/PCIXCC.
The ICSF callable service CSNBENC (Encipher) and CSNBDEC (Decipher) to proceed with the encryption or decryption of data using the ENCTDES option (the T-DES data key is always used encrypted with the coprocessor master key).
The service is provided by the CEX2C/PCIXCC.
Encryption and decryption of data using the T-DES algorithm with a clear key. The CPACF is directly called by the Encryption Facility for z/OS using the KMC instruction.
Encryption and decryption of data using the AES-128 algorithm with a clear key on the System z9 environment.
The CPACF is directly called by the Encryption Facility for z/OS using the KMC instruction.
The ICSF callable services CSNBSYE and CSNBSYD (Symmetric Key Encipher and Decipher) to proceed with the encryption and decryption of data using the AES-128 algorithm with a clear key on the z990 and
z890environments. These two services are provided as software services only by ICSF.
The following ICSF callable services are solely used for the management of the cryptographic keys in the PKDS, either through the RACF RACDCERT
command or the ICSF PKDS Key Management panel (we explain these facilities in Chapter 4, “Planning for the Encryption Facility for z/OS” on page 39). All these services are provided by the CEX2C.
CSNDPKG (PKA Key Generate): To generate an RSA key pair
CSNDPKB (PKA Key Token Build): To prepare a formatted key token to receive a new RSA key pair
CSNDKRC (PKDS Record Create) CSNDKRR (PKDS Record Read) CSNDKRD (PKDS Record Delete) CSNDPKX (PKA Public Key Extract) CSNDDSG (Digital Signature Generate)
Cryptographic services exploited on z900 and z800
The Encryption Facility for z/OS invokes the following services:The ICSF callable service CSNBRNG (Random Number Generate) in order to get a high quality random number for a dynamically generated symmetric key and a corresponding initialization vector.
The service is provided by the CCF.
The ICSF callable service CSNBOWH (One Way Hash Generate) is called with the SHA-1 keyword for the generation of a T-DES or AES-128 clear key derived from the optional password
The service is provided by the CCF.
The ICSF callable service CSNBCKM (Multiple Clear Key Import). Some of the ICSF callable services that the Encryption Facility for z/OS exploits operate only on T-DES keys already encrypted with the coprocessor’s master key. CSNBCKM is a service that takes a clear T-DES data key value and returns it encrypted under the master key.
The service is provided by the CCF.
The ICSF callable service CSNDSYX (Symmetric Key Export) to get a T-DES key encrypted with a designated RSA public key.
The T-DES key is presented to the service already encrypted under the coprocessor master key.
The service is provided by the CCF or the PCICC.
The ICSF callable service CSNDSYI (Symmetric Key Import) to likewise decrypt with a designated RSA private key a T-DES key that was encrypted with the corresponding RSA public key.
The T-DES key is provided by the service encrypted with the coprocessor master key.
The service is provided by the CCF or the PCICC.
The ICSF callable service CSNDPKE (PKA Encrypt). This service is called to encrypt a clear AES-128 key with a designated RSA public key.
The service is provided by the CCF or the PCICC.
The ICSF callable service CSNDPKD (PKA Decrypt). This service is called to decrypt with a designated RSA private key a clear AES-128 key encrypted with the corresponding RSA public key.
Chapter 3. Principles of operation and hardware and software requirements for the Encryption Facility 35
The ICSF callable service CSNDSYG (Symmetric Key Generate). This service is used to produce directly inside the coprocessor a T-DES key that comes as two different output formats: One form is the T-DES key encrypted with the coprocessor master key and the other form is the same T-DES key encrypted with a designated RSA public key. This is the service used for the ENCTDES option, because the T-DES key is never seen in clear outside of the coprocessor.
The service is provided by the CCF or PCICC.
The ICSF callable service CSNBENC (Encipher) and CSNBDEC (Decipher) to proceed with the encryption or decryption of data using either secure T-DES key (ENCTDES option) or clear T-DES key.
The service is provided by the CCF.
The ICSF callable services CSNBSYE and CSNBSYD (Symmetric Key Encipher and Decipher) to proceed with the encryption and decryption of data using the AES-128 algorithm with a clear key. These two services are provided as software services only by ICSF.
The following ICSF callable services are solely used for the management of the cryptographic keys in the PKDS, either through the RACF RACDCERT
command or the ICSF PKDS Key Management panel (we explain these facilities in Chapter 4, “Planning for the Encryption Facility for z/OS” on page 39). All these services are provided by the CCF, except for the CSNDPKG service, which is only provided by the PCICC.
CSNDPKG (PKA Key Generate): To generate an RSA key pair. This service is provided by the PCICC only.
CSNDPKB (PKA Key Token Build): To prepare a formatted key token to receive a new RSA key pair.
CSNDKRC (PKDS Record Create). CSNDKRR (PKDS Record Read). CSNDKRD (PKDS Record Delete). CSNDPKX (PKA Public Key Extract). CSNDDSG (Digital Signature Generate).