Quick Start

This guide demonstrates generating a secret key, producing a dual-channel QR code, and reading both public and private channels using the CLI.

---

1. Key Generation

PlyQR uses 256-bit symmetric keys for ChaCha20-Poly1305 authenticated encryption. Generate a cryptographically secure random key file:

# Using the lab runner or cargo
cargo run --release -- keygen secret.key

The resulting secret.key is a 32-byte raw binary file. Keep this file confidential.

---

2. Encoding a Dual-Channel QR Code

Create sample inputs for the public message and the private secret:

echo -n "https://verify.brand.com/item/A89021" > public.txt
echo -n "CONFIDENTIAL: Factory Batch #992-B, Hash: 8f4a1" > private.txt

Encode into a dual-channel QR code:

# Syntax: encode <public_file> <private_file> <key_file> <output_prefix> <version> <ec_level> <hidden_per_block> <noise_reserve> <private_ecc> <mask>
cargo run --release -- encode \
  public.txt \
  private.txt \
  secret.key \
  output_qr \
  10 M 4 2 8 0

Generated Artifacts

• output_qr.svg: The ready-to-print vector QR code.
• output_qr.matrix: Raw binary matrix for programmatic use.
• output_qr-public.svg: Reference plain standard QR code without private data (for visual comparison).

---

3. Decoding and Verification

Reading the Public Channel (Any Scanner)

Scan output_qr.svg using any mobile phone camera or standard QR scanner. It immediately reads:

https://verify.brand.com/item/A89021

The scanner gives no indication that hidden data exists.

Reading the Private Channel (Authorized Reader)

Run the PlyQR decoder with the shared key:

cargo run --release -- decode \
  output_qr.matrix \
  secret.key \
  decoded_public.out \
  decoded_private.out

Output:

Public payload: https://verify.brand.com/item/A89021
Private payload: CONFIDENTIAL: Factory Batch #992-B, Hash: 8f4a1
Status: AEAD Authentication Verified (Poly1305 Tag OK)

If the QR code image has been altered or tampered with, decoding fails with an authentication error, preventing spoofing.