qrcp Documentation

File: README.md Copy Chapter

$ qrcp

Transfer files over Wi-Fi from your computer to a mobile device by scanning a QR code without leaving the terminal.

Join the Telegram channel qrcp_dev or the @qrcp_dev Twitter account for news about the development.

How does it work? Copy Chapter

qrcp binds a web server to the address of your Wi-Fi network interface on a random port and creates a handler for it. The default handler serves the content and exits the program when the transfer is complete. When used to receive files, qrcp serves an upload page and handles the transfer.

The tool prints a QR code that encodes the text:

http://{address}:{port}/{random_path}

Most QR apps can detect URLs in decoded text and act accordingly (i.e., open the decoded URL with the default browser), so when the QR code is scanned, the content will begin downloading by the mobile browser.

Demo Copy Section

Send files to mobile:

Receive files from mobile:

Installation Copy Chapter

Using Go (Latest Development Version) Copy Section

Requires Go 1.18 or later:

go install github.com/claudiodangelis/qrcp@latest

Prebuilt Binaries Copy Section

Download the latest release for your platform from the Releases page.

Package Managers Copy Section

Confirm Installation Copy Section

After installation, verify that qrcp is working:

qrcp --help

Usage Copy Chapter

Send Files Copy Section

Receive Files Copy Section

Configuration Copy Chapter

qrcp works without prior configuration, but you can customize it using a configuration file or environment variables.

Configuration File Copy Section

The default configuration file is stored in $XDG_CONFIG_HOME/qrcp/config.yml. You can specify a custom location using the --config flag:

qrcp --config /tmp/qrcp.yml MyDocument.pdf

Configuration Options Copy Section

Environment Variables Copy Section

All configuration parameters can also be set via environment variables prefixed with QRCP_:

• $QRCP_INTERFACE
• $QRCP_PORT
• $QRCP_KEEPALIVE

Advanced Usage Copy Chapter

Network Interface Copy Section

To use a specific network interface:

qrcp -i tun0 MyDocument.pdf

To bind the web server to all interfaces:

qrcp -i any MyDocument.pdf

HTTPS Copy Section

Enable secure transfers with HTTPS by providing a TLS certificate and key:

qrcp --tls-cert /path/to/cert.pem --tls-key /path/to/cert.key MyDocument.pdf

Shell Completion Copy Chapter

qrcp provides shell completion scripts for Bash, Zsh, and Fish.

Authors and Credits Copy Chapter

• Author: Claudio d'Angelis
• Logo: Provided by @arasatasaygin as part of the openlogos initiative.
• Releases: Managed with goreleaser.

Clones and Similar Projects Copy Chapter

License Copy Chapter

MIT. See LICENSE.

File: docs/tutorials/secure-transfers-with-mkcert.md Copy Chapter

Secure transfers with mkcert

Published on October 14th, 2020, by Claudio d'Angelis.

In this tutorial you will learn how to securely transfer files with qrcp by creating a local Certificate Authority using mkcert and generating a certificate for qrcp. From its README, mkcert is a simple tool for making locally-trusted development certificates. It requires no configuration.

The following values will be used for this tutorial, they refer to a typical Linux system and may differ for you according to your operating system:

Note: secure transfers are only supported by qrcp version 0.7.0 and above.

Generate certificates Copy Chapter

Open your terminal, create a directory called certs and change to it
Install mkcert (refer to the README).

Generate the Certificate Authority:

mkcert --install

If everything worked correctly, you should see the similar output:

Created a new local CA at "/home/me/.local/share/mkcert"
Sudo password:
The local CA is now installed in the system trust store! ⚡️
The local CA is now installed in the Firefox and/or Chrome/Chromium trust store (requires browser restart)!

Generate a certificate for the IP of your computer/laptop:

mkcert 192.168.1.107

You should see a similar output:

Using the local CA at "/home/me/.local/share/mkcert"

Created a new certificate valid for the following names 
 - "192.168.1.107"

The certificate is at "./192.168.1.107.pem" and the key at "./192.168.1.107-key.pem"

At this point you should securely upload the root certificate generated by mkcert to your mobile phone. You have a few options for this, the simplest is just sending it by email. You can check the location of the root certificate's parent directory by running:

mkcert --CAROOT

If you are using iOS, you should trust the certificate authority, you can find more information here: Trust manually installed certificate profiles in iOS and iPadOS.

If you are using Android, you must convert the root certificate from PEM format to DER format. Note that you may need to install the openssl tool.

openssl x509 -inform PEM -outform DER -in $(mkcert --CAROOT)/rootCA.pem -out $(mkcert --CAROOT)/rootCA.der.crt

Upload the converted certificate to your Android device, and install it by simply opening the file. When asked to enter the certificate name, you can enter a friendly name, for example "mkcert".

Transfer something! Copy Chapter

You are now ready to securely transfer a file using the certificates generated by mkcert:

qrcp --tls-cert ~/certs/192.168.1.107.pem --tls-key ~/certs/192.168.1.107-key.pem screenshot.png

The output will be something like this (note that the printed URL starts with "https"):

