z/VSE: 45 Years of Progress - z/VM - IBM

The CCA host library is available
free at http://ibm.com/security/cryptocards/;
select PCIe Cryptographic
Coprocessor from the navigation bar on
the left side of the page for more information
or to download the CCA package.
The host library provides the tools
necessary to manage secure master keys
and build applications in C or Java that
can exploit the diverse array of cryptographic
functions available with CEX2C
and CEX3C.
A Peek Under the Covers
All these new features are great, but
you have to jump in and move some bits
and bytes around. Building successful
solutions requires understanding what
the application must do from a cryptographic
standpoint and creating a specification
that identifies the algorithms
and functions required. In addition, you
must determine how keys will be managed
in accordance with the security
policy. Then it’s a simple matter of picking
the right verb and parameters to
create the crypto building blocks needed.
The CCA verbs are similar in format,
so crypto components can be built
quickly. The following explains how to
implement one of the verbs based on a
specification.
The Java entry points for each verb
are similar to the C entry points and are
distinguished by adding the letter “J” to
the C entry point name. For example,
CSNBKGN is the C entry point for the
key generate verb, and CSNBKGNJ is
the Java entry point for the same verb.
Figures 1 and 2 show simple examples
that generate a single length data key.
These examples aren’t complete solutions
or programming style guides;
they’re code samples for simple key generate
verbs in C and Java.
Incorporating cryptography into an
application can be a daunting task, but
hopefully these examples show how
simple it can be when each part is built
step by step. The examples generate a
single length key (an 8-byte value)
which can be used later to encrypt a
data string using the Data Encryption
Standard (DES) algorithm. The key isn’t
imported or exported; it’s generated and
used as an operational key only. It may
be useful to download the Programmer’s
Guide from www-03.ibm.com/security/
cryptocards/; the keywords are described
on pages 132 to 139.
In the examples, an operational key
(keyword: OP) is needed. Other options,
such as a pair of operational keys (keyword:
OPOP), some other pair of keys
void main() {
static long return_code;
static long reason_code;
static unsigned char key_form[4];
static unsigned char key_length[8];
static unsigned char key_type_1[8];
static unsigned char key_type_2[8];
static unsigned char kek_key_id_1[64];
static unsigned char kek_key_id_2[64];
static unsigned char des_key_id_1[64];
static unsigned char des_key_id_2[64];
/* Initialize values for Key Generate call */
return_code = 0;
reason_code = 0;
memcpy(key_form, “OP “, 4);
memcpy(key_length, “SINGLE “, 8);
memcpy(key_type_1, “DATA “, 8);
memcpy(key_type_2, “ “, 8);
memset(kek_key_id_1, 0x00, sizeof(kek_key_id_1));
memset(kek_key_id_2, 0x00, sizeof(kek_key_id_2));
memset(des_key_id_1, 0x00, sizeof(des_key_id_1));
memset(des_key_id_2, 0x00, sizeof(des_key_id_2));
/* Generate an operational key */
CSNBKGN(&return_code, &reason_code, NULL, NULL, key_form, key_length,
key_type_1, key_type_2, kek_key_id_1, kek_key_id_2,
des_key_id_1, des_key_id_2);
/* Check the return/reason codes and terminate if there is an error. */
if (return_code != 0 || reason_code != 0) {
printf(“Key Generate failed: “);
printf(“return_code = %ld, “, return_code);
printf(“reason_code = %ld.”, reason_code);
}
else /* No error occurred */
printf(“Key Generated successfully.\n”);
} /* end main */
Figure 1: Code Example for the Key Generate Verb
public class des {
public static void main (String args[]) {
byte [] exitData = new byte [4];
byte [] key_form = new byte [4];
byte [] key_length = new byte [8];
byte [] key_type_1 = new byte [8];
byte [] key_type_2 = new byte [8];
byte [] kek_key_id_1 = new byte [64];
byte [] kek_key_id_2 = new byte [64];
byte [] des_key_id_1 = new byte [64];
byte [] des_key_id_2 = new byte [64];
/* Set up initial values for Key Generate call */
hikmNativeInteger returnCode = new hikmNativeInteger(0);
hikmNativeInteger reasonCode = new hikmNativeInteger(0);
hikmNativeInteger exitDataLength = new hikmNativeInteger(0);
key_form = new String(“OP “).getBytes();
key_length = new String(“SINGLE “).getBytes();
key_type_1 = new String(“DATA “).getBytes();
key_type_2 = new String(“ “).getBytes();
/* Generate an operational key */
new HIKM().CSNBKGNJ (returnCode, reasonCode, exitDataLength, exitData,
key_form, key_length, key_type_1, key_type_2,
kek_key_id_1, kek_key_id_2, des_key_id_1, des_key_id_2);
/* Check the return/reason codes and terminate if there is an error. */
if ( 0 != returnCode.getValue() || 0 != reasonCode.getValue() ){
System.out.println (“Key Generate Failed: “);
System.out.println (“Return_code = “ + returnCode.getValue());
System.out.println (“Reason_code = “ + reasonCode.getValue());
}
else {
System.out.println (“Key Generated successful.”);
}
}//end main
}//end class
Figure 2: Java Code Example for the Key Generate Verb
1 0 • z / J o u r n a l • O c t o b e r / N o v e m b e r 2 0 1 0