GitLocker Usage Guide

🔐 Understanding Encryption Modes

GitLocker offers two main encryption modes, each optimized for different security requirements and use cases. Choosing the right encryption mode is crucial for your project's security.

✨ Simple Mode

Simple Mode is a password-based encryption approach that provides a balance of convenience and security for most users.

How It Works

1. User provides a password
2. GitLocker processes the password using the PBKDF2 algorithm to generate an encryption key
3. This key is used to encrypt/decrypt files
4. Key information is securely stored in the Git repository's configuration

Key Benefits

Suitable For

• Personal projects or small team collaboration
• Environments where passwords can be securely shared
• Scenarios that don't require complex key management

Simple Mode Variants

• AES-CTR-128-simple (Mode 0): AES-CTR encryption with 128-bit key
• AES-CTR-256-simple (Mode 1): AES-CTR encryption with 256-bit key
• AES-GCM-256-simple (Mode 2): AES-GCM encryption with 256-bit key (Recommended)

🔒 Normal Mode

Normal Mode provides more advanced security features, suitable for enterprises and teams with strict security requirements.

How It Works

1. GitLocker randomly generates a strong key
2. This key is used to encrypt/decrypt files
3. The key itself can optionally be encrypted with a password
4. The key is not stored in the Git repository and needs to be exported and managed separately

Key Benefits

Suitable For

• Enterprise environments and high-security requirement scenarios
• Projects with special key management requirements

Normal Mode Variants

• AES-CTR-256-normal (Mode 3): AES-CTR encryption with 256-bit key
• AES-GCM-256-normal (Mode 4): AES-GCM encryption with 256-bit key

💡 Mode Selection Recommendations

Decrypting on a New Device

• Simple Mode: Only need to provide the original password
• Normal Mode: Need the exported key file and the password protecting that key (if set)

⚠️ Important Notes

When using Normal Mode, be sure to export and securely save the key file (using the gitl exportkey command)

Loss of the key file without a backup will result in inability to decrypt data

The encryption mode can only be set during initialization and cannot be changed afterwards

📋 1. Encryption Initialization

Before using GitLocker, you need to initialize the encryption settings. Here are several common initialization methods:

🔑 1.1 Basic Initialization with Password

The simplest way to initialize is by providing a strong password:

gitl init -p your_password

# Output
Generating key...
Done!

💡 Tip: Choosing a strong password is crucial. It's recommended to use at least 12 characters, including uppercase and lowercase letters, numbers, and special symbols.

🛠️ 1.2 Initialization with Specific Encryption Mode

GitLocker supports five encryption modes that you can choose based on your security requirements:

gitl init -p your_password -m 2

# Output
Generating key with AES-GCM-256-simple mode...
Done!

📄 1.3 Initialization with Key File (Normal Mode)

If you already have an exported key file, you can use it for initialization:

gitl init -k keyfile.key

# Output
Initializing with key file...
Done!

⚠️ Note: Using a key file for initialization is typically used for Normal mode or when setting up an existing encrypted repository on a new device.

🗑️ 1.4 Clearing Encryption Configuration

If you need to remove encryption settings, you can use the -c option:

gitl init -c

# Output
Clearing encryption configuration...
Done!

⚠️ Warning: After clearing the encryption configuration, you may lose access to encrypted content if files haven't been decrypted.

🔒 2. File Encryption

GitLocker provides multiple file encryption methods to meet different security requirements and workflows.

🌐 2.1 Repository Encryption

It encrypts files when they are committed to the remote repository, while local copies remain unencrypted for easy editing.

gitl encrypt your_folder

# Output
Encrypting files for remote repository...
Encrypt done!

💡 Use Case: Remote encryption is ideal for team collaboration, allowing local editing while protecting sensitive data in the remote repository.

🔍 2.2 Selective Encryption by File Type

Including Specific File Types

Use the -I option to specify which file types to encrypt:

gitl encrypt src/ -I "cpp;h;c"

# Output
Encrypting only C/C++ source files...
Encrypt done!

Excluding Specific File Types

Use the -E option to exclude specific file types:

gitl encrypt src/ -E "obj;a;so"

# Output
Encrypting all files except object and library files...
Encrypt done!

📋 Tip: Selective encryption improves efficiency by only encrypting files that truly need protection, avoiding unnecessary encryption of binary or compiled files.

🖥️ 2.3 Using the Graphical Interface

For users who prefer a graphical interface, use the -g option:

gitl encrypt your_folder -g

# This will open a graphical interface for encryption operations

📊 3. Viewing Encryption Status

GitLocker provides simple commands to view the encryption status of files and directories, helping you understand which files are encrypted and how.

📂 3.1 Checking Encryption Status of Current Directory

gitl status

# Example output
R foo.txt
R bar.txt

Status Indicator Explanation

💡 Tip: Regularly checking encryption status ensures sensitive files are properly protected.

📄 3.2 Checking Encryption Status of Specific Files or Directories

You can specify a particular file or directory to view its encryption status:

gitl status src/main.cpp

# Example output
R src/main.cpp

🔍 Note: For directories, GitLocker will recursively display the encryption status of all files within.

🔑 4. Exporting Encryption Keys

For users of Normal mode, exporting keys is a critical step in ensuring data security. Even for Simple mode users, exporting keys as a backup is good practice.

📤 4.1 Basic Key Export

gitl exportkey ~/my-repo-key.key

# Output
Exporting key...
Done!

⚠️ Important: Exported key files should be stored securely, preferably in a safe offline location such as an encrypted USB drive.

🖥️ 4.2 Exporting Keys Using the Graphical Interface

For users who prefer a graphical interface, use the -g option:

gitl exportkey backup.key -g

# This will open a graphical interface for key export

🔐 Security Recommendations:

• Set a strong password to protect your key file
• Create multiple backups and store them in different secure locations
• Periodically verify the availability of your key files

🧩 5. Using Shell Extensions

GitLocker provides shell extensions for various operating systems, allowing you to easily work with encrypted files directly from your file manager without having to remember complex command-line parameters.

🪟 5.1 Windows Explorer Integration

In Windows Explorer, right-click on files or folders in a Git repository to access GitLocker functions:

💡 Tip: Windows Shell extension is automatically registered during GitLocker installation, no additional configuration required.

🐧 5.2 Linux Nautilus Integration

In the Nautilus file manager, right-click on files or folders to access the same functions through the GitLocker submenu:

🍎 5.3 macOS Finder Integration

In macOS Finder, right-click on files or folders to access the same functions through the GitLocker submenu:

⚙️ Setup Tip: When using for the first time, you may need to enable the GitLocker Finder extension in System Preferences.

📚 More Information

For detailed installation and configuration instructions for shell extensions, please refer to the GitLocker Handbook.