2183 words

11 minutes

Creating a Command Line Password Manager in Python with Encryption

2025-06-29

Project

Python

/

CLI

/

Security

/

Encryption

/

Tools

Developing a Command Line Password Manager in Python with Encryption#

Secure password management is a critical component of digital security. Reusing passwords or using weak ones across multiple services significantly increases the risk of account compromise. While graphical password managers offer convenience, a command-line alternative can be valuable for developers, system administrators, or those who prefer terminal-based workflows. Creating such a tool involves understanding data storage, user input handling, and, most importantly, robust encryption techniques.

A command-line password manager stores credentials (like usernames and passwords) securely within a file on the local system, accessible and manageable via terminal commands. Encryption is essential to protect this stored data from unauthorized access, even if the file is obtained by a third party. The process involves using a master password provided by the user to encrypt and decrypt the stored credentials.

Essential Concepts for Secure Password Management#

Building a secure password manager, even a simple command-line one, requires understanding several core cryptographic and programming concepts:

Master Password: A single, strong password the user remembers and uses to unlock the entire password database. The security of the stored credentials hinges entirely on the strength and secrecy of this master password.
Key Derivation Function (KDF): Passwords, especially user-chosen ones, are typically not suitable for direct use as cryptographic keys. KDFs are functions designed to derive a strong, fixed-length cryptographic key from a password or passphrase, often incorporating a salt and computationally intensive work factors (iterations, memory usage) to resist brute-force attacks. Examples include PBKDF2, Scrypt, and Argon2. Using a KDF is crucial; deriving a key directly from a password via simple hashing is insecure.
Salt: A unique, random piece of data associated with each password derivation. The salt is stored alongside the encrypted data (it does not need to be secret). Its purpose is to ensure that identical passwords produce different derived keys and encrypted outputs, preventing attackers from using precomputed tables (rainbow tables) and requiring them to crack each password individually.
Symmetric Encryption: An encryption method where the same key is used for both encryption and decryption. This is suitable for encrypting the bulk of the password data. Algorithms like AES (Advanced Encryption Standard) are widely used and considered secure when implemented correctly. The security depends entirely on keeping the encryption key secret.
Authenticated Encryption: A method that provides both confidentiality (encryption) and integrity/authenticity (ensuring the data hasn’t been tampered with). Using an authenticated encryption mode or combining a symmetric cipher with a message authentication code (MAC) is best practice. Libraries often provide this as a single function.
Secure Input: When prompting the user for the master password, the input should not be echoed to the terminal to prevent shoulder-surfing.

Choosing Python Libraries for Encryption#

Python offers several libraries for cryptographic operations. For building a password manager, the cryptography library is a recommended choice. It provides both high-level recipes (like Fernet) and low-level interfaces to common cryptographic primitives.

The cryptography library is developed and maintained by cryptographers and is designed with security best practices in mind. It is preferred over older or built-in modules like hashlib (which only provides hashing, not encryption) or deprecated ones.
Specifically, the cryptography.hazmat.primitives.kdf module contains implementations of KDFs like Scrypt and PBKDF2.
The cryptography.fernet module provides Fernet, an opinionated authenticated encryption scheme that is suitable for this purpose. It uses AES in CBC mode with HMAC for authentication and includes the IV (Initialization Vector) and timestamp within the ciphertext. Fernet keys are derived from a base URL-safe encoding, but the underlying secret key for Fernet needs to be a 32-byte value, which can be derived from the master password using a KDF.

Implementing the Command Line Password Manager#

Building the manager involves several steps, focusing on the core encryption/decryption and data handling logic. This outline assumes storing password entries as a Python dictionary that gets serialized (e.g., to JSON) before encryption.

Step 1: Project Setup and Dependencies#

Ensure Python is installed. Install the cryptography library using pip:

1
pip install cryptography

Step 2: Designing the Data Structure#

A simple structure to store multiple password entries is a dictionary where keys are service names (e.g., “google”, “github”) and values are dictionaries containing the username and password.

1
{
2
    "service_name_1": {
3
        "username": "user1",
4
        "password": "password123"
5
    },
6
    "service_name_2": {
7
        "username": "user2",
8
        "password": "anotherpassword"
9
    }
10
    # ... more entries
11
}

This dictionary will be converted to a string (e.g., JSON), encrypted, and saved to a file.

Step 3: Handling the Master Password and Key Derivation#

The master password is the user’s secret. It should not be stored. Instead, a cryptographic key is derived from it using a KDF and a salt. The salt must be stored alongside the encrypted data (or within the encrypted file header) so the correct key can be derived later for decryption.

Generate a Salt: A unique salt (at least 16 bytes is recommended) should be generated when the password manager is initialized or when the master password is first set.
```
1
import os
2
salt = os.urandom(16)
3
# Store this salt alongside the encrypted data
```

