Bitbucket Cloud SSH host key rotation - FAQ

Still need help?

The Atlassian Community is here for you.

Ask the community


 

Platform Notice: Cloud Only - This article only applies to Atlassian products on the cloud platform.

   

General Questions

Question

Response

Do I need to change my personal Bitbucket Cloud SSH key?

No, your personal SSH key as well as any deploy keys are not affected by this change.

What does a host key do?

The SSH protocol uses host keys to establish the identity of a trusted server for every SSH connection, like when a git pull establishes a SSH connection to bitbucket.org .

I’m no longer able to connect to Bitbucket Cloud using SSH, what gives?

On May 15, 2023 Bitbucket Cloud introduced two new SSH host keys for SSH clients to transition to ahead of its scheduled replacement of the old keys on June 20, 2023. Please refer to the blog post for additional details and instructions to safely re-establish your host key connections: https://bitbucket.org/blog/ssh-host-key-changes .

Alternatively, you can switch to Git over HTTPS if you prefer, by updating the remote repository URL:
https://support.atlassian.com/bitbucket-cloud/docs/change-the-remote-url-to-your-repository/

and configure authentication using an App Password:
https://support.atlassian.com/bitbucket-cloud/docs/using-app-passwords/

Should I be worried about Man-in-the Middle (MITM) attacks? What can I do to prevent that?

We don't believe there is an imminent and significant risk to customers. Continuing to allow clients to use a known host key gives users time to carefully and securely establish trust in the new keys.

By taking a measured approach, we are giving users time to transition to the new keys safely and with as little interruption to workflows as possible.

MITM attacks generally require the network to be compromised in some way. Avoiding insecure and untrusted networks (e.g., unencrypted WiFi connections) will limit your exposure to MITM attacks.

You can also make sure that you are connecting to the right host, by running:

ssh git@bitbucket.org host_key_info

and then making sure the fingerprint matches one of the updated fingerprints listed in our blog:

https://bitbucket.org/blog/ssh-host-key-changes

Why aren’t you rotating the RSA host key immediately

We don't believe there is an imminent and significant risk to customers. Continuing to allow clients to use a known host key gives users time to carefully and securely establish trust in the new keys.

By taking a measured approach, we are giving users time to transition to the new keys safely and with as little interruption as possible to workflows.

Do we need to make any changes to Bitbucket Pipelines config to be able to connect with Bitbucket?

No, the trusted host keys provided to your builds will be updated by Atlassian.

Will this affect my ability to clone repositories hosted on Bitbucket using my private image in pipelines?

If your team has chosen to configure an action using Bitbucket within their builds using the SSH protocol that has strict host key checking enabled, you will need to ensure that the host key is updated.
We recommend that you or your team verify whether you are utilizing SSH-based operations and update accordingly.

For more details on how you update the SSH key or configure one, please refer to our support documentation:

https://support.atlassian.com/bitbucket-cloud/docs/using-ssh-keys-in-bitbucket-pipelines/

Will this affect my ability to clone repositories hosted on Bitbucket to my private environment with runners

Self-hosted Runners use tokens issued during creation via the HTTPS protocol, this will not be affected by the host key change.
However, if a customer has chosen to configure an action using Bitbucket within their builds that has strict host key checking enabled, they will need to follow any steps appropriate for their environment in: https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/ and update their builds.

What do I need to do to ensure that once you rotate the RSA key I’m still able to connect to Bitbucket over SSH?

Please refer to our blog which provides detailed instructions about what actions you need to take.

In addition to the blog, we encourage you to fully review this FAQ and take recovery/mitigation steps appropriate to your SSH client. 

Since every environment and configuration can be different, our support team cannot provide a more individualized approach on how you should be configuring your systems, this falls outside of our area of expertise and is outside of our Support offerings.

Technical Questions

1. Q: Is there an available workaround if I’m unable to fix SSH connection? What other alternatives do I have to push my code to Bitbucket Cloud?

A: You can configure your connection to Bitbucket Cloud over HTTPS if you are not able to temporarily use SSH. You will first need to create an App Password associated with your user and then update the repository remote URL to use HTTPS protocol for GIT transactions.

https://support.atlassian.com/bitbucket-cloud/docs/using-app-passwords/

Alternatively, you may consider using Access tokens for authentication over HTTPS protocol:

https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/


2. Q: How do I know what SSH client I’m currently using?

A: If you are using MacOS, open the terminal and run ssh debug by using the command below:

ssh -v git@bitbucket.org

First line after the command should give you indication what SSH client you are currently using, example OpenSSH_9.0p1. Once you know the client, please refer to our blog for more details on how to update the Bitbucket Cloud host key or change SSH client configuration to restore your connection. If you are not able to identify which SSH client you are using, please feel free to reach out to our support team and we can help you.


3. Q: How can I verify which host key my client is using?

A: You can check which host key your client is using by using our host_key_info command and then comparing the host fingerprints specified in our blog https://bitbucket.org/blog/ssh-host-key-changes.

Example:

ssh git@bitbucket.org host_key_info
/Users/user-name/.ssh/config
Enter passphrase for key '/Users/user-name/.ssh/id_rsa': 
You are using host key with fingerprint:
ssh-rsa SHA256:zzXQOXSRBEiUtuE8AikJYKwbHaxvSc0ojez9YXaGp1A

WARNING: The host key your client is using will be removed in the near future.

Please configure your client to trust a new host key.

See https://bitbucket.org/blog/ssh-host-key-changes for more details.

4. Q: I have integration with Bitbucket Cloud and Bamboo and my Bamboo builds stopped running

A: If your Bamboo instance is configured to use trusted keys, your administrator will need to update your configuration to trust the new ECDSA/Ed25519 host keys as described in https://confluence.atlassian.com/bamboo0901/managing-trusted-keys-1188402906.html

To add the new keys, please refer to our blog post to obtain public keys:

https://bitbucket.org/blog/ssh-host-key-changes


5. Q: I’m using OpenSSH_XX and I’m no longer able to connect to bitbucket.org, over SSH protocol, what do I need to do to get the connection restored?

A: There are multiple options as to how you can update bitbucket.org fingerprint stored on your local machine.

  1. By removing the old fingerprint first and then simply running the SSH connection to Bitbucket from secure network and store the new fingerprint:

    $ ssh-keygen -R bitbucket.org && curl -L https://bitbucket.org/site/ssh >> ~/.ssh/known_hosts
  2.  Manually updating your known_hosts file stored on your machine by using an editor of your choice and updating the file with the new fingerprint.

We are happy to share a few resources to help you:

https://www.techrepublic.com/article/how-to-remove-or-update-a-single-entry-from-the-ssh-known-hosts-file/

https://help.dreamhost.com/hc/en-us/articles/217239087-Updating-host-keys

If none of these steps allow you to connect, then the problem may be unrelated to the host key changes.


6. Q: I’m using SSH-2.0-PuTTY_* and I’m no longer able to connect to Bitbucket Cloud server, over SSH protocol, what do I need to do to restore my connection after you rotated host key?

A:  If you are using PuTTY, then you will need to access the known_hosts file from the system registry.

  1. Follow this simplified step-by-step guide in order to delete the existing fingerprint for bitbucket.org from the registry
    https://www.simplified.guide/putty/edit-delete-ssh-hosts-keys

  2. Open Git Bash and run the following command

    ”C:\Program Files\PuTTY\plink.exe” git@bitbucket.org

    Make sure to replace the path with the path to plink.exe on your machine, if you have installed PuTTY in a different directory.

  3. You will see a message similar to the following:

    The host key is not cached for this server:  
      bitbucket.org  (port 22)
    You have no guarantee that the server is the computer
    you think it is.
    The server's ssh-ed25519 key fingerprint is:  
      ssh-ed25519 255 SHA256:ybgmFkzwOSotHTHLJgHO0QN8L0xErw6vd0VhFA9m3SM
    If you trust this host, enter "y" to add the key to
    PuTTY's cache and carry on connecting.
    If you want to carry on connecting just once, without
    adding the key to the cache, enter "n".
    If you do not trust this host, press Return to abandon the
    connection.
    Store key in cache? (y/n, Return cancels connection, i for more info)

  4. Before entering y, please make sure that the fingerprint you see in the message matches one of the fingerprints listed on this page, in the section SSH Host Keys:
    https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/

    After confirming that the fingerprint in the prompt matches the new one for bitbucket.org, enter y.

    The new key should now be added to the registry.


7. Q: I’m using SSH-2.0-JSCH-0.1.44 and I’m no longer able to connect to Bitbucket Cloud, over SSH protocol, what do I need to do to restore my connection after you rotated host key?

A: JSch prefers SHA_RSA and while connecting it will try to compare SHA-RSA fingerprint. Since the Bitbucket fingerprint has recently changed, you will need to update known_hosts file stored on your local machine.

There are multiple options around how you can update the Bitbucket fingerprint.

By removing the old one first and then simply running the SSH connection to Bitbucket from secure network and store the new fingerprint:

  1. Remove the old key(s) from known_hosts file and add the new in

    $ ssh-keygen -R bitbucket.org && curl -L https://bitbucket.org/site/ssh >> ~/.ssh/known_hosts
  2.  Manually update your known_hosts file stored on your machine by using an editor of your choice and updating the file with the new fingerprint.


