doc:Expand README.md

README.md

@@ -15,7 +15,7 @@
 
 _Shufflecake_ is a plausible deniability (hidden storage) layer for Linux. You can consider Shufflecake a spiritual successor of tools like TrueCrypt and VeraCrypt, but vastly improved, both in terms of security and functionality. Official website: <https://www.shufflecake.net>.
 
-This repository contains source code and installation instructions to correctly manage the creation, opening, and closing of Shufflecake volumes.
+This repository contains C source code and documentation to use and manage Shufflecake volumes.
 
 __WARNING__: Shufflecake is still experimental software, please do not rely on its security or stability.
 
@@ -26,6 +26,9 @@ __WARNING__: Shufflecake is still experimental software, please do not rely on i
     - [Initializing Device](#init)
     - [Opening Volumes](#open)
     - [Closing Volumes](#close)
+    - [Other Commands](#other)
+      - [Changing A Password](#changepwd)
+      - [Check If A Password Is Correct](#testpwd)
     - [Advanced Usage](#advanced)
       - [Volume Corruption Mitigation](#mitigcorr)
       - [Providing Passwords Non-Interactively](#passwordnonint)
@@ -40,16 +43,19 @@ __WARNING__: Shufflecake is still experimental software, please do not rely on i
 
 ## Overview <a id="user-content-overview"></a>
 
-In the context of Shufflecake, a _device_, or _cake_, is the underlying raw block device (e.g., a disk) that is formatted to contain hidden data, while a _volume_, or _layer_, is the logical, encrypted and hidden "partition" within a device. The device can be a whole USB stick (or disk), a partition, a file-backed loop device, etc. (you likely find it under `/dev`).
+In the context of Shufflecake, a _device_, or _cake_, is the underlying raw block device (e.g., a disk) that is formatted to contain hidden data, while a _volume_, or _layer_, is the logical, encrypted and hidden "partition" within a device. The device can be a whole USB stick (or disk), a physical or logical partition, a file-backed loop device, etc. (you likely find it under `/dev`).
 
-The two operating principles of Shufflecake are:
+The three operating principles of Shufflecake are:
 - 1 device = multiple volumes
 - 1 volume = 1 password = 1 "secrecy level"
+- unlocking a volume also unlocks all those of lesser secrecy level
 
-Volumes are password-protected, and embedded in the underlying device as data _slices_ which are indistinguishable from random noise without the proper password. Headers are also indistinguishable from random when not decrypted.
+Volumes are password-protected, and embedded in the underlying device as data _slices_ which are indistinguishable from random noise without the proper password. Headers are also indistinguishable from random when not decrypted. A Shufflecake-initialized device does not have cleartext headers, and is indistinguishable from random noise when not decrypted.
 
 Up to 15 _ordered_ Shufflecake volumes can be created on a single device, with the implicit assumption that "lower-order" volumes (e.g. layer 0) are _less_ _secret_ than "higher-order" ones (e.g. layer 3). The Shufflecake header is designed in such a way that it _chains_ volumes in a backwards-linked list: volume __i__ "points to" (contains the key of) volume __i-1__. This way, providing the key of volume __M__ allows this tool to traverse the list and also automatically open volumes __0__ through __M-1__ (besides volume __M__). 
 
+[![Scheme of Shufflecake device layout](doc/headers.png)]
+
 Opened volumes appear as block devices of the form `sflc_N_M` in `/dev/mapper`. It is up to the user to format them with an appropriate filesystem and mounting them before use. It is recommended to always unlock the most sensitive volume for daily use ("home alone" scenario), even if that volume is not being used or even mounted. Only open a subset of volumes (with a "decoy password") if under coercion. This is due to the high possibility of corrupting hidden volumes otherwise.
 
 For security and consistency reasons, you cannot init/open/close nested volumes within the same device one at a time; the tool only allows to perform these operations on a _chain_ of volumes in a device.
@@ -145,6 +151,28 @@ Closes all the volumes currently open on a device, removing them from `/dev/mapp
 The command only asks for the block device name, i.e., it will close _all_ volumes provided by that device at once, by first forcing a write on disk of any pending changes. However, in order to avoid any risk of data loss, it is always advisable to first `umount` any mounted open volume.
 
 
+
+### Other Commands <a id="user-content-other"></a>
+
+The following commands implement additional useful features.
+
+#### Changing A Password <a id="user-content-changepwd"></a>
+
+```
+sudo shufflecake changepwd <block_device>
+```
+
+A password will be required. If this is the correct password for a volume within that device, then the user will be prompted to enter a new password for that volume. Shufflecake will only modify a single ciphertext field in the header of that volume, without need of re-encrypting the volume itself.
+
+#### Check If A Password Is Correct <a id="user-content-changepwd"></a>
+
+```
+sudo shufflecake testpwd <block_device>
+```
+
+A password will be required. If this is the correct password for volume __M__, then this information will be returned to the user, without actually opening the volume. This can be useful if a user wants to be sure that a password unlocks a certain volume without risk of the OS logging the access to that volume and without the risk of corrupting the content of other, unlocked, hidden volumes.
+
+
 ### Advanced Usage <a id="user-content-advanced"></a>
 
 Certain features of Shufflecake are not yet implemented, but sometimes a workaround is possible. Consider all the instructions in this sections as experimental, use them at your own risk.

dm-sflc/sflc_constants.h

@@ -30,8 +30,8 @@
 
 #define SFLC_VER_MAJOR 0
 #define SFLC_VER_MINOR 4
-#define SFLC_VER_REVISION 1
-#define SFLC_VER_SPECIAL ""
+#define SFLC_VER_REVISION 2
+#define SFLC_VER_SPECIAL "rc1"
 
 #define STRINGIFY0(s) # s
 #define STRINGIFY(s) STRINGIFY0(s)