114 lines
3.3 KiB
Markdown
114 lines
3.3 KiB
Markdown
# FileVault
|
|
|
|
[](https://git.unturf.com/engineering/unturf/filevault/-/commits/main)
|
|
[](https://en.wikipedia.org/wiki/Public_domain)
|
|
|
|
FileVault is a class for managing a hash directory tree of files on a filesystem.
|
|
|
|
A Vault will:
|
|
|
|
* Create a hash directory tree of custom depth
|
|
* Spread out files to keep CLI snappy when traversing the tree
|
|
* Scale to hundreds of thousands of files
|
|
* Obfuscate directory paths and filenames
|
|
|
|
## How to Install
|
|
|
|
### From GitLab
|
|
```bash
|
|
pip install git+https://git.unturf.com/engineering/unturf/filevault.git
|
|
```
|
|
|
|
### From Source
|
|
```bash
|
|
git clone https://git.unturf.com/engineering/unturf/filevault.git
|
|
cd filevault
|
|
pip install .
|
|
```
|
|
|
|
## How to Use
|
|
|
|
### Creating a Vault
|
|
|
|
```python
|
|
from filevault import Vault
|
|
|
|
# Default vault (creates a 'vault' directory in current working directory)
|
|
v = Vault()
|
|
|
|
# Custom vault
|
|
v = Vault(
|
|
vaultpath="/tmp/for-test", # Directory to store files
|
|
depth=2, # Depth of directory structure
|
|
salt="your-secret-salt" # Change this for production!
|
|
)
|
|
```
|
|
|
|
### Vault Parameters
|
|
|
|
- **vaultpath**: Where should the tree be created? (default: 'vault' in current directory)
|
|
- **depth**: How deep should the tree span? (default: 3 directories deep)
|
|
- **salt**: Custom salt for unique and secure hashing (default: 'changeme')
|
|
|
|
### Examples
|
|
|
|
#### Create a hashed filename
|
|
```python
|
|
# Create a consistent filename
|
|
filename = v.create_filename("my-document", ".pdf")
|
|
# Example: "3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.pdf"
|
|
|
|
# Get absolute path
|
|
abs_path = v.create_filename("my-document", ".pdf", absolute=True)
|
|
# Example: "/tmp/for-test/3/9/39938...e32.pdf"
|
|
```
|
|
|
|
#### Create a random filename
|
|
```python
|
|
# Random filename
|
|
random_file = v.create_random_filename(".png")
|
|
# Example: "6/1/6169d6ee0ac0bc63ab667fb94d9cc747df0c03596ac43e24a51b3517d74bdc42.png"
|
|
```
|
|
|
|
## Full Example
|
|
|
|
```python
|
|
from filevault import Vault
|
|
|
|
# Create vault instance
|
|
v = Vault(vaultpath="/tmp/for-test", depth=2, salt="sugar")
|
|
|
|
# Create and print a filename
|
|
print(v.create_filename("my-first-file", ".png"))
|
|
# Output: 3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.png
|
|
|
|
# Same input produces same output
|
|
print(v.create_filename("my-first-file", ".png"))
|
|
# Output: 3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.png
|
|
|
|
# Get absolute path
|
|
print(v.create_filename("my-first-file", ".png", absolute=True))
|
|
# Output: /tmp/for-test/3/9/3993817d4f9b3867c6db29b23c9d2ff9bb8a87d89426002adbb6ed34289d9e32.png
|
|
|
|
# Generate a random filename
|
|
print(v.create_random_filename())
|
|
# Output: 6/1/6169d6ee0ac0bc63ab667fb94d9cc747df0c03596ac43e24a51b3517d74bdc42
|
|
```
|
|
|
|
## About the Salt
|
|
|
|
The `salt` parameter is used to add uniqueness and security to the generated file paths:
|
|
|
|
- Prevents easy guessing of file paths
|
|
- Makes directory traversal attacks more difficult
|
|
- Ensures different applications generate different paths for the same filenames
|
|
|
|
**Important**: Always change the default salt value in production environments.
|
|
|
|
## License
|
|
|
|
This project is released into the [Public Domain](https://en.wikipedia.org/wiki/Public_domain).
|
|
|
|
## Original Author
|
|
|
|
Russell Ballestrini ([russell@ballestrini.net](mailto:russell@ballestrini.net))
|