Whackberry mobo

WhackberryPi

Disconnected Cyberdeck for password management.

Features:

• Disconnected computer (with display) with no wireless connectivity on any part of the device
• QWERTY keyboard with access to most standard symbols
• A mouse for navigating the OS in GUI mode
• A additional Micro SD card reader that can be used to create backups of passwords for storage in a secure secondary location
• A Camera to take pictures that are unable to reach the internet (useful for QR backup codes of 2FA apps)
• A disconnected microcontroller that is able to transmit data from the disconnected computer to another computer using a data diode

How the data diode works:

1. The disconnected computer has a special command for transmitting data (ir-sender). This program can take standard input in bash.
2. The program encrypts the input. NOTE that the hardware only suport very weak and out-of-date encryption. Although it may provide a small layer of security, it should not be relied upon. This means anyone able to read the IR led blinking from inside the case, may be able to eventually decypt the messages. This seems like a low-level risk.
3. The program break the message into packets then into pulses and used the IR LED light transmit the password. Since there is no way to read messages from the LED, this is a one way communication. This is the data diode and it uses the "fire and forget" principle. This means errors in reading the message is possible. A check sum is part of the protocol to account for this possible error.
4. On the other side of the LED there is a IR Reciever. It is connected to a microcontroller that is completely disconnected* from the raspberry PI. The only way to communicate is over the air-gap via IR (one way). *Note that the microcontroller is connected via power (5v and Ground). This allows the disconnected computer to be powered when the microcontroller is pluged into a computer. This does technically open the possibility of side channel attacks.
5. The signal is recieved, decapsulated, combined, and de-crypted. The checksum is verified before decryption and the process will only continue if the checksum and decryption are successful.
6. When plugged into a computer, the air-gapped microcontroller acts as a keyboard and the message recieved is transmitted as keystrokes to the computer.

Setup:

To set up a device, follow the instructions in each section of this readme from top to bottom.

Main Hardware

• Raspberry Pi Zero v1.3 link
• M5 CardKB (v1.1)
• HDMI 5" Display link
• Raspberry Pi Camera Module 3 link
• Infrared LED link
• Infrared Receiver Sensor link
• QT Py RP2040 link
• At least 1 micro CD card
• A Raspberry Pi with internet (for setup only)

Supporting Hardware and PCB Mounting / cable accessories

• SMD Grove Female Header link
• USB Type-A Jack link
• HDMI cable link1 link2 link3
• Thru-hole 5-way Navigation switch (used as a mouse) link
• 2x Buttons link
• Pogo pins link
• Stand-off screws (the camera module may require a different size) link
• 1x 10k resistor link
• Male-male pin headers link
• USB Type C Breakout Board link
• SD card reader - SanDisk MobileMate USB 3.0 Reader link
• DPDT switch link
• One M4 nut and bolt (to attach CardKB)
• Solder and an soldering iron

PCB

There PCB (Printed Circuit Board) design is included in this repository. This can be ordered online for a PCB manufacturer. If you want to forgo the case, you can order 2 boards and use the second with the one with standoffs to protect the device.

Schematic

Design view

Front view

Back view

Assembly guide

This guide assumes you have some experince with soldering. Locational references (up, down, left, right) assume the PCB is upright with the logo facing you. The logo side is the front of the board, the other side is the back.

Prepare parts

1. Break the Male-male pin headers into 2 7 pin pieces and 1 8 pin piece
2. Solder the QTpy to the two 7 pin headers with the pins facing away from the side with the USB port on it.
3. Repeat the previous step for the Raspberry Pi Zero, and USB-c Breakout board.
4. Break the POGO pins into 2 single pins and 1 pieces with 2 still attatched pins.

Attach USB-c Breakout board

1. Use a M2.5 hex nut as a space between the USB-c breakout board and the main PCB, with the USB-c breakour board on the back of the main PCB. Secure the breakout board in place with more M2.5 nuts and screws
2. Clip of excess pin length from the pins of the USB-c breakout board headers and then solder the pins in place

Attach QTpy

1. Place the QTpy in place on the back of the main PCB
2. Clip of excess pin length from the pins of the QTpy headers and then solder the pins in place

Attach Raspberry Pi Zero

