Merge pull request #383 from nasa/382-documentation-refresh

[#382] Sphinx Documentation Refresh POC

.github/workflows/build.yml

@@ -12,7 +12,7 @@ jobs:
     # Container Setup
     runs-on: ubuntu-latest
     container:
-        image: ivvitc/cryptolib:20241220
+        image: ivvitc/cryptolib:20250108
     steps:
     - uses: actions/checkout@v4
     - name: Update
@@ -32,7 +32,7 @@ jobs:
     # Container Setup
     runs-on: ubuntu-latest
     container:
-        image: ivvitc/cryptolib:20241220
+        image: ivvitc/cryptolib:20250108
     steps:
     - uses: actions/checkout@v4
     - name: Update
@@ -43,11 +43,13 @@ jobs:
 
     - name: Internal Build Script
       working-directory: ${{github.workspace}}
-      run: bash ${GITHUB_WORKSPACE}/support/scripts/build_internal.sh
+      run: |
+        export CFLAGS="-fprofile-arcs -ftest-coverage -fcondition-coverage -g"
+        bash ${GITHUB_WORKSPACE}/support/scripts/build_internal.sh
 
-    - name: Code-Coverage
-      working-directory: ${{github.workspace}}
-      run: make gcov
+    # - name: Code-Coverage
+    #   working-directory: ${{github.workspace}}
+    #   run: make gcov
 
     - name: Upload 
       uses: codecov/codecov-action@v4
@@ -113,7 +115,7 @@ jobs:
     # Container Setup
     runs-on: ubuntu-latest
     container:
-        image: ivvitc/cryptolib:20241220
+        image: ivvitc/cryptolib:20250108
     steps:
     - uses: actions/checkout@v4
     - name: Update
@@ -143,11 +145,13 @@ jobs:
 
     - name: Wolf Build Script
       working-directory: ${{github.workspace}}
-      run: bash ${GITHUB_WORKSPACE}/support/scripts/build_wolf.sh
+      run: |
+        export CFLAGS="-fprofile-arcs -ftest-coverage -fcondition-coverage -g"
+        bash ${GITHUB_WORKSPACE}/support/scripts/build_wolf.sh
     
-    - name: Code-Coverage
-      working-directory: ${{github.workspace}}
-      run: make gcov
+    # - name: Code-Coverage
+    #   working-directory: ${{github.workspace}}
+    #   run: make gcov
 
     - name: Upload 
       uses: codecov/codecov-action@v4
@@ -218,7 +222,7 @@ jobs:
     # Container Setup
     runs-on: ubuntu-latest
     container:
-        image: ivvitc/cryptolib:20241220
+        image: ivvitc/cryptolib:20250108
     steps:
     - uses: actions/checkout@v4
     - name: Update
@@ -229,11 +233,13 @@ jobs:
 
     - name: Internal Build Script
       working-directory: ${{github.workspace}}
-      run: bash ${GITHUB_WORKSPACE}/support/scripts/build_ep.sh
+      run: |
+        export CFLAGS="-fprofile-arcs -ftest-coverage -fcondition-coverage -g"
+        bash ${GITHUB_WORKSPACE}/support/scripts/build_ep.sh
 
-    - name: Code-Coverage
-      working-directory: ${{github.workspace}}
-      run: make gcov
+    # - name: Code-Coverage
+    #   working-directory: ${{github.workspace}}
+    #   run: make gcov
 
     - name: Upload 
       uses: codecov/codecov-action@v4

.gitignore

@@ -30,3 +30,6 @@ test/cmake_install.cmake
 test/CTestTestfile.cmake
 test/CMakeFiles/*
 Testing/Temporary/*
+docs/wiki/_build
+docs/wiki/_templates
+

Makefile

@@ -21,10 +21,14 @@ all:
 
 clean:
 	rm -rf ./build
+	rm -rf ./docs/wiki/_build
 
 debug:
 	./support/scripts/docker_debug.sh
 
+docs:
+	./support/scripts/documentation_build.sh
+
 internal: 
 	./support/scripts/internal_docker_build.sh
 

docs/wiki/Environment_Building.md

@@ -0,0 +1,101 @@
+# Environment
+
+Environment and dependency details may be found within `./support/Dockerfile`. If running via docker, dependencies will be installed automatically.
+
+If building locally, ensure all dependencies below are met.
+
+
+*Note:* Theses dependencies are for the default internal build, other builds may vary.
+
+## Dependencies
+### Running
+| __Apt:__        |                       |
+|-----------------|-----------------------|
+| autoconf        | automake              |
+| ca-certificates | cmake                 |
+| curl            | g++-multilib          |
+| gcc-multilib    | gettext               |
+| git             | gdb                   |
+| lcov            | libcurl4-openssl-dev  | 
+| libmariadb-dev  | libmariadb-dev-compat |
+| libtool         | unzip                 |
+| make            | python3-dev           |
+| python3-pip     | build-essential       |
+
+<br />
+
+| __Web:__           |                       |
+|--------------------|-----------------------|
+| libgpg-error 1.50  | libgcrypt 1.11.0      |
+
+<br />
+<br />
+
+### Documentation
+| __Apt:__            |                          |
+|---------------------|--------------------------|
+| python3-sphinx      | python3-sphinx-rtd-theme |
+| python3-myst-parser | 
+
+<br />
+<br />
+
+## Building
+There are numerous configurations when building CryptoLib.  References to necessary build flags can be found within `./support/scripts/`.  For example to build the current internal build:
+
+> Clone the CryptoLib repo. Switch to the desired branch. Currently, integration efforts are occurring in the _main_ branch.
+> * cd Cryptolib
+> * cmake -DCODECOV=1 -DDEBUG=1 -DTEST=1 -DTEST_ENC=1 .
+> * make
+> * make test
+
+This will build the internal debug environment, with code coverage, testing, and encryption testing.
+
+*Other Build Configurations:*
+> * KMC, Minimal, WolfSSL, and other configurations have convenience scripts which can be referenced within the `./support/scripts/` directory.
+
+*Code Coverage:*
+With the DCODECOV Flag set, users may produce code coverage results similarly to the code below:
+> * cmake -DMYSQL=1 -DENCTEST=1 -DDEBUG=1 -DCODECOV=1 ../
+> * make
+> * make gcov
+
+This will produce local coverage reports in /build/coverage, with the HTML results within /build/coverage/results/index.html
+
+*Cleanup:*
+> * make clean  -- Cleans Build
+> * make scrub  -- Cleans Code Coverage
+
+The two flags (DEBUG and TEST_ENC) can be used simultaneously, or separately. 
+
+*All Build Flags:*
+> * CODECOV -- "Code Coverage" -- Default OFF
+> * CRYPTO_LIBGCRYPT -- "Cryptography Module - Libgcrypt" -- Default ON
+> * CRYPTO_KMC -- "Cryptography Module - KMC" -- Default OFF
+> * CRYPTO_WOLFSSL -- "Cryptography Module - WolfSSL" -- Default OFF
+> * CRYPTO_CUSTOM -- "Cryptography Module - CUSTOM" -- Default OFF
+> * CRYPTO_CUSTOM_PATH -- "Cryptography Module - CUSTOM PATH" -- Default OFF
+> * DEBUG -- "Debug" -- Default OFF
+> * KEY_CUSTOM -- "Key Module - Custom"-- Default  OFF
+> * KEY_CUSTOM_PATH -- "Custom Key Path" -- Default OFF
+> * KEY_INTERNAL -- "Key Module - Internal" -- Default ON
+> * KEY_KMC -- "Key Module - KMC"-- Default  OFF
+> * MC_CUSTOM -- "Monitoring and Control - Custom" -- Default OFF
+> * MC_CUSTOM_PATH -- "Custom Monitoring and Control path" -- Default OFF
+> * MC_DISABLED -- "Monitoring and Control - Disabled" -- Default OFF
+> * MC_INTERNAL -- "Monitoring and Control - Internal" -- Default ON
+> * SA_CUSTOM -- "Security Association - Custom" -- Default OFF
+> * SA_CUSTOM_PATH -- "Custom Security Association Path" -- Default OFF
+> * SA_INTERNAL -- "Security Association - Internal" -- Default ON
+> * SA_MARIADB -- "Security Association - MariaDB" -- Default OFF
+> * SUPPORT -- "Support" -- Default OFF
+> * SYSTEM_INSTALL -- "SystemInstall" -- Default OFF
+> * TEST -- "Test" -- Default OFF
+> * SA_FILE -- "Save Security Association to File" -- Default OFF
+> * KEY_VALIDATION -- "Validate existence of key duplication"-- Default OFF
+
+> * KMC_MDB_RH "KMC-MDB-RedHat-Integration-Testing" -- Default OFF 
+> * KMC_MDB_DB "KMC-MDB-Debian-Integration-Testing" -- Default OFF 
+> * KMC_CFFI_EXCLUDE "KMC-Exclude-Problematic-CFFI-Code" -- Default OFF
+
+> * CRYPTO_EPROC "Enables building of Extended Procedures -- Default OFF (CURRENTLY A WIP - Not ready for Operations)

docs/wiki/Home.md

@@ -0,0 +1,39 @@
+![CryptoLib logo Final All orange](https://github.com/user-attachments/assets/acb15175-9ba5-44a5-ae86-c9615400fcb7)
+
+This documentation is designed to provide information on how to build, test, and utilize the CryptoLib library.
+
+# CryptoLib
+CryptoLib provides a C-based software-only implementation of the CCSDS Space Data Link Security Protocol (SDLS), and SDLS Extended Procedures (SDLS-EP) to secure communications between a spacecraft flight software and ground station. Originally designed as a Core Flight System (cFS) spacecraft library, CryptoLib has expanded in scope to allow generic support for multiple space and ground implementations.  At its core, CryptoLib can be configured to make use of multiple encryption libraries, including WolfSSL, LibGcrypt, and JPL's Key Management and Cryptography (KMC) encryption interfaces. 
+
+Specific communications protocols that are supported include:
+> * Telecommand (TC)
+> * Telemetry (TM)
+> * Advanced Orbiting Systems (AOS)
+
+CryptoLib includes a standalone module that allows for generic coupling with Ground Systems that lack SDLS support.
+
+## Documentation
+
+* [Environment and Building](Environment_Building.md)
+
+* [Releases](Releases.md)
+
+* [Testing and Validation](Testing_Validation.md)
+
+## Usage
+
+* [Usage](Usage.md)
+
+## References
+### Bluebook References
+
+* [SDLS](https://public.ccsds.org/Pubs/355x0b1.pdf)
+
+* [SDLS-EP](https://public.ccsds.org/Pubs/355x1b1.pdf)
+
+* [CCSDS Cryptographic Algorithms](https://public.ccsds.org/Pubs/352x0b2.pdf)
+
+### Greenbook References
+
+* [The Application of Security to CCSDS Protocols](https://public.ccsds.org/Pubs/350x0g3.pdf)
+

docs/wiki/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/wiki/Releases.md

@@ -0,0 +1,29 @@
+# Releases
+
+* [v1.3.1](https://github.com/nasa/CryptoLib/releases/tag/v1.3.1)
+
+* [v1.3.0](https://github.com/nasa/CryptoLib/releases/tag/v1.3.0)
+
+* [v1.2.3](https://github.com/nasa/CryptoLib/releases/tag/v1.2.3)
+
+* [v1.2.2](https://github.com/nasa/CryptoLib/releases/tag/v1.2.2)
+
+* [v1.2.1](https://github.com/nasa/CryptoLib/releases/tag/v1.2.1)
+
+* [v1.2.0](https://github.com/nasa/CryptoLib/releases/tag/v1.2.0)
+
+* [v1.1.1](https://github.com/nasa/CryptoLib/releases/tag/v1.1.1)
+
+* [v1.0.3](https://github.com/nasa/CryptoLib/releases/tag/v1.0.3)
+
+* [v1.0.2](https://github.com/nasa/CryptoLib/releases/tag/v1.0.2)
+
+* [v1.0.1](https://github.com/nasa/CryptoLib/releases/tag/v1.0.1)
+
+* [v1.0.0](https://github.com/nasa/CryptoLib/releases/tag/v1.0.0)
+
+* [v0.1.0](https://github.com/nasa/CryptoLib/releases/tag/v0.1-engineering-release)
+
+
+
+