Technical Bulletin #5 AFCARS Encryption/Decryption Utility: C Version 2.0 REVISED: March, 20001,2

This technical bulletin provides guidance for installing and executing the AFCARS Encryption/Decryption Utility. By following the guidance of this bulletin, States will be able to properly encrypt and decrypt case numbers to report as the record number in the State's data file (foster care element # 4 and adoption element #5).

I. GENERAL INFORMATION

1. Overview

   This technical bulletin provides guidance for installing and executing the AFCARS Encryption/Decryption Utility: C Version 2.0. The utility follows all guidelines listed for encryption software development found in AFCARS Technical Bulletin #4: Encryption Guidelines & Algorithms for State Use. It is designed to insure the confidentiality of State case record numbers; ACF will be unable to decode the encrypted case record identifier. This utility consists of three programs that perform different functions:

   1. One program will encrypt the client case record identifiers in a State's properly formatted and concatenated AFCARS submission file with delimiters;³

   2. A second program will decrypt the case record identifiers that have been encrypted using the AFCARS Encryption/Decryption Utility; and

   3. A third program will decrypt the case record identifiers in any report that is sent to the State that includes case record identifiers that have been encrypted with the AFCARS Encryption/Decryption Utility, such as the detailed error reports that are sent back to the States after each submission.

   IMPORTANT NOTICE: The AFCARS Case Record Identifier Encryption/Decryption Utility will process only ASCII formatted files as specified in Technical Bulletin #2: AFCARS File Format. The utility will not work for files created in EBCDIC and/or other non-ASCII formats, or files concatenated in an order other than the one specified in Technical Bulletin #2.

2. Utility Files

   The utility is available in the C programming language. The utility includes the source code and PC-compatible executables. Following is a complete listing of the files:

3. Options for Using the Utility

   ACF is providing both source code and executables to allow the States to select their own approach for encrypting case record identifiers. Three options are listed below:

   1. Use the executables. This is the easiest option. Simply copy the three executables to the PC where the AFCARS data submission is stored and execute them. The executables will only run on a PC under DOS. An authorized individual must enter the encryption/decryption key each time the program is executed.
   2. Use the source code. This option provides the flexibility to execute the utility on different computer platforms. The source code can be copied to a PC or mainframe. The code must then be compiled and executed with the key entered at run-time. Additionally, the code may be edited by hard-coding the key directly into the source program prior to compilation. If the key is hard-coded, the utility will not prompt for the key when the program is executed.

   3. Use both executables and source code. Options 1 and 2 may be combined. For example, the encryption/decryption key may be hard-coded into the source code of the encryption program, but the executables might be used for the file decryption and report decryption programs. An advantage of this option is that an operator would not be required to remember the key each time the encryption program is executed. However, an authorized individual would have to have access to the key to decrypt the case record identifiers, thus adding an extra measure of security. If this option is selected, use the executables that were written in the same language as the modified source code.

4. The Encryption/Decryption Key

   When using the utility, the authorized State personnel must agree precisely what the key will be in accordance with the guidelines and specifications outlined in AFCARS Technical Bulletin #4: Encryption Guidelines & Algorithms for State Use, to determine how the case record identifiers are encrypted. The key can be any 12 character combination of letters and/or numbers. However, it is imperative that the authorized personnel responsible for the key remember that:

   1. The exact same key must be used for encrypting and decrypting files.
   2. The key must be exactly 12 characters long.
   3. The key is case sensitive. For example, "THISISTHEKEY" is not the same as "thisisthekey" or "Thisisthekey".

   Since the key can be used to decrypt the AFCARS data submission, it must be safeguarded against unauthorized access. The key must also be protected against loss. If the key is lost, ACF will not be able to assist in decrypting the case record identifiers since the key is determined by the State and only known to authorized State personnel.

   If option 1, "Use the executables," is selected, please follow the specific directions in Section II of this document. If using the source code (option 2), please follow the specific directions in Section III of this document.

II. USING ONLY THE EXECUTABLES - OPTION 1

1. Installing the Software

   The ready-to-use executable files for the case record identifier encryption, file decryption, and report decryption programs are available on the AFCARS web site. Copy the files to an IBM 386 (or higher) compatible personal computer running DOS 3.0 or higher.

   The executable files are as follows:

