648 lines
28 KiB
HTML
648 lines
28 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Migrating from CR1-57xx</title>
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- 050629 HAG New -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link-->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2><img src="delta.gif" alt="Start of change">Migrating from 57xx-CR1</h2>
|
||
|
|
<p>IBM plans to drop support of IBM Cryptographic Support for AS/400 (5722-CR1) in the release after V5R4. This article will help you migrate your CR1 applications to the Cryptographic Services APIs.</p>
|
||
|
|
<p>Prior to reading this article, you may want to review the information
|
||
|
|
in the following articles:</p>
|
||
|
|
<ul>
|
||
|
|
<li><a href="../rzajc/rzajcconcepts.htm">Cryptography Concepts</a></li>
|
||
|
|
<li><a href="qc3MasterKeys.htm">Cryptographic Services Master Keys</a></li>
|
||
|
|
<li><a href="qc3KeyStore.htm">Cryptographic Services Key Store</a></li>
|
||
|
|
</ul>
|
||
|
|
<h3>General Functional Differences</h3>
|
||
|
|
<ul>
|
||
|
|
<li><b>PIN functions</b>
|
||
|
|
<br>The Cryptographic Services APIs do not support the CR1 PIN functions.
|
||
|
|
CR1 supports the 3624 PIN calculation method. It is possible
|
||
|
|
to code the 3624 PIN calculation method using the Cryptographic
|
||
|
|
Services APIs. To do so, implement the "PIN Generation Algorithm" described
|
||
|
|
in Chapter 4 of the <a href="http://publib.boulder.ibm.com/cgi-bin/bookmgr/bookmgr.cmd/BOOKS/QBKALT01/CCONTENTS">Cryptographic User's Guide</a>, replacing the CR1 APIs with
|
||
|
|
Cryptographic Services APIs as described below. However, a better solution
|
||
|
|
would be to use a cryptographic
|
||
|
|
coprocessor and the Common Cryptographic Architecture API set, which supports
|
||
|
|
many PIN calculation methods and PIN block formats. For more
|
||
|
|
information, see <a href="../rzajc/rzajcco4758.htm">4764 and 4758
|
||
|
|
Cryptographic Coprocessors</a>.
|
||
|
|
<br><br>
|
||
|
|
<li><b>Key management</b>
|
||
|
|
<br>Both CR1 and the Cryptographic Services APIs implement key management using
|
||
|
|
a key hierarchy. At the top, a clear master key is securely stored.
|
||
|
|
Other keys can be stored in a database file where the key values are encrypted
|
||
|
|
under the master key. However, note the following differences in key management
|
||
|
|
between CR1 and the Cryptographic Services APIs:
|
||
|
|
<br><br>
|
||
|
|
<ul>
|
||
|
|
<li>CR1 supports one master key.
|
||
|
|
<p>The Cryptographic Services APIs support
|
||
|
|
eight master keys.</p>
|
||
|
|
</li>
|
||
|
|
<li>CR1 supports one key store file, QCRP/QACRKTBL, also known as the cross-domain
|
||
|
|
key table.
|
||
|
|
<p>With the Cryptographic
|
||
|
|
Services APIs, the user can create any number of key store files.</p>
|
||
|
|
</li>
|
||
|
|
<li>CR1 defines key-encrypting keys (KEKs) as those keys stored within the
|
||
|
|
cross-domain key table as sending and receiving cross-domain key types.
|
||
|
|
They are limited to
|
||
|
|
export (encrypting keys to send to another system)
|
||
|
|
and import (decrypting keys received from another system) operations.
|
||
|
|
The user is responsible for storing data-encrypting keys.
|
||
|
|
<p>The Cryptographic Services APIs do not distinguish between
|
||
|
|
key-encrypting keys and data-encrypting keys. It is up to the user to define
|
||
|
|
what keys are used as key-encrypting keys and as data-encrypting keys.</p>
|
||
|
|
</li>
|
||
|
|
<li>Only keys for export, import, and PIN protection operations can be stored
|
||
|
|
in the CR1 cross-domain key table.
|
||
|
|
<p>Any type of key can be stored in a Cryptographic
|
||
|
|
Services APIs key store file.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
</li>
|
||
|
|
<li><b>Master key variants</b>
|
||
|
|
<br>Master key variants are values that are exclusive-OR'd into the master
|
||
|
|
key value prior to encrypting or decrypting a key. Master key variants are
|
||
|
|
used to limit how the encrypted key can be used. Both CR1 and the
|
||
|
|
Cryptographic Services APIs use master key variants. However, the values of
|
||
|
|
the variants and how they are used are completely different.
|
||
|
|
<p>CR1 uses master key variants to limit cross-domain keys to either export, import, or PIN protection operations. The CR1 master key variants are the following:
|
||
|
|
<table width="95%">
|
||
|
|
<tr>
|
||
|
|
<td valign="top" width="30%"><strong>Sending cross-domain key</strong></td>
|
||
|
|
<td>Eight bytes of hexadecimal 88.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><strong>Receiving cross-domain key</strong></td>
|
||
|
|
<td>Eight bytes of hexadecimal 22.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><strong>PIN cross-domain key</strong></td>
|
||
|
|
<td>Eight bytes of hexadecimal 44.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</p>
|
||
|
|
<p>Cryptographic Services APIs use master key variants to limit master key
|
||
|
|
encrypted keys to any combination of encrypt, decrypt, MAC, and sign operations.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<h3>Migrating Keys</h3>
|
||
|
|
<p>If you have not already established a Cryptographic Services APIs master key,
|
||
|
|
do so using the <A HREF="qc3ldmkp.htm">Load Master Key Part</A> and
|
||
|
|
<A HREF="qc3setmk.htm">Set Master Key</A> APIs.</p>
|
||
|
|
<p>Write a program that performs the following steps to migrate your keys from the CR1
|
||
|
|
cross-domain key table to a Cryptographic Services APIs key store file.</p>
|
||
|
|
<ol>
|
||
|
|
<li>Create a key store file using the <A HREF="qc3crtks.htm">Create Key Store</A>
|
||
|
|
API.
|
||
|
|
<br><br>
|
||
|
|
</li>
|
||
|
|
<li>Get the CR1 master key value.
|
||
|
|
<ul>
|
||
|
|
<li>You should not hard-code the CR1 master key value in your program, but instead
|
||
|
|
request the input interactively.</li>
|
||
|
|
<li>If the CR1 master key was established using multiple key parts, you should
|
||
|
|
maintain multiple responsibility and request input of multiple key parts.
|
||
|
|
Your program would then exclusive-OR those parts together to obtain the master
|
||
|
|
key value.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>Create a key context token for each variant of the CR1 master key.
|
||
|
|
<ul>
|
||
|
|
<li>Create three new key values by
|
||
|
|
exclusive-ORing the master key value with each variant value (as described
|
||
|
|
above). For example, a master key value of hex 3BA93722AF8D0526 exclusive-OR'd
|
||
|
|
with the sending cross-domain key variant (hex 8888888888888888) would be
|
||
|
|
hex B321BFAA27058DAE.</li>
|
||
|
|
<li>If you will be migrating more CR1 cross-domain keys in the future,
|
||
|
|
save all three key values to your key store file. Do this using the
|
||
|
|
<A HREF="qc3wrtkr.htm">Write Key Record</A> API.
|
||
|
|
<ul>
|
||
|
|
<li>The key string parameter should contain the key value (for example, hex B321BFAA27058DAE).</li>
|
||
|
|
<li>The length of key string parameter should specify a value of 8.</li>
|
||
|
|
<li>The key format parameter should specify a value of 0 to indicate it is a
|
||
|
|
binary value.</li>
|
||
|
|
<li>The key type parameter should specify a value of 20 to indicate it is a
|
||
|
|
DES key.</li>
|
||
|
|
<li>The key form parameter should specify a value of 0 to indicate the key
|
||
|
|
value is not encrypted.</li>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>Create a key context for each of the three values using the
|
||
|
|
<a href="qc3crtkx.htm">Create Key Context</a> API. The key string, length
|
||
|
|
of key string, key format, key type, and key form parameters should all
|
||
|
|
match what was specified above for the Write Key Record API. If in the future
|
||
|
|
you retrieve these key values from the key store file, you would specify
|
||
|
|
the Create Key Context parameters as follows:
|
||
|
|
<ul>
|
||
|
|
<li>The key string parameter would contain the key store label structure as
|
||
|
|
described in the API.</li>
|
||
|
|
<li>The length of key string parameter would specify 56, which is the length
|
||
|
|
of the key store label structure.</li>
|
||
|
|
<li>The key format parameter would specify a value of 4 to indicate it is a
|
||
|
|
key store label structure.</li>
|
||
|
|
<li>The key type and key form parameters would not change.</li>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>Erase the master key value, the three new key values, and any key part values
|
||
|
|
from program storage.<br><br></li>
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Create a DES algorithm context token using the
|
||
|
|
<a href="qc3crtax.htm">Create Algorithm Context</a> API.
|
||
|
|
<ul>
|
||
|
|
<li>The algorithm description format name parameter should specify a value of
|
||
|
|
"ALGD0200".</li>
|
||
|
|
<li>The algorithm description parameter should contain the ALGD0200
|
||
|
|
structure. The entire ALGD0200 structure should be set to null. The
|
||
|
|
fields should then be specified as follows:
|
||
|
|
<ul>
|
||
|
|
<li>The block cipher algorithm field should specify a value of 20 to indicate
|
||
|
|
the DES algorithm.</li>
|
||
|
|
<li>The block length field should specify a value of 8.</li>
|
||
|
|
</ul>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>Read each record of the cross-domain key table and import the key value
|
||
|
|
to your key store file.
|
||
|
|
<ul>
|
||
|
|
<li>The format of a cross-domain key table record is as follows: <table width="95%">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Field</th>
|
||
|
|
<th align="left" valign="top">Length</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" width="30%">Key Label</td>
|
||
|
|
<td>10</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>Key Type</td>
|
||
|
|
<td>1</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>Encrypted Key Value</td>
|
||
|
|
<td>8</td>
|
||
|
|
</tr>
|
||
|
|
</table> <p>A key type of "S" indicates the key is a sending cross-domain key. A key type
|
||
|
|
of "R" indicates the key is a receiving cross-domain key. A key type of "P"
|
||
|
|
indicates the key is a PIN key.</p></li>
|
||
|
|
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Use the <A HREF="qc3wrtkr.htm">Write Key Record</A> API to import the key
|
||
|
|
value to the key store file.
|
||
|
|
<ul>
|
||
|
|
<li>For the record label parameter, you should be able to use the same value
|
||
|
|
as the label from the cross-domain key table record unless a key record by that
|
||
|
|
label already exists in the key store file.</li>
|
||
|
|
<li>The key string parameter should contain the encrypted key value.</li>
|
||
|
|
<li>The length of key string parameter should specify a value of 8.</li>
|
||
|
|
<li>The key format parameter should specify a value of 0 to indicate it is a
|
||
|
|
binary value.</li>
|
||
|
|
<li>The key type parameter should specify a value of 20 to indicate it is a
|
||
|
|
DES key.</li>
|
||
|
|
<li>The key form parameter should specify a value of 1 to indicate the key
|
||
|
|
value is encrypted.</li>
|
||
|
|
<li>The key-encrypting key context token parameter should specify the appropriate
|
||
|
|
key context token created in step 3 above. Use the key type field of the
|
||
|
|
cross-domain key record to determine which token to use.</li>
|
||
|
|
<li>The key-encrypting algorithm context token should specify the algorithm
|
||
|
|
context token created in step 5 above.</li>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
<p>To migrate CR1 master key encrypted keys not stored in the cross-domain key
|
||
|
|
table, your program should perform the following steps.</p>
|
||
|
|
<ol>
|
||
|
|
<li>Get the CR1 master key value.
|
||
|
|
<ul>
|
||
|
|
<li>You should not hard-code the CR1 master key value in your program, but instead
|
||
|
|
request the input interactively.</li>
|
||
|
|
<li>If the CR1 master key was established using multiple key parts, you should
|
||
|
|
maintain multiple responsibility and request input of multiple key parts.
|
||
|
|
Your program would then exclusive-OR those parts together to obtain the master
|
||
|
|
key value.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>Create a key context token for the CR1 master key.
|
||
|
|
<ul>
|
||
|
|
<li>If you will be migrating more CR1 keys in the future,
|
||
|
|
save the master key to a key store file. Do this using the
|
||
|
|
<A HREF="qc3wrtkr.htm">Write Key Record</A> API.
|
||
|
|
<ul>
|
||
|
|
<li>The key string parameter should contain the master key value.</li>
|
||
|
|
<li>The length of key string parameter should specify a value of 8.</li>
|
||
|
|
<li>The key format parameter should specify a value of 0 to indicate it is a
|
||
|
|
binary value.</li>
|
||
|
|
<li>The key type parameter should specify a value of 20 to indicate it is a
|
||
|
|
DES key.</li>
|
||
|
|
<li>The key form parameter should specify a value of 0 to indicate the key
|
||
|
|
value is not encrypted.</li>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>Create a key context for the CR1 master key value using the
|
||
|
|
<a href="qc3crtkx.htm">Create Key Context</a> API. The key string, length
|
||
|
|
of key string, key format, key type, and key form parameters should all
|
||
|
|
match what was specified above for the Write Key Record API. If in the future
|
||
|
|
you retrieve the CR1 master key value from the key store file, you would specify
|
||
|
|
the Create Key Context parameters as follows:
|
||
|
|
<ul>
|
||
|
|
<li>The key string parameter would contain the key store label structure as
|
||
|
|
described in the API.</li>
|
||
|
|
<li>The length of key string parameter would specify 56, which is the length
|
||
|
|
of the key store label structure.</li>
|
||
|
|
<li>The key format parameter would specify a value of 4 to indicate it is a
|
||
|
|
key store label structure.</li>
|
||
|
|
<li>The key type and key form parameters would not change.</li>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>Erase the master key value and any key part values from program storage. <br><br></li>
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Create a DES algorithm context token using the
|
||
|
|
<a href="qc3crtax.htm">Create Algorithm Context</a> API.
|
||
|
|
<ul>
|
||
|
|
<li>The algorithm description format name parameter should specify a value of
|
||
|
|
"ALGD0200".</li>
|
||
|
|
<li>The algorithm description parameter should contain the ALGD0200
|
||
|
|
structure. The entire ALGD0200 structure should be set to null. The
|
||
|
|
fields should then be specified as follows:
|
||
|
|
<ul>
|
||
|
|
<li>The block cipher algorithm field should specify a value of 20 to indicate
|
||
|
|
the DES algorithm.</li>
|
||
|
|
<li>The block length field should specify a value of 8.</li>
|
||
|
|
</ul>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>Import the CR1 master key encrypted keys.
|
||
|
|
<p>For each CR1 master key encrypted key, use the <a href="qc3impky.htm">Import Key</a> API to re-encrypt the key under a Cryptographic Services APIs master key.
|
||
|
|
<ul>
|
||
|
|
<li>The key string parameter should contain the encrypted key value.</li>
|
||
|
|
<li>The length of key string parameter should specify a value of 8.</li>
|
||
|
|
<li>The key form parameter should specify a value of 1 to indicate the key
|
||
|
|
value is encrypted.</li>
|
||
|
|
<li>The key-encrypting key context token parameter should specify the
|
||
|
|
key context token created in step 2 above. </li>
|
||
|
|
<li>The key-encrypting algorithm context token should specify the algorithm
|
||
|
|
context token created in step 4 above.</li>
|
||
|
|
<li>Follow the API instructions for the remaining parameters.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
<h3>Migrating Programs</h3>
|
||
|
|
<p>Use the following list to determine how to replace CR1 APIs with
|
||
|
|
Cryptographic Services APIs.</p>
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Add Cross-Domain Key (CL, ADDCRSDMNK)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3crtks.htm">Create Key Store (OPM, QC3CRTKS; ILE, Qc3CreateKeyStore)</a></li>
|
||
|
|
<li><a href="qc3wrtkr.htm">Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>Whereas CR1 supports one key store file which is shipped with the product,
|
||
|
|
the Cryptographic Services APIs user must create a key store file.</li>
|
||
|
|
<li>Cryptographic Services APIs key store keys can not be restricted to export,
|
||
|
|
import, and PIN protection functions as is done with CR1. However, they can be
|
||
|
|
restricted to any combination of encrypt, decrypt, MAC, and sign operations.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Change Cross-Domain Key (CL, CHGCRSDMNK)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3dltkr.htm">Delete Key Record (OPM, QC3DLTKR; ILE, Qc3DeleteKeyRecord)</a></li>
|
||
|
|
<li><a href="qc3wrtkr.htm">Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>There is no Cryptographic Services API to change a key record.
|
||
|
|
The application must first delete the record and then re-create it.
|
||
|
|
</li>
|
||
|
|
<li>Cryptographic Services APIs key store keys can not be restricted to export,
|
||
|
|
import, and PIN protection functions as is done with CR1. However, they can be
|
||
|
|
restricted to any combination of encrypt, decrypt, MAC, and sign operations.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Change Master Key (CL, CHGMSTKK)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3tstmk.htm">Test Master Key (OPM, QC3TSTMK; ILE, Qc3TestMasterKey)</a></li>
|
||
|
|
<li><a href="qc3ldmkp.htm">Load Master Key Part (OPM, QC3LDMKP; ILE, Qc3LoadMasterKeyPart)</a></li>
|
||
|
|
<li><a href="qc3setmk.htm">Set Master Key (OPM, QC3SETMK; ILE, Qc3SetMasterKey)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
The CR1 Change Master Key API requires knowledge of the master key verification
|
||
|
|
code. The Cryptographic Services APIs application program can implement this
|
||
|
|
function using the Test Master Key API.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Cipher Data (CL, CPHDTA; OPM, QCRCIPHR)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3encdt.htm">Encrypt Data (OPM, QC3ENCDT; ILE, Qc3EncryptData)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>OPTION(*SCPH) is not supported by the Cryptographic Services APIs. Your
|
||
|
|
application program must convert the 16 hexadecimal characters to the 8-byte
|
||
|
|
binary value prior to calling the Encrypt Data API. Similarly, if a 16
|
||
|
|
hexadecimal character output is desired, the application program must
|
||
|
|
do the conversion.</li>
|
||
|
|
<li>To duplicate the function of Cipher Data, the Encrypt Data API should
|
||
|
|
specify an algorithm description for DES. However, it is recommended that
|
||
|
|
you upgrade the security of your application by moving to a newer algorithm
|
||
|
|
such as TDES or the better performing AES.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Encrypt Cipher Key (CL, ENCCPHK; OPM, QCRENCKY)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3impky.htm">Import Key (OPM, QC3IMPKY; ILE, Qc3ImportKey)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Encipher From Master Key (CL, ENCFRMMSTK; OPM, QCRENCFR)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3crtkx.htm">Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)</a></li>
|
||
|
|
<li><a href="qc3crtax.htm">Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)</a></li>
|
||
|
|
<li><a href="qc3expky.htm">Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>The Export Key API requires a key context be created for the key-encrypting
|
||
|
|
key. It is on the Create Key Context API that you specify the key store file
|
||
|
|
and label.</li>
|
||
|
|
<li>The Export Key API also requires an algorithm context. To duplicate the
|
||
|
|
function of Encipher From Master Key, create a DES algorithm context. The
|
||
|
|
algorithm description should specify ECB mode and no padding.</li>
|
||
|
|
<li>The Export Key API does not support the output of two encrypted key values
|
||
|
|
as does Encipher From Master Key. To obtain a second encrypted key value,
|
||
|
|
create another key context and issue the Export Key API again. You may reuse
|
||
|
|
the same algorithm context.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Encipher To Master Key (CL, ENCTOMSTK; OPM, QCRENCTO)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3crtkx.htm">Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)</a></li>
|
||
|
|
<li><a href="qc3crtax.htm">Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)</a></li>
|
||
|
|
<li><a href="qc3impky.htm">Import Key (OPM, QC3IMPKY; ILE, Qc3ImportKey)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>When importing an encrypted key, the Import Key API requires a key context
|
||
|
|
be created for the key-encrypting key. It is on the Create Key Context API that
|
||
|
|
you specify the key store file and label.</li>
|
||
|
|
<li>Importing an encrypted key also requires an algorithm context. To duplicate
|
||
|
|
the function of Encipher To Master Key, create a DES algorithm context. The
|
||
|
|
algorithm description should specify ECB mode and no padding.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Generate Cipher Key (CL, GENCPHK; OPM, QCRGENKY)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3gensk.htm">Generate Symmetric Key (OPM, QC3GENSK; ILE, Qc3GenSymmetricKey)</a></li>
|
||
|
|
<li><a href="qc3crtkx.htm">Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)</a></li>
|
||
|
|
<li><a href="qc3crtax.htm">Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)</a></li>
|
||
|
|
<li><a href="qc3expky.htm">Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>The Generate Symmetric Key API will generate a random key value and return
|
||
|
|
it in the clear, encrypted under a master key, or encrypted under a
|
||
|
|
key-encrypting key. If both a master key encrypted form and a KEK encrypted
|
||
|
|
form is required, first use Generate Symmetric Key API to generate a key
|
||
|
|
encrypted under a master key. Then follow the same procedures outlined for
|
||
|
|
Encipher From Master Key.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Generate Cross-Domain Key (CL, GENCRSDMNK)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3addprngseed.htm">Add Seed for Pseudorandom Number Generator (OPM, QC3ADDSD; ILE, Qc3AddPRNGSeed)</a></li>
|
||
|
|
<li><a href="qc3genkr.htm">Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>The Generate Key Record API does not require a seed value because it uses
|
||
|
|
the system's pseudorandom number generator which automatically seeds.
|
||
|
|
However, if your security practices require the input of seed data,
|
||
|
|
first use the Add Seed for Pseudorandom Number Generator API.</li>
|
||
|
|
<li>The Generate Key Record API generates a single key record. To generate
|
||
|
|
multiple key records, invoke this API multiple times.</li>
|
||
|
|
<li>Cryptographic Services APIs key store keys can not be restricted to export,
|
||
|
|
import, and PIN protection functions as is done with CR1. However, they can be
|
||
|
|
restricted to any combination of encrypt, decrypt, MAC, and sign operations.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Generate Message Authentication Code (CL, GENMAC; OPM, QCRGENMA)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3calma.htm">Calculate MAC (OPM, QC3CALMA; ILE, Qc3CalculateMAC)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>To duplicate the function of Generate Message Authentication Code,
|
||
|
|
the Calculate MAC API should
|
||
|
|
specify an algorithm description for DES. However, it is recommended that
|
||
|
|
you upgrade the security of your application by moving to a newer algorithm
|
||
|
|
such as TDES or the better performing AES.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Generate PIN (CL, GENPIN; OPM, QCRGENPN)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3encdt.htm">Encrypt Data (OPM, QC3ENCDT; ILE, Qc3EncryptData)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>Although the Cryptographic Services APIs do not support PIN functions,
|
||
|
|
it is possible for your application to implement the 3624 PIN generation
|
||
|
|
algorithm. The Encrypt Data API would be used for encrypting the PIN
|
||
|
|
validation data.</li>
|
||
|
|
<li>The PIN validation data must be presented to the Encrypt Data API as an
|
||
|
|
8-byte value. Your application program may need to convert the 8-byte
|
||
|
|
encrypted value to 16 hexadecimal characters prior to decimalization.
|
||
|
|
Refer to the "PIN Generation Algorithm" described in Chapter 4 of the <a href="http://publib.boulder.ibm.com/cgi-bin/bookmgr/bookmgr.cmd/BOOKS/QBKALT01/CCONTENTS">Cryptographic User's Guide</a>.</li>
|
||
|
|
<li>There are a number of security issues involved in supporting PIN functions
|
||
|
|
with the Cryptographic Services APIs.
|
||
|
|
A better solution would be to use a cryptographic
|
||
|
|
coprocessor and the Common Cryptographic Architecture API set. For more
|
||
|
|
information, see <a href="../rzajc/rzajcco4758.htm">4764 and 4758
|
||
|
|
Cryptographic Coprocessors</a>.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Remove Cross-Domain Key (CL, RMVCRSDMNK)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3dltkr.htm">Delete Key Record (OPM, QC3DLTKR; ILE, Qc3DeleteKeyRecord)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>The Delete Key Record API deletes a single key record. To delete multiple
|
||
|
|
key records, you must invoke this API multiple times.</li>
|
||
|
|
<li>Cryptographic Services APIs key store files are created with no capabilities.
|
||
|
|
You can not modify a key store file using other APIs. To remove all records from
|
||
|
|
the key store file, you must delete the file and then recreate it.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Set Master Key (CL, SETMSTK)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3ldmkp.htm">Load Master Key Part (OPM, QC3LDMKP; ILE, Qc3LoadMasterKeyPart)</a></li>
|
||
|
|
<li><a href="qc3setmk.htm">Set Master Key (OPM, QC3SETMK; ILE, Qc3SetMasterKey)</a></li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Translate PIN (CL, TRNPIN; OPM, QCRTRNPN)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3crtkx.htm">Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)</a></li>
|
||
|
|
<li><a href="qc3crtax.htm">Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)</a></li>
|
||
|
|
<li><a href="qc3trndt.htm">Translate Data (OPM, QC3TRNDT; ILE, Qc3TranslateData)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>Although the Cryptographic Services APIs do not support PIN functions,
|
||
|
|
it is possible to translate a PIN using the Translate Data API.</li>
|
||
|
|
<li>The Translate Data API does not support the specification of 16 hexadecimal
|
||
|
|
characters for the encrypted PIN number. You must supply it as an 8-byte value.
|
||
|
|
</li>
|
||
|
|
<li>There are a number of security issues involved in supporting PIN functions
|
||
|
|
with the Cryptographic Services APIs.
|
||
|
|
A better solution would be to use a cryptographic
|
||
|
|
coprocessor and the Common Cryptographic Architecture API set. For more
|
||
|
|
information, see <a href="../rzajc/rzajcco4758.htm">4764 and 4758
|
||
|
|
Cryptographic Coprocessors</a>.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Verify Master Key (CL, VFYMSTK)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3tstmk.htm">Test Master Key (OPM, QC3TSTMK; ILE, Qc3TestMasterKey)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>The Verify Master Key CL command compares the input verification code
|
||
|
|
against the master key verification code. The Test Master Key API just
|
||
|
|
returns the master key verification code. Therefore, your application
|
||
|
|
program must do the comparison.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
<dt><strong>Verify PIN (CL, VFYPIN; OPM, QCRVFYPN)</strong></dt>
|
||
|
|
<dd>Replace with
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3encdt.htm">Encrypt Data (OPM, QC3ENCDT; ILE, Qc3EncryptData)</a></li>
|
||
|
|
<li><a href="qc3decdt.htm">Decrypt Data (OPM, QC3DECDT; ILE, Qc3DecryptData)</a></li>
|
||
|
|
</dd>
|
||
|
|
</ul>
|
||
|
|
Notes:
|
||
|
|
<ul>
|
||
|
|
<li>Although the Cryptographic Services APIs do not support PIN functions,
|
||
|
|
it is possible for your application to implement the 3624 PIN generation
|
||
|
|
algorithm.
|
||
|
|
The Encrypt Data API would be used for encrypting the PIN
|
||
|
|
validation data.
|
||
|
|
The Decrypt Data API would be used to decrypt the PIN prior to the
|
||
|
|
comparison.</li>
|
||
|
|
<li>The encrypted PIN value must be presented to the Decrypt Data API as an
|
||
|
|
8-byte value.
|
||
|
|
The PIN validation data must be presented to the Encrypt Data API as an
|
||
|
|
8-byte value. Your application program may need to convert the output from
|
||
|
|
Encrypt Data to 16 hexadecimal characters prior to decimalization.
|
||
|
|
Refer to the "PIN Generation Algorithm" described in Chapter 4 of the <a href="http://publib.boulder.ibm.com/cgi-bin/bookmgr/bookmgr.cmd/BOOKS/QBKALT01/CCONTENTS">Cryptographic User's Guide</a>.</li>
|
||
|
|
<li>There are a number of security issues involved in supporting PIN functions
|
||
|
|
with the Cryptographic Services APIs.
|
||
|
|
A better solution would be to use a cryptographic
|
||
|
|
coprocessor and the Common Cryptographic Architecture API set. For more
|
||
|
|
information, see <a href="../rzajc/rzajcco4758.htm">4764 and 4758
|
||
|
|
Cryptographic Coprocessors</a>.</li>
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
||
|
|
<a href= "catcrypt.htm">Cryptographic Services APIs</a> |<a href=
|
||
|
|
"aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|