1. Solder the 2 attached pogo pins below the main headed pins in the Raspberry Pi Zero footprint. The pins should be facing the back of the board
2. Use 6mm long F-F hex standoffs and screws to attach the Raspberry Pi Zero fo the back of the main PCB. The pogo pins should be making contect with the Raspberry Pi Zero, and the main header pins should slightly protrude through the main PCB.
3. Solder all the main header pins into place.

Other soldered-in pieces

1. Solder the GROVE Female Header onto the back of the main PCB
2. Solder the USB Type-A Jack onto the back of the main PCB
3. Insert the 5-way nav switch on the front of the PCB and solder in the pins
4. Repeat step above for both buttons below the 5-wav nav switch
5. Insert the Resistor on the back of the main PCB, clip excess pin lenth, and solder into place
6. Repeat step above for the IR-Reciever and the IR LED

Attach the camera module

1. The mounting holes on the camera module are slightly smaller than M2.5 screws. You will either need to largen the holes are buy different hardware.
2. Use 6mm long F-F hex standoffs to attatch the camera to the back of the main PCB

Attach CardKB

1. Use the M4 nut and bolt to attach the CardKB to the front of the main PCB

Cables

1. Connect the Camera module to the Raspberry Pi Zero
2. Connect the CardKB to the main PCB GROVE header
3. Use the DYI HDMI cable to connect the display to the Raspberry Pi Zero

Protection plate

Only do this if you are not making a 3D printed case

1. Choose 4 or 5 well distributed, unused, and accessible mounting holes and insert into each a M2.5 10mm Screw into an unused PCB (with nothing else solder or attached to it)
2. To the back of each of the screws, screw on a 6mm long F-F hex standoff untill snug
3. To the still protruding screws, screw on a 8mm long F-F hex standoff untill snug
4. Place the this PCB on the main on being careful not to pitch any cables
5. Screw the two boards together with M2.5 4mm Screws into the standoffs

Setup guide

1.00: SD card setup

This part can be done on any trusted computer connected to the internet

1. Download Official Raspberry Pi Imager
2. Select Legacy, 32-bit - Debian Bullseye (released 2024-10-22)
3. Flash the SD card and then access the files on the SD card
4. Set up the display
   1. Setup the display. Under bootfs > config.txt if accessing from a SD Card reader or \boot\config.txt if accessing from the OS, add the following lines (more info here)

      hdmi_group=2
      hdmi_mode=87
      hdmi_cvt=800 480 60 6 0 0 0
      hdmi_drive=1
      max_usb_current=1

   2. Enable i2c. In the same config.txt file, uncomment "dtparam=i2c_arm=on". Follow instructions here

2.00: Configure the OS

I suggest doing the configuartion from another pi with internet. Plug the SD card into a internet-connected Raspberry Pi and boot it. Follow the commands to set up your account and apply any updates. You can use a less secure password if you want, the more import one will be the one you use when setting up a GPG key. Reboot the device.

2.01: Enable i2c

1. In terminal type, sudo raspi-config
2. Interface Options > I2C > Yes (enable) > OK > Finish

2.02: Turn on boot to terminal by default (optional)

1. In terminal type, sudo raspi-config
2. System Options > Boot / Auto login > Console Autologin > Finish
3. In subsequent boots, if you want a GUI, enter startx into the terminal

2.03: Updrade all apps / install new apps

1. In teminal: sudo apt update && sudo apt full-upgrade
2. Install password manager sudo apt-get install pass
3. Install password manager GUI sudo apt-get install qtpass
4. Install a game (helpful for using the system to build up randomness) sudo apt-get install ninvaders
5. Install 7z for secure ziped exports: 'sudo apt-get install p7zip-full'
6. Install circuit python: sudo pip3 install adafruit-blinka
7. Install PyUserInput for mouse: sudo pip3 install PyUserInput pynput
8. Install web3 for ethereum wallet generation: sudo pip3 install web3

2.04: Install Electum

1. Go to https://electrum.org/#download
2. mkdir ~/electrum, then cd ~/electrum
3. Follow the instructions for "Installation from Python sources" (tested with version 4.5.8)

2.05: Copy Etherium wallet script

