Secure your data using encryption/decryption APIs within RPG.

The encryption/decryption APIs can be difficult to work with, so let's create some procedures to simplify all of the details of the initialization and data structures. We'll create the functionality that we are really looking for through the simplicity of reuse!

With all of the advancements of technology, it is getting easier and easier for users to get access to the data they need. But it is also getting easier for people who you don't want to have access to get to your data. So you have to think about security. In this article, we will discuss how to encrypt and decrypt your data using RPG.

The APIs

Here are the APIs that we will be using to perform the encryption and decryption.

There are a lot of different ways of providing encryption, and there is quite a bit of configuration to get the APIs working properly. For the purpose of this article, we will be working only with the block cipher algorithms: DES, Triple DES, and AES.

The Prototypes

For our examples, we will use the QC3ENCDT and QC3DECDT API references, because they work in both OPM and ILE environments. The hyperlinks will direct you to the API reference on the IBM Web site for additional information.

QC3ENCDT will encrypt the data.

     D encryptDataAPI...

     D                 PR                  extPgm('QC3ENCDT')

     D  argIn                     65535    const options(*varsize)

     D  argInLen                     10I 0 const

     D  argInFmt                      8    const

     D  argAlg                    65535    const options(*varsize)

     D  argAlgFmt                     8    const

     D  argKey                    65535    const options(*varsize)

     D  argKeyFmt                     8    const

     D  argCryptoPro                  1    const

     D  argCryptoDev                 10    const

     D  argOut                    65535

     D  argOutBuffLen                10I 0 const

     D  argOutLen                    10I 0

     D  argError                           likeDs(QUSEC)

QC3DECDT will decrypt the data. The prototype for decryption is the same as for encryption, with the exception of one field. The third field (argInFmt) is omitted for the decryption API.

     D decryptDataAPI...

     D                 PR                  extPgm('QC3DECDT')

     D  argIn                     65535    const options(*varsize)

     D  argInLen                     10I 0 const

     D  argAlg                    65535    const options(*varsize)

     D  argAlgFmt                     8    const

     D  argKey                    65535    const options(*varsize)

     D  argKeyFmt                     8    const

     D  argCryptoPro                  1    const

     D  argCryptoDev                 10    const

     D  argOut                    65535

     D  argOutBuffLen                10I 0 const

     D  argOutLen                    10I 0

     D  argError                           likeDs(QUSEC)

Cipher Setup

Those encryption and decryption APIs have a lot of parameters! Let's take a walk through them. When we're done, we'll create an initialization procedure to take care of the settings before we start using the APIs.

We will specifically be using block algorithm ciphers on a single field. You can click on the API hyperlinks above to find out other configurations that are available. Here are the settings that we will be using to set up for these types of operations.

Once we have the values initialized, the only values that will change will be the input and output data and the associated lengths that we are working with. The following procedure can be used to initialize these values:

     D cipherSetup...

     D                 PR

     D  argKey                     1024A   const varying

     D                                     options(*varsize)

     D  argAlgorithm                 10I 0 const

     D**********************************************************************

     D*  cipherSetup() using Block Cipher Algorithms

     D**********************************************************************

     P cipherSetup...

     P                 B                   EXPORT

     D cipherSetup...

     D                 PI

     D  argKey                     1024A   const varying

     D                                     options(*varsize)

     D  argAlgorithm                 10I 0 const

     D*

     D svBytes         S             52A

      /free

        // Initialize the Algorithm Data Structure QC3D0200

        QC3D0200 = *AllX'00';

        QC3BCA = argAlgorithm;

        select;

          when argAlgorithm = DES;

            QC3BL = 8;

          when argAlgorithm = TRIPLE_DES;

            QC3BL = 8;

          when argAlgorithm = AES;

            // For AES, could be 16, 24 or 32

            QC3BL = 16;

          other;

            QC3BL = 0;

        endsl;

        QC3MODE = '1';

        QC3PO = '1';

        QC3EKS = 0;

        // Initialize the Key Data Structure QC3D020000

        keyDesc.QC3D020000 = *AllX'00';

        keyDesc.QC3D020000.QC3KT = argAlgorithm;

        keyDesc.QC3D020000.QC3KF = '0';

        keyDesc.QC3D020000.QC3KSL = %len(%trim(argKey));

        keyDesc.QC3Key = %trim(argKey);

        // Initialize the Rest of the Parameters

        stdError.QUSEC = *AllX'00';

        stdError.QUSEC.QUSBPRV = 1040;

        cryptoPro = '0';

        cryptoDev = *BLANKS;

      /end-free

     P                 E

