CryptoLib: Testing and Validation
| Version # | Author | Revision Date | Peer Reviewer | Revision Reason |
|---|---|---|---|---|
| Test Plan and Procedures 11/19/2021 | R. Brown, D. Cody Cutright, S. Zemerick | 11/19/2021 | Justin Morris, John Lucas | Initial |
| 1.0 | R. Brown, D. Cody Cutright, S. Zemerick | 12/02/2021 | Justin Morris, John Lucas | Scheduled Release |
| # | Document | Title | Description |
|---|---|---|---|
| 1 | CryptoLib_FY22_Task_Plan_draft01.docx | CryptoLib Task Plan, Draft 01, 10/29/2021 | Task Plan developed by both ITC and JPL MGSS |
| 2 | 2021-11-05 CryptoLib Engineering Release Draft Docs Final.pdf | CryptoLib: 1st Engineering Release and API Draft Documentation 11/05/2021 | Engineering Release, API Documentation, and Task Plan Management Document |
This Test Plan and Procedures document describes the CryptoLib V&V testing that will be performed by the NASA IV&V Independent Test Capability (ITC) Team. The ITC Team is collaborating with the JPL AMMOS team to provide a telecommand (TC) CCSDS SDLS encryption C library. This plan describes in detail the testing scope, testing methods, frameworks, and how the results will be managed and maintained. This plan is meant to serve as a “living” document and will be updated as the Test Plan changes and matures.
The CryptoLib library is a C library with public API functions that are meant to be called from a library user. For example, for TC encryption, the user provides an unencrypted transfer frame (TF) to the Crypto_TC_ApplySecurity() function and the function returns an encrypted TF for uplinking to the spacecraft.
Figure 1, below, shows the JPL-developed functional diagram (11/03/2021) for the CryptoLib and SDLS integration. The ITC Team is focused on implementing and testing the blue boxes, which represent the CryptoLib C library. The blue boxes represent the specific functionality that is being implemented by the ITC Team, which includes the CryptoWrapper and the C code that interfaces with libgcrypt. A set of agreed-upon functions serve as an Application Program Interface (API) for utilizing the CryptoLib. Test activities are focusing on the blue boxes and the API.
CryptoLib V&V falls into three categories:
- API Functionality – Ensures that the API is robust and operates as intended.
- Encryption / Decryption Functionality – Ensures proper usage of the libgcrypt library.
- CCSDS SDLS Standard for TC – Ensures proper adherence and creation of valid TC frames
The Testing Strategy for each category is described below. Each category will utilize a combination of test strategies that can include: 1) Unit and Regression Testing, 2) Automated Continuous Integration Testing, 3) Validation Testing, and 4) Static Code Analysis using Klocwork.
The API functionality will primarily be tested through Unit Tests. Unit Tests are designed to test the inputs, outputs, and functionality of the API functions. Also, Unit Tests will be executed automatically on the github.com server and serve as first-check regression testing for new functionality. The Table below lists the API functions that are currently being Unit Tested. Please note that this is a current snapshot and Unit Tests are added often.
Each of the unit tests are named in such a manner that what is being tested is mostly distinguishable by their naming convention. Tests can easily be listed by calling the specific unit testing application with the –lists-tests flag. These tests will be listed in set.name fashion. As can be seen above the current tests are being utilized to test nominal paths, and the functionality of TC_ApplySecurity when functions like CryptoInit are not called, or bad information is passed. They are also being utilized to test that encryption is being applied properly, and that libgcrypt is being utilized in a correct manner. Current unit tests are described in the following section.
HAPPY_PATH
This is the nominal test case. Optimal inputs are given, and CRYPTO_LIB_SUCCESS is expected from the final output of the TC_APPLY_SECURITY function
NO_CRYPTO_INIT
Testing to verify that CRYPTO_LIB_ERR_NO_INIT is returned when the Crypto_Init() function is not called before attempting to process any other inputs
BAD_SPACE_CRAFT_ID
Validates that proper response is given (CRYPTO_LIB_ERR_INVALID_SCID) when invalid space craft ID is passed as one of the parameters of a data input
BAD_VIRTUAL_CHANNEL_ID
Validates that proper response is given (CRYTPO_LIB_ERR_INVALID_VCID) when invalid virtual channel ID is passed as one of the parameters of a data input
NULL_BUFFER
Verifies the proper OS_ERROR response when an invalid or NULL buffer is passed to the TC_APPLY_SECURITY. This should be verified and checked by external users to be sure this already does not happen, but it tested here to be sure it is handled in this location as well.
Standard AES-256 test vectors are being generated with predefined shared keys and known inputs to ensure that the functions Crypto_TC_ApplySecurity() and Crypto_TC_ProcessSecurity() correctly utilize the libgcrypt library. Known and existing plaintext/ciphertext test vectors will be utilized as inputs and outputs, and a comparison will be performed to verify that the Crypto_TC_ApplySecurity() function is encrypting as expectedn and that Crypto_TC_ProcessSecurity is decryping as expected. Please note that these tests are not designed to test the libgcrypt library, but instead, test ITC’s usage and configuration of the library.
The section below lists the NIST test cases as found at https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/CAVP-TESTING-BLOCK-CIPHER-MODES. The general idea will be to make use of these vectors within a testing framework that utilizes the Crypto_TC_ApplySecurity and Crypto_TC_ProcessSecurity functions. The vector plain text will have an appended header and FECF trailer. The test frame vector will then be digested by these functions and the payload output compared to the cipher text.
VALIDATION_TEST, AUTH_ENCRYPTION_TEST
ET_VALIDATION.AUTH_ENCRYPTION_TEST Makes use of the Python3 Cryptodome module to verify that TC_APPLY_SECURITY properly utilizes LibGCrypt to produce the same results as an external third party software. This external Python program is internalized.
AUTH_DECRYPTION_TEST
DT_VALIDATION.AUTH_DECRYPTION_TEST Reverses the AUTH_ENCRYPTION_TEST to verify that TC_PROCESSSECURITY is functioning properly and makes appropriate use of libgcrypt. Output should be comparable to the original data that is passed into the authorization test.
The following validation tests make use of NIST vectors with known outputs to verify that TC_APPLYSECURITY and TC_PROCESSSECURITY generate the output that is expected via known output tests through the NIST standard, and referenced from the following page and document: https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/CAVP-TESTING-BLOCK-CIPHER-MODES.
Test Vector 0:
Key Length 256 bits, IV Length 96 bits, Plaintext Length 128 bits, MAC Length 120 bits
Key = ef9f9284cf599eac3b119905a7d18851e7e374cf63aea04358586b0f757670f8
IV = b6ac8e4963f49207ffd6374c
PT = 722ee47da4b77424733546c2d400c4e5
CT = 1224dfefb72a20d49e09256908874979
Tag = 882eafea22adf8dbed06a2265f907b
Test Case(s):
NIST_ENC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_0
NIST_DEC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_0
Authorization only MAC validation. Making use of both TC_Apply and TC_Process fucntionality.
Test Case(s):
NIST_ENC_MAC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_0
NIST_DEC_MAC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_0
Test Vector 1:
Key = e9ccd6eef27f740d1d5c70b187734e11e76a8ac0ad1702ff02180c5c1c9e5399
IV = 1af2613c4184dbd101fcedce
PT = 419635e6e12b257a8ecae411f94480ff
CT = 9cd21f414f1f54d5f6f58b1f2f77e5b6
Tag = 5ea75738899abce4c8b7e091054b59
Test Case(s):
NIST_ENC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_1, NIST_DEC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_1
Test Vector 2:
Key Length 256 bits, IV Length 96 bits, Plaintext Length 128 bits,** MAC Length** 120 bits
Key = 7ecc9dcb3d5b413cadc3af7b7812758bd869295f8aaf611ba9935de76bd87013
IV = 6805be41e983717bf6781052
PT = 73d4d7984ce422ac983797c0526ac6f9
CT = 487211dd440f4d09d00bc5c3158a822c
Tag = e74e74630331350c0d6233d11c554f
Test Case(s):
NIST_ENC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_2, NIST_DEC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_2
Test Vector 3:
[https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/CAVP-TESTING-BLOCK-CIPHER-MODES](https://csrc.nist.gov/projects/cryptographic- algorithm-validation-program/CAVP-TESTING-BLOCK-CIPHER-MODES)
Key Length 256 bits, IV Length 96 bits, Plaintext Length 128 bits, MAC Length 120 bits
Key = a881373e248615e3d6576f5a5fb68883515ae72d6a2938e3a6f0b8dcb639c9c0
IV = f0b744f157087df4e41818a9
PT = 07d1dc9930e710b1ebe533c81f671101
CT = b65a2878b9dddbd4a0204dae6a6a6fc0
Tag = dc34a5401542745a650c75e693367b
Test Case(s):
NIST_ENC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_3, NIST_DEC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_3
Test Vector 4:
Key Length 256 bits, IV Length 96 bits, Plaintext Length 128 bits, MAC Length 120 bits
Key = 84c90349539c2a7989cb24dfae5e4182382ae94ba717d385977017f74f0d87d6
IV = eeddeaf4355c826dfd153393
PT = 31c4e1d0ccece6b7a999bfc31f38559a
CT = 5c6cfbdd06c19445ecf500c21aeca173
Tag = c4df572d5c64825d7e8903ad268bc8
Test Case(s):
NIST_ENC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_4, NIST_DEC_VALIDATION.AES_GCM_256_IV_96_PT_128_TEST_4
CryptoLib, and its functions all assume valid frames are passed into the system. It is up to the user or calling program calling the API to verify and validate these frames as they are passed into the library.
All testing activities will be tracked on GitHub as Activities/Issues, and test results will be stored locally on GitHub as well. Below are the return codes from Crypto_TC_ApplySecurity() that are utilized within all unit and validation tests:
| Success / Error Code Description | Constant |
|---|---|
| Success / No Error | CRYPTO_LIB_SUCCESS (0) |
| General Error | CRYPTO_LIB_ERROR (-1) |
| No Initialization | CRYPTO_LIB_ERR_NO_INIT (-2) |
| Invalid Transfer Frame Version Number | CRYPTO_LIB_ERR_INVALID_TFVN (-3) |
| Invalid Spacecraft ID | CRYPTO_LIB_ERR_INVALID_SCID (-4) |
| Invalid Virtual Channel ID | CRYPTO_LIB_ERR_INVALID_VCID (-5) |
| Invalid Map ID | CRYPTO_LIB_ERR_INVALID_MAPID (-6) |
| Invalid Command Control Flag | CRYPTO_LIB_ERR_INVALID_CC_FLAG (-7) |
| No Operational Security Association | CRYPTO_LIB_ERR_NO_OPERATIONAL_SA (-8) |
| Null Buffer | CRYPTO_LIB_ERR_NULL_BUFFER (-9) |