Crate muddy

muddy

muddy is a static string obfuscation library, designed to provide an easy way of avoiding simple static binary analysis tools such as strings or YARA rules. It functions by encrypting texts at buildtime, and decrypting them lazily at runtime.

Usage & Examples

use muddy::{m, muddy_init};

muddy_init!();

println!("{}", m!("My highly obfuscated text"));
println!("{}", "My non obfuscated static str - ripgrep me");

Compile this example and grep the binary for obfuscated:

cargo b --example simple

strings ./target/debug/examples/simple | grep obfuscated
Only the second nonobfuscated line should appear.

muddy primarily provides the exported m!(), #[muddy], and muddy_all! { } macros, all which take text as input and encrypt it. The muddy_init!() macro provides the scaffolding for decrypting the strings at runtime and should be placed at the root of the user’s crate.

These macros can be used as an in-place text replacement with m!("my text"):

use muddy::{muddy_init, m};

muddy_init!();

println!("{}", m!("my plaintext"));

As an annotated &'static str with the muddy attribute:

use muddy::{muddy, muddy_init};

muddy_init!();

#[muddy]
static MY_STR: &str = "my plaintext";

Or as an invocation around multiple annotated &'static strs with muddy_all:

use muddy::{muddy_all, muddy_init};

muddy_init!();

muddy_all! {
   pub static MY_STR: &str = "my plaintext";
   pub static MY_SECOND_STR: &str = "my second plaintext";
   static MY_THIRD_STR: &str = "my module-specific third plaintext";
}

By default, muddy will encrypt the static strings with the chacha20poly1305 implementation, and embed the key inside the binary.

To avoid hardcoding the deobfuscation key into your binary, you may use:

// NOTE: this test will fail if run by tests since the key needs to be provided at runtime

use muddy::{m, muddy_init};

muddy_init!("env");

// If you build your program with `muddy_init!("env")`,
// the deobfuscation key env variable and deobfuscation key
// will be printed out to stderr:  
// `MUDDY='D47A372C13DEFED74FD3B9B4C741C355F9CB2C23C43F98ADE2C02FD50CA55C3D'`

// This key needs to be provided at runtime else the program will panic.  
// `MUDDY='D47A372C13DEFED74FD3B9B4C741C355F9CB2C23C43F98ADE2C02FD50CA55C3D' ./target/debug/examples/env`
    println!("{}", m!("My highly obfuscated text"));
    println!("{}", "My non obfuscated static str - ripgrep me");

If muddy_init!("env") is set, the MUDDY (by default) env variable will be checked at runtime for the key and the program will panic if it’s not found.

You can also set your own env key identifier at buildtime through MUDDY:
This: MUDDY='MY_KEY_NAME_2' cargo b --example env
prints: MY_KEY_NAME_2='FD5B85045B5278F5EDA567AD7C58EB56934BD8D7432C878B1AB6090052A64080'

muddy_init!

muddy_init!() can take one of two values:

• muddy_init!("embed")
• muddy_init!("env")

If no value is provided, the macro defaults to the "embed" configuration.
If "env" is provided, you may also set the env key identifier as the second field: muddy_init!("env", "MY_KEY")

Note on obfuscation and encryption

This crate does not provide any form of real encryption. It only makes the task of understanding strings in your binary more difficult. Obfuscation is not security.

This crate also does not obfuscate any debug symbols you may have. Profile settings such as

# inside Cargo.toml

[profile]
strip = true
panic = "abort"
# ...

and more can be found in the cargo reference.

Macro expansion

To check what this macro expands to:

• install cargo expand
• run: cargo expand -p muddy --example env

Macros

• m
  Obfuscates a literal text. (aka muddy_str!)
• muddy_all
  Obfuscates multiple static string expressions.
• muddy_init
  Initialization macro that must be called at the crate root. This sets up the scaffolding for the lazy decryption at runtime.
• muddy_str
  Obfuscates a literal text. (aka m!)

Structs

• GenericArray
  Struct representing a generic array - GenericArray<T, N> works like [T; N]
• Lazy
  A value which is initialized on the first access.
• LazyStr
  A wrapper around a [Lazy<&'static str>]
• OsRng
  A random number generator that retrieves randomness from the operating system.

Traits

• Aead
  Authenticated Encryption with Associated Data (AEAD) algorithm.
• AeadCore
  Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
• FromHex
  Types that can be decoded from a hex string.
• KeyInit
  Types which can be initialized from key.

Type Aliases

• ChaCha20Poly1305
  ChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD).
• Key
  Key type (256-bits/32-bytes).
• Nonce
  Nonce type (96-bits/12-bytes).
• U32

Attribute Macros

• muddy
  Obfuscates a static string expression as an attribute macro.