z/OS Open Cryptographic Services Facility Application Programming
Previous topic | Next topic | Contents | Index | Contact z/OS | Library | PDF


Cryptographic Services API

z/OS Open Cryptographic Services Facility Application Programming
SC24-5899-01

Cryptographic Service Providers (CSPs) are service provider modules which perform cryptographic operations including encryption, decryption, digital signaturing, key and key pair generation, random number generation (RNG), message digest, key wrapping, key unwrapping, and key exchange. Cryptographic services can be implemented by a hardware-software combination, by software only, or by hardware only. Besides the traditional cryptographic functions, CSPs may provide other vendor-specific services. The set of services provided can be dynamic even after a caller has attached the CSP for service. This means the capabilities registered when the CSP was installed can change during execution based on changes internal or external to the system.

The CSP is always responsible for the secure storage of private keys. Optionally, the CSP may assume responsibility for the secure storage of other object types, such as symmetric keys and certificates. The implementation of secured persistent storage for keys can use the services of a Data Storage Library (DL) module within the OCSF Framework or some approach internal to the CSP. Accessing persistent objects managed by the CSP, other than keys, is performed using OCSF's DL application programming interfaces (APIs).

CSPs optionally support a password-based login sequence. When login is supported, the caller is allowed to change passwords as deemed necessary. This is part of a standard user-initiated maintenance procedure. Some CSPs support operations for privileged CSP administrators. The model for CSP administration varies widely among CSP implementations. For this reason, OCSF does not define APIs for vendor-specific CSP administration operations. CSP vendors can makes these services available to CSP administration tools using the CSSM_CSP_Passthrough function.

The range and types of cryptographic services a CSP supports are at the discretion of the vendor. A registry and query mechanism is available through the OCSF for CSPs to disclose the services and details about the services. As an example, a CSP may register this with the OCSF: Encryption is supported, algorithms present are Data Encryption Standard (DES) with cipher block chaining for key sizes 40 and 56 bits, and triple DES with three keys for key-size 168 bits.

All cryptographic services requested by applications will be channeled to one of the CSPs through OCSF. CSP vendors only need target their modules to OCSF for all security-conscious applications to have access to their product.

Calls made to a CSP to perform cryptographic operations occur within a framework called a session, which is established and terminated by the application. Applications must create a session context (simply referred to as the context) prior to starting CSP operations and delete it as soon as possible upon completion of the operation. Context information is not persistent; it is not saved permanently in a file or database.

Before an application calls a CSP to perform a cryptographic operation, the application uses the query services function to determine what CSPs are installed and what services they provide. Based on this information, the application then can determine which CSP to use for subsequent operations; the application creates a session with this CSP and performs the operation.

Depending on the class of cryptographic operations, individualized attributes are available for the cryptographic context. Besides specifying an algorithm when creating the context, the application may also initialize a session key, pass an initialization vector and/or pass padding information to complete the description of the session. A successful return value from the create function indicates the desired CSP is available. Functions are also provided to manage the created context. When a context is no longer required, the application calls CSSM_DeleteContext. Resources that were allocated for that context can be reclaimed by the operating system.

There are two basic types of cryptographic operations – a single call to perform an operation and a staged method of performing the operation. For the single call method, only one call is needed to obtain the result. For the staged method, there is an initialization call followed by one or more update calls, and ending with a completion (final) call. The result is available after the final function completes its execution for most cryptographic operations – staged encryption/decryption are an exception in that each update call generates a portion of the result.

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014