QC3D0200 is the data structure that sets up the algorithm. We will initially clear out the entire data structure bits with zeros. Then, we can just set the values that we need to:

• QC3BCA uses constants to determine the type of encryption that we will be using: DES, Triple DES, or AES.
• QC3BL is the block length to be used. For DES and Triple DES, the value must be 8. For AES, you could use 16, 24, or 32. We will be using 16, but you can change that to suit your needs.
• QC3MODE will be set to '1', indicating the CBC mode.
• QC3PO will be set to '1', indicating that padding will be used with the character specified in QC3PC, which we will leave as zeros.

QC3D020000 is the data structure that sets up the key. We will initially clear out the entire data structure bits with zeros. Then, we can just set the values that we need to:

• QC3KT is the key type, indicating the type of encryption that we will be using: DES, Triple DES, or AES. For the options that we are using, we can reuse the constants used in the QC3BA field of QC3D0200. If you were to use the additional values available, such as 30, 50, or 51, then you would not be able to reuse the codes. But, for simplicity in this example, we were able to.
• QC3KF is the key format; '0' specifies that the key is a binary value.
• QC3KSL is the key length.

Extending the IBM Data Structures

I find the code easier to understand if I create qualified data structures to extend the existing IBM data structures to contain character fields that I will be working with.

The QUSEC data structure is the IBM-provided common error code data structure to be used with APIs. It can be found in the QSYSINC/QRPGLESRC,QUSEC source file.

     D* The QUSEC Source Contains the Common Error Code Data Structure.

     D/COPY QSYSINC/QRPGLESRC,QUSEC

     D stdError        DS                  qualified

     D  QUSEC                              likeDs(QUSEC)

     D  outError                   1024A

The QC3D020000 data structure is used for the key description data structure and can be found in the QSYSINC/QRPGLESRC,QC3CCI source file, along with the QC3D0200 data structure. We will be passing in a key that we can add to the end of the existing data structure.

     D* The QC3CCI Source Contains Encryption Data Structures.

     D/COPY QSYSINC/QRPGLESRC,QC3CCI

     D keyDesc         DS                  qualified

     D  QC3D020000                         likeDs(QC3D020000)

     D  QC3Key                     1024A

Encapsulating the APIs

We will simplify the use of the encryption APIs by creating custom procedures to handle all of the details.

Here are the encryptData prototype and procedure:

     D encryptData...

     D                 PR         65535A

     D  argData                   65535A   const varying

     D                                     options(*varsize)

     D  argOutLen                    10I 0

     D**********************************************************************

     D*  encryptData() using Block Cipher Algorithms

     D**********************************************************************

     P encryptData...

     P                 B                   EXPORT

     D encryptData...

     D                 PI         65535A

     D  argData                   65535A   const varying

     D                                     options(*varsize)

     D  argOutLen                    10I 0

     D*

     D svOutData       S          65535A

     D svBytes         S             52A

      /free

        svOutData = *BLANKS;

        // API

        encryptDataAPI(argData: %len(argData): 'DATA0100':

                    QC3D0200: 'ALGD0200':

                    keyDesc: 'KEYD0200':

                    cryptoPro: cryptoDev:

                    svOutData: %size(svOutData): argOutLen:

                    stdError);

        if stdError.QUSEC.QUSBAVL > 0;

          // Error

          svBytes = 'Error: ' + stdError.QUSEC.QUSEI;

          DSPLY svBytes;

          svOutData = *BLANKS;

        else;

        endif;

        return svOutData;

      /end-free

     P                 E

