[PATCH v4 2/2] doc: updated out-of-date acvp_tool readme

[jspewock@iol.unh.edu]

From: Jeremy Spewock <jspewock@iol.unh.edu>

this updates the readme to show current coverage of algorithms as well
as how to setup a proper environment and run tests.

Signed-off-by: Jeremy Spewock <jspewock@iol.unh.edu>
---
 tools/acvp/README | 76 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 67 insertions(+), 9 deletions(-)

diff --git a/tools/acvp/README b/tools/acvp/README
index 0cd3acc..23a1aef 100644
--- a/tools/acvp/README
+++ b/tools/acvp/README
@@ -3,23 +3,33 @@ in order to test different cryptographic implementations.
 
 It produces machine-readable output for parsing in a CI environment.
 
+Supported Algorithms
+--------------------
+* AES-CBC
+* AES-CMAC
+* AES-GMAC
+* HMAC-SHA-1
+* TDES-CBC
+* AES-CTR
 
 Requirements
 ------------
 
-There are also packages you need to download from the requirements.txt file:
+There are also python packages you need to download from the requirements.txt file:
 * pyotp
 * requests
 
+Along with these, you will also need to install the `nasm` package using your local package manager.
+
 The tool expects that you have all the credential files from NIST:
 * Client certificate (usually a .cer file from NIST)
 * Key file for the certificate
 * Time-based one-time password seed file (usually a .txt file from NIST)
 
 The path to each file must be stored in an environment variable:
-$ACVP_SEED_FILE  =  Path to the TOTP seed .txt file    (given by NIST).
-$ACVP_CERT_FILE  =  Path to the client .cer/.crt file  (given by NIST).
-$ACVP_KEY_FILE   =  Path to the certificate key file   (generated by user).
+* $ACVP_SEED_FILE  =  Path to the TOTP seed .txt file    (given by NIST).
+* $ACVP_CERT_FILE  =  Path to the client .cer/.crt file  (given by NIST).
+* $ACVP_KEY_FILE   =  Path to the certificate key file   (generated by user).
 
 If you do not have the required files from NIST, you must email them
 to create demo credentials.
@@ -38,34 +48,82 @@ containing two keys: "url" and "algorithms"
 "url" must be the base URL string of the API you want to use.
 "algorithms" must be an array of algorithm objects as detailed in the
 ACVP API specification here:
-https://github.com/usnistgov/ACVP/wiki/ACVTS-End-User-Documentation
+https://github.com/usnistgov/ACVP/wiki/ACVTS-End-User-Documentation . In the case of the supported algorithms listed above, the only thing that will need to change in the config file is the `"algorithm"` field to match the name of the algorithm you would like to test.
+* In order to test AES-CTR you'll also have to remove the key `"ivGenMode"` 
 
 Now you can use the acvp_tool.py script to register a test session,
 upload the results, and download the verdict.
 
-
+In order to run the DPDK sample application, there are a few libraries which must be installed:
+* Intel IPSec Multi-buffer (v1.3)
+```
+git clone https://github.com/intel/intel-ipsec-mb.git
+cd intel-ipsec-mb
+git checkout v1.3
+make -j 4
+make install
+```
+* FIPS Object Module
+```
+curl -o openssl-fips-2.0.16.tar.gz https://www.openssl.org/source/openssl-fips-2.0.16.tar.gz
+tar xvfm openssl-fips-2.0.16.tar.gz
+cd openssl-fips-2.0.16
+./config
+make
+make install
+```
+* OpenSSL library
+```
+curl -o openssl-1.0.2o.tar.gz https://www.openssl.org/source/openssl-1.0.2o.tar.gz
+export CFLAGS='-fPIC'
+tar xvfm openssl-1.0.2o.tar.gz
+cd openssl-1.0.2o
+./config shared fips
+make depend
+make
+```
 Usage
 -----
-
+### Interacting with ACVP API
 To see all options available, use the --help flag.
 
 First, register and download a new test session with the tool:
+
     acvp_tool.py --request $DOWNLOAD_PATH
-The file written to $DOWNLOAD_PATH will contain both the session information
-and the test vectors.
+The file written to $DOWNLOAD_PATH will contain both the session information and the test vectors.
 
 You should use the DPDK FIPS validation example application to test
 the vectors in this file. The example application will generate
 the result file which is uploaded back to the ACVP API.
 
 After running tests with the vector file, you can submit the result:
+
     acvp_tool.py --response $RESULT_PATH --upload
 where $RESULT_PATH is the path of the file containing the answers.
 
 Once you submit your results, you can do
+
     acvp_tool.py --response $RESULT_PATH --verdict $VERDICT_PATH
 where $VERDICT_PATH is where you want to save the verdict information.
 The verdict file will contain the result of each test case submitted.
 
 You can also combine the options:
+
     acvp_tool.py --response $RESULT_PATH --upload --verdict $VERDICT_PATH
+
+### Using the DPDK FIPS Validation Example Application
+First, you have to make sure that you configure DPDK to build the FIPS sample application before you compile with ninja
+```
+#inside dpdk/
+meson build --werror
+meson configure -Dexamples=fips_validation build
+sudo ninja -C build
+```
+Once this has finished, you can now run the sample application and validate the test vectors. In order to run this validation step, you have to supply a valid crypto device and either a `*.json` or `*.req` file with vectors for validation. You can use the virtual device `crypto_aesni_mb` provided by the Intel IPSec Multi-buffer library and pass the JSON file containing test vectors from the ACVP API using `--req-file`. 
+
+Example usage:
+    
+    #inside dpdk/
+    build/examples/dpdk-fips_validation --vdev crypto_aesni_mb -- --req-file aes-cbc-vectors.json --rsp-file aes-cbc-answers.rsp --cryptodev crypto_aesni_mb`
+
+The file path passed into `--rsp-file` will contain the validated vectors from the sample applications and can be passed to the ACVP API to receive a verdict on your results.
\ No newline at end of file
-- 
2.39.2