Support cryptography module

.github/workflows/rust.yml

@@ -14,6 +14,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  TONGSUO_VERSION: 8.4.0
 
 jobs:
   unix-default-test:
@@ -31,6 +32,34 @@ jobs:
     - name: Run tests
       run: cargo test --verbose
 
+  unix-tongsuo-test:
+    strategy:
+      matrix:
+        os:
+          - macos-latest
+          - ubuntu-latest
+    runs-on: ${{matrix.os}}
+
+    steps:
+    - name: Build Tongsuo
+      run: |
+        wget "https://github.com/Tongsuo-Project/Tongsuo/archive/refs/tags/${TONGSUO_VERSION}.tar.gz"
+        tar zxf "${TONGSUO_VERSION}.tar.gz"
+        pushd "Tongsuo-${TONGSUO_VERSION}"
+        ./config --prefix=${RUNNER_TEMP}/tongsuo --libdir=${RUNNER_TEMP}/tongsuo/lib
+        make -j4
+        make install
+        popd
+    - uses: actions/checkout@v3
+    - name: Build
+      run : |
+        OPENSSL_DIR=${RUNNER_TEMP}/tongsuo cargo build --verbose --features crypto_adaptor_tongsuo --no-default-features --config 'patch.crates-io.openssl.git="https://github.com/Tongsuo-Project/rust-tongsuo.git"' --config 'patch.crates-io.openssl-sys.git="https://github.com/Tongsuo-Project/rust-tongsuo.git"'
+    - name: Run tests
+      run : |
+        export LD_LIBRARY_PATH=${RUNNER_TEMP}/tongsuo/lib
+        OPENSSL_DIR=${RUNNER_TEMP}/tongsuo cargo test --verbose --features crypto_adaptor_tongsuo --no-default-features --config 'patch.crates-io.openssl.git="https://github.com/Tongsuo-Project/rust-tongsuo.git"' --config 'patch.crates-io.openssl-sys.git="https://github.com/Tongsuo-Project/rust-tongsuo.git"'
+
+
   unix-mysql-test:
     strategy:
       matrix:
@@ -101,6 +130,8 @@ jobs:
         Start-Process msiexec.exe -ArgumentList '/i', 'mysql-connector.msi', '/quiet', '/norestart' -NoNewWindow -Wait
     - name: Set MySQLCLIENT_LIB_DIR
       run: echo "MYSQLCLIENT_LIB_DIR=C:\Program Files\MySQL\MySQL Connector C 6.1\lib\vs14" | Out-File -FilePath $env:GITHUB_ENV -Append
+    - name: Set MYSQLCLIENT_VERSION
+      run: echo "MYSQLCLIENT_VERSION=8.4.0" | Out-File -FilePath $env:GITHUB_ENV -Append
     - uses: shogo82148/actions-setup-mysql@v1
       with:
         mysql-version: "5.7"

Cargo.toml

@@ -25,8 +25,6 @@ serde_json = "^1.0"
 serde_bytes = "0.11"
 go-defer = "^0.1"
 rand = "^0.8"
-openssl = { version = "0.10" }
-openssl-sys = { version = "0.9" }
 derivative = "2.2.0"
 enum-map = "2.6.1"
 strum = { version = "0.25", features = ["derive"] }
@@ -61,12 +59,20 @@ serde_asn1_der = "0.8"
 base64 = "0.22"
 ipnetwork = "0.20"
 
-[patch.crates-io]
-openssl = { git = "https://github.com/Tongsuo-Project/rust-tongsuo.git" }
-openssl-sys = { git = "https://github.com/Tongsuo-Project/rust-tongsuo.git" }
+# optional dependencies
+openssl = { version = "0.10", optional = true }
+openssl-sys = { version = "0.9", optional = true }
+
+# uncomment the following lines to use Tongsuo as underlying crypto adaptor
+#[patch.crates-io]
+#openssl = { git = "https://github.com/Tongsuo-Project/rust-tongsuo.git" }
+#openssl-sys = { git = "https://github.com/Tongsuo-Project/rust-tongsuo.git" }
 
 [features]
+default = ["crypto_adaptor_openssl"]
 storage_mysql = ["diesel", "r2d2", "r2d2-diesel"]
