04 - CLI & options

We shall be starting off from the CLI. That will be the behavior that will be built first. Here we will write (and update) the behavior of commands that will be available for the CLI.

The overall CLI when run without switches should show the help. We are going to assume that the program is called “chamber” and that the file(s) it works on will be called chamberfile(s). Chamberfiles for a single vault should always be stored in a single directory (since a chamberfile can be split into pieces, we will need a place to keep them all), the contents of which are not supposed to be edited by the user manually, or by using other tools. The path where those file are will be called “chamberpath”.

That being said, the CLI invocation without any switches should print this:

% chamber
Chamber is a tool to create and manage encrypted vaults. The options are: 

new     Create a new chamberfile at a new location.
ls      List contents of a chamberfile 
cp      Copy a file (or a directory) from file system to chamberfile (or vice-versa) 

Except the new command, a global --chamberfile argument will be applicable for all other commands, indicating the file to operate on. An environment variable called CHAMBERFILE_LOC may be set to avoid passing the argument and the value for every command. In case both are present, the value of argument supplied in the CLI command shall take precedence. This will make sure that although a default location can be set, the CLI tool can be used in a one-off way to operate on a different file.

As we go on, we will add more commands.

new

The command to create a new chamber. It will take a directory and create the chamberfile in it.

% chamber new /Users/vaibhavkaushal/tmp/chamber

The path has to be a directory. When successful, a new file named chamberfile will be created in the directory.

Behavior and failure conditions

1. If the directory does not exist, it will be created.
2. If the directory exists, it must be empty.
3. If the directory exists (or was created newly) and is empty, a new chamberfile will be created.
4. The password to encrypt the chamberfile contents will be asked before the chamberfile is created.
5. The password will always have to be entered interactively and cannot be passed as an argument (in short - you cannot automate creation of a new chamberfile).
6. If the password matches the password criteria, the password goes through the transformation (hashing steps) and is saved in chamberfile.

Once the chamberfile is created, you may be asked for a password hint which you may or may not provide.

ls

This command will be used to list the contents of a chamberfile. The path can be specified optionally.

% chamber --chamberfile /Users/vaibhavkaushal/tmp/chamber ls path_inside_chamber

Behavior and failure conditions

1. The path supplied must be a valid, existing directory inside which a valid chamberfile must be present.
2. The password to decrypt and read the contents might be asked interactively before the listing is done.
3. A method to list files without asking a password is not yet defined. ( #todo )
4. The path indicated by path_inside_chamber must exist within the Chamberfile.
5. ls may not be invoked on a single split of a chamberfile.

cp

This command will be used to copy files and directories from the Host FS to the Chamberfile, and vice versa.

Important: This command can not be used to copy contents from one path on Host FS to another path on Host FS.

% chamber --chamberfile /Users/vaibhavkaushal/tmp/chamber cp source destination

Behavior and failure conditions

1. The password to decrypt the chamberfile and perform the read/write operation might be asked interactively before the copying is started.
2. A method to copy files without asking a password is not yet defined. ( #todo )
3. The conditions below might produce an error and it would not be possible to show those errors without entering the password first.
4. At least one of the source or destination paths supplied MUST be within the chamberfile.
5. For either the source or the destination, a path referred within the chamberfile must start with chamber:// and should be followed by an intended path.
6. Anytime an operation (read or write) is being performed on the host FS, the command might fail due to a failure reported by the host (e.g. permission issues, hardware error, file transfer error, file corruption etc.) and a recovery will not be attempted. In case the operation is being performed recursively, the first failure will stop the entire operation.
7. In case of copying from Host FS to Chamberfile, the source file must be present and readable and the destination must not be present. If the source is a directory, passing a -r would be required to copy contents within it. If destination exists, copy operation will fail. However passing a --overwrite should delete the previous contents and copy the new ones.
8. In case of copying from chamberfile to host FS, the source file or directory must be present and the destination must not be present. If the source is a directory, passing a -r would be required to copy contents to the host FS. If the destination exists, the operation will fail; however, passing a --overwrite should allow the destination to be overwritten.
9. If both source and destination are within the chamberfile, the same rules as above will apply. The source files or directory must exist and destination must not exist. In case the source is a directory, passing -r would be required to copy contents. If the destination exists, the operation will fail. However, passing a --overwrite should allow the destination to be overwritten with new content.
10. The command will NOT incorporate the CoW behavior and all new files created will take up the required space within the chamberfile as soon as they are copied. CoW can be implemented later (much later). ( #todo ).
11. The command may not be used to copy files from one chamberfile to another. Such an operation is not supported.