From ed1816002c6fdd83f7a8038007252a680fef98ee Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:04:25 -0500 Subject: [PATCH 01/14] fix Python3 configuration under Homebrew - Homebrew 3.3.16 (and possibly earlier) on recent versions of macOS are unable to build the necessary Python3 libraries without some additional flags passed to clang and/or llvm. - The Homebrew zbar package is needed to provide the zbarimg executable, but interferes with building zbar-py, so it needs to be removed and re-added after zbar-py is built. --- paperbackup-homebrew-setup.sh | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100755 paperbackup-homebrew-setup.sh diff --git a/paperbackup-homebrew-setup.sh b/paperbackup-homebrew-setup.sh new file mode 100755 index 0000000..2103f4b --- /dev/null +++ b/paperbackup-homebrew-setup.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash + +set -e + +brew install --cask basictex +brew install \ + enscript ghostscript gnu-sed imagemagick libqrencode pillow python3 + +python3 -m pip install --upgrade pip +python3 -m pip install --upgrade setuptools + +# the homebew zbar package interferes with the compilation of zbar-py +brew uninstall zbar --force + +CFLAGS="-I$(brew --prefix)/include" LDFLAGS="-L$(brew --prefix)/lib" pip3 install qrencode pyx zbar-py + +# (re)install the zbar package to provide the zbarimg binary +brew install zbar From 9d8cc3ac8b10eabd6d6dfc11a627ddf7229ada75 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:10:12 -0500 Subject: [PATCH 02/14] don't hard-code the location of the Bash shell - MacOS and some Linux distros have Bash in a different location, or may not have Bash at all. - Use env to find the location of Bash, rather than hard-coding it. - Some Bashisms in the scripts may prevent it from running with other Bourne-like shells, and definitely won't work with the Fish shell. --- paperbackup-verify.sh | 2 +- paperrestore.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/paperbackup-verify.sh b/paperbackup-verify.sh index 2120667..19e0246 100755 --- a/paperbackup-verify.sh +++ b/paperbackup-verify.sh @@ -1,4 +1,4 @@ -#!/usr/bin/bash +#!/usr/bin/env bash # USAGE: paperbackup-verify.sh backup.pdf # where backup.pdf should be the pdf created with paperbackup.py diff --git a/paperrestore.sh b/paperrestore.sh index ab0fa1d..dc49b05 100755 --- a/paperrestore.sh +++ b/paperrestore.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # restore data backed up with paperbackup.py From 85bfba0f26117407758f19ba8bd096c903b6b3f2 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:15:18 -0500 Subject: [PATCH 03/14] quote the positional parameter for safety --- paperrestore.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paperrestore.sh b/paperrestore.sh index dc49b05..76fe874 100755 --- a/paperrestore.sh +++ b/paperrestore.sh @@ -4,7 +4,7 @@ # give one file containing all qrcodes as parameter -SCANNEDFILE=$1 +SCANNEDFILE="$1" if [ -z "$SCANNEDFILE" ]; then echo "give one file containing all qrcodes as parameter" From 26fb87a149f02ee512b5e080073029cae9f88241 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:18:35 -0500 Subject: [PATCH 04/14] if macOS, assume homebrew with gnu-sed installed - Homebrew typically installs binaries to /usr/local/bin, so prepend that to the PATH. - Alias sed to gnu-sed, or upstream's sed commands will break. --- paperrestore.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/paperrestore.sh b/paperrestore.sh index 76fe874..d14fdd2 100755 --- a/paperrestore.sh +++ b/paperrestore.sh @@ -6,6 +6,11 @@ SCANNEDFILE="$1" +if [ "$(uname)" = "Darwin" ]; then + PATH="/usr/local/bin:$PATH" + alias sed="gsed" +fi + if [ -z "$SCANNEDFILE" ]; then echo "give one file containing all qrcodes as parameter" exit 1 From c6e9a935ec52f89f4b9c0095defe8773c59fb391 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:28:13 -0500 Subject: [PATCH 05/14] move negation inside conditional - Possible Bashism. - Prevent history issues when testing at the command line when `set -H` is enabled by placing the negation inside the test brackets. --- paperrestore.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paperrestore.sh b/paperrestore.sh index d14fdd2..a2d6f79 100755 --- a/paperrestore.sh +++ b/paperrestore.sh @@ -16,7 +16,7 @@ if [ -z "$SCANNEDFILE" ]; then exit 1 fi -if ! [ -f "$SCANNEDFILE" ]; then +if [ ! -f "$SCANNEDFILE" ]; then echo "$SCANNEDFILE is not a file" exit 1 fi From 92e7a23a2f7960865fb09820efc990b692a6b25e Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:34:33 -0500 Subject: [PATCH 06/14] send error messages to stderr, not stdout --- paperrestore.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/paperrestore.sh b/paperrestore.sh index a2d6f79..03e3c8a 100755 --- a/paperrestore.sh +++ b/paperrestore.sh @@ -17,12 +17,12 @@ if [ -z "$SCANNEDFILE" ]; then fi if [ ! -f "$SCANNEDFILE" ]; then - echo "$SCANNEDFILE is not a file" + echo "$SCANNEDFILE is not a file" > /dev/stderr exit 1 fi if [ ! -x "/usr/bin/zbarimg" ]; then - echo "/usr/bin/zbarimg missing" + echo "/usr/bin/zbarimg missing" > /dev/stderr exit 2 fi From 7a69704d27c3939fc2878319c0e63582dd8d769a Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:37:27 -0500 Subject: [PATCH 07/14] don't rely on a hard-coded location for zbarimg - Use `which` to check the PATH for zbarimg, rather than hard-coding its location. - Use whichever zbarimg is in the PATH, rather than defining the executable's fully-qualified PATH. - If zbarimg is missing, the error message now identifies the PATH as the problem, rather than pointing to a (possibly) incorrect location for the executable. --- paperrestore.sh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/paperrestore.sh b/paperrestore.sh index 03e3c8a..21755ae 100755 --- a/paperrestore.sh +++ b/paperrestore.sh @@ -21,10 +21,10 @@ if [ ! -f "$SCANNEDFILE" ]; then exit 1 fi -if [ ! -x "/usr/bin/zbarimg" ]; then - echo "/usr/bin/zbarimg missing" > /dev/stderr +which zbarimg > /dev/null 2>&1 || { + echo "zbarimg not found in PATH" > /dev/stderr exit 2 -fi +} # zbarimg ends each scanned code with a newline @@ -32,7 +32,7 @@ fi # so convert that to \0, so sort can sort on that # then remove all \n\0 so we get the originial without newlines added -/usr/bin/zbarimg --raw -Sdisable -Sqrcode.enable "$SCANNEDFILE" \ +zbarimg --raw -Sdisable -Sqrcode.enable "$SCANNEDFILE" \ | sed -e "s/\^/\x0/g" \ | sort -z -n \ | sed ':a;N;$!ba;s/\n\x0[0-9]* //g;s/\x0[0-9]* //g;s/\n\x0//g' From 4111cd0110c42540e9d0846ca8b645e6781bb191 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 20:41:25 -0500 Subject: [PATCH 08/14] make the name of the restore script match Since paperrestore-verify.sh has a dash, the restore script should too. --- paperrestore.sh => paperbackup-restore.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename paperrestore.sh => paperbackup-restore.sh (100%) diff --git a/paperrestore.sh b/paperbackup-restore.sh similarity index 100% rename from paperrestore.sh rename to paperbackup-restore.sh From ba3e08231865520f369ec844ed5eea91ae232c4e Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 21:02:41 -0500 Subject: [PATCH 09/14] set sections to H3 instead of H5 - Normalize the header structure to avoid jumping from H2 to H5, skipping H3 and H3. - This is mostly cosmetic, but semanticly it improves the HTML. --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 84bebc8..bad8ffc 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Designed to backup ASCII-armored GnuPG and SSH key files and ciphertext. ## How to use -###### Backup +### Backup ``` gpg2 --armor --export-options export-minimal --export-secret-key "User Name" >key.asc @@ -19,9 +19,9 @@ private key is still encrypted with it's passphrase, so make sure you don't lose or forget it. See some example output here: -https://github.com/intra2net/paperbackup/raw/master/example_output.pdf + -###### Restore +### Restore 1. Scan the papers 2. Create one file containing all the pages. zbar supports e.g. PDF, TIFF, PNG, JPG,... @@ -134,35 +134,35 @@ in the constants section of the source to change to US Letter. ## Similar projects -###### paperbackup with reportlab backend https://github.com/tuxlifan/paperbackup +### paperbackup with reportlab backend https://github.com/tuxlifan/paperbackup Should behave the same as this paperbackup but with using reportlab instead of PyX/LaTeX for PDF generation. Any discrepancies should be filed at https://github.com/tuxlifan/paperbackup/issues -###### PaperBack http://ollydbg.de/Paperbak/ and https://github.com/Rupan/paperbak/ +### PaperBack http://ollydbg.de/Paperbak/ and https://github.com/Rupan/paperbak/ Although it is GPL 3, this original version **PaperBack** (program 8-character name PaperBak) is for Windows only (but in 2018 a crossplatform, backwards-compatible, command line version paperbak-cli has been published, see next entry). It uses it's own proprietary barcode type. That allows it to produce much more dense code, but in case of a problem with decoding you are on your own. -###### paperback-cli https://git.teknik.io/scuti/paperback-cli +### paperback-cli https://git.teknik.io/scuti/paperback-cli Paperback-cli is the crossplatform, backwards-compatible, command line version of Oleh Yuschuk's PaperBack. https://github.com/Wikinaut/paperback-cli is a copy on github. See discussion on https://github.com/Rupan/paperbak/issues/1 for further programs. -###### ColorSafe https://github.com/colorsafe/colorsafe +### ColorSafe https://github.com/colorsafe/colorsafe A data matrix for printing on paper. Inspired by PaperBak, ColorSafe is written with modern methods and technologies and is cross-platform. It aims to allow a few Megabytes of data (or more) to be stored on paper for a worst case scenario backup, for extremely long-term archiving, or just for fun. With best practices, ColorSafe encoded data can safely withstand the viccissitudes of technology changes over long periods of time. -###### Twibright Optar http://ronja.twibright.com/optar/ +### Twibright Optar http://ronja.twibright.com/optar/ Uses the not-so-common Golay code to backup 200KB per page. So it offers a much higher density than paperbackup.py, but is probably more affected by defects on the paper. GPL 2 and designed for Linux. -###### Paperkey http://www.jabberwocky.com/software/paperkey/ +### Paperkey http://www.jabberwocky.com/software/paperkey/ It is designed to reduce the data needed to backup a private GnuPG key. It does not help you to print and scan the data. So it could be used in addition to paperbackup.py. -###### asc2qr.sh https://github.com/4bitfocus/asc-key-to-qr-code +### asc2qr.sh https://github.com/4bitfocus/asc-key-to-qr-code Very similar to paperbackup.py. But it only outputs .png images without ordering information. So you have to arrange printing and ordering yourself. From 6776a41d2d88415121c18ddf49aaecefa6a72296 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 21:07:02 -0500 Subject: [PATCH 10/14] fix URL markup --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index bad8ffc..ba0b91c 100644 --- a/README.md +++ b/README.md @@ -66,10 +66,10 @@ you still have the printed plaintext that paperbackup produces. The ISO has some standards for preservation and long term storage of paper: ISO/TC 46/SC 10 - Requirements for document storage and conditions for preservation -http://www.iso.org/iso/home/store/catalogue_tc/catalogue_tc_browse.htm?commid=48842 + Here's an example of what ISO 16245 describes: -http://www.iso.org/iso/livelinkgetfile-isocs?nodeId=15011261 + ## Choice and error resilency of barcodes @@ -134,35 +134,35 @@ in the constants section of the source to change to US Letter. ## Similar projects -### paperbackup with reportlab backend https://github.com/tuxlifan/paperbackup +### paperbackup with reportlab backend Should behave the same as this paperbackup but with using reportlab instead of PyX/LaTeX for PDF generation. Any discrepancies should be filed at https://github.com/tuxlifan/paperbackup/issues -### PaperBack http://ollydbg.de/Paperbak/ and https://github.com/Rupan/paperbak/ +### PaperBack and Although it is GPL 3, this original version **PaperBack** (program 8-character name PaperBak) is for Windows only (but in 2018 a crossplatform, backwards-compatible, command line version paperbak-cli has been published, see next entry). It uses it's own proprietary barcode type. That allows it to produce much more dense code, but in case of a problem with decoding you are on your own. -### paperback-cli https://git.teknik.io/scuti/paperback-cli +### paperback-cli Paperback-cli is the crossplatform, backwards-compatible, command line version of Oleh Yuschuk's PaperBack. https://github.com/Wikinaut/paperback-cli is a copy on github. See discussion on https://github.com/Rupan/paperbak/issues/1 for further programs. -### ColorSafe https://github.com/colorsafe/colorsafe +### ColorSafe A data matrix for printing on paper. Inspired by PaperBak, ColorSafe is written with modern methods and technologies and is cross-platform. It aims to allow a few Megabytes of data (or more) to be stored on paper for a worst case scenario backup, for extremely long-term archiving, or just for fun. With best practices, ColorSafe encoded data can safely withstand the viccissitudes of technology changes over long periods of time. -### Twibright Optar http://ronja.twibright.com/optar/ +### Twibright Optar Uses the not-so-common Golay code to backup 200KB per page. So it offers a much higher density than paperbackup.py, but is probably more affected by defects on the paper. GPL 2 and designed for Linux. -### Paperkey http://www.jabberwocky.com/software/paperkey/ +### Paperkey It is designed to reduce the data needed to backup a private GnuPG key. It does not help you to print and scan the data. So it could be used in addition to paperbackup.py. -### asc2qr.sh https://github.com/4bitfocus/asc-key-to-qr-code +### asc2qr.sh Very similar to paperbackup.py. But it only outputs .png images without ordering information. So you have to arrange printing and ordering yourself. From af3e1c3c56b3508687255f2d26df84ca1ca98464 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 21:07:19 -0500 Subject: [PATCH 11/14] add space after the shell redirection --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ba0b91c..4871ce9 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Designed to backup ASCII-armored GnuPG and SSH key files and ciphertext. ### Backup ``` -gpg2 --armor --export-options export-minimal --export-secret-key "User Name" >key.asc +gpg2 --armor --export-options export-minimal --export-secret-key "User Name" > key.asc paperbackup.py key.asc paperrestore.sh key.asc.pdf | diff key.asc - lpr key.asc.pdf From b65bac1b938d461ba8a2041f42775d7035ec7769 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 21:08:02 -0500 Subject: [PATCH 12/14] update dependencies with new section - Add section for newer MacOS systems since the current list doesn't work as-is on Big Sur with Python 3.9.10 and zbar 0.23.91. - Assumes Homebrew as the package manager, but should provide guidance for anyone using an alternative like MacPorts. --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 4871ce9..cdfc036 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,18 @@ not work, type in the missing letters from the plaintext output at the end of th - ghostscript https://www.ghostscript.com/ - ZBar http://zbar.sourceforge.net/ +### MacOS with Homebrew + +Some of the dependencies listed above are either outdated, or don't work +on Big Sur, recent versions of Homebrew, or newer versions of Python3. +These issues can be addressed by installing [Homebrew](https://brew.sh/) +and then running the new `paperbackup-homebrew-setup.sh` script to +configure the dependencies. + +*Note: Please adjust the script if you'd rather use a LaTex package other +than the BasicTex cask, or if you'd prefer to use GraphicsMagick rather +than ImageMagick.* + ## Why backup on paper? Some data, like GnuPG or SSH keys, can be really really important for you, like that your whole From 61eb98813be644a1a9d9ab2ddbfc7b53336e9e95 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 21:58:50 -0500 Subject: [PATCH 13/14] add SPDX identifier; refer questions upstream - Added the SPDX identifier for the MIT license. - Add link to the MIT license. - Document the discrepency between the upstream wording and the included license. - Refer questions about the intended license terms to the upstream copyright holder. --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cdfc036..cf98978 100644 --- a/README.md +++ b/README.md @@ -181,4 +181,13 @@ So you have to arrange printing and ordering yourself. ## License -MIT X11 License +[MIT X11 License](https://opensource.org/licenses/MIT) + + +*NB: The upstream author marked this as "MIT X11" (there's an MIT +license, and an X11 license, but there's no SPDX identifier for an "MIT +X11" license) but included the MIT license in the +[LICENSE](https://github.com/intra2net/paperbackup/blob/master/LICENSE) +file. Please contact +[upstream](https://github.com/intra2net/paperbackup) if you're confused +about which license(s) apply.* From d08b71c03164a9e8d1d2294ae67365af04783720 Mon Sep 17 00:00:00 2001 From: "Todd A. Jacobs" <385462+todd-a-jacobs@users.noreply.github.com> Date: Wed, 23 Feb 2022 22:03:59 -0500 Subject: [PATCH 14/14] markup, grammar, and spelling updates - Move links inline where possible. - Minor grammar, spelling, and semantic updates throughout. - Reflow line wrapping to a standard 72 characters. - Sort dependencies. - Indent explicit Python3 dependencies. --- README.md | 222 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 132 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index cf98978..51d305e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # paperbackup.py -Create a pdf with barcodes to backup text files on paper. -Designed to backup ASCII-armored GnuPG and SSH key files and ciphertext. +Create a PDF with barcodes to backup text files on paper. Designed to +backup ASCII-armored GnuPG and SSH key files and ciphertext. ## How to use @@ -15,8 +15,8 @@ lpr key.asc.pdf ``` This will print out the public and private key of "User Name". The -private key is still encrypted with it's passphrase, so make sure -you don't lose or forget it. +private key is still encrypted with it's passphrase, so make sure you +don't lose or forget it. See some example output here: @@ -24,23 +24,25 @@ See some example output here: ### Restore 1. Scan the papers -2. Create one file containing all the pages. zbar supports e.g. PDF, TIFF, PNG, JPG,... -3. `paperrestore.sh scanned.pdf >key.asc` +2. Create one file containing all the pages. zbar supports e.g. PDF, + TIFF, PNG, JPG,... +3. `paper-restore.sh scanned.pdf > key.asc` 4. `gpg2 --import key.asc` -If one or more barcodes could not be decoded, try scanning them again. If that does -not work, type in the missing letters from the plaintext output at the end of the pdf. +If one or more barcodes could not be decoded, try scanning them again. +If that does not work, type in the missing letters from the plaintext +output at the end of the PDF. ## Dependencies -- python 3 https://www.python.org/ -- python3-pillow https://python-pillow.org/ -- PyX http://pyx.sourceforge.net/ -- LaTeX (required by PyX) https://www.latex-project.org/ -- python3-qrencode https://github.com/Arachnid/pyqrencode -- enscript https://www.gnu.org/software/enscript/ -- ghostscript https://www.ghostscript.com/ -- ZBar http://zbar.sourceforge.net/ +- [Python 3](https://www.python.org/) + - [python3-pillow](https://python-pillow.org/) + - [python3-qrencode](https://github.com/Arachnid/pyqrencode) +- [enscript](https://www.gnu.org/software/enscript/) +- [ghostscript](https://www.ghostscript.com/) +- [LaTeX (required by PyX)](https://www.latex-project.org/) +- [PyX](http://pyx.sourceforge.net/) +- [ZBar](http://zbar.sourceforge.net/) ### MacOS with Homebrew @@ -50,134 +52,174 @@ These issues can be addressed by installing [Homebrew](https://brew.sh/) and then running the new `paperbackup-homebrew-setup.sh` script to configure the dependencies. -*Note: Please adjust the script if you'd rather use a LaTex package other -than the BasicTex cask, or if you'd prefer to use GraphicsMagick rather -than ImageMagick.* +*Note: Please adjust the script if you'd rather use a LaTex package +other than the BasicTex cask, or if you'd prefer to use GraphicsMagick +rather than ImageMagick.* ## Why backup on paper? -Some data, like GnuPG or SSH keys, can be really really important for you, like that your whole -business relies on them. If that is the case, you should have multiple backups at multiple -places of it. +Some data, like GnuPG or SSH keys, can be really really important for +you, like that your whole business relies on them. If that is the case, +you should have multiple backups at multiple places of it. -I also think it is a good idea to use different media types for it. Hard disks, flash based -media and CD-R are not only susceptible to heat, water and strong EM waves, but also age. +I also think it is a good idea to use different media types for it. Hard +disks, flash based media and CD-R are not only susceptible to heat, +water and strong EM waves, but also age. -Paper, if properly stored, has proven to be able to be legible after centuries. It is also -quite resistant to fire if stored as a thick stack like a book. +Paper, if properly stored, has proven to be able to be legible after +centuries. It is also quite resistant to fire if stored as a thick stack +like a book. -So I think it is a good idea to throw a backup on paper into the mix of locations and media -types of your important backups. +So I think it is a good idea to throw a backup on paper into the mix of +locations and media types of your important backups. -Storing the paper backup in a machine readable format like barcodes makes it practical to restore -even large amounts in short order. If the paper is too damaged for the barcodes to be readable, -you still have the printed plaintext that paperbackup produces. +Storing the paper backup in a machine readable format like barcodes +makes it practical to restore even large amounts in short order. If the +paper is too damaged for the barcodes to be readable, you still have the +printed plaintext that paperbackup produces. ## How to properly store the paper -The ISO has some standards for preservation and long term storage of paper: +The ISO has some standards for preservation and long term storage of +paper: -ISO/TC 46/SC 10 - Requirements for document storage and conditions for preservation - +- ISO/TC 46/SC 10 - Requirements for document storage and conditions for +preservation -Here's an example of what ISO 16245 describes: - + + + +- Here's an example of what ISO 16245 describes: + + ## Choice and error resilency of barcodes -Only 2D barcodes have the density to make key backup practical. QR Code and DataMatrix are -the most common 2D barcodes. +Only 2D barcodes have the density to make key backup practical. QR Code +and DataMatrix are the most common 2D barcodes. -Using a common barcode symbology makes sure that there are several independent implementations -of decoders available. This increases the probability that they handle defects and error -correction differently and are able to tolerate different kinds of defects. So if the barcode +Using a common barcode symbology makes sure that there are several +independent implementations of decoders available. This increases the +probability that they handle defects and error correction differently +and are able to tolerate different kinds of defects. So if the barcode gets damaged, you have several programs you can try. -Several papers comparing QR and DataMatrix come to the conclusion that DataMatrix allows -a higher density and offers better means for error correction. I tested this and came -to the conclusion that the QR code decoding programs available to me had better error -resilency than the ones for DataMatrix. +Several papers comparing QR and DataMatrix come to the conclusion that +DataMatrix allows a higher density and offers better means for error +correction. I tested this and came to the conclusion that the QR code +decoding programs available to me had better error resilency than the +ones for DataMatrix. -The toughest test I found, other than cutting complete parts from a code, was printing -the code, scanning it, printing the scanned image on a pure black and white printer -and then repeating this several times. While the barcode still looks good to the human -eye, this process slightly deforms the barcode in an irregular pattern. +The toughest test I found, other than cutting complete parts from a +code, was printing the code, scanning it, printing the scanned image on +a pure black and white printer and then repeating this several times. +While the barcode still looks good to the human eye, this process +slightly deforms the barcode in an irregular pattern. -libdmtx was still able to decode a DataMatrix barcode with 3 repetitions of the above -procedure. A expensive commercial library was still able to decode after 5 repetitions. +libdmtx was still able to decode a DataMatrix barcode with 3 repetitions +of the above procedure. A expensive commercial library was still able to +decode after 5 repetitions. -ZBar and the commercial library could still decode a QR code after 7 repetitions. +ZBar and the commercial library could still decode a QR code after 7 +repetitions. -A laser printed QR code, completely soaked in dirty water for a few hours, rinsed with -clean water, dried and then scanned, could be decoded by ZBar on the first try. +A laser printed QR code, completely soaked in dirty water for a few +hours, rinsed with clean water, dried and then scanned, could be decoded +by ZBar on the first try. This is why I chose QR code for this program. ## Encoding and data format -In my tests I found that larger QR codes are more at risk to becoming undecodable due to -wrinkles and deformations of the paper. So paperbackup splits the barcodes at 140 bytes of data. +In my tests I found that larger QR codes are more at risk to becoming +undecodable due to wrinkles and deformations of the paper. So +paperbackup splits the barcodes at 140 bytes of data. -QR codes offer a feature to concatenate the data of several barcodes. As this is not supported -by all programs, I chose not to use it. +QR codes offer a feature to concatenate the data of several barcodes. As +this is not supported by all programs, I chose not to use it. -Each barcode is labeled with a start marker `^`. After that the raw -and otherwise unencoded data follows. +Each barcode is labeled with a start marker `^`. +After that the raw and otherwise unencoded data follows. ## Plaintext output -paperbackup prints the plaintext in addition to the QR codes. If decoding one or more barcodes -should fail, you can use it as fallback. +paperbackup prints the plaintext in addition to the QR codes. If +decoding one or more barcodes should fail, you can use it as fallback. + +To ease entering large amounts of "gibberish" like base64 data, each +line is printed with a checksum. The checksum is the first 6 hexadecimal +characters of MD5 sum of the line content. The MD5 is on the "pure" line +content without the line break (e.g. `\n` or `\r\n`). -To ease entering large amounts of "gibberish" like base64 data, each line is printed with -a checksum. The checksum is the first 6 hexadecimal characters of MD5 sum of the line content. -The MD5 is on the "pure" line content without the line break (e.g. \n or \r\n) +To verify a line checksum use: -To verify a line checksum use -`echo -n "line content" | md5sum | cut -c -6` + echo -n "line content" | md5sum | cut -c -6 -If a line is too long to be printed on paper, it is split. This is denoted by a "^" character -at the begin of the next line on paper. The "^" is not included in the checksum. +If a line is too long to be printed on paper, it is split. This is +denoted by a `^` character at the begin of the next line on paper. The +`^` is not included in the checksum. ## Changing the paper format -The program writes PDFs in A4 by default. You can uncomment the respective lines -in the constants section of the source to change to US Letter. +The program writes PDFs for A4 paper by default. You can uncomment the +respective lines in the constants section of the source to change to US +Letter. ## Similar projects -### paperbackup with reportlab backend +### [paperbackup with reportlab +backend](https://github.com/tuxlifan/paperbackup) -Should behave the same as this paperbackup but with using reportlab instead of PyX/LaTeX for PDF generation. -Any discrepancies should be filed at https://github.com/tuxlifan/paperbackup/issues +Should behave the same as this paperbackup but with using reportlab +instead of PyX/LaTeX for PDF generation. Any discrepancies should be +filed at https://github.com/tuxlifan/paperbackup/issues -### PaperBack and +### [PaperBack](https://github.com/Rupan/paperbak/) +See also: -Although it is GPL 3, this original version **PaperBack** (program 8-character name PaperBak) is for Windows only (but in 2018 a crossplatform, backwards-compatible, command line version paperbak-cli has been published, see next entry). It uses it's own proprietary barcode type. That allows it to produce much more dense code, but in case of a problem with decoding you are on your own. +Although it is GPLv3, this original version **PaperBack** (program +8-character name PaperBak) is for Windows only (but in 2018 a +cross-platform, backwards-compatible, command line version paperbak-cli +has been published, see next entry). It uses it's own proprietary +barcode type. That allows it to produce much more dense code, but in +case of a problem with decoding you are on your own. -### paperback-cli +### [paperback-cli](https://git.teknik.io/scuti/paperback-cli) -Paperback-cli is the crossplatform, backwards-compatible, command line version of Oleh Yuschuk's PaperBack. https://github.com/Wikinaut/paperback-cli is a copy on github. See discussion on https://github.com/Rupan/paperbak/issues/1 for further programs. +Paperback-cli is the crossplatform, backwards-compatible, command line +version of Oleh Yuschuk's PaperBack. + is a copy on github. See +discussion on for further +programs. -### ColorSafe +### [ColorSafe](https://github.com/colorsafe/colorsafe) -A data matrix for printing on paper. Inspired by PaperBak, ColorSafe is written with modern methods and technologies and is cross-platform. It aims to allow a few Megabytes of data (or more) to be stored on paper for a worst case scenario backup, for extremely long-term archiving, or just for fun. With best practices, ColorSafe encoded data can safely withstand the viccissitudes of technology changes over long periods of time. +A data matrix for printing on paper. Inspired by PaperBak, ColorSafe is +written with modern methods and technologies and is cross-platform. It +aims to allow a few megabytes of data (or more) to be stored on paper +for a worst case scenario backup, for extremely long-term archiving, or +just for fun. With best practices, ColorSafe encoded data can safely +withstand the viccissitudes of technology changes over long periods of +time. -### Twibright Optar +### [Twibright Optar](http://ronja.twibright.com/optar/) -Uses the not-so-common Golay code to backup 200KB per page. So it offers a much higher -density than paperbackup.py, but is probably more affected by defects on the paper. -GPL 2 and designed for Linux. +Uses the not-so-common Golay code to backup 200KB per page. So it offers +a much higher density than paperbackup.py, but is probably more affected +by defects on the paper. It is licensed under GPLv2 and designed for +Linux. -### Paperkey +### [Paperkey](http://www.jabberwocky.com/software/paperkey/) -It is designed to reduce the data needed to backup a private GnuPG key. It does not help you -to print and scan the data. So it could be used in addition to paperbackup.py. +It is designed to reduce the data needed to backup a private GnuPG key. +It does not help you to print and scan the data. So it could be used in +addition to paperbackup.py. -### asc2qr.sh +### [asc2qr.sh](https://github.com/4bitfocus/asc-key-to-qr-code) -Very similar to paperbackup.py. But it only outputs .png images without ordering information. -So you have to arrange printing and ordering yourself. +Very similar to paperbackup.py. But it only outputs PNG images without +ordering information, so you have to arrange printing and ordering +yourself. ## License