Scan the following URL with a QR reader to start the file transfer:
https://192.168.1.107:40221/send/ljd7
█████████████████████████████████████
█████████████████████████████████████
████ ▄▄▄▄▄ █ █▀▀ █▀ ▄█▄▀▀█ ▄▄▄▄▄ ████
████ █   █ █▀█▄▄▄▄▄▄█▄█▄██ █   █ ████
████ █▄▄▄█ ██▀▄▄▀▄▀█▀█ ▀▄█ █▄▄▄█ ████
████▄▄▄▄▄▄▄█ ▀▄█ ▀ ▀ ▀ █ █▄▄▄▄▄▄▄████
████ ▀▄ ▀▄▄ ▀██▀▄▄▄▄   ▄█▀▄██▄█▄ ████
████▀▀   █▄▀▀ ▄▄█▀ █▀▄█▄▀ ▄▄██▄▄▀████
████▀█ ▀█▄▄█ ▄██ ▀██▀▀  ▄█▀▀█▄ ▀▀████
████  █▀█▀▄ █  ▄ ▀▄   ▀▄██ █▀█▄ ▄████
█████ ▀ ▀▀▄  ▄▀█ ▀██▄█▄▀▄██ ▀ ▀ █████
████▄████▄▄  ▀█ ▀████▄█▄ ▄▀█ █ ██████
█████▄█▄▄▄▄█▀ ▀█  ▀ ▀▀   ▄▄▄   ▀▀████
████ ▄▄▄▄▄ █  █▄▄▄█ █▀█  █▄█  █▄▀████
████ █   █ █▀ ▀ ▄▀ █ █▀ ▄   ▄▀▄▄▄████
████ █▄▄▄█ █▄█▄█ ▀▀▀▄▀ █▄▄ █▀█▄▀▄████
████▄▄▄▄▄▄▄█▄▄▄██▄▄▄█▄▄██▄█▄█▄▄▄█████
█████████████████████████████████████
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

Scan the QR and the file will be securely transferred to your mobile. Congratulations!

Configure qrcp to default to those value Copy Chapter

If you want to make this setup persistent so that all transfers will be secured by default, run the wizard with qrcp config and make sure the choose the right values to the following questions:

(Note: you must enter the absolute path of the certificates)

• Should files be securely transferred with HTTPS?
  Yes
• Choose TLS certificate path. Empty if not using HTTPS
  /home/user/certs/192.168.1.107.pem
• Choose TLS certificate key. Empty if not using HTTPS
  /home/user/certs/192.168.1.107-key.pem

After configuring qrcp, all transfers will be always secured.
If you'll want to temporarily disable security, just add the --secure=false flag.

Secure transfer:

qrcp MyDocument.pdf

Insecure transfer:

qrcp --secure=false MyDocument.pdf

Conclusion Copy Chapter

In this tutorial we have seen how to:

• create a local certificate authority with mkcert
• issue a certificate for your computer/laptop
• use that certificate to secure the transferring of a file with qrcp

If you want to learn more about HTTPS and secure connections, have a look at the How HTTPS works ...in a comic! website.

Useful Links Copy Chapter

• qrcp homepage
• mkcert homepage
• qrcp Telegram channel

File: docs/index.md Copy Chapter

$ qrcp

Transfer files over Wi-Fi from your computer to a mobile device by scanning a QR code without leaving the terminal.

Join the Telegram channel qrcp_dev or the @qrcp_dev Twitter account for news about the development.

How does it work? Copy Chapter

qrcp binds a web server to the address of your Wi-Fi network interface on a random port and creates a handler for it. The default handler serves the content and exits the program when the transfer is complete. When used to receive files, qrcp serves an upload page and handles the transfer.

The tool prints a QR code that encodes the text:

http://{address}:{port}/{random_path}

Most QR apps can detect URLs in decoded text and act accordingly (i.e., open the decoded URL with the default browser), so when the QR code is scanned, the content will begin downloading by the mobile browser.

Demo Copy Section

Send files to mobile:

Receive files from mobile:

Installation Copy Chapter

Using Go (Latest Development Version) Copy Section

Requires Go 1.18 or later:

go install github.com/claudiodangelis/qrcp@latest

Prebuilt Binaries Copy Section

Download the latest release for your platform from the Releases page.

Package Managers Copy Section

Confirm Installation Copy Section

After installation, verify that qrcp is working:

qrcp --help

Usage Copy Chapter

Send Files Copy Section

Receive Files Copy Section

Configuration Copy Chapter

qrcp works without prior configuration, but you can customize it using a configuration file or environment variables.

Configuration File Copy Section

The default configuration file is stored in $XDG_CONFIG_HOME/qrcp/config.yml. You can specify a custom location using the --config flag:

qrcp --config /tmp/qrcp.yml MyDocument.pdf

Configuration Options Copy Section

Environment Variables Copy Section

All configuration parameters can also be set via environment variables prefixed with QRCP_:

• $QRCP_INTERFACE
• $QRCP_PORT
• $QRCP_KEEPALIVE

Advanced Usage Copy Chapter

Network Interface Copy Section

To use a specific network interface:

qrcp -i tun0 MyDocument.pdf

To bind the web server to all interfaces:

qrcp -i any MyDocument.pdf

HTTPS Copy Section

Enable secure transfers with HTTPS by providing a TLS certificate and key:

qrcp --tls-cert /path/to/cert.pem --tls-key /path/to/cert.key MyDocument.pdf

Shell Completion Copy Chapter

qrcp provides shell completion scripts for Bash, Zsh, and Fish.

Authors and Credits Copy Chapter

• Author: Claudio d'Angelis
• Logo: Provided by @arasatasaygin as part of the openlogos initiative.
• Releases: Managed with goreleaser.

Clones and Similar Projects Copy Chapter

License Copy Chapter

MIT. See LICENSE.