git-crypt

Home

Using Git with Encryption (e.g., git-crypt)

If security is a major concern due to sensitive information, consider using git-crypt or GPG encryption with Git.

How to Use git-crypt:

Install git-crypt:

sudo apt-get install git-crypt

Initialize git-crypt in Your Repository: In your Git repository, run:

git-crypt init

Encrypt Specific Files or Directories: Create a .gitattributes file in the repository and list files to encrypt:

*.txt filter=git-crypt diff=git-crypt

Unlock the Repository on Another Machine: After cloning the repository on another machine, unlock it using:

git-crypt unlock /path/to/keyfile

This way, even if someone gains access to your repository, they won’t be able to view sensitive files without the decryption key.

When you run git-crypt init for the first time in a Git repository, it initializes the repository for use with git-crypt and sets up encryption. However, the actual encryption key that git-crypt uses is not saved in a separate, visible keyfile in your repository. Instead, the encryption key is stored securely in the .git directory, inside a special configuration file managed by git-crypt.

Key Storage Details

Location: The key is stored inside the .git directory of the repository.

File Path: .git/git-crypt/keys/default

Access: You won’t directly see this file unless you navigate into the .git directory and inspect the contents.

How Does the Key Management Work?

When you run git-crypt init, it generates a symmetric encryption key. This key is saved internally in the .git/git-crypt/keys directory of your Git repository. This key is not meant to be accessed directly. Instead, git-crypt uses GPG (if configured) to encrypt and manage the key for different users. Using git-crypt with GPG for Key Management If you add users with GPG (using git-crypt add-gpg-user <username>), git-crypt will encrypt this symmetric key with the GPG key of each user. This allows users to decrypt and access encrypted files if they have the corresponding GPG private key.

How to Back Up the Key File?

To decrypt the repository later (e.g., after a fresh clone), you’ll need the symmetric key if you are not using GPG keys. The best practice is to manually back up the symmetric key and share it securely with other collaborators.

You can extract and save the keyfile using the following command:

git-crypt export-key /path/to/your/keyfile

This command creates a keyfile that you can use to unlock the repository on other machines.

How to Use the Key File for Unlocking on Another Machine

If you want to unlock an encrypted repository on a different machine, you can use the exported keyfile:

git-crypt unlock /path/to/your/keyfile

This imports the symmetric key into git-crypt and decrypts the necessary files.

Important Considerations

Do Not Commit the Key File: Do not commit the exported keyfile (keyfile) to your repository. This would defeat the purpose of encryption and expose your files to anyone with access to the repository.

Store the Key Securely: If using keyfile-based encryption, store the exported keyfile in a secure location (e.g., a password manager or a secure cloud storage service) and share it securely with trusted collaborators.

Using GPG Is Recommended: If possible, use GPG for key management instead of exporting and managing the symmetric key manually. With GPG, you don’t have to worry about handling raw keys, as each user can unlock the repository using their private GPG key.

Summary After running git-crypt init, the symmetric key is stored inside .git/git-crypt/keys/default. Use git-crypt export-key /path/to/your/keyfile to create a backup keyfile. Use git-crypt unlock /path/to/your/keyfile to unlock the repository on another machine. For better key management, consider using GPG keys.