From 8075c51547de8d5576d03a27854b92118676343f Mon Sep 17 00:00:00 2001 From: quasar Date: Mon, 12 Oct 2026 20:43:55 +0000 Subject: [PATCH 1/3] Add the landing page and update the build documentation (#13) --- README.md | 79 ++++++++++++++++- docs/USAGE.md | 11 ++- pages/index.html | 223 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 306 insertions(+), 7 deletions(-) create mode 100644 pages/index.html diff --git a/README.md b/README.md index 29f90f1..0886a63 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,41 @@ This library contains interfaces for the signing and encryption data. ``` * rebuild your project +### qmake + + * cd yourRepo + * git submodule add https://github.com/QuasarApp/easyssl.git # add the repository of EasySSL into your repo like submodule + * git submodule update --init --recursive + * Include in your `.pro` file the EasySSL sources directly: + + ```qmake + # myapp.pro + + QT += core network + + INCLUDEPATH += $$PWD/../easyssl/src/lib/src/public + + SOURCES += \ + ../easyssl/src/lib/src/public/easyssl.cpp \ + ../easyssl/src/lib/src/public/easyssl/icrypto.cpp \ + ../easyssl/src/lib/src/public/easyssl/ecdsassl.cpp \ + ../easyssl/src/lib/src/public/easyssl/rsassl.cpp \ + ../easyssl/src/lib/src/public/easyssl/x509.cpp \ + ../easyssl/src/lib/src/public/easyssl/icertificate.cpp \ + ../easyssl/src/lib/src/private/easysslutils.cpp + + DEFINES += EASYSSL_LIBRARY + + # Link the OpenSSL 3.0+ libraryes: + LIBS += -lcrypto -lssl + ``` + + * rebuild your project + + > **Note:** the CMake build is the recommended way. The EasySSL library has the + > `EASYSSL_STATIC_SSL` and `BUILD_WITH_OPENSSL` build options that are only + > available for the CMake build. + ### Independent of SSL build Dependency on the ssl library greatly complicates the deployment of the final product. For fix this issue, you can build EasySSL library with static SSL library. In this case, SSL library code will be saved in your EasySSL binary, and deploy of your application will be easily. The ssl code will not available for your application or other libraries, so you will not get conflicts between different major versions ssl libraries if your distribution kit has it. @@ -42,6 +77,39 @@ cmake .. -DEASYSSL_STATIC_SSL=1 The described case may be useful for the Qt 5.15.x, because the QNetwork 5.15 depends on the SSL v1.1 and EasySSL works with the SSL >= 3.0. +### Build without the system OpenSSL (BUILD_WITH_OPENSSL) + + If your system (or the target device) has no OpenSSL 3.0+ library, you can + build the OpenSSL library together with the EasySSL library. Just set the + **BUILD_WITH_OPENSSL** option to true: + + ``` bash + cmake .. -DBUILD_WITH_OPENSSL=1 + ``` + + In this case the EasySSL project clones the OpenSSL `openssl-3.0.9` sources, + builds the static OpenSSL libraries and links them privately into the EasySSL + binary. So your application has no runtime dependency on the system OpenSSL. + + * Supported platforms: Linux, Windows (MinGW), Android, iOS and macOS (arm/x86). + * The WASM platform is **not** supported. + * On Windows the build requires the MinGW (GNU) compiler and the + `mingw32-make` tool. The OpenSSL Configure script also requires a perl + that produces Unix-like paths and that provides the perl core modules + (for example the MSYS2 perl; set the `MSYS2_ROOT` environment variable + to the MSYS2 installation directory if it is not found automatically). + * The OpenSSL version can be changed with the `EASYSSL_OPENSSL_TAG` option + (default `openssl-3.0.9`). + +### Unit tests + + The unit tests of the EasySSL library are built and run by default. To + disable the tests, set the **EASYSSL_TESTS** option to false: + + ``` bash + cmake .. -DEASYSSL_TESTS=0 + ``` + ## Usage ### Encryption @@ -113,12 +181,15 @@ edsa.auth(1000, &userID); ## Documentation -* [Usage and working examples](docs/USAGE.md) — build with CMake and qmake, - RSA/ECDSA examples, X509 certificates, async authentication. -* [Migration from the Qt-Secret library](docs/MIGRATION_FROM_QT_SECRET.md) — +* [EasySSL on the web](https://quasarapp.github.io/easyssl/) — the GitHub + Pages site of this repository: the landing page and the full API reference + generated automatically with Doxygen. +* [Usage and working examples](https://github.com/QuasarApp/easyssl/blob/main/docs/USAGE.md) — + build with CMake and qmake, RSA/ECDSA examples, X509 certificates, async authentication. +* [Migration from the Qt-Secret library](https://github.com/QuasarApp/easyssl/blob/main/docs/MIGRATION_FROM_QT_SECRET.md) — API mapping, before/after code examples, key and signature format changes. ## Do not forget to help us make this library better... See our main documentation about contributing to [EasySSL](https://github.com/QuasarApp/easyssl/blob/main/CONTRIBUTING.md) -Full documentation available [here](https://quasarapp.ddns.net:3031/docs/QuasarApp/easyssl/latest/index.html) +Full documentation and the API reference available on the [EasySSL GitHub Pages](https://quasarapp.github.io/easyssl/) site. diff --git a/docs/USAGE.md b/docs/USAGE.md index 28e0d80..0c9a3e4 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -89,8 +89,13 @@ binary. The built OpenSSL libraries are saved in the build directory on the system OpenSSL libraries and you will not get conflicts between different major versions of the SSL libraries. -* Supported platforms: Linux, Android, iOS and macOS (arm/x86). -* The Windows and WASM platforms are **not** supported. +* Supported platforms: Linux, Windows (MinGW), Android, iOS and macOS (arm/x86). +* The WASM platform is **not** supported. +* On Windows the build requires the MinGW (GNU) compiler and the + `mingw32-make` tool. The OpenSSL Configure script also requires a perl + that produces Unix-like paths and that provides the perl core modules + (for example the MSYS2 perl; set the `MSYS2_ROOT` environment variable + to the MSYS2 installation directory if it is not found automatically). * The OpenSSL version can be changed with the `EASYSSL_OPENSSL_TAG` option (default `openssl-3.0.9`). @@ -351,7 +356,7 @@ int main() { ## More information -* Full doxygen documentation: [here](https://quasarapp.ddns.net:3031/docs/QuasarApp/easyssl/latest/index.html) +* Full doxygen documentation: [here](https://quasarapp.github.io/easyssl/doc/) * Migration from the Qt-Secret library: [MIGRATION_FROM_QT_SECRET.md](MIGRATION_FROM_QT_SECRET.md) * Contributing: [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/pages/index.html b/pages/index.html new file mode 100644 index 0000000..af0d9bb --- /dev/null +++ b/pages/index.html @@ -0,0 +1,223 @@ + + + + + + +EasySSL - Simple OpenSSL wrapper for C++ Qt projects + + + + +
+ EasySSL + +
+ +
+

EasySSL - Simple OpenSSL wrapper for C++ Qt projects

+

+ EasySSL is a Qt wrapper of the OpenSSL 3.0+ library that makes working with + the asymmetric cryptography simple: RSA and ECDSA encryption and signing, + key generation, self-signed X509 certificates and asynchronous + authentication. +

+
+ Read the Documentation + Get it on GitHub +
+
+ +
+
+

API Reference

+

Complete reference of the EasySSL classes (RSASSL, ECDSASSL, + X509, AuthECDSA, ...), generated automatically with Doxygen.

+ Open API Reference → +
+
+

Features

+
    +
  • RSA: encryption, decryption and signing
    • +
  • ECDSA: signing and checking the sign
    • +
  • Self-signed X509 certificates
    • +
  • Async authentication based on the asymmetric keys
    • +
  • Works with Qt 5 and Qt 6, CMake and qmake
    • +
+
+
+

Build Options

+
    +
  • EASYSSL_STATIC_SSL - link the static OpenSSL libraries into the EasySSL binary
    • +
  • BUILD_WITH_OPENSSL - build the OpenSSL 3.0+ library together with EasySSL (no system OpenSSL needed)
    • +
  • EASYSSL_TESTS - enable or disable the unit tests
    • +
+
+
+

Repository

+ +
+
+ + +
+

Quick example

+

Create the RSA keys, encrypt and decrypt the data and check the signature:

+ 
#include <easyssl/rsassl.h>
+#include <QByteArray>
+
+int main() {
+    // create a public and private keys array.
+    EasySSL::RSASSL crypto;
+    QByteArray pub, priv;
+    crypto.makeKeys(pub, priv);
+
+    QByteArray message = "Hello EasySSL!";
+
+    auto signature = crypto.signMessage(message, priv);
+    crypto.checkSign(message, signature, pub);
+
+    auto encryptedMsg = crypto.encrypt(message, pub);
+    auto decryptedMsg = crypto.decrypt(encryptedMsg, priv);
+}
+
+ +
+

Build with CMake

+

Add the repository as a submodule and include it in your CMakeLists.txt. + To build without the system OpenSSL library, set the BUILD_WITH_OPENSSL option:

+ 
# add the repository of EasySSL into your repo like submodule
+git submodule add https://github.com/QuasarApp/easyssl.git
+git submodule update --init --recursive
+
+# CMakeLists.txt
+add_subdirectory(easyssl)
+target_link_libraries(yourLib PUBLIC easyssl)
+
+# build without the system OpenSSL 3.0+ library
+cmake .. -DBUILD_WITH_OPENSSL=1
+
+ + + + + + From a1893d8da1d02a868eeb7062eed76caa61f51bdc Mon Sep 17 00:00:00 2001 From: quasar Date: Mon, 12 Oct 2026 20:43:55 +0000 Subject: [PATCH 2/3] Add the GitHub Pages docs deploy workflow (#13) --- .github/workflows/deploy-docs.yml | 56 +++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 .github/workflows/deploy-docs.yml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..954e17e --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,56 @@ +name: Deploy Documentation (GitHub Pages) + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: write + +jobs: + build-and-deploy: + name: Build Doxygen and deploy to GitHub Pages + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + # The full history is required to compute the + # 0.. project version. + fetch-depth: 0 + # The CMake submodule provides the Doxygen style sheet + # (submodules/CMake/DoxyStyle/doxygenStyles.css). + submodules: recursive + + - name: Install Doxygen and Graphviz + uses: doxygen/setup-doxygen@v2 + + - name: Generate the Doxygen configuration file + run: | + PROJECT_VERSION="0.$(git rev-list --count HEAD).$(git rev-parse --short HEAD)" + sed -e "s|@PROJECT_NAME@|easyssl|" \ + -e "s|@EASYSSL_VERSION@|${PROJECT_VERSION}|" \ + doxygen.conf.in > doxygen.conf + grep -E '^(PROJECT_NAME|PROJECT_NUMBER)' doxygen.conf + + - name: Generate Doxygen HTML documentation + run: doxygen doxygen.conf + + - name: Stage the website + run: | + mkdir -p stage/doc + cp pages/index.html stage/index.html + cp -r docs/. stage/doc/ + # Remove the raw markdown documents from the staged docs folder: + # they are not part of the generated documentation. + rm -f stage/doc/USAGE.md stage/doc/MIGRATION_FROM_QT_SECRET.md + ls -la stage stage/doc | head -30 + + - name: Deploy to GitHub Pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + branch: gh-pages + folder: stage + clean: true From c46b242d144ef05f130c5ec509df6b901e1dd7eb Mon Sep 17 00:00:00 2001 From: quasar Date: Mon, 12 Oct 2026 20:58:47 +0000 Subject: [PATCH 3/3] Fix the typo in the qmake build example (libraryes -> libraries) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0886a63..9922160 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ This library contains interfaces for the signing and encryption data. DEFINES += EASYSSL_LIBRARY - # Link the OpenSSL 3.0+ libraryes: + # Link the OpenSSL 3.0+ libraries: LIBS += -lcrypto -lssl ```