CryptPass free password manager


What is CryptPass

CryptPass is a free system for encrypting, storing and managing secret credentials, mainly passwords, within a text file.

This system is composed of two main parts: a library (the core of CryptPass) and an “app” (a graphic interface for the library). I’m aware that many other similar systems have already existed for a long time, and that they are very stable and widely used too. Nonetheless, I wanted to create my own, designed with some peculiarities and small differences compared to similar products, to reflect my philosophy, that can be resumed in the following requirements:

Simplicity Architecture and functionalities must be simple, since this makes expansion, bugs correction and the entire code handling easier.
Strength* The cryptographic functions used and their combination must be quite strong..
Focus The system must perform well only on its specific task: to organize and to encrypt secrets into a string storable anywhere. Any additional feature should be implemented externally.
Two-ways protection The cryptographic keys are derived both by a user-created password and by a pseudo-random system-generated token.
Being local The system stores data locally (i.e. offline).
Flexibility Users should not have any additional constraints than what the system requires for security reasons.
Openness The source code must be open.
Being free The system must be free software-licensed.
Reusability The system must be primarily a reusable library, ready for any contexts.
Being cross-platform* The system must be cross-platform.

* As of now, these aspects are not completely satisfied: Strength, because the system is too young and was not sufficiently analyzed or tested by community yet; being cross-platform, because only the library, compatible with node.js or pure javascript, is really cross-platform while the “app”, for the moment, only supports Android, Linux and Windows-operating systems.

↑ Up to summary

App features

At the moment, CryptPass has the following features:

Multi-OS Support CryptPass runs on Android, Linux and Windows (see downloads)
Two-ways protection CryptPass protects your secrets in two ways at the same time:
  • With a master password (you must choose a strong password and never forget it, otherwise you won’t be able to recover your wallet)
  • With a sequence of 26 numbers, from 0 to 25, randomly generated by the app (you have to write it down on a paper sheet or any similar support and never lose it, otherwise you won’t be able to recover your wallet). This sequence is stored locally and it’s not necessary to type it every time you open the app, but it’s needed only in case you want to recover the storage file. This sequence can also be viewed at any time using the app, as long as it runs correctly.
Description You can set a description of the wallet (that won’t be encrypted)
Secrets storage You can store your secrets in a collection of entries, each of which has:
  • A mandatory field (“name”), which must be unique (i.e. every entry must have a different name)
  • Five optional default fields (“description”, “tags”, “username”, “password”, “PIN”)
  • Unlimited optional custom fields (a list of pairs like “label / content”, where the label must be unique per entry)
Secrets search engine By default, entries are listed in alphabetical order. When you store a huge amount of entries, they can also be retrieved more comfortably in one of the following ways:
  • By name (you can search, case insensitively, for an entry, either with its complete name or even only a part of it)
  • By tags (you can select one or more tags to filter the entries list)
Managing You can also: view the secret sequence, change the master password and restore or reset the wallet

↑ Up to summary

How it works, in a nutshell

CryptPass App simply and safely stores your secret credentials into a file, in a location of your filesystem of your own choosing. In fact, your credentials are completely encrypted with a password that you create (master password) before saving them into the file. To read your credentials, you just have to type your master password.

If you want your secrets to be safely stored (for example in case your device stops working or has to be reset), you can use your favorite cloud data storage service (like Dropbox and many others) to keep an always updated replica of your CryptPass file. But remember, only in case of restoring that file, along with your master password, you must also type the sequence number CryptPass provided during the initiation and viewable at any time using the specific app menu item (other options → view sequence).

↑ Up to summary

CryptPass architecture

As said above, CryptPass is primarily a library, written in Typescript and using NodeJS libraries. CryptPassApp is an application whose aims are: to provide a graphical interface to CryptPass library, to implement the read/write functions for storing encrypted secrets and to be cross-platform. More technical and architectural details as follows.

The library

The core of CryptPass is the library. This library is NodeJS native (with full performance) but, in order for it to be also used in pure javascript, even if with some performance loss, some specific bundling libraries were added ("browser-resolve", "buffer", "crypto-browserify", "randombytes-pure", "scrypt-js", "stream-browserify").

The library completely abstracts the mass storage layer of the two main data structures, which are: KeyPass (containing the encrypted secrets) and Sequence (containing the secret sequence number). In fact, to instantiate the library, it’s necessary to pass as input the following 4 parameters: 1) the KeyPass (i.e. the encrypted secrets data structure); 2) the Sequence (i.e. the secret sequence number); 3) the KeyPassWriter and 4) the SequenceWriter, both functions that take as input argument the content of the respective data structures and provide a storage mechanism (for example they could write data as a file on filesystem).

We can distinguish two main components of the library: cryptographic APIs and entries management APIs. Since the latter is just a database-like collection of methods that simply add/edit/delete entries in a JSON data structure (implicitly described by the previous section “app feature” within the “secrets storage” item), we’ll only focus on the cryptographic APIs.

The cryptographic scheme is the following:

CryptPass cryptographic scheme
CryptPass cryptographic scheme

