Merge branch 'main' into approle

.github/workflows/rust.yml

@@ -3,11 +3,18 @@ name: Rust
 on:
   push:
     branches: [ "main" ]
+    paths-ignore:
+      - "docs/**/*"
+      - ".github/workflows/website.yml"
   pull_request:
     branches: [ "main" ]
+    paths-ignore:
+      - "docs/**/*"
+      - ".github/workflows/website.yml"
 
 env:
   CARGO_TERM_COLOR: always
+  TONGSUO_VERSION: 8.4.0
 
 jobs:
   unix-default-test:
@@ -27,6 +34,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:

.github/workflows/website.yml

@@ -0,0 +1,31 @@
+name: Test deployment
+
+on:
+    pull_request:
+      paths:
+        - ".github/workflows/website.yml"
+        - "docs/**/*"
+    push:
+      branches: [main]
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./docs
+
+jobs:
+    test-deploy:
+        name: Test deployment
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - uses: actions/setup-node@v4
+              with:
+                node-version: 18
+
+            - name: Install dependencies
+              run: yarn install --frozen-lockfile
+            - name: Test build website
+              run: yarn build

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"] }
@@ -65,12 +63,20 @@ derive_more = "0.99.17"
 dashmap = "5.5"
 tokio = "1.38"
 
-[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.

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/NOTES.md

@@ -0,0 +1 @@
+cp -r docs/* versioned_docs/version-0.12.x/

docs/README.md

@@ -0,0 +1,33 @@
+# SeaORM Documentation
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/install.md

@@ -0,0 +1,78 @@
+---
+sidebar_position: 2
+title: Install
+---
+
+# Install RustyVault
+
+RustyVault must be installed properly in your environment before it actually works. Currently RustyVault is only available by source code. RustyVault can be used as an application or a library, thus:
+
+1. RustyVault is available to compile from source code only, or
+2. RustyVault is availabe on [crates.io](https://crates.io/crates/rusty_vault) for other Rust projects.
+
+This document is about how to build and install RustyVault in the application form. For the library form, please go to [docs.rs](https://docs.rs/rusty_vault/latest/rusty_vault) for more information.
+
+## Operating System
+
+RustyVault is supposed to work on the following operating systems:
+
+* Linux
+* macOS
+* Windows (experimental)
+
+In this document, macOS is used as the demonstration operating system.
+
+## Prerequisite
+
+RustyVault is developed in [Rust](https://rust-lang.org) programming language, so Rust must be properly installed in your environment before building RustyVault.
+
+Read [this](https://www.rust-lang.org/tools/install) to make Rust work for you.
+
+## Build from Source
+
+Clone the latest RustyVault source code from Github:
+
+~~~bash
+git clone https://github.com/Tongsuo-Project/RustyVault.git
+~~~
+
+Then you have a directory called RustyVault now. Change directory into it.
+
+~~~bash
+cd RustyVault
+~~~
+
+Simply build the binary by using the tool Cargo.
+
+~~~bash
+cargo build
+~~~
+
+Rust toolchain is responsible for taking care of almost everything during the build process. After RustyVault is successfully built, you get a bundle of files in the `RustyVault/target/debug` directory. There will be a executable file called `rvault`, which is the application of RustyVault.
+
+## Verify RustyVault
+
+Simply run the following command:
+
+~~~bash
+target/debug/rvault --help
+~~~
+
+And you will get a response similar to:
+
+~~~bash
+A secure and high performance secret management software that is compatible with Hashicorp Vault.
+
+Usage: rvault [COMMAND]
+
+Commands:
+  server  Start a rusty_vault server
+  status  Print seal and HA status
+  help    Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+~~~
+
+That means you now have a ready-to-use RustyVault binary.