Technical Documentation

• 1: API documentation
• 2: Frontend customization
• 3: Server Options
• 4: Setting up as service (systemd)
• 5: Storage model

1 - API documentation

2 - Frontend customization

This document specifies the vault frontend customization capabilities implemented by the PersonalMediaVault backend, such as custom title, custom style or custom icons.

Custom title and frontend style

You can customize the vault frontend title and also setup custom CSS code if you need it. Simply go to Settings and then Advanced Settings.

The custom title will affect the page base title.

The custom CSS code can be used to do complex stuff, like changing colors or font sizes. Note that this is not a recommended feature, since the style is already optimized for both dark and light theme.

Custom favicon

By default, the PersonalMediaVault backend will serve the official icon.

You can change it by adding a custom favicon.ico into your vault folder.

You may have to clear cache to see the change, since the browser caches the icon to prevent requesting it multiple times.

Custom logos

Similar to the favicon, by default, the official logos will be served.

If you want to change them, you must create a folder inside your vault folder with the name img/icons.

You can copy the official ones and modify them.

3 - Server Options

This is a list of all available server options for the PersonalMediaVault backend.

Usage

In order to run the server, you can run the pmvd binary.

In order to see the options, use:

pmvd --help

In order to run the daemon, use:

pmvd --daemon [OPTIONS]

Here is the full list of available options:

Also, here is a list of available debug options:

Also, here is a list of environment variables to configure other options:

4 - Setting up as service (systemd)

This technical guide explains how to set up PersonalMediaVault as a service in a Linux machine using systemd.

Make sure to follow the installation guide on Linux before doing this. This guide expects you to have PersonalMediaVault already installed in your system.

The first step for creating a systemd service is to create an user for that service.

In order to create the user, run the following commands:

sudo groupadd pmv
sudo useradd -M pmv -g pmv
sudo usermod -L pmv

After you did this, now it’s time to create a folder to store the vault. In this guide we are going to use /var/pmv/vault.

Run the following commands:

sudo mkdir /var/pmv
sudo mkdir /var/pmv/vault
sudo chown -R pmv:pmv /var/pmv

Then, it’s time to create the service file, run the following command:

sudo nano /etc/systemd/system/pmv.service

Copy the following contents and save it:

[Unit]
Description=PersonalMediaVault
After=network.target auditd.service

[Service]
Type=simple
ExecStart=/usr/bin/pmvd --daemon --log-requests --skip-lock --vault-path /var/pmv/vault
User=pmv
Group=pmv
WorkingDirectory=/var/pmv/vault
Environment=FRONTEND_PATH=/usr/lib/pmv/www
Environment=FFMPEG_PATH=/usr/bin/ffmpeg
Environment=FFPROBE_PATH=/usr/bin/ffprobe
Environment=TEMP_PATH=/tmp/pmv
LimitNOFILE=infinity
LimitCORE=infinity
KillMode=process
StandardInput=null
StandardOutput=syslog
StandardError=syslog
Restart=always

[Install]
WantedBy=multi-user.target

Note: You may want to change some options. For that, make sure to check the following:

• Server options for PersonalMediaVault
• Systemd service file manual

After you saved the service file, and exited the editor, run the following command to enable the service, so it runs every time the system starts:

sudo systemctl enable pmv

Then, you can start it:

sudo systemctl start pmv

After it was started, you can check the logs with journalctl. Example:

sudo journalctl -u pmv

You can also check the service status with:

sudo systemctl status pmv

5 - Storage model

This is the documentation for the vault storage model, including the types of files it uses, their internal structure and the encryption algorithms used.

Use this document as reference for any software development that requires interaction with the vault files.

File types

The vault storage model uses different types of files:

• Lock file: File used to prevent multiple instances of PersonalMediaVault accessing the same vault.
• Unencrypted JSON files: Configuration files that do not contain any protected vault data.
• Encrypted JSON files: Used to store metadata.
• Index files: Used to store lists of media asset IDs, in order to make searching faster.
• Encrypted assets: Encrypted files containing the media assets. They can be single-file or multi-file.

Lock file

The lock file has the .lock extension.

It stores in plain text, a decimal number representing the PID of the current Process accessing the vault.

PersonalMediaVault backend should check for the existence of this file and the process before accessing the vault.

Unencrypted JSON files

Unencrypted JSON files have the .json extension.

They follow the JSON format. The schema varies depending on the specific file.

Since they are not encrypted, they just store configuration, like the port it should listen, or the encryption parameters.

Encrypted JSON files

Encrypted JSON files have the .pmv extension.

They take as a base a JSON plaintext, that is encrypted using an algorithm like AES.

They are binary files, with the following structure:

The system is flexible enough to allow multiple encryption algorithms. Currently, there are 2 supported ones:

• AES256_FLAT: ID = 1, Uses ZLIB (RFC 1950) to compress the data, and then uses AES with a key of 256 bits to encrypt the data, CBC as the mode of operation and an IV of 128 bits. This algorithm uses a header containing the following fields:

• AES256_FLAT: ID = 2, Uses AES with a key of 256 bits to encrypt the data, CBC as the mode of operation and an IV of 128 bits. This algorithm uses a header containing the following fields:

Index files

Index files have the .index extension.

They are sorted lists of media assets identifiers. They can store all the existing identifiers, or a fraction of them, for example, for a tag.

Thanks to being sorted, searching for a specific identifier can be achieved using binary search.

They are binary files, consisting of the following fields:

Encrypted assets

Encrypted assets have the .pma extension.

They stored one or multiple encrypted files.

They are also binary files, and they can be of two types:

• Single-File encrypted assets: They store a single file in size-limited chunks. Their name usually starts with s_.
• Multi-File encrypted assets: They store multiple smaller files. Their name usually starts with m_.

