244 lines
11 KiB
HTML
244 lines
11 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>Scenario: Key Management and File Encryption</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 -->
|
||
|
|
<!-- 050621 HAG Rewrite for new APIs. -->
|
||
|
|
<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>Scenario: Key Management and File Encryption Using the Cryptographic Services APIs</h2>
|
||
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
||
|
|
for information pertaining to code examples.</p>
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<p>Briana is writing an application that handles customer data and accounts receivable. Because of recent privacy legislation, she needs to store the customer data encrypted.</p>
|
||
|
|
<p>Briana will store customer data encrypted in a database file. Each record will represent a different customer. Each record includes a customer unique number which is used as the database key field, an initialization vector which is used in the encrypt/decrypt operations, the accounts receivable balance, and the encrypted customer data.</p>
|
||
|
|
<p>The following is Briana's DDS for the customer file, which she names CUSDTA.</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
|
||
|
|
A* CUSTOMER FILE
|
||
|
|
A*
|
||
|
|
A R CUSDTAREC TEXT('Customer record')
|
||
|
|
A CUSNUM 8 0 TEXT('Customer number')
|
||
|
|
A IV 16 TEXT('Initialization vector')
|
||
|
|
A CCSID(65535)
|
||
|
|
A ARBAL 10 2 TEXT('Accounts receivable balance')
|
||
|
|
A CUSDTA 80 TEXT('Encrypted customer data')
|
||
|
|
A CCSID(65535)
|
||
|
|
A* 20 Name
|
||
|
|
A* 20 Address
|
||
|
|
A* 20 City
|
||
|
|
A* 2 State
|
||
|
|
A* 5 Zip Code
|
||
|
|
A* 10 Phone number
|
||
|
|
A* 3 Pad
|
||
|
|
A K CUSNUM
|
||
|
|
A*
|
||
|
|
</pre>
|
||
|
|
<p>Briana has several choices for an encryption key (which we will call the file key).
|
||
|
|
<ul>
|
||
|
|
<li>A clear key
|
||
|
|
<li>A key store key
|
||
|
|
<li>A key encrypted under a clear key
|
||
|
|
<li>A key encrypted under a master key
|
||
|
|
<li>A key encrypted under a key store key
|
||
|
|
<li>A key encrypted under a certificate store key
|
||
|
|
<li>A key derived from PKCS5 parameters
|
||
|
|
<li>Combinations of the above
|
||
|
|
</ul>
|
||
|
|
<p>Briana carefully thinks through the requirements of her application and the security implications. Her decision is to use a key encrypted under a key store key. She will store the encrypted file key in a separate file
|
||
|
|
called CUSPI. Although the file key is encrypted, Briana is
|
||
|
|
still careful to restrict authority to CUSPI.</p>
|
||
|
|
<p>In addition to the encrypted file key, Briana needs to store the
|
||
|
|
last used customer number. Following is Briana's DDS for the customer
|
||
|
|
processing information file, CUSPI.</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
|
||
|
|
A* CUSTOMER PROCESSING INFORMATION
|
||
|
|
A*
|
||
|
|
A R CUSPIREC TEXT('Customer processing info')
|
||
|
|
A KEY 16 TEXT('Encryption key')
|
||
|
|
A CCSID(65535)
|
||
|
|
A LASTCUS 8 0 TEXT('Last customer number')
|
||
|
|
A*
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Briana's application includes a program to setup and intialize the files and
|
||
|
|
keys, a program that writes customer data to the CUSDTA file, and a program
|
||
|
|
that bills customers. These programs are described below. Code examples for
|
||
|
|
these programs are also provided.</p>
|
||
|
|
<h4>Setup_Cus</h4>
|
||
|
|
<p>The Setup_Cus program performs the following steps:</p>
|
||
|
|
<ol>
|
||
|
|
<li>Create CUSDTA and CUSPI files.</li>
|
||
|
|
<li>Create key store file CUSKEYFILE using the
|
||
|
|
<a href="qc3crtks.htm">Create Key Store API</a>.</li>
|
||
|
|
<li>Generate a KEK in CUSKEYFILE with a label of CUSDTAKEK using the
|
||
|
|
<a href="qc3genkr.htm">Generate Key Record API</a>.</li>
|
||
|
|
<li>Create a key context for CUSDTAKEK using the
|
||
|
|
<a href="qc3crtkx.htm">Create Key Context API</a>.</li>
|
||
|
|
<li>Create an AES algorithm context for CUSDTAKEK using the
|
||
|
|
<a href="qc3crtax.htm">Create Algorithm Context API</a>.</li>
|
||
|
|
<li>Generate a file key encrypted under CUSDTAKEK using the
|
||
|
|
<a href="qc3gensk.htm">Generate Symmetric Key API</a>.</li>
|
||
|
|
<li>Write a record containing the encrypted file key and last customer number
|
||
|
|
(set to 0) to file CUSPI.</li>
|
||
|
|
<li>Erase the encrypted file key value from program storage.</li>
|
||
|
|
<li>Destroy key context using the
|
||
|
|
<a href="qc3deskx.htm">Destroy Key Context API</a>.</li>
|
||
|
|
<li>Destroy algorithm context using the
|
||
|
|
<a href="qc3desax.htm">Destroy Algorithm Context API</a>.</li></ol>
|
||
|
|
<h4>Examples</h4>
|
||
|
|
<p>Here are example programs for Setup_Cus.
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3SetupCusILEC.htm">Example in ILE C: Setting up keys</a></li>
|
||
|
|
<li><a href="qc3SetupCusILERPG.htm">Example in ILE RPG: Setting up keys</a></li>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h4>Write_Cus</h4>
|
||
|
|
|
||
|
|
<p>The Write_Cus program performs the following steps:</p>
|
||
|
|
<ol>
|
||
|
|
<li>Create an AES algorithm context for CUSDTAKEK
|
||
|
|
using the <a href="qc3crtax.htm">Create Algorithm Context API</a>.</li>
|
||
|
|
<li>Create a key context for CUSDTAKEK using the
|
||
|
|
<a href="qc3crtkx.htm">Create Key Context API</a>.</li>
|
||
|
|
<li>Open the customer processing information file, CUSPI. (Return an error if
|
||
|
|
the file does not exist.)</li>
|
||
|
|
<li>Read the first (and only) record from CUSPI to retrieve the encrypted file
|
||
|
|
key and last customer number. (Return an error if record not found.)</li>
|
||
|
|
<li>Create a key context for the file key using the
|
||
|
|
<a href="qc3crtkx.htm">Create Key Context API</a>.</li>
|
||
|
|
<li>Erase the encrypted file key value from program storage.</li>
|
||
|
|
<li>Open the customer data file, CUSDTA, for update.
|
||
|
|
(Return an error if the file does not exist.)</li>
|
||
|
|
<li>Call Get_Customer_Info to retrieve customer information and customer number.
|
||
|
|
(If customer number = 0, it is a new customer.
|
||
|
|
If customer number = 99999999, end the application.)</li>
|
||
|
|
<li>While customer number != 99999999.
|
||
|
|
<li>Generate an IV using the
|
||
|
|
<a href="qc3genprns.htm">Generate Pseudorandom Numbers API</a>.</li>
|
||
|
|
<li>Encrypt the customer data using the
|
||
|
|
<a href="qc3encdt.htm">Encrypt Data API</a>.
|
||
|
|
<ul>
|
||
|
|
<li>If customer number = 0 (new customer)
|
||
|
|
<ul>
|
||
|
|
<li>Add one to last customer number.</li>
|
||
|
|
<li>Set customer number to last customer number.</li>
|
||
|
|
<li>Write the new record to CUSDTA file.
|
||
|
|
</ul>
|
||
|
|
Else
|
||
|
|
<ul>
|
||
|
|
<li>Read CUSDTA record using customer number as the database key.
|
||
|
|
(Return error if record not found.)</li>
|
||
|
|
<li>Update record.</li>
|
||
|
|
</ul>
|
||
|
|
<li>Call Get_Customer_Info.</li>
|
||
|
|
</ul></li>
|
||
|
|
<li>Update last customer number in CUSPI.</li>
|
||
|
|
<li>Erase any customer plaintext data still in program storage.</li>
|
||
|
|
<li>Destroy key contexts using the
|
||
|
|
<a href="qc3deskx.htm">Destroy Key Context API</a>.</li>
|
||
|
|
<li>Destroy the algorithm context using the
|
||
|
|
<a href="qc3desax.htm">Destroy Algorithm Context API</a>.</li>
|
||
|
|
<li>Close CUSDTA and CUSPI files.</li>
|
||
|
|
</ol>
|
||
|
|
<h4>Examples</h4>
|
||
|
|
<p>Here are example programs for Write_Cus.
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3WriteCusILEC.htm">Example in ILE C: Writing encrypted data to a file</a></li>
|
||
|
|
<li><a href="qc3WriteCusILERPG.htm">Example in ILE RPG: Writing encrypted data to a file</a></li>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h4>Bill_Cus</h4>
|
||
|
|
|
||
|
|
<p>The Bill_Cus program performs the following steps:</p>
|
||
|
|
<ol>
|
||
|
|
<li>Create an AES algorithm context for CUSDTAKEK
|
||
|
|
using the <a href="qc3crtax.htm">Create Algorithm Context API</a>.</li>
|
||
|
|
<li>Create a key context for CUSDTAKEK using the
|
||
|
|
<a href="qc3crtkx.htm">Create Key Context API</a>.</li>
|
||
|
|
<li>Open the customer processing information file, CUSPI. (Return an error if
|
||
|
|
the file does not exist.)</li>
|
||
|
|
<li>Read the first (and only) record from CUSPI to retrieve the encrypted file
|
||
|
|
key. (Return an error if record not found.)</li>
|
||
|
|
<li>Create a key context for the file key using the <a href="qc3crtkx.htm">Create Key Context API</a>.</li>
|
||
|
|
<li>Erase the encrypted file key value from program storage.</li>
|
||
|
|
<li>Close CUSPI file.</li>
|
||
|
|
<li>Open the customer data file, CUSDTA, for sequential read.</li>
|
||
|
|
<li>Setup the algorithm description.
|
||
|
|
<li>While not EOF
|
||
|
|
<ul>
|
||
|
|
<li>Read next record.</li>
|
||
|
|
<li>If accounts receivable balance > 0
|
||
|
|
<ul>
|
||
|
|
<li>Decrypt customer data using the <a href="qc3decdt.htm">Decrypt Data API</a>.</li>
|
||
|
|
<li>Call Create_Bill, passing in the decrypted customer data and balance.</li>
|
||
|
|
</ul></li>
|
||
|
|
</ul></li>
|
||
|
|
<li>Erase any customer plaintext data still in program storage.</li>
|
||
|
|
<li>Destroy the key contexts using the
|
||
|
|
<a href="qc3deskx.htm">Destroy Key Context API</a>.</li>
|
||
|
|
<li>Destroy the algorithm context using the
|
||
|
|
<a href="qc3desax.htm">Destroy Algorithm Context API</a>.</li>
|
||
|
|
<li>Close CUSDTA file.</li>
|
||
|
|
</ol>
|
||
|
|
<h4>Examples</h4>
|
||
|
|
<p>Here are example programs for Bill_Cus.
|
||
|
|
<ul>
|
||
|
|
<li><a href="qc3BillCusILEC.htm">Example in ILE C: Reading encrypted data from a file</a></li>
|
||
|
|
<li><a href="qc3BillCusILERPG.htm">Example in ILE RPG: Reading encrypted data from a file</a></li>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
<h3>Other Considerations</h3>
|
||
|
|
<p>To backup file CUSDTA, you must backup files CUSPI and CUSKEYFILE as well.
|
||
|
|
A perpetrator should not be able to use these files on another system because
|
||
|
|
CUSDTAKEK is encrypted under a master key, and master keys should never
|
||
|
|
be shared between systems. However, if the perpetrator has the ability to
|
||
|
|
restore these files onto the orignal system and has access to the Decrypt
|
||
|
|
Data API, he will be able to hack the customer data.</p>
|
||
|
|
<p>It is a good idea to periodically change the value of the master key.
|
||
|
|
Whenever the master key is changed, CUSDTAKEK must be re-encrypted under the
|
||
|
|
new master key value. You can do this with the
|
||
|
|
<A HREF="qc3trnks.htm">Translate Key Store</A> API. Remember to backup
|
||
|
|
a key store file whenever you re-encrypt the key values under a new master
|
||
|
|
key.</p>
|
||
|
|
<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>
|
||
|
|
|