OS Keyring (Recommended)
The OS keyring uses the native operative system's keyring to store the keys securely. This is the recommended and more secure way to store your Gitopia keys.
Typically, an operating system's credential sub-system handles password prompts, private key storage, and user sessions according to the user's password policies. Here is a list of the most popular operating systems and their respective passwords manager:
- macOS (since Mac OS 8.6): Keychain
- Windows: Credentials Management API
- GNU/Linux:
Follow the steps below to configure git to use your key from OS keyring.
We recommend that you use pass keyring instead of OS keyring for headless environments. OS keyring won't work in headless environment.
Gitopia Wallet
This method requires you to know your Gitopia wallet's 24-word mnemonic. If you need help finding your wallet's mnemonic Click here.
- Open the Terminal on your computer and add your key to the os keyring using the command given below.
git gitopia keys add <YOUR-KEY-NAME> --recover
Example:
git gitopia keys add gitopia-key --recover
- On executing the above command, you will be prompted to enter your wallet mnemonic. Type in your wallet's 24-word recovery phrase and press ENTER.
Your output would look similar to this:
❯ git gitopia keys add gitopia-key --recover
> Enter your bip39 mnemonic
music rose owner spy flight belt belt kitchen wrist axis zebra creek trouble they tool length ...
- address: gitopia1fpsu530cf6ysraxwe68hzvql9v4w0v87rg82qv
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8aBFL62PsLLGc0bIigsaGB4j+YCOOGetf82ENaQ0OOx"}'
type: local
Done
- Configure your gitopia key name in git config.
git config --global gitopia.key <YOUR-GITOPIA-KEY-NAME>
Example:
git config --global gitopia.key gitopia-key
In macOS, during git push, you will get prompted to enter your user password to access the OS Keyring.
To configure a new key, you need to remove the old gitopia.key from git config and then configure your new key name in git config. You can do this easily by using the below command:
git config --global --unset gitopia.key
Keplr Wallet
Users using Keplr wallet to sign in to Gitopia can push repositories to Gitopia only if they have configured git to use their Keplr wallet key from OS Keyring. Unlike Gitopia Wallet Users they cannot use the Gitopia Wallet File method.
1. Finding your Keplr Wallet Mnemonic Seed Phrase
- Before moving on to the main steps, you need to find your Keplr wallet Mnemonic Seed Phrase. For this, first, click on the Keplr extension icon on your toolbar to access your account and then click on the account icon as shown in the image.
- Now, click on the three dots next to your account name as shown.
- In the resulting selection menu, click on View Mnemonic Seed.
- You will be asked to type in your wallet password. Once filled, click on Confirm.
- Your Keplr wallet Mnemonic Seed Phrase will now be displayed. You will need this mnemonic to set up your key in OS keyring.
- Now that you have your mnemonic, the next steps are similar to that of Gitopia wallet. You just need to enter the Keplr wallet Mnemonic Seed Phrase when asked for the mnemonic.
2. Configure git to use your key from OS keyring
- Open the Terminal on your computer and add your key to the os keyring using the command given below.
git gitopia keys add <YOUR-KEY-NAME> --recover
Example:
git gitopia keys add gitopia-key --recover
- On executing the above command, you will be prompted to enter your wallet mnemonic. Type in your Keplr Wallet Mnemonic Seed Phrase and press ENTER.
Your output would look similar to this:
❯ git gitopia keys add gitopia-key --recover
> Enter your bip39 mnemonic
music rose owner spy flight belt belt kitchen wrist axis zebra creek trouble they tool length ...
- address: gitopia1fpsu530cf6ysraxwe68hzvql9v4w0v87rg82qv
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8aBFL62PsLLGc0bIigsaGB4j+YCOOGetf82ENaQ0OOx"}'
type: local
Done
- Configure your gitopia key name in gitconfig.
git config --global gitopia.key <YOUR-GITOPIA-KEY-NAME>
Example:
git config --global gitopia.key gitopia-key
To configure a new key, you need to remove the old gitopia.key from git config and then configure your new key name in git config. You can do this easily by using the below command:
git config --global --unset gitopia.key
Available backends for the keyring
The os backend
The os backend relies on operating system-specific defaults to handle key storage
securely. Typically, an operating system's credential sub-system handles password prompts,
private keys storage, and user sessions according to the user's password policies. Here
is a list of the most popular operating systems and their respective passwords manager:
- macOS: Keychain
- Windows: Credentials Management API
- GNU/Linux:
GNU/Linux distributions that use GNOME as default desktop environment typically come with
Seahorse. Users of KDE based distributions are
commonly provided with KDE Wallet Manager.
Whilst the former is in fact a libsecret convenient frontend, the latter is a kwallet
client.
os is the default option since operating system's default credentials managers are designed to meet user's most common needs and provide them with a comfortable experience without compromising on security.
Example:
❯ git gitopia keys add gitopia-key --recover --keyring-backend os
> Enter your bip39 mnemonic
music rose owner spy flight belt belt kitchen wrist axis zebra creek trouble they tool length ...
- address: gitopia1fpsu530cf6ysraxwe68hzvql9v4w0v87rg82qv
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8aBFL62PsLLGc0bIigsaGB4j+YCOOGetf82ENaQ0OOx"}'
type: local
Done
git config for os keyring:
git config --global gitopia.key gitopia-key
git config --global gitopia.backend os
The pass backend
The pass backend uses the pass utility to manage on-disk
encryption of key's sensitive data and metadata. Keys are stored inside gpg encrypted files
within app-specific directories. pass is available for the most popular UNIX
operating systems as well as GNU/Linux distributions.
Steps to setup keyring with pass backend:
- Generate a new
gpgkey without password (it won't work with password)
gpg --full-generate-key
- Initialize pass keyring with that gpg key (In this example, gitopia is the identifier/name of the gpg key)
pass init gitopia
- Add your gitopia key to the pass keyring
git gitopia keys add test-key --recover --keyring-backend pass
- Verify that the key has been created successfully
git gitopia keys list --keyring-backend pass
git config for pass keyring:
git config --global gitopia.key test-key
git config --global gitopia.backend pass
Basic Key Management
1. Create a new key by seed phrase
git gitopia keys add <YOUR-KEY-NAME> --recover
You can create a new key with the name gitopia-key as in the following example
Example:
git gitopia keys add gitopia-key --recover
2. List your keys
git gitopia keys list
Multiple keys can be created when needed. You can list all keys saved.
git gitopia keys list
Successfully migrated key test.info.
- address: gitopia10vazc96z8g032gqaaaeangd7zsydm5luzaayxt
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+I4HCUY/TJ/x/I7h2Ju64/cYfT/8ZeTRcyvDiCQo6qj"}'
type: local
- address: gitopia1qg7u0mvamw6k6pk9mn9ncxrwnpjdlgt7plapvq
name: test-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AxfC40EsEdUPeweFgVV9VL8lp0wwK+t46/4NE7lbv9tj"}'
type: local
Done
3. Retrieve key information
git gitopia keys show <YOUR-KEY-NAME>
You can retrieve key information by its name:
git gitopia keys show gitopia-key
- address: gitopia10vazc96z8g032gqaaaeangd7zsydm5luzaayxt
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+I4HCUY/TJ/x/I7h2Ju64/cYfT/8ZeTRcyvDiCQo6qj"}'
type: local
Done
4. Delete a key
git gitopia keys delete <key_name>
You can delete a key by its name.
git gitopia keys delete gitopia-key
Key reference will be deleted. Continue? [y/N]: y
Key deleted forever (uh oh!)
Done