From fbc9f774ed8934fa06edd940dba172e8dab307e1 Mon Sep 17 00:00:00 2001 From: PinkP4nther <0x0090@protonmail.com> Date: Wed, 6 Oct 2021 19:18:51 -0700 Subject: [PATCH] Added documentation for crate --- Cargo.toml | 16 ++++++--- README.md | 2 ++ src/lib.rs | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++- src/relay.rs | 14 ++++---- 4 files changed, 114 insertions(+), 12 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index cbde7d8..886805a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,9 +1,15 @@ [package] name = "sslrelay" -version = "0.4.1" -authors = ["PinkP4nther "] +version = "0.4.2" +authors = ["PinkP4nther @Pink_P4nther"] edition = "2018" +description = "" +repository = "https://github.com/PinkP4nther/SSLRelay-lib" +keywords = ["tcp", "networking", "relay", "tls", "ssl"] +categories = ["reverse-engineering", "network-relay", "tcp"] -[dependencies] -openssl = "0.10.36" -toml = "0.5.8" \ No newline at end of file +[dependencies.openssl] +version = "0.10.36" + +[dependencies.toml] +version = "0.5.8" \ No newline at end of file diff --git a/README.md b/README.md index a8e287b..dd20c27 100644 --- a/README.md +++ b/README.md @@ -20,4 +20,6 @@ Then use this library to continuously rewrite or display decrypted network traff 09/28/2021 | v0.4.1 | Code restructured and organized. +10/06/2021 | v0.4.2 | Added documentation. + More updates/ideas to come.. I think.. \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index 1f0bb18..3231fec 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,86 @@ +#![warn(missing_docs)] + +//! ## SSLRelay + +//! Library for relaying TCP traffic as well as TLS encrypted TCP traffic. +//! This Library allows you to implement callback functions for upstream and downstream traffic. +//! These callbacks can R/W the data from a stream(Blocking) or only R the data(Non-Blocking). +//!``` +//!pub trait HandlerCallbacks { +//! fn ds_b_callback(&self, _in_data: Vec) -> CallbackRet {CallbackRet::Relay(_in_data)} +//! fn ds_nb_callback(&self, _in_data: Vec){} +//! fn us_b_callback(&self, _in_data: Vec) -> CallbackRet {CallbackRet::Relay(_in_data)} +//! fn us_nb_callback(&self, _in_data: Vec){} +//!} +//!``` +//! The blocking callbacks return an enum called CallbackRet with four different variants. +//! The variants control the flow of the tcp stream. +//!``` +//! pub enum CallbackRet { +//! Relay(Vec),// Relay data +//! Spoof(Vec),// Skip relaying and send data back +//! Shutdown,// Shutdown TCP connection +//! Freeze,// Dont send data (pretend as if stream never was recieved) +//! } +//! ``` +//! ## Example (basic.rs) +//! ``` +//! use sslrelay::{self, ConfigType, RelayConfig, HandlerCallbacks, CallbackRet, TCPDataType}; +//! +//! // Handler object +//! #[derive(Clone)] // Must have Clone trait implemented. +//! struct Handler; +//! +//! /* +//! Callback traits that can be used to read or inject data +//! into data upstream or downstream. +//! */ +//! impl HandlerCallbacks for Handler { +//! +//! // DownStream non blocking callback (Read Only) +//! fn ds_nb_callback(&self, _in_data: Vec) { +//! println!("[CALLBACK] Down Stream Non Blocking CallBack!"); +//! } +//! +//! // DownStream blocking callback (Read & Write) +//! fn ds_b_callback(&self, _in_data: Vec) -> CallbackRet { +//! println!("[CALLBACK] Down Stream Blocking CallBack!"); +//! CallbackRet::Relay(_in_data) +//! } +//! +//! // UpStream non blocking callback (Read Only) +//! fn us_nb_callback(&self, _in_data: Vec) { +//! println!("[CALLBACK] Up Stream Non Blocking CallBack!"); +//! } +//! +//! // UpStream blocking callback (Read & Write) +//! fn us_b_callback(&self, _in_data: Vec) -> CallbackRet { +//! println!("[CALLBACK] Up Stream Blocking CallBack!"); +//! CallbackRet::Relay(_in_data) +//! } +//! } +//! +//! fn main() { +//! +//! // Create new SSLRelay object +//! let mut relay = sslrelay::SSLRelay::new( +//! Handler, +//! ConfigType::Conf(RelayConfig { +//! downstream_data_type: TCPDataType::TLS, +//! upstream_data_type: TCPDataType::TLS, +//! bind_host: "0.0.0.0".to_string(), +//! bind_port: "443".to_string(), +//! remote_host: "remote.com".to_string(), +//! remote_port: "443".to_string(), +//! ssl_private_key_path: "./remote.com.key".to_string(), +//! ssl_cert_path: "./remote.com.crt".to_string(), +//! }) +//! ); +//! // Start listening +//! relay.start(); +//! } +//! ``` + use openssl::ssl::{ SslVerifyMode, SslConnector, @@ -67,12 +150,18 @@ enum DataStreamType { TLS(SslStream), } +/// Specifies the upstream or downstream data type (TLS or RAW). #[derive(Copy, Clone)] pub enum TCPDataType { TLS, RAW, } +/// The relay configuration type. +/// Env: Uses the SSLRELAY_CONFIG environmental variable for the path to the config file. +/// Path: Specifies the path to the config file. +/// Conf: For passing an instance of the object instead of using a config file. +/// Default: Uses ./relay_config.toml config file. pub enum ConfigType { Env, Path(T), @@ -80,6 +169,7 @@ pub enum ConfigType { Default, } +/// Relay Config structure for passing into the SSLRelay::new() config parameter. #[derive(Clone)] pub struct RelayConfig { pub downstream_data_type: TCPDataType, @@ -92,6 +182,7 @@ pub struct RelayConfig { pub ssl_cert_path: String, } +/// CallbackRet for blocking callback functions #[derive(Debug)] pub enum CallbackRet { Relay(Vec),// Relay data @@ -100,6 +191,7 @@ pub enum CallbackRet { Freeze,// Dont send data (pretend as if stream never was recieved) } +/// Callback functions a user may or may not implement. pub trait HandlerCallbacks { fn ds_b_callback(&self, _in_data: Vec) -> CallbackRet {CallbackRet::Relay(_in_data)} fn ds_nb_callback(&self, _in_data: Vec){} @@ -107,7 +199,7 @@ pub trait HandlerCallbacks { fn us_nb_callback(&self, _in_data: Vec){} } - +/// The main SSLRelay object. #[derive(Clone)] pub struct SSLRelay where diff --git a/src/relay.rs b/src/relay.rs index 14fc6b9..c4c65e4 100644 --- a/src/relay.rs +++ b/src/relay.rs @@ -1,3 +1,5 @@ +//! SSLRelay + use crate::{ SSLRelay, HandlerCallbacks, @@ -21,15 +23,15 @@ use crate::{ }; impl SSLRelay { - - pub fn new(handlers: H, config_path: ConfigType) -> Self { + /// Creates new SSLRelay instance. + pub fn new(handlers: H, config: ConfigType) -> Self { SSLRelay { - config: Self::load_relay_config(config_path), + config: Self::load_relay_config(config), handlers: Some(InnerHandlers{cb: handlers}), } } - + /// Starts the SSLRelay connection handling. pub fn start(&mut self) { let rhost = self.config.remote_host.clone(); @@ -104,10 +106,10 @@ impl) -> RelayConfig { + fn load_relay_config(config: ConfigType) -> RelayConfig { let mut resolved_path = String::from("./relay_config.toml"); - match config_path { + match config { ConfigType::Path(path) => { resolved_path = path.clone(); },