Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/maxpat78/pycryptomator

Utilty to access a Cryptomator V8 vault from command line with Python 3
https://github.com/maxpat78/pycryptomator

crypto-tools cryptomator python-script python3 recovery-crypto recovery-tool utility-application

Last synced: 7 days ago
JSON representation

Utilty to access a Cryptomator V8 vault from command line with Python 3

Awesome Lists containing this project

README 

        
# pycryptomator



A Python 3 package to access a [Cryptomator](https://github.com/cryptomator/cryptomator) [V8](https://docs.cryptomator.org/en/1.7/security/architecture) vault and carry on some useful operations.



```

usage: pycryptomator  [-h] [--init] [--print-keys [{a85,b64,words}]] [--master-keys PRIMARY_KEY HMAC_KEY]

                      [--password PASSWORD] [--change-password]

                      vault_name



Access to a Cryptomator V8 vault



positional arguments:

  vault_name            Location of the existing Cryptomator V8 vault to open



options:

  -h, --help            show this help message and exit

  --init                Initialize a new vault in an empty directory

  --print-keys [{a85,b64,words}]

                        Print the raw master keys as a list of English words for Cryptomator (default), in ASCII85

                        (a85) or BASE64 (b64) format

  --master-keys PRIMARY_KEY HMAC_KEY

                        Primary and HMAC master keys in ASCII85 or BASE64 format, or - - to read a words list from

                        standard input

  --password PASSWORD   Password to unlock master keys stored in config file

  --change-password     Change the password required to open the vault

```



Passing a couple options, you can show you master keys or recover them in case

configuration files are corrupted:



`--print-keys` shows the decrypted primary and hmac master key in ASCII85

or BASE64 form, or as a list of English words like Cryptomator itself, to

annotate them in a safe place for recovering purposes.



`--master-keys`  grants access to the vault even in case of lost configuration

files `vault.cryptomator` and/or `masterkey.cryptomator`, provided the master

keys as ASCII85 or BASE64 strings; `- -` can be used to read the words list

from standard input.



After the `vault_name`, you can specify some useful operations like:



```

cd       change vault's current directory

ls       list unecrypted vault contents (with size and time)

mkdir    create a new directory/tree in the vault

mv       move or rename files and directories

ln       create a symbolic link

rm       erase files or directories

decrypt  decrypt a file or directory from the vault's virtual filesystem into a given destination

encrypt  encrypt a file or directory

alias    show the real pathname linked to a virtual one

backup   backup the Directory IDs (required to decrypt names) in a ZIP file

```



If no operation is specified, an interactive shell is launched on open vault. It can do transparent wildcards expansion (`*` and `?` only).



Functionality was tested in Windows 11 and Ubuntu 22.04 LTS Linux (under Windows WSL).



It's pure Python 3, with pycryptodome addon.



MIT licensed.

Absolutely no warranty!



# Internal commands



`*` and `?` wildcards can be specified on command line to enable automatic shell expansion.



`alias `

show the real base64 (encrypted and obfuscated) pathname corresponding to the

vault's pathname



`backup `

make in archive.zip a backup of all the directory id files dir.c9r

encountered in the vault tree: they are required to reconstruct original file

names



`cd `

make the specified vault's directory the current one in the pycryptomator

internal shell



```

decrypt [-fmF]  

decrypt  -

```

decrypt one or more files and/or directories to the specified destination in the

real file system.

`-f` forces to overwrite existing files, `-m` moves (i.e. deletes) the source

files after decryption, `-F` replicates the full command line path of source

in destination (by default only filenames are copied).

With `-` as destination, a file is decrypted and printed to standard output.



`encrypt [-fmF]  `

encrypt one or more files and/or directories to the specified destination.

If multiple sources are specified, the destination directory will be created

if not existent.

`-f` forces to overwrite existing files, `-m` moves (i.e. deletes) the source

files after encryption, `-F` replicates the full command line path of source

in destination (by default only filenames are copied).



`ln [-old]  `

make a symbolic link to a target file or directory in the vault.

It does not check for target existence.

An absolute target should be avoided, since it prevents portability

(i.e. to Windows).

When targeting a directory with `-old`, its dir.c9r file is copied to enable

compatibility with old vault formats (i.e. with current Cryptomator for Android

v. 1.10.3).



`ls [-b] [-r] [-s NSDE-!]  [...]`

list files and directories with minimal informations like DOS DIR (type/size,

write time, name, symbolic link target).

`-b` prints bare names

`-r` traverses specified directories recursively

`-s` sorts results by one or more criteria: `N`ame, `S`ize, `D`ate, `E`xtension

(a.k.a. file type), `-` sorts in reverse order and `!` puts directories first.



`mkdir [-R]  [...]`

make one or more directories or directory trees (i.e. intermediate directories

get created) in the vault or in the real file system if `-R` is specified.



`mv  [...] `

rename or move files and directories. If more files or directories are specified,

destination must be an existing directory and objects are moved inside it;

else, if destination does not exist, it renames the file or directory.



`rm [-f]  [...]`

remove files and directories. Root directory is protected against accidental

deletion. If a directory is not empty, `-f` switch is required to force its

removal.