Introduction to Clypher

Clypher is a small Python program that allows you to encrypt and decrypt files via a simple CLI interface.

Note

This project is intended as a little personal project, and not as an actual secure solution for file encryption.

If you’re looking for a secure solution for storing sensitive files, look for other utilities, such as VeraCrypt.

I cannot guarantee security, so only use this for low-security applications.

Getting Started

Installation

To use Clypher, first install it using pip:

$ pip install clypher

Alternatively, you can install it as a package in editable mode using pip -e.

  1. Navigate to the project’s root directory. (Where proyect.toml is located.)

  2. Install Clypher using pip:

$ pip install -e .

To check that everything went well, you can run the --version command.

$ python3 -m clypher version

This should output “Clypher v 0.4”. If it does, then the installation succeeded.

CLI Usage

You interact with Clypher via command line arguments. If you’ve installed Clypher system-wide, you can just call it from the terminal:

$ python3 -m clypher

To display a list of available arguments, run the --help command:

$ python3 -m clypher --help

This will display a list of all available commands, as well as a short description of each one.

You can get more information about a command, such as a detailed description and the arguments it takes, by adding --help after it:

$ python3 -m clypher enc --help

Specifying input files

Both the enc and dec commands can take one or more input files or directories. Just pass them as arguments to said commands:

$ python3 -m clypher enc foo.txt

$ python3 -m clypher dec foo.txt ./baz/

By default, Clypher ignores any duplicate input files. If the same file is passed as an input multiple times, it will only be processed once.

Recursively adding input files

If you use the --recursive option, Clypher will recursively walk any input directories, adding every single file to the input list. Use with caution.

It is recommended you use it along with the --out option.

Specifying an output directory

By default, Clypher places any output files in the same directory as their source files. However, you can override this by using the --out option. Simply specify the desired output directory after the option, and Clypher will save all files to that directory:

$ python3 -m clypher foo.txt --out ./encrypted-foo/

Note

Specifying an --out directory will place all output files in that directory.

As of version 0.4, creating new directories, and/or duplicating the structure (as in creating any subfolders) of an input directory is not supported.

If the output directory does not exist, or the program lacks write privileges, Clypher will fail.

Specifying a password

By default, Clypher will ask you to enter a password before encrypting or decrypting a file.

You can pass a password as an argument by using the --pass option:

$ python3 -m clypher enc foo.txt --pass supersecretpassword1234

There are a few things to keep in mind about passwords:

  • When a password is specified, either by passing it as an argument or entering it when prompted by the program, it is applied for all input files. Currently, multiple passwords are not supported.

  • As of version 0.4, Clypher does not enforce a specific password format. You can use as many or as few characters as you want. As long as they are all printable ASCII characters, it should work.

Overwriting files

Clypher will throw an error if an output file already exists. To force the program to overwrite any conflicting files, simply pass the --fo option.

$ python3 -m clypher enc foo.txt --fo

Specifying an engine

Clypher can use different engines to process files. To specify an engine, use the --engine option, followed by the name of the engine you want to use:

$ python3 -m clypher enc foo.txt --engine fernet

Note

As of version 0.4, the only available engine is the FernetEngine. It is used as the default engine.

You can learn more about engines in the Engines documentation.