SHA256
Tidied up a bit.
This commit is contained in:
Discsearcher
@@ -1,206 +0,0 @@
|
||||
# Password Protection for markmywords
|
||||
|
||||
This document describes the password protection feature for encrypted markdown files in markmywords.
|
||||
|
||||
## Overview
|
||||
|
||||
When you encrypt a file with a password, it is automatically password-protected. Users must authenticate with the password before viewing the content in a browser.
|
||||
|
||||
**Important**: Only encrypted files (`.md.enc`) support password protection. Regular markdown files (`.md`) are always publicly viewable.
|
||||
|
||||
## Security Features
|
||||
|
||||
- **Bcrypt Hashing**: Passwords are hashed using bcrypt, a secure password hashing algorithm
|
||||
- **Session Management**: Once authenticated, users remain authenticated for that file in their session
|
||||
- **File Permissions**: Password database is stored with restricted file permissions (0600)
|
||||
- **No Plain Text**: Passwords are never stored in plain text
|
||||
- **HTTPS Ready**: Works seamlessly with HTTPS/SSL
|
||||
- **Encryption Compatible**: Works with encrypted files for defense-in-depth security
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Set a strong secret key for Flask sessions (REQUIRED for production)
|
||||
export FLASK_SECRET_KEY="your-very-secure-random-key"
|
||||
|
||||
# Optional: Set master admin password for programmatic file operations
|
||||
export MARKMYWORDS_ADMIN_PASSWORD="your-admin-password"
|
||||
```
|
||||
|
||||
## Using the CLI Tool
|
||||
|
||||
The `manage_content.py` script provides encryption and password protection management.
|
||||
|
||||
### Encrypt a File (Automatically Protected)
|
||||
|
||||
```bash
|
||||
python manage_content.py encrypt <filepath> <password>
|
||||
|
||||
# Example:
|
||||
python manage_content.py encrypt content/docs/secret-guide.md "mypassword123"
|
||||
```
|
||||
|
||||
This encrypts the file and automatically sets password protection. The same password is used for both encryption and browser authentication.
|
||||
|
||||
### Remove Password Requirement (Keep Encryption)
|
||||
|
||||
```bash
|
||||
python manage_content.py unprotect <filepath>
|
||||
|
||||
# Example:
|
||||
python manage_content.py unprotect content/docs/secret-guide.md.enc
|
||||
|
||||
# File stays encrypted but no password prompt in browser
|
||||
```
|
||||
|
||||
### List Protected Files
|
||||
|
||||
```bash
|
||||
# List all encrypted/protected files
|
||||
python manage_content.py list
|
||||
|
||||
# List encrypted files in a directory
|
||||
python manage_content.py list content/docs/
|
||||
```
|
||||
|
||||
### Check Protection Status
|
||||
|
||||
```bash
|
||||
python manage_content.py status <filepath>
|
||||
|
||||
# Example:
|
||||
python manage_content.py status content/docs/secret-guide.md.enc
|
||||
|
||||
# Output shows: Encrypted: Yes, Protected: Yes
|
||||
```
|
||||
|
||||
## Encrypted Files with Automatic Protection
|
||||
|
||||
When you encrypt a file, password protection is automatic:
|
||||
|
||||
```bash
|
||||
# Encrypt a file - automatically sets password protection
|
||||
python manage_content.py encrypt content/secret.md "mypassword"
|
||||
|
||||
# In browser:
|
||||
# 1. User navigates to file
|
||||
# 2. User sees password prompt (same password as encryption)
|
||||
# 3. User enters password
|
||||
# 4. File is decrypted and displayed with full markdown support
|
||||
```
|
||||
|
||||
The same password is used for both encryption and browser authentication.
|
||||
|
||||
## Using the API
|
||||
|
||||
### Authenticate for an Encrypted File
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/auth/docs/secret-guide.md.enc \
|
||||
-d "password=mypassword123"
|
||||
|
||||
# Response:
|
||||
# {"success": true, "redirect": "/view/docs/secret-guide.md.enc"}
|
||||
```
|
||||
|
||||
After successful authentication, the password is stored in the session and used to decrypt the file for display.
|
||||
|
||||
## Password Database
|
||||
|
||||
Passwords are stored in `/config/page_passwords.json` with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"content/path/to/file.md": {
|
||||
"protected": true,
|
||||
"password_hash": "$2b$12$...",
|
||||
"created_at": "2024-01-15T10:30:00.000000"
|
||||
},
|
||||
"content/path/to/encrypted.md.enc": {
|
||||
"encrypted": true,
|
||||
"protected": true,
|
||||
"password_hash": "$2b$12$...",
|
||||
"encrypted_at": "2024-01-15T10:30:00.000000",
|
||||
"created_at": "2024-01-15T10:30:00.000000"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important**: This file should be backed up and kept secure. The password hashes cannot be reversed, but the file itself should have restricted access.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **User Requests File**: User navigates to a protected file
|
||||
2. **Protection Check**: Application checks if file is password protected
|
||||
3. **Password Prompt**: If protected and user not authenticated, show password form
|
||||
4. **Authentication**: User enters password
|
||||
5. **Verification**: Password is checked against the stored bcrypt hash
|
||||
6. **Session Storage**: On success, file authentication is stored in user's session
|
||||
7. **Content Display**: Protected file content is displayed
|
||||
8. **Session Expiry**: Authentication expires when user's session expires (typically when browser is closed)
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Sensitive Documentation**: Encrypt internal documentation
|
||||
- **Private Notes**: Keep personal notes encrypted and password-protected
|
||||
- **Confidential Information**: Encrypt security guidelines, API keys, or business secrets
|
||||
- **Draft Content**: Encrypt unfinished or embargoed content with password protection
|
||||
- **Temporary Public Access**: Use `unprotect` to share encrypted content without password requirement
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Strong Passwords**: Use passwords with at least 8 characters including mixed case and numbers
|
||||
2. **Unique Passwords**: Use different passwords for different files
|
||||
3. **Regular Backups**: Backup the password database
|
||||
4. **Secure Secret Key**: Set a strong `FLASK_SECRET_KEY` environment variable
|
||||
5. **HTTPS**: Always use HTTPS in production
|
||||
6. **Share Carefully**: Share passwords through secure channels only
|
||||
7. **Monitor Access**: Check logs for authentication attempts
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Invalid password" error repeatedly
|
||||
|
||||
- Check that the password is exactly correct (case-sensitive)
|
||||
- Verify the file is actually protected: `python manage_content.py status content/path/to/file.md`
|
||||
|
||||
### Session expires too quickly
|
||||
|
||||
- The session expires based on Flask's session cookie settings
|
||||
- For persistent authentication longer than the browser session, consider implementing "Remember Me" functionality
|
||||
|
||||
### Lost access to protected file
|
||||
|
||||
- If you lose the password, you must unprotect the file using the CLI:
|
||||
```bash
|
||||
python manage_content.py unprotect content/path/to/file.md
|
||||
```
|
||||
- Then set a new password if desired
|
||||
|
||||
### Password database corruption
|
||||
|
||||
- If `/config/page_passwords.json` becomes corrupted, delete it and recreate protections:
|
||||
```bash
|
||||
rm /config/page_passwords.json
|
||||
python manage_content.py protect content/path/to/file.md <password>
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Never** share passwords via email or unencrypted channels
|
||||
- **Always** use HTTPS in production
|
||||
- **Regularly** audit which files are protected
|
||||
- **Securely** delete the password database when no longer needed
|
||||
- **Use** strong, random passwords generated by a password manager
|
||||
- **Backup** the password database in a secure location
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential future features:
|
||||
- Per-user authentication and roles
|
||||
- IP whitelisting for protected files
|
||||
- Audit logging of access attempts
|
||||
- Time-limited access links
|
||||
- Integration with external authentication systems (LDAP, OAuth, SAML)
|
||||
Reference in New Issue
Block a user