diff --git a/config/_default/menus.toml b/config/_default/menus.toml index 1622351..13beb47 100644 --- a/config/_default/menus.toml +++ b/config/_default/menus.toml @@ -4,11 +4,11 @@ identifier = "Webmasters" url = "/docs/webmasters/" -#[[docs]] -# name = "Terminology" -# weight = 520 -# identifier = "Terminology" -# url = "/docs/terminology/" +[[docs]] + name = "User Manual" + weight = 520 + identifier = "user-manual" + url = "/docs/user-manual/" [[docs]] name = "Self-Hosting" diff --git a/content/docs/user-manual/_index.md b/content/docs/user-manual/_index.md new file mode 100644 index 0000000..189f610 --- /dev/null +++ b/content/docs/user-manual/_index.md @@ -0,0 +1,9 @@ +--- +title : "User Manual" +description: "Introduction to mCaptcha for users" +lead: "" +date: 2023-10-27T08:48:45+00:00 +lastmod: 2023-10-27T08:48:45+00:00 +draft: false +images: [] +--- diff --git a/content/docs/user-manual/cli.md b/content/docs/user-manual/cli.md new file mode 100644 index 0000000..ed339ce --- /dev/null +++ b/content/docs/user-manual/cli.md @@ -0,0 +1,151 @@ +--- +title: "CLI tool" +description: "Instructions to install mCaptcha CLI" +lead: "" +date: 2023-10-27T08:48:45+00:00 +lastmod: 2023-10-27T08:48:45+00:00 +draft: false +menu: + docs: + parent: "user-manual" +--- + +A CLI tool exists to compute mCaptcha challenges. It can be installed +from multiple sources: + +## Install + +### crates.io + +The CLI tool is available on, [crates.io](https://crates.io), the Rust +language's package registry. Rust language toolchain is required to +install from crates.io, please see [rustup.rs](https://rustup.rs) for +Instructions to install it. + +```bash +cargo install mcaptcha-cli +``` + +### Pre-compiled binaries + +Nightly builds and stable releases are regularly published to +[dl.mcaptcha.org](https://dl.mcaptcha.org/mcaptcha/cli) for a variety of +CPU architectures and operating systems. + +1. Download binary, checksum and GPG signature files + +```bash +wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz +wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz.asc +wget https://dl.mcaptcha.org/mcaptcha/cli/{VERSION}/{FILENAME}.tar.gz.sha256 +``` + +2. Verify checksum + +```bash +sha256sum -c {FILENAME}.tar.gz.sha256 +``` + +3. Download mCaptcha's GPG release keys and verify GPG signature + +```bash +gpg --keyserver keyserver.ubuntu.com --recv 73DAC973A9ADBB9ADCB5CDC4595A08135BA9FF73 +gpg --verify {FILENAME}.tar.gz.asc +``` + +4. Install Binary + +```bash +tar -xvzf {FILENAME}.tar.gz && sudo cp {FILENAME}/mcaptcha-cli /usr/local/bin +``` + +### Build from source + +1. Install Rust tool chain + Please see [here](https://rustup.rs) for instructions. +2. Download source code + +```bash +git clone https://git.batsense.net/mCaptcha/cli +``` + +3. Compile and install + +```bash +cargo build --release && sudp cp ./target/release/mcaptcha-cli +/usr/local/bin +``` + +## Pass mCaptcha challenge + +The CLI tool requires details about the challenge to work on it. The +tool can be used in three different modes compute challenge: + +1. Protected Page: Compute mCaptcha challenge for the CAPTCHA at a + protected page +2. Widget URL: Compute PoW for captcha at widget URL +3. (Developer mode) Offline: Computes PoW over given CAPTCHA parameters + +### From protected page URL + +The most convenient mode: copy the URL of the webpage which has the +mCaptcha widget (example: showcase.mcaptcha.org) and run the CLI tool +with it to get an authorization code: +Compute challenge using the URL + +```bash +03:39 atm@lab cli ±|feat-parse-webpage ✗|→ mcaptcha-cli protected-page https://showcase.mcaptcha.org/ +Authorization token: eRAZJiMrW58uDYA1s64Tmwq1u30HutuF +``` + +### Widget URL + +If you have the widget URL (will be in format https://mcaptcha.example.org/widget?sitekey=randomstring), it can be used to solve challenge as well: + +```bash +Compute PoW by fetching parameters from CAPTCHA URL + +Usage: mcaptcha-cli online --url + +Options: + -u, --url URL of the CAPTCHA. Example: https://example.org/widget?sitekey=foo + -h, --help Print help +``` + +Example usage: + +```bash +13:32 atm@lab cli ±|online ✗|→ mcaptcha-cli online -u https://demo.mcaptcha.org/widget?sitekey=pHy0AktWyOKuxZDzFfoaewncWecCHo23 +Authorization token: 3xleN26OctBuVu3X4t6CYyUjErhaxQvz +``` + +### [Developer mode] Offline + +Useful while debugging mCaptcha configurations, works on raw challenge +parameters. + +Help menu: + +```bash +Compute PoW with offline parameters + +Usage: mcaptcha-cli offline --salt --phrase --difficulty-factor + +Options: + -s, --salt Salt with which PoW should be computed + -p, --phrase Phrase over which PoW should be computed + -d, --difficulty-factor Difficulty Factor + -h, --help Print help +``` + +Example usage: + +```bash +13:28 atm@lab cli ±|online|→ mcaptcha-cli offline -s $(rand 32) -p $(rand 32) -d 50000 +difficulty: 50000 +nonce: 90507 +original phrase: f351f333d44b2c6b5bf7f033b065bbb8fb5e9dd153bd402e43ed04425f5a3859 +result: 340276562956196291522979356090220150471 +``` + +Where rand is [this](https://github.com/realaravinth/dotfiles/blob/6fc6c87cc912e17488a35c0d3327ecf393221270/scripts/rand#L20) script.