And here are our decryptData prototype and procedure:

     D decryptData...

     D                 PR         65535A

     D  argData                   65535A   const varying

     D                                     options(*varsize)

     D  argInLen                     10I 0

     D**********************************************************************

     D*  decryptData() using Block Cipher Algorithms

     D**********************************************************************

     P decryptData...

     P                 B                   EXPORT

     D decryptData...

     D                 PI         65535A

     D  argData                   65535A   const varying

     D                                     options(*varsize)

     D  argInLen                     10I 0

     D*

     D svOutData       S          65535A

     D svOutDataLen    S             10I 0

     D svBytes         S             52A

      /free

        svOutData = *BLANKS;

        // API

        decryptDataAPI(argData: argInLen:

                    QC3D0200: 'ALGD0200':

                    keyDesc: 'KEYD0200':

                    cryptoPro: cryptoDev:

                    svOutData: %size(svOutData): svOutDataLen:

                    stdError);

        if stdError.QUSEC.QUSBAVL > 0;

          // Error

          svBytes = 'Error: ' + stdError.QUSEC.QUSEI;

          DSPLY svBytes;

          svOutData = *BLANKS;

        else;

        endif;

        return svOutData;

      /end-free

     P                 E

You can see that with the custom procedures, you have only two parameters, which makes the code much easier to work with.

The Code

Now we get to enjoy the fruits or our labor! Let's use our new procedures to encrypt a piece of valuable data and then decrypt it to make sure we get back the same results that we put in.

One obvious piece of information you would want to protect would be Social Security numbers. We will use an invalid Social Security number, 987-65-4320, for our example.

     D ssn             S            128A

     D results         S          65535A

     D secretKey       S             32A

     D cryptoPro       S              1A

     D cryptoDev       S             10A

     D encryptLen      S             10I 0

     D displayBytes    S             52A

     D************************* Constants *******************************

     D* Block Cipher Algorithms

     D DES             C                   20

     D TRIPLE_DES      C                   21

     D AES             C                   22

     D**************************** Main *********************************

      /free

       ssn = '987654320';

       //------------------------------------------------

       // AES

       //------------------------------------------------

       secretKey = 'MC_pr3$$!0nL1N3_';

       displayBytes = '----- AES ENCRYPTION -----';

       DSPLY displayBytes;

       displayBytes = 'Original: ' + %trim(ssn);

       DSPLY displayBytes;

       // Configure Encryption Cipher

       cipherSetup(secretKey: AES);

       // Encrypt the Data

       results = encryptData(ssn: encryptLen);

       displayBytes = 'Encrypted: ' + %trim(results);

       DSPLY displayBytes;

       // Decrypt the Data

       results = decryptData(results: encryptLen);

       displayBytes = 'Decrypted: ' + %trim(results);

       DSPLY displayBytes;

       //------------------------------------------------

       // Triple DES

       //------------------------------------------------

       secretKey = 'MC_pr3$$';

       displayBytes = '----- TRIPLE DES ENCRYPTION -----';

       DSPLY displayBytes;

       displayBytes = 'Original: ' + %trim(ssn);

       DSPLY displayBytes;

       // Configure Encryption Cipher

       cipherSetup(secretKey: TRIPLE_DES);

       // Encrypt the Data

       results = encryptData(ssn: encryptLen);

       displayBytes = 'Encrypted: ' + %trim(results);

       DSPLY displayBytes;

       // Decrypt the Data

       results = decryptData(results: encryptLen);

       displayBytes = 'Decrypted: ' + %trim(results);

       DSPLY displayBytes;

       *inlr = *ON;

      /end-free

The Output

When you run the program, you will see the following screen:

Figure 1: This is the output you get when you run the program.

The error code logic in the encryptData and decryptData procedures could come in handy if you have any problems. Just go to the hyperlinks on the API names and look up their meanings to translate the error codes.

Is Your Data Secure?

Now your data is encrypted! But is it safe? Not completely. What if someone were to get at the source code? The key is coded right there, and anyone who can view the source could decrypt the data.

You may have a bunch of ideas about how to overcome that obstacle. Maybe you could be creative with how you create your key, but the person reading the code would just be challenged with figuring out your logic. Or maybe you could remove the source from the system and upload it only when you are modifying it. But could someone retrieve the source from the program?

Don't fear. There is an answer for that with key stores, but we'll save that topic for another day. This article is the first step to understanding encryption and the resources that are available to you. If we tackle this a piece at a time, total understanding will be much easier.

Download the Code

You can download the code used in this article—as well as the fixed-format version—by clicking here.

Happy coding!