2. Encrypting State Client Files

   IMPORTANT NOTICE: The AFCARS Encryption/Decryption Utility will process only ASCII formatted files as specified in Technical Bulletin #2: AFCARS File Format. The utility will not work for files created in EBCDIC and/or other non-ASCII formats, or files concatenated in an order other than the one specified in Technical Bulletin #2.

   Execute the encrypt command with one parameter - the name of the AFCARS detail file containing the State client identifiers. For example, if the AFCARS detail file name is "FC_DET.DOC", the command would be:

   ENCR_C(space)FC_DET.DOC

   The program will prompt for the encryption key. Type the encryption key and press <Enter>.

   The file "OUTFILE" will be generated. The data in "OUTFILE" is unaltered; only the case record identifiers will be encrypted.

3. Decrypting the State Case Record Identifiers

   A decryption routine is included to allow States to decode the case record identifiers. This utility is included as a safeguard. If the AFCARS submission file is inadvertently lost, this utility can recreate it using the file generated by the encryption utility.

   Execute the decrypt command with the name of the AFCARS detail file with the encrypted case record identifiers. For example, if the input encrypted file name is "OUTFILE," the command would be:

   DECR_C(space)OUTFILE

   The program will prompt for the key. MAKE SURE TO USE EXACTLY THE SAME KEY that was used when the case identifiers in the original file were encrypted using the AFCARS Encryption/Decryption Utility. Type the key and press <Enter>. A file named "DECRYPT.OUT" will be generated; it will be identical to the file that was originally encrypted.

4. Decrypting the AFCARS Detail Reports

   Another important use for the AFCARS Encryption/Decryption Utility is to decrypt the Detailed AFCARS Reports that are returned to the State by the Federal AFCAR system. These reports enumerate all errors that are subject to penalty in the submission file. States receive two of these report files for each AFCARS submission: one for foster care and one for adoption.

   Since these files will be returned with the encrypted record identifiers, States will not be able to match them to the records in the State data system until the decryption routine is executed.

   Execute the report decryption command with the name of the AFCARS Detail Report. For example, if the name of the report is "FC_RPT.DOC", the command would be:

   RDCR_C(space)FC_RPT.DOC

   The program will prompt for the key. MAKE SURE TO USE EXACTLY THE SAME KEY that was used when the case identifiers in the original file were encrypted using the AFCARS Encryption/Decryption Utility. Type the key and press <Enter>. A file named "DECRYPT2.OUT" will be generated; it will be identical to "FC_RPT.DOC" except that each record will have the State case record identifier in place of the encrypted case record identifier.

III. MODIFYING THE SOURCE CODE - OPTION 2

1. Installing the Software

   To modify the source code for any of the three programs copy those files to a personal computer or mainframe. The file names for the source code files written in C are:

   File Purpose	C Source Code File Name
   Encrypting Record Identifier	ENCR_C.C
   Decrypting Record Identifier	DECR_C.C
   Decrypting Standard Format Reports	RDCR_C.C

    

   After copying the source code, use a text editor to make changes to the source code. The following section explains what changes to make.

2. Modifying the C Source Code

   The code may be modified to include the key. Without this modification, an encryption key will be required at each run-time.
   
   Ordinarily, when executing the programs, the program will prompt for the key. Hard-coding an encryption key eliminates this prompt. The key must be 12 characters long. For example, thisisthekey is acceptable. (This example is for illustration purposes only; do not use this key when executing this utility.)

   Figure 1 contains the C code that appears in all three source code files that need to be modified. Modifications are shaded.

   Original Code

   Modified Code

   /* ** ** This is what requires MODIFICATION. ** Please note that source code will be shipped without ** any key at all. The following comment will be shipped ** with the source code. ** ** NOTE: You must enter the KEY into the variable "inputline" ** (a 12-character string) in the strcpy function cell ** if you want the program to execute properly! */ strcpy(inputline,""); /* ** And you will comment out the following code, from here... */ printf("Enter the key: "); if (gets(inputline) == NULL) { fprintf(stderr, "You must supply a key for this program to run!\n"); fprintf(stderr, "Terminating...\n"); exit(-1); } if (strlen(inputline) != 12) { fprintf(stderr, "You must supply a key with exactly 12 characters.\n"); fprintf(stderr, "Your key has %d characters.\n", strlen(inputline)); fprintf(stderr, "Terminating...\n"); exit(-1); } /* ** To here... */

   /* ** ** This is what requires MODIFICATION. ** Please note that source code will be shipped without ** any key at all. The following comment will be shipped ** with the source code. ** ** NOTE: You must enter the KEY into the variable "inputline" ** (a 12-character string) in the strcpy function cell ** if you want the program to execute properly! */ strcpy(inputline,"thisisthekey"); /* ** And you will comment out the following code, from here... */ /* printf("Enter the key: "); if (gets(inputline) == NULL) { fprintf(stderr, "You must supply a key for this program to run!\n"); fprintf(stderr, "Terminating...\n"); exit(-1); } if (strlen(inputline) != 12) { fprintf(stderr, "You must supply a key with exactly 12 characters.\n"); fprintf(stderr, "Your key has %d characters.\n", strlen(inputline)); fprintf(stderr, "Terminating...\n"); exit(-1); } */ /* ** To here... */

    

   Please note that while this code appears in all three C source code files, it is not necessary to modify it in all three files. For example, one option is to choose to hard-code the key only into the encrypt program, while not modifying the source code in the file decrypt or report decrypt programs. The advantage of this approach is that an operator would not need the key to execute the encryption program, but an authorized individual will have to have access to the key to decrypt the case record identifiers, thus adding an extra measure of security.