Derive the Key: Use a KDF like Scrypt or PBKDF2. Scrypt is often preferred due to its memory hardness. The KDF requires the master password (as bytes), the salt, and work factors (n, r, p for Scrypt; iterations for PBKDF2). These work factors should be chosen based on desired security levels and performance constraints. Higher values mean more security but slower derivation. The output is the derived key of the required length (e.g., 32 bytes for Fernet).

1
from cryptography.hazmat.primitives import hashes
2
from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
3
from cryptography.hazmat.backends import default_backend
4
import getpass # For secure password input
5

6
# --- When setting up or loading ---
7
# Assume master_password_str is obtained securely via getpass
8
master_password_bytes = master_password_str.encode('utf-8')
9
# Assume salt is loaded from file or generated if new
10

11
kdf = Scrypt(
12
    salt=salt,
13
    length=32, # For Fernet
14
    n=2**14,   # CPU/memory cost - adjust based on testing
15
    r=8,       # Block size
16
    p=1,       # Parallelization factor
17
    backend=default_backend()
18
)
19

20
try:
21
    derived_key = kdf.derive(master_password_bytes)
22
    # Use derived_key for encryption/decryption
23
except InvalidKeyException:
24
    # Master password was incorrect during derive/verify
25
    print("Error: Incorrect master password.")
26
    # Exit or handle failure

Verify the Key (Optional but Recommended during Decryption): KDF objects often have a verify method which performs the derivation and checks if the result matches a known derived key (though in a password manager, verifying against the data’s integrity after decryption is often sufficient, provided the KDF parameters and salt are stored correctly). The derive method is used when you need the key to encrypt or decrypt.

Step 4: Encrypting and Decrypting Data#

Using the derived key with Fernet:

Encryption: Serialize the data structure (e.g., to a JSON string), encode it to bytes, and then use the Fernet object created with the derived key to encrypt it.

1
import json
2
from cryptography.fernet import Fernet
3

4
# Assume data_dict is the Python dictionary of credentials
5
data_bytes = json.dumps(data_dict).encode('utf-8')
6

7
fernet = Fernet(derived_key)
8
encrypted_data = fernet.encrypt(data_bytes)
9

10
# Save salt and encrypted_data to a file

Decryption: Load the salt and encrypted data from the file. Obtain the master password from the user and derive the key using the same salt and KDF parameters. Use the Fernet object with this key to decrypt the data. Handle potential InvalidToken exceptions, which indicate either the wrong key was used (wrong master password) or the data was corrupted.

1
# Assume salt and encrypted_data are loaded from file
2
# Assume derived_key is obtained by deriving from user input master password and loaded salt
3

4
fernet = Fernet(derived_key)
5
try:
6
    decrypted_bytes = fernet.decrypt(encrypted_data)
7
    data_dict = json.loads(decrypted_bytes.decode('utf-8'))
8
    # Data successfully decrypted and loaded
9
except InvalidToken:
10
    print("Error: Could not decrypt data. Incorrect master password or corrupted data.")
11
    # Exit or handle failure

Step 5: File Handling#

The salt and encrypted data need to be stored persistently. A common approach is to store them together in a single file. A simple format could be storing the salt, followed by the encrypted data, perhaps separated by a delimiter or with the salt length indicated. Storing them as part of a structured format like JSON (with the salt encoded, e.g., in base64) is also feasible.

1
# Example structure for storage (can be JSON, or a custom binary format)
2
storage_data = {
3
    "salt": salt.hex(), # Store salt as hex or base64
4
    "encrypted_data": encrypted_data.hex() # Store encrypted data as hex or base64
5
}
6
# Write storage_data (as JSON string) to file
7
# When loading, read JSON, decode salt and encrypted_data back to bytes

Using hexadecimal or base64 encoding for binary data (like salt and ciphertext) when storing in a text format like JSON or a plain text file is standard practice.

Step 6: Building the Command-Line Interface#

Implement functions to handle user commands:

add: Prompt for service name, username, and password. Load data (decrypt), add the new entry, save data (encrypt).
get: Prompt for service name. Load data (decrypt), retrieve and display the username and password for the service.
list: Load data (decrypt), display all stored service names.
set-master-password: For initial setup or changing the master password. This requires re-encrypting the entire dataset with the new password and a new salt.

Use getpass.getpass() to securely prompt for the master password and sensitive credentials.

Example Snippet: Basic Get Function#

This illustrates the core load, decrypt, and retrieve logic.

1
import json
2
import getpass
3
import os
4
from cryptography.fernet import Fernet, InvalidToken
5
from cryptography.hazmat.primitives import hashes
6
from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
7
from cryptography.hazmat.backends import default_backend
8

