Using IBM AD and Quantum-Safe Cryptography Feature

Introduction

IBM AD allows you to identify cryptographic API calls and create a cryptographic inventory.

Important: This feature is available only for COBOL Programs.

The main component that helps you to perform Application Crypto Analysis is IBM AD Build Client and has the following advantages:

Discover where and what API crypto is used in applications.
Capture valuable metadata and dependencies by identifying values for Rule Array and other important parameters.
Store the generated results in a repository.
Aid in migration and modernization planning.
Aid in quickly reacting to security issues.

Procedure

To help you get started with the Application Crypto Analysis, the following steps need to be performed.

Note: Before you start, make sure that the IBM AD Installation and Configuration process are complete. For more information, see:

Go to the <IBM ADDI Installation Folder> > IBM Application Discovery Build Client > bin > release > > samples folder and copy the CAPIResolutions.json crypto resolutions file in the bin > release folder.
By using IBM AD Build Client, create a new project or open an existing one. For more information, see Creating a project.
In case that a new project was created, add the COBOL files to the zOS Cobol project folder in IBM AD Build Client. The COBOL files will be scanned and analyzed for CALL statements (CALLs to the cryptographic services). For more information, see Adding Files to Project Folders.
Build the project. For more information, see Building Projects.
Once the build process is complete, two report files related to crypto CALLs services are generated in the project's folder > reports > GenericAPI folder, in html and csv format.
Note:
- Both files contain the same information. The file in the CSV format can be processed by other tools as raw data. The HTML file can be used as a report, where you can filter the results according to various criteria.
  Example of .csv file.
```
GenericAPI_<timestamp>.csv
```
  Example of .html file.
```
GenericAPI_<timestamp>.html
```
- The same information is also displayed in HTML format in the main build report present in the reports folder.
  Example of main build report:
```
MainBuildReport_<timestamp>.html
```
For more information, see Displaying Build Results.

Interpreting the report files

Each CALL statement is identified by an ID (OccurID).

For each CALL statement uniquely identified by an ID (column A – OccurID),
CALL to a CRYPTO service (column B – APIName),
CALL that can be located in the file (column K – PathStr) at the line (column L – StartRow),
the following parameter values have been collected (column G - ParamValue)
forming one or more tuples (column H – GroupID),
corresponding to the parameter positions (column F - OrdinalPos)
specified in CAPIResolutions.json for the respective service.

Snippet of the Crypto Resolutions file - CAPIResolutions.json

{
    "formatVersion":"1.0",
    ...
    "GenericAPIs":
    [
        ...
        {
            "GenericAPIName":"CSNBENC1,CSNEENC1",
            "Description":"Encipher",
            "Metadata":"DES",
            "Metadata1": "Encryption/Decryption",
            "Parameters":
            [
                {
                    "Name":"RULE_ARRAY_COUNT",
                    "Position":9,
                    "DefaultValues":"0"
                },
                {
                    "Name":"RULE_ARRAY",
                    "Position":10,
                    "DefaultValues":"INITIAL, TOKEN"
                }
            ]
        }
        ...
    ]
}

Where:

GenericAPIName - is the name of the service. If the service has multiple names, you can initialize it with all values separated by comma.
Description - represents a short description of the service.
Metadata - this field is mapped to the Algorithm used by that service.
Metadata1 - this field is mapped to the Category to which that service belongs.
Parameters - it is an array of parameter objects where each object has:
- Name - can be a convention. For example, the Rule Array Parms column – the RULE_ARRAY_COUNT and RULE_ARRAY names are used, but for any Other Parms PARAM<No> is used. Examples: PARAM6, PARAM7, PARAM8.
- Position - represents the position of the parameter for which its values are collected.
- DefaultValues - comma-separated default parameter values, if any.

Note:

The CAPIResolutions.json file can be edited and extended with other client interfaces as follows:

{
    "GenericAPIName":"MYENCPHR",
    "Description":"Custom Encipher", 
    "Metadata":"DES",
    "Metadata1": "CustomImplementation of Encryption/Decryption",
    "Parameters":
    [
        {
            "Name":"RULE_ARRAY_COUNT",
            "Position":9,
            "DefaultValues":"0"
        },
        {
            "Name":"RULE_ARRAY",
            "Position":10,
            "DefaultValues":"INITIAL, TOKEN"
        }
    ]
}

If no CALL statements to the cryptographic services are encountered through the COBOL source files, an empty report will be generated, stating that:
```
GenericAPI query returned no results.
```