# RXS_Crypt()

This subprocedure performs cryptographic operations like hashing and encryption. Currently supported operations are:

* MD5
* SHA1
* SHA256
* SHA384
* SHA512
* AES128
* AES192
* AES256

For AES encryption, block modes ECB, CBC, and CTR are supported.

## Subprocedure Prototype

### IBM i 7.1+

| Field | Description |
|---|---|
| `     D RXS_Crypt...      D                 PR                  Extproc('RXS_Crypt') Opdesc      D                                     Like(RXS_Var16Mv_t)      D                                     Rtnparm` | Returns the output of the specified hashing/crytographic operation. |
| `     D  pInput                             Like(RXS_Var16Mv_t) Const      D                                     Options(*Varsize:*Omit)` | Field to hold the input of the selected hashing/crytographic operation. You can pass a field smaller than 16M without any additional effort. |
| `     D  pDS                                Like(RXS_Var64K_t)      D                                     Options(*Varsize)` | Holds settings which control how RXS_Crypt operates. This parm can accomodate a number of possible data structures, listed below. |


## Example Code

### IBM i 7.1+

#### Example 1: MD5 Hash of Character Field
```rpgle
      *--------------------------------------------------------------
      * This example code calculates an MD5 hash from a character field.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB

     D HashMD5DS       DS                  LikeDS(RXS_MD5CryptDS_t)
     D                                     Inz(*LikeDS)
     D Data            S                   Like(RXS_Var1Kv_t)
     D Hash            S                   Like(RXS_Var1Kv_t)
      /free
        Data = 'Hello World';

        RXS_ResetDS( HashMD5DS : RXS_DS_TYPE_MD5CRYPT );
        Hash = RXS_Crypt( Data : HashMD5DS );

        RXS_JobLog( 'Hash: %s' : Hash ); // Output: Hash: B10A8DB164E0754105B7A99BE72E3FE5

        *INLR = *ON;
      /end-free
```

#### Example 2: AES128 Encryption of Character Field
```rpgle
      *--------------------------------------------------------------
      * This example code performs AES128 encryption on a string.
      *--------------------------------------------------------------
     H DFTACTGRP(*NO) BNDDIR('RXSBND') ACTGRP(*CALLER)

      /copy QRPGLECPY,RXSCB

     D AESDS           DS                  LikeDS(RXS_AESCryptDS_t)
     D Input           S                   Like(RXS_Var1Kv_t)
     D Output          S                   Like(RXS_Var1Kv_t)
      /free
        Input = 'abc';

        RXS_ResetDS( AESDS : RXS_DS_TYPE_AESCRYPT );

        AESDS.PadInput = RXS_YES;
        AESDS.Algorithm = RXS_CRYPT_AES128_ALGORITHM;
        AESDS.BlockMode = RXS_CRYPT_AESBLOCKMODE_CBC;
        AESDS.EncryptDecrypt = RXS_ENCRYPT;
        AESDS.EncryptAsCcsid = RXS_CCSID_EBCDIC;
        AESDS.Key128 = x'00000000000000000000000000000000';
        AESDS.KeyFormat = RXS_CRYPT_AESKEYFORMAT_BIN;
        AESDS.OutputPadOption = RXS_CRYPT_PADOUTPUT_NONE;
        AESDS.InitializationVector = x'00000000000000000000000000000000';

        Output = RXS_Crypt( Input : AESDS );

        RXS_JobLog( 'Encrypted output: %s' : Output ); // Encrypted output: 81743865f4a9ce13349d67f5642fd971

        *INLR = *ON;
      /end-free
```

## Data Structures

### RXS_MD5CryptDS_t

| Field | Description |
|---|---|
| `     D RXS_MD5CryptDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_MD5CRYPT)` |  |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   InputStmf                         Like(RXS_Var1Kv_t)` | Optional IFS stream file to use as input data for hash operation. |
| `     D   InputCcsid                  10I 0 Inz(RXS_CCSID_JOB)` | CCSID of input data. Used when the input data is of a different CCSID of the job CCSID. Not necessary if using InputStmf. **Default Value:** `RXS_CCSID_JOB` |
| `     D   EncryptAsCcsid...      D                               10I 0 Inz(RXS_CCSID_ISO88591)` | CCSID to convert the input data into before hashing. Note that this is typically going to be RXS_CCSID_ISO88591 or RXS_CCSID_UTF8. **Default Value:** `RXS_CCSID_ISO88591` |
| `     D   InputPointer...      D                                 *` | **Internal use only** |
| `     D   InputLength                 10I 0` | **Internal use only** |
| `     D   OutputPointer...      D                                 *` | **Internal use only** |
| `     D   OutputLength                10I 0` | **Internal use only** |
| `     D   Reserved                  2048A` | **Internal use only** |


### RXS_SHACryptDS_t

| Field | Description |
|---|---|
| `     D RXS_SHACryptDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_SHACRYPT)` |  |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   Algorithm                    4P 3` | Determines which SHA algorithm/block size to use when hashing. **Valid Values:** `RXS_CRYPT_SHA1_ALGORITHM`, `RXS_CRYPT_SHA256_ALGORITHM`, `RXS_CRYPT_SHA384_ALGORITHM`, `RXS_CRYPT_SHA512_ALGORITHM` |
| `     D   InputStmf                         Like(RXS_Var1Kv_t)` | Optional IFS stream file to use as input data for hash operation. |
| `     D   InputCcsid                  10I 0 Inz(RXS_CCSID_JOB)` | CCSID of input data. Used when the input data is of a different CCSID of the job CCSID. Not necessary if using InputStmf. **Default Value:** `RXS_CCSID_JOB` |
| `     D   EncryptAsCcsid...      D                               10I 0 Inz(RXS_CCSID_ISO88591)` | CCSID to convert the input data into before hashing. Note that this is typically going to be RXS_CCSID_ISO88591 or RXS_CCSID_UTF8. **Default Value:** `RXS_CCSID_ISO88591` |
| `     D   InputPointer...      D                                 *` | **Internal use only** |
| `     D   InputLength                 10I 0` | **Internal use only** |
| `     D   OutputPointer...      D                                 *` | **Internal use only** |
| `     D   OutputLength                10I 0` | **Internal use only** |
| `     D   Reserved                  2049A` | **Internal use only** |