1. mkdir ~/cryptowallet
2. Copy cryptowallet/gen-eth-wallet.py from this repo to ~/cryptowallet/gen-eth-wallet.py on the raspberry pi
3. chmod +x gen-eth-wallet.py

2.06: CarKB setup

1. mkdir ~/cardkb, then cd ~/cardkb
2. Follow instructions here (Note: add sudo to modprobe uinput)

2.07: Camera Setup

• Just plug and play
• libcamera-hello to test
• libcamera-jpeg -o /path/to/file.jpg to take a picture

2.08: Set up 5-way navi mouse

1. mkdir ~/navmouse, then cd ~/navmouse
2. Copy navmouse/mouse.py and navmouse/navmouselauncher.sh from this repo to ~/navmouse on the raspberry pi
3. chmod +x *
4. 'sudo nano /etc/xdg/lxsession/LXDE-pi/autostart`
5. Add this line to the end of the file, then save and exit: @/home/{name of user}/navmouse/navmouselauncher.sh TODO: Fix this section

2.09: Infrared Transmitter

1. Create a RAM disk for storing output:
   1. Add newramdisk  /mnt/ramdisk  tmpfs  rw,size=8M  0 0 to /etc/fstab (Note, you must replace each set of spaces with a tab)
2. Configuration
   1. sudo nano /boot/config.txt
   2. Add a line with dtoverlay=gpio-ir-tx,gpio_pin=18 to the file, then save and exit
   3. sudo nano /etc/modules
   4. Add a line with lirc_dev to the file, then save and exit
3. mkdir ~/ir-sender
4. Copy ir-protocol/ir-sender from this repo to the folder ~/ir-sender
5. Copy ir-protocol/ir-sender-gui from this repo to the folder ~/Desktop/ir-sender-gui
6. chmod +x ~/ir-sender
7. chmod +x ~/Desktop/ir-sender-gui
8. Add these lines ~/.profile

   if [ -d "$HOME/ir-sender" ] ; then
   PATH="$PATH:$HOME/ir-sender"
   fi

9. Generate new key: ir-sender --genkey
10. Copy the contents of the json and use it when setting up the Infrared Reciever
11. For ease of use, add an alias for ir-sender
12. Edit ~/.bashrc
13. Add this line to the bottom: alias irs=ir-sender

2.10: Infrared Reciever

This part of the device is on an isolated device that emulates a keyboard when plugged into the computer. On a PC connected to the Pico

1. Download circuit python for the QTPy RP2040 (link) (I used CircuitPython 9.2.6)
2. Download the circuit python bundle (link) (I used 'March 19, 2025 auto-release')
3. While holding down the BOOT button on the QTPy, connect it to the PC.
4. Copy the "uf2" file you downloaded in step 1 to the device. You should see INDEX.HTM and INFO_UF2.TXT there already. Wait for the device to reboot.
5. Unzip the folder from step 2 and copy the following folders and file to the lib folder of the QTPy. adafruit_hid, adafruit_pixelbuf.mpy, neopixel.mpy, adafruit_rsa, adafruit_logging.mpy, adafruit_binascii, adafruit_hashlib
6. Copy the contents of the ir-receiver-code.py to code.py
7. Copy boot.py to boot.py at the top level of the QTPy
8. Create a new file at the top level called private_key.json and put the json contents in it generated when setting up the Infrared Transmitter

