feat: mcaptcha/cli isntructions

This commit is contained in:
Aravinth Manivannan 2023-10-28 01:09:37 +05:30
parent f6a6bf371c
commit 4636d94374
Signed by: realaravinth
GPG key ID: F8F50389936984FF
3 changed files with 165 additions and 5 deletions

View file

@ -4,11 +4,11 @@
identifier = "Webmasters" identifier = "Webmasters"
url = "/docs/webmasters/" url = "/docs/webmasters/"
#[[docs]] [[docs]]
# name = "Terminology" name = "User Manual"
# weight = 520 weight = 520
# identifier = "Terminology" identifier = "user-manual"
# url = "/docs/terminology/" url = "/docs/user-manual/"
[[docs]] [[docs]]
name = "Self-Hosting" name = "Self-Hosting"

View file

@ -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: []
---

View file

@ -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 <URL>
Options:
-u, --url <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 <SALT> --phrase <PHRASE> --difficulty-factor <DIFFICULTY_FACTOR>
Options:
-s, --salt <SALT> Salt with which PoW should be computed
-p, --phrase <PHRASE> Phrase over which PoW should be computed
-d, --difficulty-factor <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.