Summary of Callable Services

z/OS Cryptographic Services ICSF Application Programmer's Guide

Summary of Callable Services

z/OS Cryptographic Services ICSF Application Programmer's Guide
SA22-7522-16

Table 6 lists the callable services described in this publication, and their corresponding verbs. The figure also references the topic that describes the callable service.

Table 6. Summary of ICSF Callable Services
Verb	Service Name	Function
Managing Symmetric Cryptographic Keys
CSNBCKI CSNECKI	Clear key import	Imports an 8-byte clear DATA key, enciphers it under the master key, and places the result into an internal key token. CSNBCKI converts the clear key into operational form as a DATA key.
CSNBCVG CSNECVG	Control vector generate	Builds a control vector from keywords specified by the `key_type` and `rule_array` parameters.
CSNBCVT CSNECVT	Control vector translate	Changes the control vector used to encipher an external key.
CSNBCVE CSNECVE	Cryptographic variable encipher	Uses a CVARENC key to encrypt plaintext by using the Cipher Block Chaining (CBC) method. The plaintext must be a multiple of eight bytes in length.
CSNBDKX CSNEDKX	Data key export	Converts a DATA key from operational form into exportable form.
CSNBDKM CSNEDKM	Data key import	Imports an encrypted source DES single- or double-length DATA key and creates or updates a target internal key token with the master key enciphered source key.
CSNBEDH CSNEEDH	ECC Diffie-Hellman	Creates symmetric key material from a pair of ECC keys using the Elliptic Curve Diffie-Hellman protocol and the static unified model key agreement scheme or “Z” data (the “secret" material output from D-H process).
CSNBKEX CSNEKEX	Key export	Converts any key from operational form into exportable form. (However, this service does not export a key that was marked non-exportable when it was imported.)
CSNBKGN CSNEKGN	Key generate	Generates a 64-bit, 128-bit, or 192-bit odd parity key, or a pair of keys; and returns them in encrypted forms (operational, exportable, or importable). CSNBKGN does not produce keys in plaintext.
CSNBKGN2 CSNEKGN2	Key generate2	Generates a variable-length HMAC or AES key or a pair of keys; and returns them in encrypted forms (operational, exportable, or importable).
CSNBKIM CSNEKIM	Key import	Converts any key from importable form into operational form.
CSNBKPI CSNEKPI	Key part import	Combines the clear key parts of any key type and returns the combined key value in an internal key token or an update to the CKDS.
CSNBKPI2 CSNEKPI2	Key part import2	Combines the clear key parts of an HMAC or AES key and returns the combined key value in an internal key token or an update to the CKDS.
CSNBKYT CSNEKYT CSNBKYTX CSNEKYTX	Key test	Generates or verifies (depending on keywords in the rule array) a secure verification pattern for keys. CSNBKYT and CSNEKYT require the tested key to be in the clear or encrypted under the master key. CSNBKYTX and CSNEKYTX also allow the tested key to be encrypted under a key-encrypting key.
CSNBKYT2 CSNEKYT2	Key test2	Generates or verifies (depending on keywords in the rule array) a secure verification pattern for keys. CSNBKYT2 and CSNEKYT2 allow the tested key to be in the clear or encrypted under the master key or a key-encrypting key.
CSNBKTB CSNEKTB	Key token build	Builds an internal or external token from the supplied parameters. You can use this callable service to build an internal token for an AKEK for input to the key generate and key part import callable services. You can also use this service to build CCA key tokens for all key types ICSF supports. You can also use this service to build CCA key tokens for all key types ICSF supports.
CSNBKTB2 CSNEKTB2	Key token build2	Builds an internal clear key or skeleton token from the supplied parameters. You can use this callable service to build an internal clear key token for any key type for input to the key test2 callable service. You can use this callable service to build a skeleton token for input to the key generate2 and key part import2 callable services.
CSNBKTR CSNEKTR	Key translate	Uses one key-encrypting key to decipher an input key and then enciphers this key using another key-encrypting key within the secure environment.
CSNBKTR2 CSNEKTR2	Key translate2	Uses one key-encrypting key to decipher an input key and then enciphers this key using another key-encrypting key within the secure environment.
CSNBCKM CSNECKM	Multiple clear key import	Imports a single-, double-, or triple-length clear DATA key, enciphers it under the master key, and places the result into an internal key token. CSNBCKM converts the clear key into operational form as a DATA key.
CSNBSKM CSNESKM	Multiple secure key import	Enciphers a single-, double-, or triple-length clear key under the master key or an input importer key, and places the result into an internal or external key token as any key type. Triple-length keys can only be imported as DATA keys. This service executes only in special secure mode.
CSNDPKD CSNFPKD	PKA decrypt	Uses an RSA private key to decrypt the RSA-encrypted key value and return the clear key value to the application.
CSNDPKE CSNFPKE	PKA encrypt	Encrypts a supplied clear key value under an RSA public key.
CSNBPEX CSNEPEX	Prohibit export	Modifies an operational key so that it cannot be exported.
CSNBPEXX CSNEPEXX	Prohibit export extended	Changes the external token of a key in exportable form so that it can be imported at the receiver node but not exported from that node.
CSNBRKA CSNERKA	Restrict Key Attribute	Modifies an operational variable-length key so that it cannot be exported.
CSNBRNG CSNERNG CSNBRNGL CSNERNGL	Random number generate	Generates an 8-byte random number or a random number with a user-specified length. The output can be specified in three forms of parity: RANDOM, ODD, and EVEN.
CSNDRKX CSNFRKX	Remote key export	Generates or exports DES keys for local use and for distribution to an ATM or other remote device. RKX uses a special structure to hold encrypted symmetric keys in a way that binds them to the trusted block and allows sequences of RKX calls to be bound together as if they were an atomic operation.
CSNBSKI CSNESKI	Secure key import	Enciphers a clear key under the master key, and places the result into an internal or external key token as any key type. This service executes only in special secure mode.
CSNBSKI2 CSNESKI2	Secure key import2	Enciphers a variable-length clear HMAC or AES key under the master key and places the result into an internal key token. This service executes only in special secure mode.
CSNDSYX CSNFSYX	Symmetric key export	Transfers an application-supplied symmetric key from encryption under the host master key to encryption under an application-supplied RSA public key or AES EXPORTER key. The application-supplied key must be an internal key token or the label in the CKDS of a DES DATA, AES DATA, or variable-length symmetric key token.
CSNDSYG CSNFSYG	Symmetric key generate	Generates a symmetric DATA key and returns the key in two forms: enciphered under the DES master key or KEK and under a PKA public key.
CSNDSYI CSNFSYI	Symmetric key import	Imports a symmetric key enciphered under an RSA public key into operational form enciphered under a host master key.
CSNDSYI2 CSNFSYI2	Symmetric key import2	Imports a symmetric key enciphered under an RSA public key or AES EXPORTER key into operational form enciphered under a host master key.
CSNBTCK CSNETCK	Transform CDMF key	Changes a CDMF DATA key in an internal or external token to a transformed shortened DES key.
CSNDTBC CSNETBC	Trusted block create	Creates a trusted block in a two step process. The block will be in external form, encrypted under an IMP-PKA transport key. This means that the MAC key contained within the trusted block will be encrypted under the IMP-PKA key.
CSNBT31X CSNET31X	TR-31 Export	Converts a CCA token to TR-31 format for export to another party.
CSNBT31I CSNET31I	TR-31 Import	Converts a TR-31 key block to a CCA token.
CSNBT31P CSNET31P	TR-31 Parse	Retrieves standard header information from a TR-31 key block without importing the key.
CSNBT31R CSNET31R	TR-31 Optional Data Read	Obtains lists of the optional block identifiers and optional block lengths, and obtains the data for a particular optional block.
CSNBT31O CSNET31O	TR-31 Optional Data Build	Constructs the optional block data structure for a TR-31 key block.
CSFUDK CSFUDK6	User Derived Key	Generates single-length or double-length MAC keys, or updates an existing user derived key.
Protecting Data
CSNBCTT CSNECTT CSNBCTT1 CSNECTT1	Ciphertext translate	Translates the user-supplied ciphertext from one key and enciphers the ciphertext to another key. (This is for DES encryption only.) CSNBCTT and CSNECTT require the ciphertext to reside in the caller’s primary address space. CSNBCTT1 and CSNECCT1 allow the ciphertext to reside in the caller’s primary address space or in a z/OS data space.
CSNBDEC CSNEDEC CSNBDEC1 CSNEDEC1	Decipher	Deciphers data using either the CDMF or the cipher block chaining mode of the DES. (The method depends on the token marking or keyword specification.) The result is called plaintext. CSNBDEC and CSNEDEC require the plaintext and ciphertext to reside in the caller’s primary address space. CSNBDEC1 and CSNEPEC1 allow the plaintext and ciphertext to reside in the caller’s primary address space or in a z/OS data space.
CSNBDCO CSNEDCO	Decode	Decodes an 8-byte string of data using the electronic code book mode of the DES. (This is for DES encryption only.)
CSNBENC CSNEENC CSNBENC1 CSNEENC1	Encipher	Enciphers data using either the CDMF or the cipher block chaining mode of the DES. (The method depends on the token marking or keyword specification.) The result is called ciphertext. CSNBENC and CSNEENC require the plaintext and ciphertext to reside in the caller’s primary address space. CSNBENC1 and CSNEENC1 allow the plaintext and ciphertext to reside in the caller’s primary address space or in a z/OS data space.
CSNBECO CSNEECO	Encode	Encodes an 8-byte string of data using the electronic code book mode of the DES. (This is for DES encryption only.)
CSNBSAD CSNESAD CSNBSAD1 CSNESAD1	Symmetric algorithm decipher	Deciphers data using the AES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. CSNBSAD and CSNESAD require the plaintext and ciphertext to reside in the caller’s primary address space. CSNBSAD1 and CSNESAD1 allows the plaintext and ciphertext to reside in the caller’s primary address space or in a z/OS data space.
CSNBSAE CSNESAE CSNBSAE1 CSNESAE1	Symmetric algorithm encipher	Enciphers data using the AES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. CSNBSAE and CSNESAE require the plaintext and ciphertext to reside in the caller’s primary address space. CSNBSAE1 and CSNESAE1 allows the plaintext and ciphertext to reside in the caller’s primary address space or in a z/OS data space.
CSNBSYD CSNBSYD1 CSNESYD CSNESYD1	Symmetric key decipher	Deciphers data using the AES or DES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. Only clear keys are supported. CSNBSYD and CSNESYD require the plaintext and ciphertext to reside in the caller’s primary address space. CSNBSYD1 and CSNESYD1 allow the plaintext and ciphertext to reside in the caller’s primary address space or in a z/OS data space.
CSNBSYE CSNBSYE1 CSNESYE CSNESYE1	Symmetric key encipher	Enciphers data using the AES or DES algorithm in an address space or a data space using the cipher block chaining or electronic code book modes. Only clear keys are supported. CSNBSYE and CSNESYE require the plaintext and ciphertext to reside in the caller’s primary address space. CSNBSYE1 and CSNESYE1 allows the plaintext and ciphertext to reside in the caller’s primary address space or in a z/OS data space.
Verifying Data Integrity and Authenticating Messages
CSNBHMG CSNEHMG CSNBHMG1 CSNEHMG1	HMAC generation	Generates message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the FIPS-198 Keyed-Hash Message Authentication Code algorithm. CSNBHMG and CSNEHMG require data to reside in the caller's primary address space. CSNBHMG1 and CSNEHMG1 allow data to reside in the caller's primary address space or in a z/OS data space.
CSNBHMV CSNEHMV CSNBHMV1 CSNEHMV1	HMAC verification	Verifies message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the FIPS-198 Keyed-Hash Message Authentication Code algorithm. CSNBHMV and CSNEHMV requires data to reside in the caller's primary address space. CSNBHMV1 and CSNEHMV1 allows data to reside in the caller's primary address space or in a z/OS data space.
CSNBMGN CSNEMGN CSNBMGN1 CSNEMGN1	MAC generate	Generates a 4-, 6-, or 8-byte message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the ANSI X9.9-1 algorithm, ANSI X9.19 optional double key algorithm the EMV padding rules or the ISO 16609 TDES algorithm. CSNBMGN and CSNEMGN require data to reside in the caller’s primary address space. CSNBMGN1 and CSNEMGN1 allow data to reside in the caller’s primary address space or in a z/OS data space.
CSNBMVR CSNEMVR CSNBMVR1 CSNEMVR1	MAC verify	Verifies a 4-, 6-, or 8-byte message authentication code (MAC) for a text string that the application program supplies. The MAC is computed using the ANSI X9.9-1 algorithm, ANSI X9.19 optional double key algorithmthe EMV padding rules or the ISO 16609 TDES algorithm. CSNBMVR and CSNEMVR require data to reside in the caller’s primary address space. CSNBMVR1 and CSNEMVR1 allow data to reside in the caller’s primary address space or in a z/OS data space.
CSNBMDG CSNEMDG CSNBMDG1 CSNEMDG1	MDC generate	Generates a 128-bit modification detection code (MDC) for a text string that the application program supplies. CSNBMDG and CSNEMDG require data to reside in the caller’s primary address space. CSNBMDG1 and CSNEMDG1 allow data to reside in the caller’s primary address space or in a z/OS data space.
CSNBOWH CSNEOWH CSNBOWH1 CSNEOWH1	One way hash generate	Generates a one-way hash on specified text.
CSNBSMG, CSNESMG CSNBSMG1 CSNESMG1	Symmetric MAC Generate	Use the symmetric MAC generate callable service to generate a 96- or 128-bit message authentication code (MAC) for an application-supplied text string using a clear AES key. CSNBSMG1 allows data to reside in the caller’s primary address space or in a z/OS data space.
CSNBSMV, CSNESMV CSNBSMV1 CSNESMV1	Symmetric MAC Verify	Use the symmetric MAC verify callable service to verify a 96- or 128-bit message authentication code (MAC) for an application-supplied text string using a clear AES key. CSNBSMV1 allows data to reside in the caller’s primary address space or in a z/OS data space.
Financial Services
CSNBCPE CSNECPE	Clear PIN encrypt	Formats a PIN into a PIN block format and encrypts the results.
CSNBPGN CSNEPGN	Clear PIN generate	Generates a clear personal identification number (PIN), a PIN verification value (PVV), or an offset using one of these algorithms: IBM 3624 (IBM-PIN or IBM-PINO) IBM German Bank Pool (GBP-PIN or GBP-PINO) VISA PIN validation value (VISA-PVV) Interbank PIN (INBK-PIN) This service executes only in special secure mode.
CSNBCPA CSNECPA	Clear PIN generate alternate	Generates a clear VISA PIN validation value (PVV) from an input encrypted PIN block. The PIN block may have been encrypted under either an input or output PIN encrypting key. The IBM-PINO algorithm is supported to produce a 3624 offset from a customer selected encrypted PIN.
CSNBCKC CSNECKC	CVV Key Combine	Combines two single-length CCA internal key tokens into 1 double-length CCA key token containing a CVVKEY-A key type.
CSNBEPG CSNEEPG	Encrypted PIN generate	Generates and formats a PIN and encrypts the PIN block.
CSNBPTR CSNEPTR	Encrypted PIN translate	Reenciphers a PIN block from one PIN-encrypting key to another and, optionally, changes the PIN block format. UKPT keywords are supported.
CSNBPVR CSNEPVR	Encrypted PIN verify	Verifies a supplied PIN using one of these algorithms: IBM 3624 (IBM-PIN or IBM-PINO) IBM German Bank Pool (GBP-PIN or GBP-PINO) VISA PIN validation value (VISA-PVV) Interbank PIN (INBK-PIN) UKPT keywords are supported.
CSNBPCU CSNEPCU	PIN Change/Unblock	Supports the PIN change algorithms specified in the VISA Integrated Circuit Card Specification; only available on a z890 or Requires May 2004 or later version of Licensed Internal Code (LIC).
CSNBSKY CSNESKY	Secure messaging for keys	Encrypts a text block, including a clear key value decrypted from an internal or external DES token.
CSNBSPN CSNESPN	Secure messaging for PINs	Encrypts a text block, including a clear PIN block recovered from an encrypted PIN block.
CSNDSBC CSNFSBC	SET block compose	Composes the RSA-OAEP block and the DES-encrypted block in support of the SET protocol.
CSNDSBD CSNFSBD	SET block decompose	Decomposes the RSA-OAEP block and the DES-encrypted block to provide unencrypted data back to the caller.
CSNBTRV CSNETRV	Transaction Validation	Supports the generation and validation of American Express card security codes; only available on a z890 or Requires May 2004 or later version of Licensed Internal Code (LIC).
CSNBCSG CSNECSG	VISA CVV service generate	Generates a VISA Card Verification Value (CVV) or a MasterCard Card Verification Code (CVC).
CSNBCSV CSNECSV	VISA CVV service verify	Verifies a VISA Card Verification Value (CVV) or a MasterCard Card Verification Code (CVC).
Key Data Set Management
CSNBKRC CSNEKRC	CKDS key record create	Adds a key record containing a key token set to binary zeros to both the in-storage and DASD copies of the CKDS.
CSNBKRC2 CSNEKRC2	CKDS key record create2	Adds a key record containing a key token to both the in-storage and DASD copies of the CKDS.
CSNBKRD CSNEKRD	CKDS key record delete	Deletes a key record from both the in-storage and DASD copies of the CKDS.
CSNBKRR CSNEKRR	CKDS key record read	Copies an internal key token from the in-storage copy of the CKDS to application storage.
CSNBKRR2 CSNEKRR2	CKDS key record read2	Copies an internal key token from the in-storage copy of the CKDS to application storage.
CSNBKRW CSNEKRW	CKDS key record write	Writes an internal key token to the CKDS record specified in the key label parameter. Updates both the in-storage and DASD copies of the CKDS currently in use.
CSNBKRW2 CSNEKRW2	CKDS key record write2	Writes an internal key token to the CKDS record specified in the key label parameter. Updates both the in-storage and DASD copies of the CKDS currently in use.
CSFCRC CSFCRC6	Coordinated KDS Administration	Performs a CKDS refresh or CKDS reencipher and change master key operation while allowing applications to update the CKDS. In a sysplex environment, this callable service performs a coordinated sysplex-wide refresh or change master key operation from a single ICSF instance.
Utilities
CSNBXBC or CSNBXCB	Character/nibble conversion	Converts a binary string to a character string or vice versa.
CSNBXEA or CSNBXAE	Code conversion	Converts EBCDIC data to ASCII data or vice versa.
CSFIQA CSFIQA6	ICSF Query Algorithm	Use this utility to retrieve information about the cryptographic and hash algorithms available. You can control the amount of data that is returned by passing in different rule_array keywords.
CSFIQF CSFIQF6	ICSF Query Service	Provides ICSF status, as well as PCICC, PCIXCC, CEX2C, and CEX3C information.
CSNB9ED	X9.9 data editing	Edits an ASCII text string according to the editing rules of ANSI X9.9–4.
Trusted Key Entry Workstation Interfaces
CSFPCI	PCI interface	Puts a request to a specific PCI Cryptographic Coprocessor / PCI X Cryptographic Coprocessor / Crypto Express2 Coprocessor / Crypto Express3 Coprocessor queue and removes the corresponding response when complete. Only the Trusted Key Entry (TKE) workstation uses this service.
CSFPKSC	PKSC interface	Puts a request to a specific cryptographic module and removes the corresponding response when complete. Only the Trusted Key Entry (TKE) workstation uses this service.
Managing Keys According to the ANSI X9.17 Standard
CSNAEGN CSNGEGN	ANSI X9.17 EDC generate	Generates an ANSI X9.17 error detection code on an arbitrary length string using the special MAC key (x'0123456789ABCDEF').
CSNAKEX CSNGKEX	ANSI X9.17 key export	Uses the ANSI X9.17 protocol to export a DATA key or a pair of DATA keys with or without an AKEK. Supports the export of a CCA IMPORTER or EXPORTER KEK. Converts a single DATA key or combines two DATA keys into a single MAC key.
CSNAKIM CSNGKIM	ANSI X9.17 key import	Uses the ANSI X9.17 protocol to import a DATA key or a pair of DATA keys with or without an AKEK. Supports the import of a CCA IMPORTER or EXPORTER KEK. Converts a single DATA key or combines two DATA keys into a single MAC key.
CSNAKTR CSNGKTR	ANSI X9.17 key translate	Uses the ANSI X9.17 protocol to translate, in a single service call, either one or two DATA keys or a single KEK from encryption under one AKEK to encryption under another AKEK. Converts a single DATA key or combines two DATA keys into a single MAC key.
CSNATKN CSNGTKN	ANSI X9.17 transport key partial notarize	Permits the preprocessing of an AKEK with origin and destination identifiers to create a partially notarized AKEK.

Notices | Terms of use | Support | Contact z/OS | zFavorites