diff --git a/README.md b/README.md index f5673b32..33a5713b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # crypto-sdcard (qcrypto edition) -#### Configuration files for unlocking and mounting encrypted SD-cards, using udev, udisks2, polkit and systemd. +### Configuration files for unlocking and mounting encrypted SD-cards, using udev, udisks2, polkit and systemd This edition is provided specifically for devices, which need to load Qualcomm's `qcrypto` kernel module in order to support modern cryptographic schemes as e.g. XTS, plus it is faster and more energy efficient.
Only SailfishOS on the Jolla 1 (sbj) is known to provide (per its *kernel-adaptation-sbj* RPM) and need the `qcrypto.ko`, hence currently it is the only device supported by the "qcrypto edition". SailfishOS on the Intex Aquafish / Jolla C (l500d / JP-1601) does not provide `qcrypto.ko`, for the Inoi R7 (p4903), Jala Accione and Accione P this is unknown (but `qcrypto.ko` is likely not provided), and on Sony's Xperias `qcrypto.ko` is definitely not provided.
@@ -12,7 +12,7 @@ The necessary steps to prepare an SD-card (or any other removable storage) are d Note that the "key"-files reside unencrypted on fixed, internal mass storage, as mobile devices usually have only a single user, who unlocks the whole device.
Thus **crypto-sdcard** solely protects "data at rest" on SD-cards and other removable storage, i.e. specifically when the device is locked or switched off (and the SD-card may be taken out). -Features: +#### Features * These configuration files do not alter, replace or delete any extant files. * Support of encrypted partitions and whole devices. * Support for (ยต)SD-cards and USB-attached storage (if supported by device hardware and Operating System). @@ -28,7 +28,7 @@ Features: Nevertheless, these configuration files are also applicable to devices without AlienDalvik installed. * Boot time is not significantly prolonged, as unlocking encrypted partitions per Cryptsetup occurs in parallel to starting udisks2; after both succeeded, all mount operations are also started concurrently. -Version history: +#### Version history * v1.3
Mounting is now restricted to users, who belong to the Unix-group **media_rw**, which is the case for the user *nemo* since some SailfishOS release before v3.2.1 and after v2.2.1 (unable to assess which one), or the *defaultuser* on freshly installed devices (since SailfishOS 3.4.0).
Significantly altered versioning scheme, git tags naming and archive file (tarball) names, again: This time to accommodate for multiple release variants per version in order to serve different SailfishOS releases from one repository easily. For details see the [document "Release version format, RPM dependencies and Git workflow"](https://github.com/Olf0/crypto-sdcard/blob/master/RPM-dependencies_Git-workflow.md). @@ -49,15 +49,15 @@ Version history: * v0.5
Although the installed configuration files are unaltered since v0.4-3, the spec-file ("RPM packaging") changes have been significant, so it ultimately earns an increased version number. * v0.4
- Optimised configuration file names.
- RPM spec file provided. + Optimise configuration file names.
+ Provide RPM spec file. * v0.3
- Switched to a UUID-based "key"-file naming scheme for LUKS partitions to allow for swapping encrypted SD-cards easily and moved "key"-files into a directory. Missed to properly implement this change for "plain" partitions, as they have no UUID!
+ Switch to a UUID-based "key"-file naming scheme for LUKS partitions to allow for swapping encrypted SD-cards easily and moved "key"-files into a directory. Missed to properly implement this change for "plain" partitions, as they have no UUID!
Hence the "key"-file path and names have changed again (please rename your "key"-files accordingly): * For Cryptsetup LUKS: `/etc/crypto-sdcard/crypto_luks_.key` * For Cryptsetup "plain": `/etc/crypto-sdcard/crypto_plain_.key` * v0.2
- Fixed automatic mounting of DM-Crypt "plain" partitions.
+ Fix automatic mounting of DM-Crypt "plain" partitions.
"Key"-file path and names are altered (please rename your "key"-files accordingly): * For Cryptsetup LUKS: `/etc/crypto_luks_.key`, e.g. */etc/crypto_luks_mmcblk1p2.key* * For Cryptsetup "plain": `/etc/crypto_plain_.key`, e.g. */etc/crypto_plain_mmcblk1p2.key* diff --git a/RPM-dependencies_Git-workflow.md b/RPM-dependencies_Git-workflow.md index 2d17d798..d1160913 100644 --- a/RPM-dependencies_Git-workflow.md +++ b/RPM-dependencies_Git-workflow.md @@ -6,8 +6,9 @@ Releases from each of these release branches are tagged in git, from which tarba #### Requirements 1. The names of the automatically generated tarballs for git tags must differ, hence they must include sub-strings (i.e., "release branch identifiers") which allow to differentiate releases from each of the release branches. Because these releases carry the same program name and version, they must differ in their release string.
- Consequently the git tags must include the release string, i.e. adhere to the format `-`. Furthermore the git tags themselves (for releases) must carry different, release branch specific names anyway, which is provided this way. -2. Thus the RPM spec file must define the tarball name in the format `--`, e.g. by a `%setup -n %{name}-%{version}-%{release}` statement in the `%prep` section, because this is the tarballs' auto-generated, fixed name (e.g., at Github). + Consequently the git tags must include the release string, i.e. adhere to the format `-`. Furthermore the git tags themselves (for releases) must carry different, release branch specific names anyway, which is provided this way.
+ Hence the auto-generated release tarballs are named `--.tar.gz`, and equally the single top level directory of ("within" / "inside") such a tar archive is created as `--`. At Github both seem to be constructed from the git tag appended to the project name in a fixed manner (i.e., not configurable). +2. Thus the RPM spec file must define the tarball name as `--.tar.gz` in a `Source:` statement, plus declare the top level directory of the archive to be called `--`, e.g. by a `%setup -n %{name}-%{version}-%{release}` macro call in the `%prep` section. For details, see e.g. at [Max-RPM](http://ftp.rpm.org/max-rpm/s1-rpm-inside-macros.html#S2-RPM-INSIDE-SETUP-MACRO). 3. All RPMs for a single version built from the release tarballs must contain mutually exclusive dependencies, otherwise the dependency resolver on a target system might pick a wrong RPM to install.
Thus the spec file must include "dependency pairs" differenciating between the target systems.
Multiple "dependency pairs" may be used as a single differentiator for the release branches, but there must be at least one "dependency pair" for each distiguishing property / feature.
@@ -42,7 +43,9 @@ common "head" branch -------------------------------> release branch non-A, non- ``` * In practice it is much easier to work with an inverted scheme, i.e. the "head" branch contains all current features activated and the "feature branches" become "non-A" and "non-Z" (instead of "A" and "Z"), then. * It is crucial to always create pull-requests between these branches in a strictly unidirectional ("forward only") manner, or git-hell will be unleashed. -* The usual precautions for merge conflicts must be applied: If a merge conflict is forseeable or arises (either technically or just "oh, this line(s) does not belong in the target branch"), do not merge directly, instead create a new branch from the target branch, merge the commit set from the originating branch into this new branch, resolve the merge conflict(s) in the new branch and ultimately merge the new branch into the target branch (after that, the new branch can be deleted). +* The usual precautions for merge conflicts must be applied: If a merge conflict is forseeable or arises (either technically or just "oh, this line(s) does not belong in the target branch"), do not merge directly!
+ Instead create a new branch from the target branch, merge the commit set from the originating branch into this new branch, resolve the merge conflict(s) in the new branch and ultimately merge the new branch into the target branch (after that, the new branch can be deleted).
+ Alternatively (sometimes: preferably), the commit (set) can be used to create a new branch from the originating branch, from where it is first merged back into the originating branch, only then into the target branch, by resolving the merge conflict(s) in the new branch and ultimately merging the new branch into the target branch (after that, the new branch can be deleted). * All branches in the diagram should be configured as "protected branches" to avoid mishaps. At Github, see *\ -> Settings -> Branches -> Add rule -> \ -> Create*. * Changes (i.e., commits), which are applicable to all variants of the program (i.e., shall end up in all release branches) are comitted to the "common head branch". * Feature specific changes are comitted to the corresponding "feature branch". @@ -55,7 +58,7 @@ common "head" branch -------------------------------> release branch non-A, non- For *crypto-sdcard*, starting with version 1.3.1, ... * the [release string format carries two feature specific identifiers in its second field](https://github.com/Olf0/crypto-sdcard/blob/master/rpm/crypto-sdcard.spec#L7): {*regular*, *qcrypto*} and *sfosABC* (currently with *ABC* out of {*321*, *340*}).
Each of those two may be used to distinguish between more than two features / properties in the future: By defining more SailfishOS releases to differentiate for, or by extending the list of specified appendices denoting mutually ecxlusive features / properties of a target system.
- Additionally a third (or more) distinguishing identifier ("differentiator") may be defined, but that would require some visual separator for more sub-fields in the second field of the release string other than the dot (`.`) and dash (`-`, minus, hyphen), or introducing a new, third field (moving the extant one to the fourth position). Both possibilities are not nice, e.g. a `+` as a separator conflicts with the set of allowed characters for git tags (at least at Github), the tilde (`~`) is also likely to cause issues, only the underscore (`_`) likely works (but is visually the ugliest option, IMO), and four or even more fields separated by dots in the release string may infringe some convention. Hence I will try to avoid this, although the `_` or another, additional field (i.e., not a sub-field of the second field) might provide viable paths for extending this scheme. + Additionally a third (or more) distinguishing identifier ("differentiator") may be defined, but that would require some visual separator for more sub-fields in the second field of the release string other than the dot (`.`) and dash (`-`, minus, hyphen), or introducing a new, third field (moving the extant one to the fourth position). Both possibilities are not nice, hence I will avoid them: E.g. a `+` as a separator conflicts with the set of allowed characters for git tags (at least at Github), IMO only the tilde (`~`) and the underscore (`_`) likely work (but are ugly options, visually), and while four fields separated by dots in the release string are used elsewhere, that makes it quite hard to capture visually. * the properties used as differentiators are the availability of the *kernel-adaptation-sbj* RPM (using form 1, above) and the version of the *sailfish-version* RPM (using form 2). * the git workflow is a slightly collapsed variant of aforementioned, generic scheme: It omits the second feature branch. ``` diff --git a/rpm/crypto-sdcard.spec b/rpm/crypto-sdcard.spec index 5944dc80..8d3215d3 100644 --- a/rpm/crypto-sdcard.spec +++ b/rpm/crypto-sdcard.spec @@ -1,6 +1,6 @@ Name: crypto-sdcard Summary: Configuration files for unlocking and mounting encrypted SD-cards automatically -Version: 1.3.1 +Version: 1.3.2 # Since v1.3.1, the release version consists of two or three fields, separated by a dot ("."): # - The first field must contain a natural number greater than zero. # This number may be prefixed by one of {alpha,beta,stable}, e.g. "alpha13". diff --git a/systemd/system/cryptosd-luks@.service b/systemd/system/cryptosd-luks@.service index 0a1ad920..c73a94b8 100644 --- a/systemd/system/cryptosd-luks@.service +++ b/systemd/system/cryptosd-luks@.service @@ -3,6 +3,7 @@ Description=Open DM-Crypt LUKS on SD-card %I Documentation=https://github.com/Olf0/crypto-sdcard After=systemd-udevd.service systemd-udev-settle.service dev-%i.device BindsTo=dev-%i.device +PartOf=cryptsetup.target Conflicts=rescue.target actdead.target factory-test.target AssertFileNotEmpty=/etc/crypto-sdcard/%I.key diff --git a/systemd/system/cryptosd-plain@.service b/systemd/system/cryptosd-plain@.service index 99cb53fb..69495e19 100644 --- a/systemd/system/cryptosd-plain@.service +++ b/systemd/system/cryptosd-plain@.service @@ -3,6 +3,7 @@ Description=Open DM-Crypt "plain" on SD-card %I Documentation=https://github.com/Olf0/crypto-sdcard After=systemd-udevd.service systemd-udev-settle.service dev-%i.device BindsTo=dev-%i.device +PartOf=cryptsetup.target Conflicts=rescue.target actdead.target factory-test.target AssertFileNotEmpty=/etc/crypto-sdcard/%I.key diff --git a/systemd/system/mount-cryptosd-luks@.service b/systemd/system/mount-cryptosd-luks@.service index 3ea195ad..9ce6fa92 100644 --- a/systemd/system/mount-cryptosd-luks@.service +++ b/systemd/system/mount-cryptosd-luks@.service @@ -18,5 +18,5 @@ RemainAfterExit=yes # Hence giving udisksd a second to settle: ExecStartPre=/bin/sleep 1 ExecStart=/usr/bin/udisksctl-user mount -b /dev/mapper/%I -ExecStop=/usr/bin/udisksctl-user unmount -b /dev/mapper/%I +ExecStop=/usr/bin/udisksctl unmount -b /dev/mapper/%I diff --git a/systemd/system/mount-cryptosd-plain@.service b/systemd/system/mount-cryptosd-plain@.service index 8ea07019..87b53068 100644 --- a/systemd/system/mount-cryptosd-plain@.service +++ b/systemd/system/mount-cryptosd-plain@.service @@ -18,5 +18,5 @@ RemainAfterExit=yes # Hence giving udisksd a second to settle: ExecStartPre=/bin/sleep 1 ExecStart=/usr/bin/udisksctl-user mount -b /dev/mapper/%I -ExecStop=/usr/bin/udisksctl-user unmount -b /dev/mapper/%I +ExecStop=/usr/bin/udisksctl unmount -b /dev/mapper/%I