In the above diagram, in orange we have the elements known only by the user: the master password and the numeric sequence (order sequence). In blue we have the elements stored together inside the same data structure (named KeyPass inside the source code). Finally, in green, we have the elements derived from the cryptographic operation between these elements and in gray we have the cleartext entries (stored in RAM) that could be encrypted. Either for encryption and decryption purposes, the first two levels of the diagram are executed because they are necessary to calculate the couple called “MasterKey2 + InitVector2” with which the library encrypts and decrypts the wallet entries (in this case with the algorithm aes-256).

Most of that cryptographic sequence is quite common in this kind of softwares: a couple “key / initial vector” is derived from a password with a strong hash function (scrypt in this case) and is used to encrypt/decrypt some cleartext/ciphertext. On the other hand, it is worth explaining the only uncommon part: the ordering sequence. Let’s start with the aim. If any criminal obtained your KeyPass data structure and, with social engineering techniques, discovered your master password, he could easily decrypt all your credentials. But it wouldn’t need to be a criminal. Suppose the KeyPass data structure is stored in a cloud storage service and the user uses the same master password both for the cloud service and for the KeyPass; in this case, the cloud storage service could potentially use that password to decrypt the whole KeyPass data. So the “sequence number” is useful to mitigate this vulnerability. First, CryptPass generates a pseudo-random sequence of numbers (from 0 to 25), then it chunks the master key into 26 segments ordered by the sequence and that shuffled master key is stored inside KeyPass data structure. Only the user knows the exact order (i.e. sequence number) that correctly rebuilds the master key, and, thanks to this, he’s even more protected (brute forcing a sequence of 26 numbers is combinatorially hard).

To easily apply the “sequence number” trick and to easily provide a master password changing operation, a secondary master key was introduced. So first the primary master key is derived by scrypt from the concatenation of user master password and master salt. Then the encrypted secondary master key chunks are reordered. That done, the secondary master key is decrypted by the primary master key and is used in turn to encrypt / decrypt wallet entries.

The app

CryptPass app is written in Typescript with Apache Cordova and optimized for Android (with Cordova native platform support), Linux and Windows (both with Cordova Electron platform support). The app user interface and functionalities are exactly the same across all the supported operating systems except for storage management, as recaped as follows:

Platforms differences for storage management
KeyPass file initialization The KeyPass file is created by the app after selecting the desired location The KeyPass file must already exist (as an empty text file) and then must be selected from the app
Sequence number storage The sequence number is encrypted within the Android Keystore system The sequence number is not encrypted (but it’s not easy to steal)

The app uses the CryptPass library in bundled version (i.e. browser compatible) and enriches it with the graphics and all the due managing and configuration features to be effectively user interactive. The graphic (actually an embedded website) is quite essential and it uses the basic Bootstrap features. The backend parts of the code also have a specific layer to abstract the different storage managing across the different platforms.

The Android version also uses a customized version of two plugins for reading and writing files on device filesystem. Original plugins, in fact, didn’t permit all the operations needed, especially for granting permanent permission on files to be read and written, also after the device has been rebooted. The source code of both customizations can be found here:

Here’s a screenshot of the starting view:

CryptPass start view
CryptPass start view

↑ Up to summary

App bugs and technical debts

For the moment, CryptPass app is sufficiently usable but with several compromises (or sometimes actual bugs) that anybody can help me solve (and thanks in advance!). The only ones known to me are summarized as follows, and none of these have to do with vulnerability or security weakness:

App bugs and technical debts list
Title Category Platform Description
Uncomplete cross-platform Technical debt ALL Since I have only PCs with linux inside and only a smartphone with Android, I could code the app for a restricted number of OS. Cordova permits to extend the support for iOS and MacOS, and also to have a native installer for Windows (now only a zipped portable version is provided for it).
File creation on Electron Technical debt Linux and Windows I have not implemented the native Electron showOpenDialog() method so, for the first usage, the password file has to be created manually by the user as an empty text file
Windows antivirus BUG Windows I tried CryptPass only once on a Windows desktop PC and it seems that Avast antivirus considered it as malicious because of the capabilities to read and write files (even if it’s just the password file). I haven’t explored any solutions yet but, as a workaround, adding an exception for the CryptPass installation folder (
Android permissions BUG Android If a cloud storage synchronization service updates the KeyPass file, CryptPass loses reading (and writing?) permissions on that file. To investigate the causes, please look at the customized plugins I used:
Multi-wallet support Technical debt ALL At the moment, the app can manage one wallet per time (represented by the couple “KeyPass file” and “sequence number”)
Languages support Technical debt ALL At the moment, only my (mediocre) english is supported. Please correct me about any errors or typos and feel free to suggest any better linguistic formulations. Also the app was not natively set up for multi-language support but, with a few edits, it could be.

↑ Up to summary


This is free software and any contribution is welcome!

You can collaborate with me on the source code (look at the next chapter for links) and you can also send me any issue always through github or emailing me (look at the bottom of this page to find my address).

Issues links

For CryptPass library

For CryprPass app

↑ Up to summary

Downloads and source code

Install on Android

CryptPass app is on Google Play Store:

Get it on Google Play

Install on Linux

Here the builded versions for Linux:

Ubuntu / Ubuntu-derived / Debian (.deb package)

Portable ZIP for Linux

Install on Windows

Portable ZIP for Windows

Source code

For each supported platforms, you can also manually build the CryptPass library and CryptPass app downloading the source code from Github:

CryptPass library source code

CryptPass app source code


↑ Up to summary