Single-File encrypted assets

These asset files are used to store a single and possibly big file in chunks, encrypted each chunk using the same method described by the Encrypted JSON files section.

They are binary files consisting of 3 contiguous sections: The header, the chunk index and the encrypted chunks.

The header contains the following fields:

After the header, the chunk index is stored. For each chunk the file was split into, the chunk index will store a metadata entry, withe the following fields:

After the chunk index, the encrypted chunks are stored following the same structure described in the Encrypted JSON files section.

This chunked structure allows to randomly access any point in the file as a low cost, since you don’t need to decrypt the entire file, only the corresponding chunks. This capability is specially great for video rewinding and seeking.

Multi-File encrypted assets

These asset files are used to store multiple smaller files, meant to be sorted and accessed by an index number.

They are binary files consisting of 3 contiguous sections: The header, the file table and the encrypted files.

The header contains the following fields:

After the header, a file table is stored. For each file stored by the asset, a metadata entry is stored, with the following fields:

After the file table, each file is stored following the same structure described in the Encrypted JSON files section.

This format is useful to store video previews, without the need to use too many files.

Vault folder structure

Media vaults are stored in folders. A vault folder may contain the following files and folders:

Media assets folder

The media assets are stored inside the media folder.

In order to prevent the folder size to increase too much, the assets are distributed evenly in 256 sub-folders. The sub-folder name for each media asset is calculated from its identifier, since it’s a 64 bit unsigned integer, the folder name is the identifier module 256, and the result turned into a 2 character hex lowercased string

Examples: 00, 01, 02…, fd, fe, ff.

Inside each subfolder, the assets are stored inside their own folders, named by turning their identifier into a decimal string. Examples:

• media_id=0 - Stored inside {VAULT_FOLDER}/media/00/0
• media_id=15 - Stored inside {VAULT_FOLDER}/media/0f/15

import (
    "fmt",
    "hex", 
    "path",
)

func GetMediaAssetFolder(vault_path string, media_id uint64) string {
    subFolderName := hex.EncodeToString([]byte{ byte(media_id % 256) });

    return path.Join(vault_path, "media", subFolderName, fmt.Sprint(media_id))
}

The media asset folder may contain up to 3 types of files:

• Media asset metadata file: Named meta.pmv and used to store metadata.
• Single-File assets: Named concatenating the s_ prefix and the asset ID in decimal, with .pma extension.
• Multi-File assets: Named concatenating the m_ prefix and the asset ID in decimal, with .pma extension.

Media asset metadata file

Each media asset folder must contain a file named meta.pmv, being an encrypted JSON file containing the metadata of the media asset.

The file contains the following fields:

The Resolution object has the following fields:

The Subtitle object has the following fields:

The TimeSplit object has the following fields:

The AudioTrack object has the following fields:

The Attachment object has the following fields:

The image notes asset is a JSON file, containing an array of ImageNote objects, with the following fields:

Tag indexes folder

When a tag is added to the vault, a new index file is created inside the tags folder, with a name made by concatenating the tag_ prefix with the tag identifier encoded in decimal, and the .index extension.

import (
    "fmt",
    "path",
)

func GetTagIndexPath(vault_path string, tag_id uint64) string {
	return path.Join(vault_path, "tags", "tag_"+fmt.Sprint(tag_id)+".index")
}

Each tag index file contains the list of media asset identifiers that have such tag.

Credentials file

The credentials file, named credentials.json is an unencrypted JSON file used to store the hashed credentials, along with the encrypted vault key.

The JSON file contains the following fields:

Each Account is an object with the following fields:

Currently, the following methods are implemented:

• AES256 + SHA256 + SALT16 - Identifier: aes256/sha256/salt16

AES256 + SHA256 + SALT16

This algorithm uses a random salt of 16 bytes (128 bits).

The password hash is calculated by using the SHA256 algorithm 2 times on the binary concatenation of the password (as UTF-8) and the random salt:

import (
    "sha256"
)

func ComputePasswordHash(password string, salt []byte) []byte {
	firstHash := sha256.Sum256(append([]byte(password), salt...))
	secondHash := sha256.Sum256(firstHash[:])
	return secondHash[:]
}

The vault ket is encrypted using the AES256 algorithm, using the system defined in the Encrypted JSON files section. Specifically using the AES256_FLAT mode.

The key for the encryption is calculated by hashing with SHA256 the the binary concatenation of the password (as UTF-8) and the random salt:

import (
    "sha256"
)

func ComputeAESEncryptionKey(password string, salt []byte) []byte {
	passwordHash := sha256.Sum256(append([]byte(password), salt...))
	return passwordHash[:]
}

Media ID tracker

The media ID tracker file, named media_ids.json is an unencrypted JSON file used to store the number of used media identifiers, very important to prevent duplicated identifiers.

The JSON file has just one field:

Tasks tracker

The task tracker file, named tasks.json is an unencrypted JSON file used to store the number of used task identifiers, in order to prevent duplicates. It also stores the pending tasks, in order to continue them in case of a vault restart.

The JSON file contains the following fields:

The PendingTask objects have the following fields:

Albums file

The albums file, named albums.pmv is an encrypted JSON file used to store the list of existing albums in the vault.

The file has the following fields:

The Album object has the following fields:

Tags file

The tags file, named tag_list.pmv is an encrypted JSON file used to store the list of existing tags in the vault.

The file has the following fields:

User configuration file

The user configuration file, named user_config.pmv is an encrypted JSON file used to store the vault configuration set by the user.

The file has the following fields:

The VideoResolution object has the following fields:

The ImageResolution object has the following fields:

Main index file

The main index file, named main.index is an index file containing every single media asset identifier existing in the vault.

This file is used to check if a media asset exists and to perform searches when a tag filter is not specified.