9
DATA_FILE = 'passwords.dat' # File to store encrypted data and salt
10
KDF_N = 2**14 # Scrypt parameters
11
KDF_R = 8
12
KDF_P = 1
13
KEY_LENGTH = 32 # For Fernet
14

15
def load_data(master_password):
16
    """Loads and decrypts data from the storage file."""
17
    if not os.path.exists(DATA_FILE):
18
        return None # File doesn't exist
19

20
    try:
21
        with open(DATA_FILE, 'r') as f:
22
            storage_content = json.load(f)
23

24
        salt = bytes.fromhex(storage_content['salt'])
25
        encrypted_data = bytes.fromhex(storage_content['encrypted_data'])
26

27
        kdf = Scrypt(salt=salt, length=KEY_LENGTH, n=KDF_N, r=KDF_R, p=KDF_P, backend=default_backend())
28
        key = kdf.derive(master_password.encode('utf-8'))
29

30
        fernet = Fernet(key)
31
        decrypted_data_bytes = fernet.decrypt(encrypted_data)
32
        data_dict = json.loads(decrypted_data_bytes.decode('utf-8'))
33
        return data_dict
34

35
    except (FileNotFoundError, json.JSONDecodeError, InvalidToken, Exception) as e:
36
        # Catch file errors, JSON errors, incorrect password (InvalidToken), etc.
37
        print(f"Error loading data: {e}")
38
        return None
39

40
def get_password():
41
    """Prompts for service and displays credentials."""
42
    master_pwd = getpass.getpass("Enter master password: ")
43
    data = load_data(master_pwd)
44

45
    if data is None:
46
        print("Could not load or decrypt data.")
47
        return
48

49
    service = input("Enter service name: ").lower()
50

51
    if service in data:
52
        print(f"Service: {service}")
53
        print(f"Username: {data[service]['username']}")
54
        print(f"Password: {data[service]['password']}")
55
    else:
56
        print(f"Service '{service}' not found.")
57

58
# --- Basic execution example ---
59
# In a real application, this would be driven by command-line arguments
60
# if __name__ == "__main__":
61
#     # Example usage (requires DATA_FILE with salt and encrypted_data)
62
#     # Need functions for add, list, and initial setup first
63
#     get_password()

Security Considerations and Best Practices#

Developing a secure tool requires more than just using encryption functions.

Protect the Master Password: The master password is the single point of failure. Choosing a strong, unique master password is paramount.
Do Not Store the Master Password: The application must never store the master password itself, neither in memory long-term nor on disk. Prompt the user for it each time the application needs to access the decrypted data.
Securely Handle Derived Keys: The derived encryption key should be kept in memory only as long as needed and cleared afterwards if possible (though Python’s garbage collection makes deterministic memory clearing difficult).
Store Salt and KDF Parameters: The salt used for key derivation and the parameters for the KDF (N, R, P for Scrypt; iterations for PBKDF2) must be stored alongside the encrypted data. These are not secret, but are necessary to derive the correct key. Storing them with the encrypted data allows decryption without hardcoding these values.
Use a Trusted Cryptography Library: Implementing cryptographic primitives or protocols from scratch is highly discouraged. Use well-vetted libraries like Python’s cryptography.
File Permissions: Ensure the file storing the encrypted data has appropriate file system permissions to restrict access to the current user.
Backup: Consider secure backup strategies for the encrypted data file. Losing the file means losing all passwords. Losing the file and forgetting the master password makes the data unrecoverable.

Real-World Application#

A command-line password manager is particularly useful in specific scenarios:

Developer Workflows: Storing database credentials, API keys, or SSH passphrases locally for quick access within scripts or command-line tools. This avoids hardcoding sensitive information directly in scripts.
Server Management: Accessing credentials on servers or minimal environments where a full GUI browser extension or application is not available or desirable.
Automation: Integrating password retrieval into secure automation scripts (though careful consideration of how the master password is provided to the script is needed – avoiding plain text in scripts is crucial).
Offline Use: Providing access to passwords without relying on cloud synchronization, which might be a preference for some users concerned about cloud security.

Such a tool, while perhaps less feature-rich than commercial options (which offer sync, sharing, browser integration), provides a transparent, local-first approach with control over the underlying implementation details.

Key Takeaways#

Creating a secure command-line password manager requires robust encryption.
A master password is used to derive a strong encryption key using a Key Derivation Function (KDF) like Scrypt or PBKDF2.
A unique salt must be used with the KDF and stored alongside the encrypted data.
Symmetric encryption (e.g., AES via Fernet in cryptography) is used to protect the password data with the derived key.
The cryptography Python library is recommended for implementing secure encryption and key derivation.
Sensitive input like the master password should be handled securely using tools like getpass.
The master password should never be stored; it must be provided by the user for each access.
Security relies on a strong master password, correct use of cryptographic primitives, and protecting the encrypted data file.