Appendix: Git Authentication - The Cargo Book

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Git Authentication

Cargo supports some forms of authentication when using git dependencies and registries. This appendix contains some information for setting up git authentication in a way that works with Cargo.

If you need other authentication methods, the `net.git-fetch-with-cli` config value can be set to cause Cargo to execute the `git` executable to handle fetching remote repositories instead of using the built-in support. This can be enabled with the `CARGO_NET_GIT_FETCH_WITH_CLI=true` environment variable.

> Note: Cargo does not require authentication for public git dependencies so if you see an authentication failure in that context, ensure that the URL is correct.

## HTTPS authentication

HTTPS authentication requires the `credential.helper` mechanism. There are multiple credential helpers, and you specify the one you want to use in your global git configuration file.

    # ~/.gitconfig

    [credential]
    helper = store

Cargo does not ask for passwords, so for most helpers you will need to give the helper the initial username/password before running Cargo. One way to do this is to run `git clone` of the private git repo and enter the username/password.

> Tip:
> macOS users may want to consider using the osxkeychain helper.
> Windows users may want to consider using the GCM helper.

> Note: Windows users will need to make sure that the `sh` shell is available in your `PATH`. This typically is available with the Git for Windows installation.

## SSH authentication

SSH authentication requires `ssh-agent` to be running to acquire the SSH key. Make sure the appropriate environment variables are set up (`SSH_AUTH_SOCK` on most Unix-like systems), and that the correct keys are added (with `ssh-add`).

Windows can use Pageant (part of PuTTY) or `ssh-agent`. To use `ssh-agent`, Cargo needs to use the OpenSSH that is distributed as part of Windows, as Cargo does not support the simulated Unix-domain sockets used by MinGW or Cygwin. More information about installing with Windows can be found at the Microsoft installation documentation and the page on key management has instructions on how to start `ssh-agent` and to add keys.

> Note: Cargo does not support git’s shorthand SSH URLs like `git@example.com:user/repo.git`. Use a full SSH URL like `ssh://git@example.com/user/repo.git`.

> Note: SSH configuration files (like OpenSSH’s `~/.ssh/config`) are not used by Cargo’s built-in SSH library. More advanced requirements should use `net.git-fetch-with-cli`.

### SSH Known Hosts

When connecting to an SSH host, Cargo must verify the identity of the host using “known hosts”, which are a list of host keys. Cargo can look for these known hosts in OpenSSH-style `known_hosts` files located in their standard locations (`.ssh/known_hosts` in your home directory, or `/etc/ssh/ssh_known_hosts` on Unix-like platforms or `%PROGRAMDATA%\ssh\ssh_known_hosts` on Windows). More information about these files can be found in the sshd man page. Alternatively, keys may be configured in a Cargo configuration file with `net.ssh.known-hosts`.

When connecting to an SSH host before the known hosts has been configured, Cargo will display an error message instructing you how to add the host key. This also includes a “fingerprint”, which is a smaller hash of the host key, which should be easier to visually verify. The server administrator can get the fingerprint by running `ssh-keygen` against the public key (for example, `ssh-keygen -l -f /etc/ssh/ssh_host_ecdsa_key.pub`). Well-known sites may publish their fingerprints on the web; for example GitHub posts theirs at https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints.

Cargo comes with the host keys for github.com built-in. If those ever change, you can add the new keys to the config or known_hosts file.

> Note: Cargo doesn’t support the `@cert-authority` or `@revoked` markers in `known_hosts` files. To make use of this functionality, use `net.git-fetch-with-cli`. This is also a good tip if Cargo’s SSH client isn’t behaving the way you expect it to.