Password Manager

This is a simple flask application that creates APIs that can be used to manage your secrets (like password, pin, keys, etc.). The APIs can be preferably accessed using cURL. There are 3 operations that are supported:

• Insert: To insert new secrets.
• Query: To query the secrets. Two subtypes of query operations are supported:
  • Type 1: To search for secrets by domain (and username).
  • Type 2: To decrypt and get secrets of a single record.
• Update: To update the username and secrets of a given record.

Build status

Pipeline	Status
Build, Lint & Test

Setup

• There are 3 MongoDB collections that are required to setup the application:

  1. Auth collection: This collection contains hashed authentication keys that the client send via auth-key header to authenticate the application. This collection must be manually created.

     Field	Description
     key	Stores the authentication key as hash.

  2. Master collection: This collection contains hashed master password and master key that are used for generation of cipher keys that are inturn used to encrypt all the secrets. The cipher keys are generated using an algorithm mentioned in the following section. This cipher key is used as the key and initialization vector of AES cipher (CBC mode). The AES cipher is then used for encrypting all the secrets before storing it in the password manager collection. The secrets are also decrypted using the same AES cipher. This collection must be manually created. This collection must contain only a single record with the following fields.

     Field	Description
     master-password	Stores the master password as hash.
     master-key	Stores the master key as hash.

  3. Password manager collection: This is the collection where the secrets are stored. This collection is populated and updated via APIs. The combination of domain and username must be unique.

     Field	Description
     domain	Domain (ex. abc.com) for the record.
     username	Username (ex. xyz@abc.com) for the record.
     secrets	List of secrets stored in encrypted format.

• Create all the 3 collections in a MongoDB.

• Add the authentication keys in hashed format to the Auth collection. The hash function must be same as the one in utils/hash.py.

• Add the master password and master key in hashed form (in a single record) to the Master collection. The hash function must be same as the one in utils/hash.py.

• Open constants/database.py and specify all the constants such as mongo URI, satabase name, collection names etc.

• Open constants/key_config.py and specify all key generation constants. Leave it to the default values if unsure.

Usage

- All requests should be made over HTTPS to avoid sniffing of authentication keys, master password and master keys.

• Run the flask server:

  > python app.py
  

• Insert new secrets:

  > curl <url>/insert -H "auth-key: s2v6" -d "master-password=abcd&master-key=1234&domain=abc.com&username=abc@xyz.com&secret=secret1&secret=secret2..."
  

  Parameter	Type	Description
  auth-key	Header	Required. Authentication key for application.
  master-password	Body	Required. Master password for Cipher Key.
  master-key	Body	Required. Master key for Cipher Key.
  domain	Body	Required. Domain (ex. abc.com) for the record.
  username	Body	Required. Username (ex. abc@xyz.com) for the record.
  secret	Body	Required. List of secrets for the record. There must be atleast one secret parameter.

• Query for searching records by domain (and username) (No secret decryption take place in this query):

  > curl <url>/query -H "auth-key: s2v6" -d "master-password=abcd&master-key=1234&domain=abc.com&username=abc@xyz.com"
  

  Parameter	Type	Description
  auth-key	Header	Required. Authentication key for application.
  query-type	Body	Required. The value must be set to 1.
  master-password	Body	Required. Master password for Cipher Key.
  master-key	Body	Required. Master key for Cipher Key.
  domain	Body	Required. Domain (ex. abc.com) for the record.
  username	Body	Optional. Username (ex. abc@xyz.com) for the record.

• Query for decrypting secrets for a single record:

  > curl <url>/query -H "auth-key: s2v6" -d "query-type=1&master-password=abcd&master-key=1234&domain=abc.com&username=abc@xyz.com"
  

  Parameter	Type	Description
  auth-key	Header	Required. Authentication key for application.
  query-type	Body	Required. The value must be set to 2.
  master-password	Body	Required. Master password for Cipher Key.
  master-key	Body	Required. Master key for Cipher Key.
  domain	Body	Required. Domain (ex. abc.com) for the record.
  username	Body	Required if multiple matches are found. Username (ex. abc@xyz.com) for the record.

• Update for decrypting secrets for a single record:

  > curl <url>/update -H "auth-key: s2v6" -d "master-password=abcd&master-key=1234&domain=abc.com&username=abc@xyz.com&new-username=cba@xyz.com&new-secret=secret1&new-secret=secret2..."
  

  Parameter	Type	Description
  auth-key	Header	Required. Authentication key for application.
  master-password	Body	Required. Master password for Cipher Key.
  master-key	Body	Required. Master key for Cipher Key.
  domain	Body	Required. Domain (ex. abc.com) for the record.
  username	Body	Required if multiple matches are found. Username (ex. abc@xyz.com) for the record.
  new-username	Body	Optional. New Username (ex. cba@xyz.com) for the record.
  new-secret	Body	Optional. List of new secrets for the record. They will REPLACE all the existing secrets.

Cryptography

Cipher Key Generation Algorithm

The constants are defined in constants/key_config.py. The key generated by the following algorithm is used as the key and initialization vector for AES cipher (CBC mode).

1. The delta for caesar cipher is computed as the mod inverse of master key under self.MOD.

2. The randomizer is seeded with the master key.

3. The key is initialized to the master password.

4. The key is trimmed (if length is greater than CIHER_KEY_LENGTH) or padded (by repeatation, if length is less than CIHER_KEY_LENGTH).

5. For CIPHER_KEY_CHURN_COUNT number of times:

   a. Caesar cipher is applied to the key. b. The key is then randomized. c. The delta for caesar cipher is re-computed as the mod inverse of existing delta under self.MOD.

Hash Algorithm

SHA256 is used for hashing the authentication keys, master password and master key.

Contributing

We follow the "fork-and-pull" Git workflow.

1. Open an issue on this repository.
2. Fork the repo on GitHub.
3. Clone the project to your own machine.
4. Commit changes to your own branch.
5. Push your work back up to your fork.
6. Submit a Pull request mentioning the issue, so that we can review your changes.

NOTE: You would be responsible for merging upstream to master.

License

MIT License

Copyright (c) 2020 Sushant Kumar Gupta

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.