Security
Vi Mongo provides optional password encryption to secure your MongoDB connection credentials stored in the configuration file. This feature helps protect sensitive information even if your configuration files are compromised.
Encryption Key Setup
Generating an Encryption Key
For now Vi Mongo can generate a secure encryption key using the --gen-key
flag:
This command will output a randomly generated 256-bit encryption key in hexadecimal format, along with instructions on how to use it:
Using Environment Variable
The most common approach is to set the encryption key as an environment variable. You have several options for managing this securely:
Permanent Setup (easy way)
For persistent access across all sessions, add the variable to your shell profile:
Then reload your shell configuration:
Or you can store it in some .env
, add proper permissions and source it, which can be consider more secure.
Session-only Usage
For temporary use without permanent storage, set the variable only when running Vi Mongo:
This approach ensures the key is only available during the application runtime and doesn't persist in your shell history or environment.
Using Key File
Alternatively, you can store the key in a file and reference it in two ways:
Via Command Line Flag
Via Configuration File
Add the key file path to your config.yaml
:
The key file should contain only the encryption key (no additional formatting):
How Encryption Works
With Encryption Key
When an encryption key is available (via environment variable or file):
- Adding Connections: Passwords are automatically encrypted before being stored in the configuration file
- Using Connections: Passwords are decrypted in memory when connecting to MongoDB
- Configuration Storage: Only encrypted passwords are stored in
config.yaml
Without Encryption Key
When no encryption key is configured:
- Adding Connections: Passwords are stored in plain text in the configuration file
- Using Connections: Passwords are used directly without decryption
- Security Risk: Credentials are visible to anyone with access to the configuration file
Security Best Practices
File Permissions
If using a key file, ensure it has restrictive permissions:
Migration Between Encrypted and Unencrypted
Adding Encryption to Existing Connections
If you have existing unencrypted connections and want to add encryption:
- Generate an encryption key:
vi-mongo --gen-key
- Set up the key (environment variable or file)
- Delete and re-add your connections - they will be automatically encrypted
Connection Compatibility
Important Compatibility Rules
- Encrypted connections: Connections added with encryption enabled cannot be used without the same encryption key
- Unencrypted connections: Connections added without encryption work regardless of encryption key presence but only if added as
uri
- Mixed configurations are supported: You can have both encrypted and unencrypted connections in the same configuration file
Troubleshooting Encryption Issues
If you encounter authentication failures when connecting:
- Verify the encryption key: Ensure the same key used to encrypt the password is available
- Check key format: Ensure the key file contains only the hexadecimal key with no extra whitespace or formatting
- Environment variables: Verify the
VI_MONGO_SECRET_KEY
environment variable is set correctly in current shell session - Key file permissions: Ensure Vi Mongo can read the key file (check file permissions)
Configuration Example
Example config.yaml
with encryption key path: