avarok-cybersecurity/citadel-protocol

Post-quantum endpoint-to-endpoint encryption for messaging and file-sharing SDK

A post-quantum signal-like protocol that makes developing hyper-secure client-to-server and p2p applications easy

Whitepaper

The whitepaper for the Citadel Protocol can be found in the repository here. Note: this whitepaper has not been updated since July 2022. While the protocol is very similar to what is covered in the whitepaper, it has since evolved. The whitepaper will be synced to the source code in the near future.

Documentation

For examples on building applications, please check the docs

Build instructions

OpenSSL and Clang are required in order to compile the libraries. View the CI files in .github for an example of getting the code to compile on a bare machine. Alternatively, you can run the following command to setup the environment

cargo make install

Testing instructions

When running unit tests inside citadel_sdk, you must use the Makefile. The Makefile contains special flags and environmental variables set to interface with cargo test. First, install cargo make:

cargo install --force cargo-make

To run tests locally with limited setup, run:

cargo make test-local

To run a comprehensive set of tests that require a SQL and/or redis server set up (please check the description in Makefile.toml for help setting up the environment variables), run:

cargo make test

WASM (dev only WIP)

The target triple wasm32-wasi is a WIP for support. These commands should be executed in order to compile to wasm

# Allows execution of `cargo wasi test --package citadel_pqcrypto`
cargo install cargo-wasi
# install wasmtime
curl https://wasmtime.dev/install.sh -sSf | bash
# get the include/build files
wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sysroot-12.0.tar.gz
tar -xvzf wasi-sysroot-12.0.tar.gz
rm wasi-sysroot-12.0.tar.gz
# Set environment variables
export WASI_SDK_DIR="$(pwd)/wasi-sysroot"
export WASMTIME_HOME="$(pwd)/.wasmtime"
export PATH="$WASMTIME_HOME/bin:$PATH"
export RUSTFLAGS="--cfg tokio_unstable"
# If on Mac M1, make sure to use the clang/ar provided by homebrew. Make sure to replace <LATEST_VERSION>
export PATH="/opt/homebrew/Cellar/llvm/<LATEST_VERSION>/bin/:$PATH"
export AR="/opt/homebrew/Cellar/llvm/<LATEST_VERSION>/bin/llvm-ar"
export CC="/opt/homebrew/Cellar/llvm/<LATEST_VERSION>/bin/clang"

Additionally, the feature wasm should be enabled when checking/compiling.

Disclaimer

This project has not (yet) been audited by a third party. While some of the underlying cryptographic primitives come from the verified Open Quantum Safe (OQS) project and/or the PQClean project, the Kyber library has not yet received an audit (the known answer tests pass, however).

As such, we recommend that, if you choose to use this library and accept the risks associated with its use, you use hybrid cryptography by using either TLS or QUIC as an underlying protocol to ensure that the protocol is at least as secure as elliptical curve cryptography.

Authors

Thomas Braun - Founder

Contributing

Contributions are welcome! I have been the only developer for the past 5 years, and, need more people to help make the ecosystem flourish.

citadel-protocol's Issues

Create more holistic integration testing in virtualized networks

As of now, our integration testing consists of booting up nodes within the same program and connecting to the corresponding localhost ports.

This approach does not mock real scenarios where there is sporadic network latency. One possible approach is to create a docker-compose file that sets up a virtual network (1 central node, n possible clients/peers) with simulated latency (e.g., 100ms). This approach will be good for basic integration testing, but, will not be good for testing NAT traversal. Thus, on top of this docker-compose setup, we will need a set up for testing NAT traversal.

Testing NAT-traversal will be more challenging. The current unit tests inside citadel_wire simulate the expected internal/external mappings for different NAT types, so in theory, when UDP hole punching begins, these predicted external endpoints should be reached. However, like before, we are making this assumption without bringing the network conditions into context. Any ideas?

Fast connections

When UDP NAT traversal is implicated in the connection process, the entire connection is blocked, even if messages could pass through via the active c2s connection or the relayed p2p connection. The protocol should allow instant relaying of messages once both peers decide to begin connecting to each other. Once NAT traversal completes, the protocol should automatically begin using the direct p2p connection over the relayed connection, only using the relay as a back up.

Add Ascon to symmetric cipher suite

https://docs.rs/ascon-aead/latest/ascon_aead/

The NIST has selected ASCON for a lightweight symmetric cipher scheme.

How quantum resistant is it? Follow the tracking issue here: https://groups.google.com/a/list.nist.gov/g/pqc-forum/c/KNYmXSqZ5M4

Allow optional custom STUN servers

Allow each node to choose which STUN servers to communicate with when attempting to find their NAT type. 3 must be specified. This setting should be present inside the NodeBuilder struct in citadel_sdk, and, should propagate all the way to the library citadel_wire where the STUN servers are used. This will require editing many function signatures, but, will be a great first issue to solve as it will walk one through the execution flow of the program.

File Transfer with InMemory Backend Silently Fails

File Transfer should not work with InMemory Backend, but an Object Transfer request can still be started and responded to. Upon accepting, the streaming of the object to the backend of the receiver is silently blocked, but a ReceptionComplete Status is still sent. The MemoryBackend implementation of stream_object_to_backend quietly consumes the stream but still returns a success result.

Credentialed Auth: Allow customizable password requirements

Extend methods used to protect data-in-transit for protecting data-at-rest

The for-profit company American Binary recently announced the release of data-at-rest protection using Kyber encryption (as opposed to common symmetric ciphers like AES/CHA-CHA). Considering The Citadel Protocol already offers Kyber encryption combined with OTP for protecting data-in-transit, using the same methods for data-at-rest should be a no-brainer. People should not pay for basic software, it should be free and open source.

Project HTTPQ:// :: Integrating The Citadel Protocol with the web browser

Both client and server NetKernel implementations will need consumers of the forwarded data for rendering and processing.

[client-side] We can use TCP/TLS for establishing a connection w/handshake via: https://docs.rs/hyper/latest/hyper/client/conn/index.html.

[server-side] We can use TCP/TLS listeners for starting a server: https://docs.rs/hyper/latest/hyper/server/conn/index.html

TODO: more speccing required

VPN support

VPN support should be added such that TUN/TAP adapts to a custom implementation of NetKernel, i.e., VPNNetKernel (VPNK). The VPNK needs to adapt to the TUN/TAP interface. The VPN "server" will be equivalent to the "globally reachable central server" already present within the Citadel Network's central server.

Client perspective (outgoing packets):
client packets -> Client VPNK -> forward to central server's VPNK over The Citadel Protocol -> forward to local tun/tap interface -> WAN

Server perspective (incoming packets):
WAN -> local tun/tap interface -> Server VPNK -> transmit packets over The Citadel Protocol to Client -> Client VPNK -> client receives packets

This would be a great first project for somebody interested in learning how to build ontop of the Citadel Protocol, and, is also interested in VPN technologies. I will be able to help extensively with this effort as needed.