{"id":15395491,"url":"https://github.com/stef/kchain","last_synced_at":"2025-03-27T20:44:51.442Z","repository":{"id":4410209,"uuid":"5547719","full_name":"stef/kchain","owner":"stef","description":"is a set of scripts that help to keep all encryption keys on a USB stick","archived":false,"fork":false,"pushed_at":"2012-08-31T01:37:04.000Z","size":160,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T23:17:12.716Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stef.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-08-25T01:52:56.000Z","updated_at":"2023-09-08T16:34:57.000Z","dependencies_parsed_at":"2022-09-20T23:12:09.296Z","dependency_job_id":null,"html_url":"https://github.com/stef/kchain","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fkchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fkchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fkchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fkchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stef","download_url":"https://codeload.github.com/stef/kchain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245924494,"owners_count":20694728,"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":[],"created_at":"2024-10-01T15:28:31.604Z","updated_at":"2025-03-27T20:44:51.400Z","avatar_url":"https://github.com/stef.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"#+OPTIONS: num:nil toc:nil \\n:nil @:t author:nil email:nil creator:nil\n\n* kchain\n... is a set of scripts that help to keep all encryption (gnupg, ssh,\notr, etc) keys on a USB stick, create encrypted containers, and\nlinking directories from the key to other locations (e.g. remapping\n~/.gnupg).\n\nWhen it works: your stick will be automatically mounted, any encrypted\ncontainers are mounted, the content of the key is made available on\nyour system.\n\n(see a less horribly formatted version of this file here: https://raw.github.com/stef/kchain/master/README.org)\n\n** Install\n   Depends on cryptsetup, inotify-tools.\n\n   Create your rc file, specifying a name and a mountpoint:\n\n#+begin_src sh\ncat \u003e~/.kchainrc \u003c\u003cEOT\nCACHEDIR=~/.cache/kchain\nEOT\n#+end_src\n\n*** Creating an encrypted container\n    Warning this procedure is experimental, you should backup your\n    files before continuing. Whenever in doubt, the script can be\n    interrupted using control-c.\n\n    You can easily create new containers on USB sticks or file-based\n    images using create-container. Create container accepts the\n    following positional parameters:\n    1. \"dev\" - can be either\n       - empty, in which case it tries to autodetect any USB storages\n         on your system.\n       - a USB storage device (e.g. /dev/sdc), then it will try to\n         create a new partition on this device.\n       - a file on the disk (e.g. /home/user/secret.img), it it does\n         not exist it's created automatically.\n       - a partition (e.g. /dev/sdc1)\n    2. \"size\" of the container in megabytes, defaults to 40.\n    3. \"name\" for the device mapper, defaults to kchain.\n    4. \"mountpoint\", the location where this kchain will be\n       automounted, defaults to \"/media/$name\"\n    5. \"keyfile\", location of a file containing the key for unlocking\n       the container, if specified but file does not exist it is\n       automatically created, and no passphrase is queried. Default is\n       empty to query the user for a passphrase.\n\n    See the following example, for a general feel what to expect:\n\n#+begin_src\n./create-container '' 100MB\nWARNING. this mostly works, sometimes not!\nWe're not taking responsibility to what happens to your data\nCreate backups of your date before continuing\ncontrol-c to abort now, or press enter to continue\n\n1 /dev/sdc  Kingston  DataTraveler II+     1GB\n2 /dev/sde  Motorola  MSnc.     0GB\nplease choose one of the above devices [1-2]: 1\nNo device specified. Guesing...\nWill try to create a new container on /dev/sdc  Kingston  DataTraveler II+     1GB\nNot enough free space. Trying to resize.\n 1      512B   1040MB  1040MB  primary  ext2\nabout to resize. ctrlc-c to abort, enter to continue\n\nyou have selected a device, that has enough space left.\ncreating the new partition now. ctrlc-c to abort, enter to continue\n\nsuccesfully created /dev/sdc2\ncreating udev rule for automounting\nmke2fs 1.42.5 (29-Jul-2012)\nFilesystem label=\nOS type: Linux\nBlock size=1024 (log=0)\nFragment size=1024 (log=0)\nStride=0 blocks, Stripe width=0 blocks\n23616 inodes, 94208 blocks\n4710 blocks (5.00%) reserved for the super user\nFirst data block=1\nMaximum filesystem blocks=67371008\n12 block groups\n8192 blocks per group, 8192 fragments per group\n1968 inodes per group\nSuperblock backups stored on blocks:\n        8193, 24577, 40961, 57345, 73729\n\nAllocating group tables: done\nWriting inode tables: done\nWriting superblocks and filesystem accounting information: done\n\nsuccesfully created kchain container on /dev/sdc2 mounted at /media/kchain\n#+end_src\n\n    When everything completes correctly, we have the newly mounted\n    container available for usage.\n\n    create-container can be used to easily create encrypted partitions\n    or file-based containers for other use as well.\n*** Intializing an kchain container\n    kchain provides additional conveniences. A mounted container can\n    be quickly populated with the users gnupg, ssh and irssi/otr keys\n    using init-kchain (for more info see the section on\n    create-dirmap). init-kchain takes the path to the mounted\n    container as a parameter:\n\n#+begin_src\n# ./init-kchain /media/kchain\nsetting up directories\ninitializing ssh, gnupg and irssi/otr dirmaps\ncall `activate-dirmap /media/kchain/.kchain/ /home/user/.ssh' to activate /home/user/.ssh dirmap\ncall `activate-dirmap /media/kchain/.kchain/ /home/user/.gnupg' to activate /home/user/.gnupg dirmap\ncall `activate-dirmap /media/kchain/.kchain/ /home/user/.irssi/otr' to activate /home/user/.irssi/otr dirmap\n\nif you want to create some images with the key stored on your new kchain\nrun `create-image /home/user/.data.img 10 /media/kchain/.kchain/data.key data /home/user/.mnt/data /media/kchain'\nthis creates a 10MB big .data.img in your home, with the key on they kchain\nHave fun using kchain\n#+end_src\n\n    One convenient feature of kchain is the automatic mounting of\n    encrypted images it knows about. Normally the keys for these\n    images are stored on the kchain container.\n\n    kchain comes with create-image, which takes the following\n    positional and mandatory parameters:\n    1. path to image (it will be overwritten)\n    2. size of image in megabytes\n    3. path to the key (automatically created and overwritten if\n       existing)\n    4. mountpoint where this image will be automounted\n    5. path to the kchain container\n\n    see the following example:\n\n#+begin_src\n# ./create-image /home/user/.data.img 10 /media/kchain/.kchain/data.key data /home/user/.mnt/data /media/kchain\n10+0 records in\n10+0 records out\n10485760 bytes (10 MB) copied, 0.0301455 s, 348 MB/s\nmke2fs 1.42.5 (29-Jul-2012)\nFilesystem label=\nOS type: Linux\nBlock size=1024 (log=0)\nFragment size=1024 (log=0)\nStride=0 blocks, Stripe width=0 blocks\n2048 inodes, 8192 blocks\n409 blocks (4.99%) reserved for the super user\nFirst data block=1\nMaximum filesystem blocks=8388608\n1 block group\n8192 blocks per group, 8192 fragments per group\n2048 inodes per group\n\nAllocating group tables: done\nWriting inode tables: done\nCreating journal (1024 blocks): done\nWriting superblocks and filesystem accounting information: done\n\nmounting image /media/kchain/.kchain/mounts/data\nsuccesfully created /media/kchain/.kchain/mounts/data\n#+end_src\n\n** Other Components\n*** kchain\n    This is the main dispatcher, it reacts to the addition/removal of\n    the key. After successful mounting of the key under $keyroot, the\n    files in $keyroot/.kchain/rules.d are being executed. Two rules\n    exist: activate-dirmap and mount-images.\n\n    For the auto-mounting fun to work, you must have this running.\n*** lock-key\n    Cleanly deactivates all rules and the key. Should also be invoked\n    by kchain when it detects the remove event of the USB stick.\n    Bind this to a key in your WM, or to the ACPI event lidclose.\n*** activate-dirmap\n    One of the rules used by kchain. Activates a dirmap, see\n    create-dirmap below. Can be reversed using a 'de' parameter.\n*** create-dirmap\n    Moves the local directory to a new location, creates a soft-link\n    back to the original name. And sets up a config that automatically\n    replaces the link to the local directory to a link pointing to an\n    alternative location, e.g.:\n\n#+begin_src\ncreate-dirmap ~/.irssi/otr ~/.keyroot/irssi-otr\n#+end_src\n\n    The original ~/.irssi/otr is renamed to ~/.irssi/otr.local, a link\n    from ~/.irssi/otr.local to ~/.irssi/otr is created, and an entry\n    in $keyroot/.kchain/conf.d/dirmap is created.\n\n    You should put something in the alternative directory, otherwise\n    when this gets activated, the directory will be empty.\n*** create-image\n    creates a new encrypted container and sets it up for automatic\n    mounting by kchain. Invoke with:\n\n#+begin_src\n# create-image $PWD/test.img 10 $PWD/test.key test /mnt /media/kchain\n#+end_src\n\n    Which creates an image $PWD/test.img which is 10MByte big, also\n    creates a random key at $PWD/test.key, calls the whole image\n    'test' and sets it up for automatic mounting under '/mnt' and\n    stores this configuration on the kchain container in\n    /media/kchain.\n*** mount-images\n    The other of the rules used by kchain. Automatically mounts\n    encrypted containers. See create-image and drop-image below.\n*** umount-images\n    Called by lock-key. Umounts all images or only those specified by\n    parameters. Images are specified by their configfile created by\n    create-image.\n*** drop-image\n    unmounts and securely deletes the storage, expects the image\n    configuration file, stored in $keyroot/.kchain/mounts/\n*** make-udev-rule\n    Creates a suitable udev rule in\n    /etc/udev/rules.d/81-kchain.rules. This is necessary for the\n    kchain dispatcher to do it's auto-mounting magic. It takes two\n    parameters:\n    1. device (e.g. /dev/sdc2)\n    2. the name for the mapper, default is 'kchain'\n\n    make-udev-rule is automatically called by create-container\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstef%2Fkchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstef%2Fkchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstef%2Fkchain/lists"}