For reference, please read more here: https://stackoverflow.com/questions/2003419/com-jcraft-jsch-jschexception-unknownhostkey


8. Q: We are using SourceTree for MAC and are connecting via SSH, will I need to make changes to my known_hosts file ?

SourceTree doesn’t support RSA key rotation. If you are a new user connecting for the first time after May 16, 2023, your SSH client will use our newly introduced ECDSA and Ed25519 keys, no manual action will be required on your part.

However if you are an existing user and have been connecting to Bitbucket via SourceTree over SSH for a while, you will need to manually update your .ssh/know_hosts file and add bitbucket.org new RSA fingerprint and remove the old one on or after June 20, 2023 as described in our blog https://bitbucket.org/blog/ssh-host-key-changes .


9. Q: We are using SourceTree for Windows and are connecting via SSH, will I need to make changes to my known_hosts file ?

f you have configured SourceTree to use OpenSSH as an SSH client

(from the menu Tools > Options > tab General), you will need to manually update your .ssh/know_hosts file, add the new fingerprint and remove the old one as described

in our blog https://bitbucket.org/blog/ssh-host-key-changes


If you have configured SourceTree to use PuTTY as an SSH client (from the menu Tools > Options > tab General), then you will need to access the known_hosts file from the system registry.

  1. Follow this simplified step-by-step guide in order to delete the existing fingerprint for bitbucket.org from the registry
    https://www.simplified.guide/putty/edit-delete-ssh-hosts-keys

  2. Open Git Bash and run the following command

    "C:\Users\username\AppData\Local\SourceTree\app-3.4.12\tools\putty\plink.exe" git@bitbucket.org


    Make sure to replace username with the name of your user on this comupter, and 3.4.12 with the version of SourceTree you are using.

  3. You will see a message similar to the following

    The host key is not cached for this server:  
      bitbucket.org  (port 22)
    You have no guarantee that the server is the computer
    you think it is.
    The server's ssh-ed25519 key fingerprint is:  
      ssh-ed25519 255 SHA256:ybgmFkzwOSotHTHLJgHO0QN8L0xErw6vd0VhFA9m3SM
    If you trust this host, enter "y" to add the key to
    PuTTY's cache and carry on connecting.
    If you want to carry on connecting just once, without
    adding the key to the cache, enter "n".
    If you do not trust this host, press Return to abandon the
    connection.
    Store key in cache? (y/n, Return cancels connection, i for more info)
  4. Before entering y, please make sure that the fingerprint you see in the message matches one of the fingerprints listed in this page, in the section SSH Host Keys:
    https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/

    1. After confirming that the fingerprint in the prompt matches the new one for bitbucket.org, enter y.

      The new key should now be added to the registry and you should be able to continue using SourceTree with PuTTY


10. Q: I used the instructions as per the blog and executed the following command:

$ ssh-keygen -R bitbucket.org && curl https://bitbucket.org/site/ssh >> ~/.ssh/known_hosts

The above command has successfully copied the bitbucket.org new keys to the known_hosts file. However, each time I connect to Bitbucket, I get the following warning and then need to press yes to proceed with the connection:

Warning: the ECDSA host key for 'bitbucket.org' differs from the key for the IP address '<IP Address>' Offending key for IP in ~/.ssh/known_hosts:<IP line number> Matching host key in ~/.ssh/known_hosts: <Bitbucket.org line number> Are you sure you want to continue connecting (yes/no)? yes

You may also see the error message below when typing ‘yes’ as a response to the message above.

error : stderr: No ECDSA host key is known for bitbucket.org and you have requested strict checking. Host key verification failed. fatal: Could not read from remote repository.


A: 
You can remove the entry associated with the IP from the known_hosts file. You can run the following command to remove the older entries and store the new one

$ ssh-keygen -R bitbucket.org && sed -i.old -e '/AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/d' ~/.ssh/known_hosts && curl https://bitbucket.org/site/ssh >> ~/.ssh/known_hosts

Once the above command is executed, you should be able to connect to Bitbucket without any issues and the warning message will not appear again.



11. Q: I’m using port 443 instead of default port 22 to connect to bitbucket.org over SSH and run my connection via altssh.bitbucket.org to connect to Bitbucket. How do I update my known_hosts file?

A: You can fetch the altssh.bitbucket.org and add it to a known_hosts file by running the following:

ssh-keygen -R '[altssh.bitbucket.org]:443' && curl https://bitbucket.org/site/ssh | sed 's/bitbucket.org/[altssh.bitbucket.org]:443/' >> ~/.ssh/known_hosts



Last modified on Jun 1, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.