{"id":13551988,"url":"https://github.com/cyphar/paperback","last_synced_at":"2025-05-14T21:06:02.163Z","repository":{"id":37049741,"uuid":"112404066","full_name":"cyphar/paperback","owner":"cyphar","description":"Paper backup generator suitable for long-term storage.","archived":false,"fork":false,"pushed_at":"2025-04-21T16:44:58.000Z","size":7659,"stargazers_count":1272,"open_issues_count":18,"forks_count":46,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-21T17:42:21.631Z","etag":null,"topics":["backup","encryption","paper","secret-sharing","shamir-secret-sharing","user-friendly"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyphar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-11-29T00:07:49.000Z","updated_at":"2025-04-21T16:44:14.000Z","dependencies_parsed_at":"2023-09-29T02:03:33.171Z","dependency_job_id":"647479f6-f72a-4e4b-b586-2a75dec43915","html_url":"https://github.com/cyphar/paperback","commit_stats":{"total_commits":148,"total_committers":3,"mean_commits":"49.333333333333336","dds":"0.22297297297297303","last_synced_commit":"f54c2632719a38038e83ba87f67e62f69540cb96"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphar%2Fpaperback","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphar%2Fpaperback/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphar%2Fpaperback/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyphar%2Fpaperback/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyphar","download_url":"https://codeload.github.com/cyphar/paperback/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227611,"owners_count":22035669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","encryption","paper","secret-sharing","shamir-secret-sharing","user-friendly"],"created_at":"2024-08-01T12:01:57.027Z","updated_at":"2025-05-14T21:06:02.098Z","avatar_url":"https://github.com/cyphar.png","language":"Rust","funding_links":[],"categories":["Rust","encryption"],"sub_categories":[],"readme":"## paperback ##\n\n**NOTE**: While paperback is currently fully functional, all of the development\nof \"paperpack v0\" is experimental and the format of the various data portions\nof paperback are subject to change without warning. This means that a backup\nmade today might not work with paperback tomorrow. However, once there is a\nproper release of paperback, the format of that version of paperback will be\nset in stone and any new changes will be done with a new version of paperback\n(paperback can detect the version of a document, so older documents will always\nbe handled by paperback).\n\n`paperback` is a paper-based backup scheme that is secure and easy-to-use.\nBackups are encrypted, and the secret key is split into numerous \"key shards\"\nwhich can be stored separately (by different individuals), removing the need\nfor any individual to memorise a secret passphrase.\n\nThis system can also be used as a digital will, because the original creator of\nthe backup is not required to be present (or consent to) the decryption of the\nbackup if enough of the \"key shards\" are collected. No individual knows the\nsecret key (not even you), and thus no party can be compelled to provide the\nkey without the consent of `k-1` other parties.\n\nTo make this system as simple-to-use as possible, `paperback` creates several\nPDFs which you can then print out and laminate, ready for recovery. Here are\nsome examples of the generated documents:\n\n|               |                                Mockups                                |                           Current Status                           |\n| ------------- | :-------------------------------------------------------------------: | :----------------------------------------------------------------: |\n| Main Document | \u003cimg style=\"max-height:400px\" src=\"contrib/mockup-maindocument.png\"/\u003e | \u003cimg style=\"max-height:400px\" src=\"contrib/poc-maindocument.png\"/\u003e |\n| Key Shard     | \u003cimg style=\"max-height:400px\" src=\"contrib/mockup-keyshard.png\"/\u003e     | \u003cimg style=\"max-height:400px\" src=\"contrib/poc-keyshard.png\"/\u003e     |\n\nThese \"key shards\" can then be given to a set of semi-trusted people.\n`paperback` also supports `(k, n)` redundancy, allowing for `n` key shards to\nbe created but only `k` being required in order for the backup to be recovered.\n\n\"Semi-trusted\" in this context means that you must be sure of the following two\nstatements about the parties you've given pieces to:\n\n1. At any time, at least `k` of the parties you've given pieces to will provide\n   you with the data you gave them. This is important to consider, as human\n   relationships can change over time, and your friend today may not be your\n   friend tomorrow.\n\n2. At any time, no party will maliciously collude with more than `k-1` other\n   parties in order to decrypt your backup information (however, if you are\n   incapacitated, you could organise with the parties to cooperate only in that\n   instance). Shamir called this having a group of \"mutually suspicious\n   individuals with conflicting interests\". Ideally, each of the parties will be\n   unaware of each other (or how many parties there are), and would only come\n   forward based on pre-arranged agreements with you. In practice, a person's\n   social graph is quite interconnected, so a higher level of trust is required.\n\nEach party will get a copy of their unique \"key shard\", and optionally a copy\nof the \"master document\" (though this is not necessary, and in some situations\nyou might want to store it separately so that even if the parties collude they\ncannot use the \"master key\" as they do not have the \"master document\"). We\nrecommend laminating all of the relevant documents, and printing them duplex\n(with each page containing the same page on both sides).\n\nNote that this design can be used in a more \"centralised\" fashion (for instance,\nby giving several lawyers from disparate law firms each an individual key shard,\nwith the intention to protect against attacks against an individual law firm).\nPaperback doesn't have a strong opinion on who would be good key shard holders;\nthat decision is up to you based on your own risk assessment.\n\nA full description of the cryptographic design and threat model is provided [in\nthe included design document][design].\n\n[design]: DESIGN.md\n\n### Usage ###\n\nPaperback is written in [Rust][rust]. In order to build Rust you need to have a\ncopy of [cargo][cargo]. Paperback can be built like this:\n\n\n```\n% cargo build --release\nwarning: patch for the non root package will be ignored, specify patch at the workspace root:\npackage:   /home/cyphar/src/paperback/pkg/paperback-core/Cargo.toml\nworkspace: /home/cyphar/src/paperback/Cargo.toml\n    Finished release [optimized] target(s) in 3m 42s\n% ./target/release/paperback ...\n```\n\nThe general usage of paperback is:\n\n * Create a backup using `paperback backup -n THRESHOLD -k SHARDS INPUT_FILE`.\n   The `-n` threshold is how many shards are necessary to recover the secret\n   (must be at least one), the `-k` shards is the number of shards that will be\n   created (must be at least as large as the threshold). The input file is the\n   path to a file containing your secret data (or `-` to read from stdin).\n\n   The main document will be saved in the current directory with the name\n   `main_document-xxxxxxxx.pdf` (`xxxxxxxx` being the document ID), and the key\n   shards will be saved in the current directory with names resembling\n   `key_shard-xxxxxxxx-hyyyyyyy.pdf` (with `hyyyyyyy` being the shard ID).\n\n * Recover a backup using `paperback recover --interactive OUTPUT_FILE`. You\n   will be asked to input the main document data, followed by the shard data and\n   codewords. The output file is the path to where the secret data will be\n   output (or `-` to write to stdout).\n\n   Note that for key shards, the QR code data will be encoded differently to\n   the \"text fallback\". This is because it is more space efficient to store the\n   data in base10 with QR codes. As long as you copy the entire payload (in\n   either encoding), paperback will handle it correctly.\n\n   Paperback will tell you how many QR codes from the main document remain to\n   be scanned (they can be input in any order), as well as how many remaining\n   key shards need to be scanned (along with a list of the key shards already\n   scanned).\n\n * Expand a quorum using `paperback expand-shards -n SHARDS --interactive`. The\n   `-n` shards number is the number of new shards to be created. You will be\n   asked to input enough key shards to form a quorum.\n\n   Paperback will tell you how many remaining key shards need to be scanned\n   (along with a list of the key shards already scanned).\n\n   The new key shards will be saved as PDF files in the same way as with\n   `paperback backup`.\n\n * Re-generate key shards with a specific identifier using `paperback\n   recreate-shards --interactive SHARD_ID...`. You can specify as many shard\n   ids as you like. Shard ids are of the form \"haaaaaaa\" (\"h\" followed by 7\n   alphanumeric characters). You can specify any arbitrary shard id.\n\n   This operation is mostly intended for allowing a shard holder to recover\n   their key shard (which may have been lost). Using `recreate-shards` is\n   preferable because (assuming you're sure the ID you recreate is the ID of the\n   shard you originally gave them) it means that they cannot trick you into\n   getting new distinct shards by pretending to lose an old shard. The recreated\n   shards are identical in almost every respect to the old shards (except with a\n   new set of codewords), so having many copies gives you no more information\n   than just one.\n\n   Paperback will tell you how many remaining key shards need to be scanned\n   (along with a list of the key shards already scanned).\n\n   The new key shards will be saved as PDF files in the same way as with\n   `paperback backup`.\n\n * Re-print an existing paperback document using `paperback reprint --[type]\n   --interactive`. `--[type]` can either be `--main-document` or `--shard` and\n   indicates what type of document needs to be reprinted.\n\n   You will be asked to enter the data of the document you have specified. The\n   new document will be saved as a PDF file in the same way as with `paperback\n   backup`.\n\n   When reprinting a main document, paperback will tell you how many QR codes\n   from the main document remain to be scanned (they can be input in any order).\n\nNote that when inputting data in \"interactive mode\" you have to put an extra\nblank space to indicate that you've finished inputting the data for that QR\ncode. This is to allow you to break the input up over several lines.\n\nCurrently, paperback only supports \"interactive\" input. In the future, paperback\nwill be able to automatically scan the data from each QR code in an image or PDF\nversion of the documents.\n\n[rust]: https://www.rust-lang.org/\n[cargo]: https://doc.rust-lang.org/cargo/\n\n### Paper Choices and Storage ###\n\nOne of the most important things when considering using `paperback` is to keep\nin mind that the integrity of the backup is only as good as the paper you print\nit on. Most \"cheap\" copy paper contains some levels of acid (either from\nprocessing or from the lignin in wood pulp), and thus after a few years will\nbegin to yellow and become brittle.\n\nArchival paper is a grade of paper that is designed to last longer than\nordinary copy paper, and has standardised requirements for acidity levels and\nso on. The [National Archives of Australia][naa-standard] have an even more\nstringent standard for Archival paper and will certify consumer-level archival\npaper if it meets their strict requirements. Though archival paper is quite a\nbit more expensive than copy paper, you can consider it a fairly minor cost (as\nmost users won't need more than 50 sheets). If archival paper is too expensive,\ntry to find alkaline or acid-free paper (you can ask your state or local\nlibrary if they have any recommendations).\n\nIn addition, while using **hot** lamination on a piece of paper may make the\ndocument more resistant to spills and everyday damage, [the lamination process\ncan cause documents to deteriorate faster][anthropology-lamination] due to the\nmaterial most lamination pouches are made from (not to mention that the process\nis fairly hard to reverse).  Encapsulation is a process similar to lamination,\nexcept that the laminate is usually made of more inert materials like BoPET\n(Mylar) and only the edges are sealed with tape or thread (allowing the\ndocument to be removed). Archival-grade polyester sleeves are more expensive\nthan lamination pouches, though they are not generally prohibitively expensive\n(you can find ~AU$1 sleeves online).\n\nThe required lifetime of a `paperback` backup is entirely up to the user, and so\nmaking the right price-versus-longevity tradeoff is fairly personal. However, if\nyou would like your backups to last indefinitely, I would recommend looking at\nthe [National Archives of Australia's website][naa-preserving-paper] which\ndocuments in quite some detail what common mistakes are made when trying to\npreserve paper documents.\n\nIt is recommended that you explain some of the best practices of storing\nbackups to the people you've given shard backups to -- as they are the people\nwho are in charge of keeping your backups safe and intact.\n\nFor even more recommendations (from archivists) about how best to produce and\nstore paper documents, the Canadian Conservation Institute [has publicly\nprovided very detailed explanations of their best practice\nrecommendations][cci-notes]. Unfortunately, there aren't as many details given\nabout what a *producer* of a document should do.\n\n[naa-standard]: https://web.archive.org/web/20180304061138/https://www.naa.gov.au/information-management/managing-information-and-records/preserving/physical-records-pres/archival-quality-paper-products.aspx\n[anthropology-lamination]: https://web.archive.org/web/20181128202230/http://anthropology.si.edu/conservation/lamination/lamination_guidelines.htm\n[naa-preserving-paper]: https://web.archive.org/web/20180324131805/http://www.naa.gov.au/information-management/managing-information-and-records/preserving/artworks.aspx\n[cci-notes]: https://www.canada.ca/en/conservation-institute/services/conservation-preservation-publications/canadian-conservation-institute-notes.html\n\n### License ###\n\n`paperback` is licensed under the terms of the GNU GPLv3+.\n\n```\npaperback: resilient paper backups for the very paranoid\nCopyright (C) 2018-2022 Aleksa Sarai \u003ccyphar@cyphar.com\u003e\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyphar%2Fpaperback","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyphar%2Fpaperback","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyphar%2Fpaperback/lists"}