3. Compiling the C Source Code

   After modifications are made, compile the source code using a C compiler to create an executable(s). Compile all modified files.
   
   While the name of the executable(s) will not affect performance, we recommend the following naming conventions.

   File Purpose	Executable Name
   Encrypting Record Identifier	ENCR_C.EXE
   Decrypting Record Identifier	DECR_C.EXE
   Decrypting Standard Format Reports	RDCR_C.EXE

    

4. Encrypting the State Client Files

   IMPORTANT NOTICE: The AFCARS Encryption/Decryption Utility will process only ASCII formatted files as specified in Technical Bulletin #2: AFCARS File Format. The Utility will not work for files created in EBCDIC and/or other non-ASCII formats, or files concatenated in an order other than the one specified in Bulletin #2. Operational instructions for C follow:

   Step 1) Execute the encrypt command with one parameter - the name of the AFCARS detail file containing the State case record identifiers. For example, if the AFCARS detail file name is "FC_DET.DOC", the command would be:

   ENCR_C(space)FC_DET.DOC

   Step 2) Provided the encryption key is not hard-coded into the source code, the operator will be prompted for the key. Type the key and press <Enter>. If the code is modified to include the encryption key, no action is required. The file "OUTFILE" will be generated. The data in "OUTFILE" is unaltered; only the case record identifiers will be encrypted.

5. Decrypting the State Client Files

   A decryption routine is included to allow States to decode the case record identifiers. This utility is included as a safeguard. If the AFCARS submission file is inadvertently lost, this utility can recreate it using the file generated by the encryption utility.

   Step 1) Execute the decrypt command with the name of the AFCARS detail file with the encrypted case record numbers. For example, if the input encrypted file name is "OUTFILE" the command would be:

   DECR_C(space)OUTFILE

   Step 2) The program will prompt for the key. MAKE SURE TO USE EXACTLY THE SAME KEY that was used when the case record identifiers in the original file were encrypted using the AFCARS Encryption/Decryption Utility. Type the key and press <Enter>. A file named "DECRYPT.OUT" will be generated; it will be identical to the file that was originally encrypted.

6. Decrypting the AFCARS Detail Reports

   Step 1) Execute the report decryption command with the name of the AFCARS Detail Report. For example, if the name of the report is "FC_RPT.DOC," the command would be:

   RDCR_C(space)FC_RPT.DOC

   Step 2) The program will prompt for the key. MAKE SURE TO USE EXACTLY THE SAME KEY that was used when the case record identifiers in the original file were encrypted using the AFCARS Encryption/Decryption Utility. Type the key and press <Enter>. A file named "DECRYPT2.OUT" will be generated; it will be identical to "FC_RPT.DOC" except that each record will have the State case record identifier in place of the encrypted record identifier.

IV. Additional Information

If additional information is required on installing and executing the AFCARS Encryption/Decryption Utility, please contact the ACF Office of Information Services at (202) 401-1462.

¹Initial issuance date May 26, 1995 as TB #10.
² Revised for century date format August 31, 1996, see ACYF-IM-CB-96-08, issued April 17, 1996, and 65 FR 4019.
3 For instructions on how to properly format an AFCARS submission file with delimiters, see Technical Bulletin #2: AFCARS File Format.