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 CAPIResolutions.json crypto resolutions file in the folder. folder and copy the
- 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 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.
folder, in - 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.
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, theRule Array Parms
column – theRULE_ARRAY_COUNT
andRULE_ARRAY
names are used, but for anyOther 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.