+crypto_adaptor_openssl = ["dep:openssl", "dep:openssl-sys"]
+crypto_adaptor_tongsuo = ["dep:openssl", "dep:openssl-sys"]
 
 [target.'cfg(unix)'.dependencies]
 daemonize = "0.5"

build.rs

@@ -1,7 +1,52 @@
 use std::env;
 
+// This is not going to happen any more since we have a default feature definition in Cargo.toml
+//#[cfg(not(any(feature = "crypto_adaptor_openssl", feature = "crypto_adaptor_tongsuo")))]
+//compile_error! {
+//    r#"
+//    No cryptography adaptor is enabled!
+//
+//    In RustyVault, the real cryptographic operations are done via "crypto_adaptor"s.
+//
+//    A crypto adaptor is a module that conveys and translates high level cryptography
+//    operations like encryption, signing into the APIs provided by underlying cryptography
+//    libraries such as OpenSSL, Tongsuo and so forth.
+//
+//    At current stage, only one crypto_adaptor can be enabled at compilation phase and later
+//    be used at run-time. "crypto_adaptor"s are configured as 'feature's in the Cargo context.
+//
+//    Currently, the supported feature names of crypto adaptors are as follows, you can enable
+//    them by adding one '--features crypto_adaptor_name' option when running "cargo build":
+//        1. the OpenSSL adaptor: crypto_adaptor_openssl
+//        2. the Tongsuo adaptor: crypto_adaptor_tongsuo
+//    "#
+//}
+
+#[cfg(all(feature = "crypto_adaptor_openssl", feature = "crypto_adaptor_tongsuo"))]
+compile_error! {
+    r#"
+    Only one cryptography adapator can be enabled!
+
+    In RustyVault, the real cryptographic operations are done via "crypto_adaptor"s.
+
+    A crypto adaptor is a module that conveys and translates high level cryptography
+    operations like encryption, signing into the APIs provided by underlying cryptography
+    libraries such as OpenSSL, Tongsuo and so forth.
+
+    At current stage, only one crypto_adaptor can be enabled at compilation phase and later
+    be used at run-time. "crypto_adaptor"s are configured as 'feature's in the Cargo context.
+
+    Currently, the supported feature names of crypto adaptors are as follows, you can enable
+    them by adding one '--features crypto_adaptor_name' option when running "cargo build":
+        1. the OpenSSL adaptor: crypto_adaptor_openssl
+        2. the Tongsuo adaptor: crypto_adaptor_tongsuo
+    "#
+}
+
 fn main() {
     if let Ok(_) = env::var("DEP_OPENSSL_TONGSUO") {
         println!("cargo:rustc-cfg=tongsuo");
+    } else if cfg!(feature = "crypto_adaptor_tongsuo") {
+        println!("cargo:rustc-cfg=tongsuo");
     }
 }

doc/crypto.md

