Git-Castle 🏰
Store Secrets in Github Securely with
git-castle
!
I was trying to work on a project with some fellow developers working on PCs. Unfortunately, existing tools are limited by platform (few work well on PC), require extremely convoluted setup/installers, or just plain-old don't work.
Introducing git-castle
! The easiest, lightweight way to manage secrets without the necessity for a full Key Management Solution.
Homepage
🏠⚙️ Install
One Line Setup! (Thank Goodness)
npm install -g git-castle
📝 Usage
⚡️ Quick Setup
git-castle initgit-castle add-user -u $YOUR_USERNAMEgit add .git-castle git-castle guard $PATHSPEC_TO_SECRET_FILES # Sets the specified file as a secret git add .git-castle-secrets git-castle add-hook # Recommended to reduce manual encrypting and decrypting on every commit. git-castle lockdown # Encrypts the files git add $PATHSPEC_TO_ENCRYPTED_SECRETS # Adds encrypted files to repositories.
When commiting your files, make sure you DO NOT commit the raw secret files 🔐. You should add those to your .gitignore
.
Files generated by git-castle
(ending with .secret
) can be safely checked-in. 💪
➕ Add A New User
On your Machine
# Inside the repository you wish to share with the user git-castle receive-key # After the New User is successfully added git add .git-castlegit commit -m "Added $USERNAME to git-castle"git push
Share your $RECEIVER_ID
with the New User.
On the New User's Machine
git-castle keygen -u $USERNAME -o $OUTFILE.cstl.pub# if -o is omitted, the public key will be stored in ~/.git-castle/$USERNAME.cstl.pub git-castle send-key -u $USERNAME -k $OUTFILE.cstl.pub -r $RECEIVER_ID # After the other user pushes the config update following the send-key operation: git clone $REMOTE_REPOSITORY # pull if already downloaded git-castle login -u $USERNAMEgit-castle reveal git-castle add-hook # Recommended for the future
📖 Commands
init
Initializes git-castle
in your repository. Run this first.
git-castle initgit add .git-castle
add-user
Adding Yourself
Do this first. There are two modes here:
- Create New Identity: if your
$username
does not exist in$HOME/.git-castle/$username.cstl
, this will create a new identity (RSA keys) in that directory. You can use this username across multiple repositories. - Add Existing Identity to Repo: if your username does exist locally (in
$HOME/.git-castle
), this script adds your RSA public key to the repository for encrypting the master key.
git-castle add-user -u $YOUR_USERNAME
Adding Others
When onboarding collaborators, you need to add their public key to the repository (they can create their key using git-castle keygen
).
Once you receive a {username}.cstl.pub
file from them, you can add them to this repository using the following command.
To securely share *.cstl.pub
files, check out git-castle send-key
below!
git-castle add-user -u $THEIR_USERNAME -k $PUBLIC_KEY_FILEPATH git add .git-castlegit commit -m "Added $USERNAME to git-castle"git push
login
After you've been added to a repository, you need to mark your local identity. You will have to do this after a collaborator adds you in add-user
.
This will fail if your private key has been moved or deleted. If this happens, repeat add-user
.
git pullgit-castle login -u $YOUR_USERNAME
keygen
This generates a set of RSA keys to use for sharing and encrypting secrets.
- The public key will be stored at the
$OUTFILE
(defaults to$HOME/.git-castle
). - The private key will be stored in
$HOME/.git-castle
git-castle keygen -u $USERNAME -o $OUTFILE
guard
This adds a pathspec or file to your .git-castle-secrets
file. Filepaths specified in this file will be encrypted when git-lockdown
runs.
git-castle guard $FILESgit-castle guard "$PATHSPEC"git add .git-castle-secrets # Examples git-castle guard data/secrets/file.keygit-castle guard data/secrets/**/*.key
lockdown
This encrypts all files specified in .git-castle-secrets
with the master_key
. Run this before every commit.
To automatically run this before every commit, run git-castle add-hook
git-castle lockdown
When adding a new secret, you need to explicitly mark the secret file. After running lockdown
make sure to commit the secret file to the repository so your collaborators can decrypt them.
git add $FILESgit add $PATHSPEC
reveal
To decrypt files specified in .git-castle-secrets
(and update your local copies of the keys), run git-castle reveal
. Run this after every pull.
To automatically run this after every pull, run git-castle add-hook
git-castle reveal
send-key
/ receive-key
🔐
git-castle
provides an easy way to securely share your public keys.
If you have access to the repository and want to add another user, run the following command.
git-castle receive-key>>> Accepting keys! Your Receiver ID is '${receiverID}'. Share this ID with a joiner.
Share the $receiverID
with the user you wish to grant access to.
As the new user, send the RSA key to the existing user using:
git-castle send-key -u $USERNAME -k $PUBKEY -r $RECEIVER_ID
Once the existing user pushes their config change to the repository, run the following to clone and download the secrets.
git clone $REMOTE_REPOSITORY # pull if already downloaded git-castle login -u $USERNAMEgit-castle reveal
Logs
To inspect how git-castle
is working under the hood and identify its action path, run git-castle -l $LEVEL $COMMAND
(or git-castle -vv $COMMAND
to use the info
log level).
We support the following log levels:
trace
debug
info
success
warn
error
fatal
How it Works
- The first encryptor generates the
master_key
which will be used to encrypt/decrypt all secrets stored in the repository. - To add another user, a
git-castle
user with access to themaster_key
creates anencrypted master_key (EMK)
using a 4096bit RSA key and stores it in the.git-castle
directory. That user can then access secrets by decrypting theEMK
using their RSA private key. - To add a new secret, a
git-castle
user simply encrypts the secret with themaster_key
and uploads the secret to the repository. All secrets are encrypted usingaes-256-cbc
.
Author
👤 Ajay Raj Merchia
- Website: ajaymerchia.com
- Github: @ajaymerchia
🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.
Show your support
Give a ⭐️ if this project helped you!
📝 License
Copyright © 2020 Ajay Raj Merchia.
This project is ISC licensed.
This README was generated with ❤️ by readme-md-generator