Optional: If you want a second reciever for any reason (for example, you don't want to plug the same reciever into every computer you need a password on), here's how to set up a secondary one.

1. Buy a secondary RP2040 device. This guide will assume you're using the Waveshare RP2040-One.
2. Solder on a IR (Infrared) Receiver (the same one listed earlier in this project). Attach GND to GND, V to 3.3V, and OUT to GP0.
3. Follow the same steps above (for the main Infrared Reciever), with these minor changes
   1. In the code.py file, change board.MOSI to board.GP0 and board.NEOPIXEL to board.GP16
   2. In the boot.py file, change board.A0 to board.GP15
   3. Copy the private_key.json from the original RP2040 device to this one

2.11: Copy over the utility scripts

1. mkdir ~/utilities
2. Copy utilities/exportbackup.sh from this repo to ~/utilities/exportbackup.sh on the raspberry pi
3. Copy utilities/importfromcsv.py from this repo to ~/utilities/importfromcsv.py on the raspberry pi
4. sudo chmod +x ~/utilities/*

2.12: Test the system

1. Power down the raspberry pi you're using for setup. Move the SD card to the offline raspberry pi.
2. Test the system to make sure all features work as expected

2.12: Copy any passwords to the SD card

Copy password from any existing password managers to the SD Card (make sure to place them in a appropriate folder as not to mess up the OS on the SD Card).

3.00: Finish system init (offline)

Only perform these steps when you're done setting up the device and ready to never connected to the internet again

1. If the SD card is still in the Raspberry Pi you were using for setup, move it to the offline Raspberry Pi Zero.
2. Use system for 5-10 minutes to generate entopy (try ninvaders)
3. mkdir ~/mydata
4. Set up password manager
   1. Generate key
      1. gpg --gen-key
      2. Real name: user
      3. Email: [empty]
      4. O for okay
      5. Enter a password (this will be the master password for the password manager). Make sure it is a secure password and do not share it.
      6. Note the id of the key. This will be a lond alphanumberic sequence right above "uid"
   2. Set key to never expire
      1. gpg --edit-key key-id-as-noted-above
      2. expire
      3. enter 0
      4. q to quit (and y to save changes)
   3. pass init key-id-as-noted-above
5. Generate Bitcoin BTC wallet
   1. Start electrum with this command ~/electrum/Electrum-4.5.8/run_electrum
   2. This application will run slowly. Be prepared to wait a few minutes between screens.
   3. Follow prompts and be sure to save the new seed to the password manager (pass). Using a password is recommended, you can generate and store one it pass, then copy it to the clipboard by using pass -c {Folder/name}
   4. In the "Recieve" tab, create a never expiring request and save the public address to pass as well. You can use this to send money to the wallet.
   5. Export the private keeys to pass
      1. Under "Wallet" > "Private keys", select "Export"
      2. Specify the file location to somewhere on /mnt/ramdisk (this way it will not presist on disk as plain text)
      3. Add a column to the CSV titled "BurntPrivKey", and set it to "No" for all rows
      4. Run cat /mnt/ramdisk/{filename-of-exported-keys.csv} | pass insert {Folder/name} -m
6. Generate Etherium ETH wallet
   1. Run the command python3 ~/cryptowallet/gen-eth-wallet.py
   2. Enter both the private key and the public key to the pass password manager

Using the system

Basic commands

• To start the GUI for the OS: startx

Password manager

• To add a password: pass insert path/to/name
• To find a password: pass find name
• To generate a password: pass generate path/to/name
• To find a password: pass find myaccount
• To add metadata: pass insert path/to/name.meta (there are other oiptions, this is just a suggestion)
• To send a password to the QT py, pass show path/to/name | irs
• To edit a password, pass edit path/to/name
• To use the password manager gui: qtpass

Saving a encrypted image

1. Take a picture libcamera-jpeg -o /mnt/ramdisk/imagename.jpg *note, raw image will not persist on reboot
2. Encrypt the image gpg -e -r key-id-as-noted-above /mnt/ramdisk/imagename.jpg -o ~/mydata/imagename.jpg.gpg

Viewing a encrypted image

1. Decrypt the image gpg -d ~/mydata/imagename.jpg.gpg -o /mnt/ramdisk/imagename.jpg
2. View the image here /mnt/ramdisk/imagename.jpg *note, image will not persist on reboot

Creating a full backup This is meant to act as either an off site backup or a way to share all your data.

1. Safely procure a un-used micro SD card. This will prevent any contamination of your disconnected system.
2. Create a backup. Run the script under ~/utilities/exportbackup.sh
3. Follow the prompts. Note that with a lot of passwords, the "Exporting passwords" step can take a long time to run (last time was ~30 minutes for me).
4. Copy or move the resulting file to the SD Card.

Import csv to password manager

1. Modify the script here: ~/utilities/importfromcsv.py to match the fields in the CSV from your password manager
2. Run python3 ~/utilities/importfromcsv.py /path/to/passwords.csv
3. After successfully importing the passwords, delete the csv rm /path/to/passwords.csv

Sending recieving Bitcoin (btc)

You can send and recieve btc without exposing your private keys to the internet.

Recieving:

1. Open Electrum
2. Go to the recieving tab and create a request. Make one of your "burnt" addresses it not being used. Send btc using any app to that address.

Sending:

Option 1: signing a transaction (requires manual transcription)

1. On a computer connected to the internet
   1. Install Electrum and wait for it to sync
   2. Go to File > New/Restore
   3. Select "Import Bitcoin addresses or private keys"
   4. Enter the public addess (NOT the private keys!) from the Whackberry device (you can do that using this command: echo bitcoin_public_address | irs)
   5. Under the send tab, enter the address you want to send to, the amount, then click "Pay..."
   6. Set the transation fee and click "OK"
   7. Click the share button and "Copy to clipboard..." (paste in a text editor)
2. On the Whackberry
   1. Open Electrum
   2. On the top menu, "Tools" > "Load transation" > "From text"
   3. The camera will not work with the Electrum app, so you will have to manually copy the transation to the whackberry (make no mistakes, good luck).
   4. "Sign" the transation
   5. Click the share button and "Copy to clipboard..." (recommend pasting it somewhere like /mnt/ramdisk/txn.txt)
   6. Transfer that file back to the internet connected computer: cat /mnt/ramdisk/txn.txt | irs (you'll want to open a text editor on the internet connected computer to capture the contents of the file)
3. On a computer connected to the internet
   1. In Electrum, on the top menu, "Tools" > "Load transation" > "From text"
   2. Paste in the transation contents you transfered from the whackberry.
   3. Click "Broadcast" Option 2: Burning a Private key
4. Mark the private key as "burnt" on the Whackberry: pass edit path/to/privatekeys. I recommend labeling it in the Electrum GUI too (under the addresses tab)
5. Copy the ONLY THE BURNT private keys to a internet connected computer
   1. Test a command to ONLY get the burnt addresses: pass show path/to/privatekeys | grep ,Yes (Make 100% sure it's only outputing the private keys you want to burn)
   2. Copy the ket to the internet connected computer: ``pass show path/to/privatekeys | grep ,Yes | irs`
6. On the internet connected computer
   1. Follow steps 1.1 to 1.3 under "Option 1"
   2. Enter the private key
   3. Transfer all the bitcoin to your intended addresses. Keep in mind you can also transfer to other addresses on the Whackberry that are not yet burnt.

Accessing cold wallets (online)

1. Use ir-sender to send the target private key from the disconnected raspberry pi to a computer connect to the internet. Make sure to note any private keys or seeds being transfered. They are no longer totaly secure.
2. For Bitcion BTC:
   1. Download and install the Electrum application. Be very careful to download from the offical page (https://electrum.org/#download)[https://electrum.org/#download]
   2. Open the application and when prompted, select "Standard wallet" then "I already have a seed"
   3. Enter the seed for the Bitcoin BTC wallet.
   4. You can use the "Send" tab to send to any address. Start with a small amount to make sure everything is working.
3. For Etherium ETH:
   1. You can use any wallet that supports importing private keys to access the BTC. I'll include instructions for MetaMask Firefox Extension (v12.6.2) below.
   2. Go to MetaMask's site. Be sure it's the official source: https://metamask.io/download/
   3. Download and lauch the extension
   4. Follow the propmts and select "create new wallet"
   5. Once on the main account page, click the account dropdown at the top of the screen
   6. Select "Add account or hardware wallet" then "Import account"
   7. Enter the private key for Etherium ETH.
   8. You can use the "Send" button to send to any address. Start with a small amount to make sure everything is working.

Case

There is a 3D printable case included in this repository to help manage the cables and protect the devices. This case is yet to be printed and tested, so it likely we need to be altered and iterated.

Front of case

Back of case

Trouble shooting

• Opening the camera causes the system to crash
  • This is likely a power issue to the camera. First try adding these two lines to the "/boot/config.txt" file; over_voltage=2 and force_turbo=1. If the problem persists, lower the blacklight one the display by cutting the trace in between the two pads labeled "Open for -25mA" (more info here).

Future work

• setup HID to act as a security key
• fix tempermental QTpy