@@ -0,0 +1,68 @@
+# RustyVault Crypto Adaptor
+
+In RustyVault, we provide a mechanism for the users to build with selectable underlying cryptography libraries. This is the "crypto adaptor" mechanism.
+
+Currently, only two adaptors are supported:
+
+* OpenSSL crypto adaptor
+* Tongsuo crypto adaptor
+
+## The OpenSSL Crypto Adaptor
+
+The following steps require a properly installed OpenSSL library. There are many ways of installing an OpenSSL on various platforms, so in this docuemnt we don't discuss that part.
+
+The OpenSSL crypto adaptor is configured by default in RustyVault, so you can simply build RustyVault to enable it:
+
+~~~
+cargo build
+~~~
+
+Otherwise if you want to explicitly configure it, you can still use something like:
+
+~~~
+cargo build --features crypto_adaptor_openssl
+~~~
+
+But this is not necessary.
+
+## The Tongsuo Crypto Adaptor
+
+Tongsuo is a fork of OpenSSL aiming to have a better support on Chinese cryptography algorithms and standards. To use Tongsuo as the cryptography functionality provider in RustyVault, typically you need to build RustyVault as follows.
+
+### Download and Install Tongsuo
+
+Firstly, you need to have a copy of Tongsuo code and successfully build it into libraires and finally install it into somewhere in your machine.
+
+Go to [https://tongsuo.net/docs/compilation/compile-and-install](https://tongsuo.net/docs/compilation/compile-and-install) for more detailed information.
+
+### Configure RustyVault to use Tongsuo
+
+RustyVault uses rust-tongsuo crate to call C APIs provided by Tongsuo. So we need to configure Cargo to use it, let's assume Tongsuo is successfully installed to `/path/to/tongsuo` directory: 
+
+~~~
+OPENSSL_DIR=/path/to/tongsuo cargo build \
+  --features crypto_adaptor_tongsuo \
+  --no-default-features \
+  --config 'patch.crates-io.openssl.git="https://github.com/Tongsuo-Project/rust-tongsuo.git"' \
+  --config 'patch.crates-io.openssl-sys.git="https://github.com/Tongsuo-Project/rust-tongsuo.git"'
+~~~
+
+Furthermore, if you choose to use a local copy of rust-tongsuo crate, you can use the file path form as well. Assume the local rust-tongsuo crate is located in `/path/to/rust-tongsuo` directory:
+
+~~~
+OPENSSL_DIR=/path/to/tongsuo cargo build \
+  --features crypto_adaptor_tongsuo \
+  --no-default-features \
+  --config 'patch.crates-io.openssl.path="/path/to/rust-tongsuo/openssl"' \
+  --config 'patch.crates-io.openssl-sys.path="/path/to/rust-tongsuo/openssl-sys"'
+~~~
+
+### The `LD_LIBRARY_PATH` Variable
+
+If you are using Linux, then you may need to specify which path for RustyVault to look for the Tongsuo libraries. There are many ways of having this done, but in this document we demonstrate with the global environment variable way.
+
+~~~
+export LD_LIBRARY_PATH=/path/to/tongsuol/lib
+~~~
+
+Then you can run RustyVault smoothly.

netlify.toml

@@ -0,0 +1,4 @@
+[build]
+  base = "docs"
+  publish = "build"
+  ignore = "git diff --quiet $COMMIT_REF $CACHED_COMMIT_REF -- ../docs/ .  ../netlify.toml"

src/errors.rs

@@ -12,6 +12,20 @@ use thiserror::Error;
 
 #[derive(Error, Debug)]
 pub enum RvError {
+    #[error("Cipher operation update failed.")]
+    ErrCryptoCipherUpdateFailed,
+    #[error("Cipher operation finalization failed.")]
+    ErrCryptoCipherFinalizeFailed,
+    #[error("Cipher initialization failed.")]
+    ErrCryptoCipherInitFailed,
+    #[error("Cipher not initialized.")]
+    ErrCryptoCipherNotInited,
+    #[error("Cipher operation not supported.")]
+    ErrCryptoCipherOPNotSupported,
+    #[error("AEAD Cipher tag is missing.")]
+    ErrCryptoCipherNoTag,
+    #[error("AEAD Cipher tag should not be present.")]
+    ErrCryptoCipherAEADTagPresent,
     #[error("Config path is invalid.")]
     ErrConfigPathInvalid,
     #[error("Config load failed.")]
@@ -274,7 +288,14 @@ pub enum RvError {
 impl PartialEq for RvError {
     fn eq(&self, other: &Self) -> bool {
         match (self, other) {
-            (RvError::ErrCoreLogicalBackendExist, RvError::ErrCoreLogicalBackendExist)
+            (RvError::ErrCryptoCipherUpdateFailed, RvError::ErrCryptoCipherUpdateFailed)
+            | (RvError::ErrCryptoCipherFinalizeFailed, RvError::ErrCryptoCipherFinalizeFailed)
+            | (RvError::ErrCryptoCipherInitFailed, RvError::ErrCryptoCipherInitFailed)
+            | (RvError::ErrCryptoCipherNotInited, RvError::ErrCryptoCipherNotInited)
+            | (RvError::ErrCryptoCipherOPNotSupported, RvError::ErrCryptoCipherOPNotSupported)
+            | (RvError::ErrCryptoCipherNoTag, RvError::ErrCryptoCipherNoTag)
+            | (RvError::ErrCryptoCipherAEADTagPresent, RvError::ErrCryptoCipherAEADTagPresent)
+            | (RvError::ErrCoreLogicalBackendExist, RvError::ErrCoreLogicalBackendExist)
             | (RvError::ErrCoreNotInit, RvError::ErrCoreNotInit)
             | (RvError::ErrCoreLogicalBackendNoExist, RvError::ErrCoreLogicalBackendNoExist)
             | (RvError::ErrCoreSealConfigInvalid, RvError::ErrCoreSealConfigInvalid)