### RXS_AESCryptDS_t

| Field | Description |
|---|---|
| `     D RXS_AESCryptDS_t...      D                 DS                  Qualified Template Inz` |  |
| `     D   ReturnedErrorInfo...      D                                     LikeDS(RXS_ReturnedErrorInfoDS_t) Inz` |  |
| `     D   DataStructureType...      D                                5I 0 Inz(RXS_DS_TYPE_AESCRYPT)` |  |
| `     D   OnErrorMessageType...      D                                5I 0` |  |
| `     D   Algorithm                    3I 0` | Determines which AES algorithm to use when encrypting. **Valid Values:** `RXS_CRYPT_AES128_ALGORITHM`, `RXS_CRYPT_AES192_ALGORITHM`, `RXS_CRYPT_AES256_ALGORITHM` |
| `     D   BlockMode                    3I 0` | Determines which AES block mode to use when encrypting. **Valid Values:** `RXS_CRYPT_AESBLOCKMODE_ECB`, `RXS_CRYPT_AESBLOCKMODE_CBC`, `RXS_CRYPT_AESBLOCKMODE_CTR` |
| `     D   EncryptDecrypt...      D                                 N` | Specifies whether input data should be encrypted or decrypted. **Valid Values:** `RXS_ENCRYPT`, `RXS_DECRYPT` |
| `     D   PadInput                      N` | AES standard requires that input data be exactly divisible into block lengths of 16 - specify this value as RXS_YES if you'd like RXS to perform this padding automatically, or to RXS_NO if you are manually padding the input data. **Valid Values:** `RXS_YES`, `RXS_NO` |
| `     D   InputPadCharacter...      D                                1A   Inz(x'00')` | If PadInput is set to RXS_YES, the hex byte value in this field will be used for padding the input data. **Default Value:** `x'00'` |
| `     D   OutputPadOption...      D                                3I 0 Inz(RXS_CRYPT_PADOUTPUT_NONE)` | Specifies if output data should be padded, and which padding method to use. **Valid Values:** `RXS_CRYPT_PADOUTPUT_NONE`, `RXS_CRYPT_PADOUTPUT_CHAR`, `RXS_CRYPT_PADOUTPUT_COUNTER` **Default Value:** `RXS_CRYPT_PADOUTPUT_NONE` |
| `     D   OutputPadCharacter...      D                                1A   Inz(x'00')` | If OutputPadOption is set to RXS_CRYPT_PADOUTPUT_CHAR, the hex byte value in this field will be used for padding the output data. **Default Value:** `x'00'` |
| `     D   KeyFormat                    3I 0 Inz(RXS_CRYPT_AESKEYFORMAT_BIN)` | The data format of the encryption key. Currently only binary keys are fully supported. **Valid Values:** `RXS_CRYPT_AESKEYFORMAT_BIN`, `RXS_CRYPT_AESKEYFORMAT_BER` **Default Value:** `RXS_CRYPT_AESKEYFORMAT_BIN` |
| `     D   Key256                      32A   Inz(*Allx'00')` | The encryption key to be used for AES256. Only the Key### field matching your AES algorithm needs to be specified. |
| `     D   Key192                      24A   Overlay(Key256)` | The encryption key to be used for AES192. Only the Key### field matching your AES algorithm needs to be specified. |
| `     D   Key128                      16A   Overlay(Key256)` | The encryption key to be used for AES128. Only the Key### field matching your AES algorithm needs to be specified. |
| `     D   InitializationVector...      D                               16A   Inz(*Allx'00')` | Initialization vector used for optional additional randomization. If this value is not null, both the encrypting party and the decrypting party need to know this value. |
| `     D   InputCcsid                  10I 0 Inz(RXS_CCSID_JOB)` | CCSID of input data. Used when the input data is of a different CCSID than the job CCSID. Not necessary if using InputStmf. **Default Value:** `RXS_CCSID_JOB` |
| `     D   EncryptAsCcsid...      D                               10I 0 Inz(RXS_CCSID_ISO88591)` | When performing encryption, this field will specify the CCSID in which the data should be encrypted. If this value is different than the InputCcsid value, the data will be converted before encryption. When performing decryption, this field will specify the CCSID of the data that was encrypted. **Default Value:** `RXS_CCSID_ISO88591` |
| `     D   KeyCcsid                    10I 0 Inz(RXS_CCSID_JOB)` | Specify the CCSID of the encryption key. Used when the key is of a different CCSID than the job CCSID. If this value is different than the EncryptAsCcsid value, the data will be converted before encryption/decryption. **Default Value:** `RXS_CCSID_JOB` |
| `     D   InputStmf                         Like(RXS_Var1Kv_t)` | Optional IFS stream file to use as input data for encryption/decryption. |
| `     D   OutputStmf                        Like(RXS_Var1Kv_t)` | Optional IFS stream file where encrypted/decrypted output will be written. |
| `     D   InputPointer...      D                                 *` | **Internal use only** |
| `     D   InputLength                 10I 0` | **Internal use only** |
| `     D   OutputPointer...      D                                 *` | **Internal use only** |
| `     D   OutputLength                10I 0` | **Internal use only** |
| `     D   Reserved                  2049A` | **Internal use only** |