SSH-based Authentication

In general, SSH-based authentication works better than HTTPS + username/password authentication for use with Cargo and private registries, and should be preferred.

Adding SSH Keys in Shipyard.rs

The Git Index page provides the ability to add and remove SSH public keys to your git.shipyard.rs account directly from Shipyard.rs.

To add an SSH public key, provide a title, paste the public key content, and decide if you want the key to have read-only permissions (recommended):

Form to add a ssh public key to your git.shipyard.rs account

Form for adding an SSH public key

After an SSH public key has been added, it will be listed in the SSH Keys section:

List of ssh public keys associated with your account

List of SSH public keys associated with your account

Removing SSH Keys

To remove a SSH key, click the "trash" icon ( ) on the row corresponding to the SSH key you want to delete.

Adding a Public Key to Gitea

SSH key management can also be performed by logging into Gitea directly:

Adding a Public Key to Gitea

Logging into the Gitea account directly is not required, and generally not needed to use the registry server, but remains available for advanced configuration and account maintenance.

Cargo-friendly SSH Url

TLDR: the git index SSH url should have the format ssh://git.shipyard.rs/<org-slug>/crate-index.git for it to work with Cargo.

The example configuration generated for you on the Git Index includes the SSH url in the correct, cargo-friendly format.

Additional Details:

The SSH clone URL provided by Gitea in its UI needs to be tweaked slightly for Cargo to play nice with it.

Gitea gives the SSH url for Shipyard.rs's crate index repo as:

git@ssh.shipyard.rs:shipyard-rs/crate-index.git`

Also, passing that url to git clone works as expected:

$ git clone git@ssh.shipyard.rs:shipyard-rs/crate-index.git   # <- that works great

However, if you create an entry in ~/.cargo/config.toml that specifies that URL, it will not work:

# this will not work

[registries.shipyard-rs]
index = "git@ssh.shipyard.rs:shipyard-rs/crate-index.git"

Two changes to the format of the url must be changed for it to work with cargo:

  1. The ssh:// scheme needs to be added to the beginning of the url
  2. The colon character (:) following the host name must be changed to a slash (/)

With those changes, authentication will work using SSH url:

# correct format 

[registries.shipyard-rs]
index = "ssh://git@ssh.shipyard.rs/shipyard-rs/crate-index.git"

Cargo Security Advisory (CVE-2022-46176)

On Jan. 10, the Rust team announced that Cargo was being patched to fix a security vulnerability relating to how it cloned git repositories over SSH.

Specifically, a previous implementation had not verified the identity of SSH keys when performing clone, leaving it vulnerable to man-in-the-middle (MITM) attacks.

The issue was fixed in Rust 1.66.1.

One important aspect of the vulnerability is that it did not affect users who had set the git-fetch-with-cli setting to true, which prompts Cargo to use the local git binary to perform clones over SSH.

We strongly recommend setting the git-fetch-with-cli configuration setting, and all Shipyard.rs rustdoc builds are performed with the setting enabled.