From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 5455F41EA2 for ; Wed, 15 Mar 2023 18:31:14 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5089540A7A; Wed, 15 Mar 2023 18:31:14 +0100 (CET) Received: from mail-il1-f225.google.com (mail-il1-f225.google.com [209.85.166.225]) by mails.dpdk.org (Postfix) with ESMTP id 6051540141 for ; Wed, 15 Mar 2023 18:31:13 +0100 (CET) Received: by mail-il1-f225.google.com with SMTP id bp11so5346022ilb.3 for ; Wed, 15 Mar 2023 10:31:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1678901473; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=7ju6ahJnEoteISp0omDNYEY3Sfa0hsgPW/Ti2M965XM=; b=LRv2QVKD6DjCeaeMK0wAKxE1tsxDui/P1rWVxpnVxeJxkLjBnqLkIywrXAOQaLZtfS J8ofr9UbnM/IUB51nt27jdfaP+TlZVBiM+kxYipDP9OojizdYTI27u+nt0v97urObQ9X WkP8r82t3WOYsiSD2OZlo6bNc4H5RcgpYHkLg= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1678901473; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=7ju6ahJnEoteISp0omDNYEY3Sfa0hsgPW/Ti2M965XM=; b=nUsF4uOHBEUhhu/kNGCBnWFDiIRajqgkbaJToOTAYzdBLd+cag1vtcR8+KcGfW2QSH 1HUEoD8nRSkO8twnb6pNIis3ygzjPRgKo55I3JShTmw8B6v6LSKORPNzORL8cstvhA8a AetGtroNp3LLBqBqRgpSLmPJfaVpOMWLUIMxmCL9It4w0BwoCcUzabdH3VZUpZeoobGH AKnjm7tGXrLJMZ5dS17vuaJz1NJ808/LxsR2WLRXdjG9vYTVgCf3jo1CCF4v6+ZFppUR Y0zRPJz79J2TillKIcpti6ciNd5ihdDMrzab15uZ5/FE9g8p1/diTPhVGUimAhj69DUK pYbg== X-Gm-Message-State: AO0yUKUZw+Y+foJGnvY04PpbD6SEOfCRm7BHeBQvV90B7gtFMRGcFSIJ KnW5OaRhknPU4ssnd3O5Zt+eneIhju/YhJsCam1xgEIV+rw9kVuOs+g1Uw/76Z3QyP1lfW+N1gP d69wOAEmQLKagKDAcmWG842bmtJWgzZXIjHdyvUeXF8nzTgKl/f355jiKSP7t+idngFkLnG3pPx 5wAPTeErzCq3ZMgE9XhSCK X-Google-Smtp-Source: AK7set/z5YRuFUzrfjWnQVLe6aT4/zHkZNSpKlhJxEKeAQWU7L5cWSTOs3rWbGzMMKImEjpECla2gSO1Yoyg X-Received: by 2002:a92:d990:0:b0:317:93dc:1121 with SMTP id r16-20020a92d990000000b0031793dc1121mr4669790iln.28.1678901472677; Wed, 15 Mar 2023 10:31:12 -0700 (PDT) Received: from postal.iol.unh.edu (postal.iol.unh.edu. [2606:4100:3880:1234::84]) by smtp-relay.gmail.com with ESMTPS id j3-20020a922003000000b003172c28d5f4sm265197ile.69.2023.03.15.10.31.12 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Wed, 15 Mar 2023 10:31:12 -0700 (PDT) X-Relaying-Domain: iol.unh.edu Received: from iol.unh.edu (unknown [IPv6:2606:4100:3880:1257::1083]) by postal.iol.unh.edu (Postfix) with ESMTP id 31110605246B; Wed, 15 Mar 2023 13:31:12 -0400 (EDT) From: jspewock@iol.unh.edu To: ci@dpdk.org Cc: Brandon Lo , Jeremy Spewock Subject: [PATCH v5 4/4] doc: add readme file for acvp_tool Date: Wed, 15 Mar 2023 13:28:38 -0400 Message-Id: <20230315172837.29736-5-jspewock@iol.unh.edu> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230315172837.29736-1-jspewock@iol.unh.edu> References: <20230315172837.29736-1-jspewock@iol.unh.edu> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: ci@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK CI discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: ci-bounces@dpdk.org From: Brandon Lo This readme file contains instructions to set up and use the acvp_tool. Signed-off-by: Brandon Lo doc: updated out-of-date acvp_tool readme Signed-off-by: Jeremy Spewock --- tools/acvp/README | 129 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 tools/acvp/README diff --git a/tools/acvp/README b/tools/acvp/README new file mode 100644 index 0000000..23a1aef --- /dev/null +++ b/tools/acvp/README @@ -0,0 +1,129 @@ +The ACVP tool is a general tool for interacting with the NIST ACVP API +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 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). + +If you do not have the required files from NIST, you must email them +to create demo credentials. +https://pages.nist.gov/ACVP/#access + + +Setup +----- + +After setting the environment variables as described in the +"Requirements" section, you will need to edit the acvp_config.json file. + +The acvp_config.json file is expected to be a json object +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 . 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. + +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