Bitbucket Support

This page describes how to create SSH keys.

SSH keys can be used to establish a secure connection with Bitbucket Data Center for:

when you are performing Git operations from your local machine
when another system or process needs access to repositories in Bitbucket (for example your build server)

The SSH key needs to be added to Bitbucket, and your Bitbucket administrator must have enabled SSH access to Git repositories before you can make use of the key.

Bitbucket supports the following SSH key types:

ED25519
RSA2
ECDSA
DSA (we recommend you use other key types)
ED25519-SK
ECDSA-SK

You can use an existing SSH key with Bitbucket if you want, in which case you can go straight to either SSH user keys for personal use or SSH access keys for system use.

Related pages:

Creating an SSH key on Windows

1. Check for existing SSH keys

You should check for existing SSH keys on your local computer. You can use an existing SSH key with Bitbucket if you want, in which case you can go straight to either SSH user keys for personal use or SSH access keys for system use.

Open a command prompt, and run:

cd %userprofile%/.ssh

If you see "No such file or directory", then there aren't any existing keys: go to step 3.
Check to see if you have a key already:
```
dir id_*
```
If there are existing keys, you may want to use those: go to either SSH user keys for personal use or SSH access keys for system use.

2. Back up old SSH keys

If you have existing SSH keys, but you don't want to use them when connecting to Bitbucket, you should back those up.

In a command prompt on your local computer, run:

mkdir key_backup
copy id_ed25519* key_backup

3. Generate a new SSH key

If you don't have an existing SSH key that you wish to use, generate one as follows:

Log in to your local computer as an administrator.
In a command prompt, run:
```
ssh-keygen -t ed25519 -C "your_email@example.com"
```
Note: If you're using a legacy system that doesn't support the ED25519 algorithm, run:
```
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```
Associating the key with your email address helps you to identify the key later on.
Note that the ssh-keygen command is only available if you have already installed Git (with Git Bash).
You'll see a response similar to this:
```
C:\Users\fperez>ssh-keygen -t ed25519 -C "your_email@example.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/c/Users/fperez/.ssh/id_ed25519):
```
Just press <Enter> to accept the default location and file name. If the .ssh directory doesn't exist, the system creates one for you.

Enter, and re-enter, a passphrase when prompted. The whole interaction will look similar to this:

C:\Users\fperez>ssh-keygen -t ed25519 -C "your_email@example.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/c/Users/fperez/.ssh/id_ed25519):
Created directory '/c/Users/fperez/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in c/Users/fperez/.ssh/id_ed25519.
Your public key has been saved in c/Users/fperez/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:wvaHYeLtY6+DlvV5sFZgDi3abcdefghijklmnopqrstuvw your_email@example.com

You're done and you can now go to either SSH user keys for personal use or SSH access keys for system use.

Creating an SSH key on Linux & macOS

1. Check for existing SSH keys

You should check for existing SSH keys on your local computer. You can use an existing SSH key with Bitbucket if you want, in which case you can go straight to either SSH user keys for personal use or SSH access keys for system use.

Open a terminal and run the following:

cd ~/.ssh

If you see "No such file or directory, then there aren't any existing keys: go to step 3.
Check to see if you have a key already:
```
ls id_*
```
If there are existing keys, you may want to use them; go to either SSH user keys for personal use or SSH access keys for system use.

2. Back up old SSH keys

If you have existing SSH keys, but you don't want to use them when connecting to Bitbucket, you should back those up.

Do this in a terminal on your local computer, by running:

mkdir key_backup
cp id_ed25519* key_backup

3. Generate a new key

If you don't have an existing SSH key that you wish to use, generate one as follows:

Open a terminal on your local computer and enter the following:

ssh-keygen -t ed25519 -C "your_email@example.com"

Note: If you're using a legacy system that doesn't support the ED25519 algorithm, use:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Associating the key with your email address helps you to identify the key later on.

You'll see a response similar to this:

fperez@homemac ~ % ssh-keygen -t ed25519 -C fperez@email.com
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/fperez/.ssh/id_ed25519):

Just press <Enter> to accept the default location and file name. If the .ssh directory doesn't exist, the system creates one for you.

Enter, and re-enter, a passphrase when prompted.
The whole interaction will look similar to this:

fperez@homemac ~ % ssh-keygen -t ed25519 -C fperez@email.com
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/fperez/.ssh/id_ed25519): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /Users/fperez/.ssh/id_ed25519.
Your public key has been saved in /Users/fperez/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:gTVWKbn41z6JgBNu3wYjLC4abcdefghijklmnopqrstuvwxy fperez@email.com
The key's randomart image is:
+--[ED25519 256]--+
|==+.    +o..     |
|.oE.   +o..      |
|    . ...o       |
|     .o...       |
|     oo+S  .     |
|  + ..B = . .    |
|.+.+.oo+ * o .   |
|o++.o+  . + +    |
|B+ o.    .   .   |
+----[SHA256]-----+
fperez@homemac ~ %

You're done and you can now go to either SSH user keys for personal use or SSH access keys for system use.

Creating a new SSH key for a hardware security key

SSH keys for hardware authenticators are a safer alternative to traditional SSH keys and protect you from accidental private key exposure or theft. You tap the hardware authenticator when you need to perform a Git operation, which provides evidence of user presence.

1. Before you start

Before generating a security key based SSH key, make sure you meet the following pre-requisites.

OpenSSH

To generate an SSH key backed by a hardware authenticator, you need to have a version of OpenSSH later than 8.2p1.

Bitbucket Data Center

Bitbucket Data Center supports the use of security key based SSH keys since version 8.13. If your environment consists of mirrors, they must be updated to this version too. Otherwise, you won’t be able to use the key you registered on an upstream for Git SSH operations via the mirror.

Hardware authenticator

You need a compatible hardware authenticator to back the new SSH key. You can choose between Yubikey, Nitrokey, Solokey, etc.

2. Generate the key

You can select from two algorithms:

ecdsa-sk based on ECDSA keys
ed25519-sk based on ED25519 keys

You can generate ecdsa-sk on most keys but ed25519-sk is generally supported only on newer hardware.

In both cases, the only supported key length is 256 bits. To generate a key of the chosen type:

Make sure your hardware authenticator is plugged in.
Generate the SSH key with ssh-keygen using the following command. The -C argument is optional and specifies a comment to identify the key.
```
ssh-keygen -t ed25519-sk -C <your-email>
```
If the command fails, your hardware authenticator might not support the ED25519 algorithm. Repeat the command replacing ed25519-sk with ecdsa-sk.
When you're prompted, touch the button on your hardware authenticator to confirm user presence.

You can optionally choose a passphrase for the key.

> Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

After the SSH key has been generated successfully, you can copy the public key and register it with Bitbucket Data Center like any other SSH key, following the instructions:

FAQ

Find answers to frequently asked questions about the generation of security key based SSH keys.

I receive an error while performing Git operations with these keys. How do I resolve it?

The most common reason for seeing the Permission denied (Public Key) error is that the key is simply not being used to perform the authentication. Check the following:

The user presence is confirmed while performing the Git command.
You don’t have a large number of generated keys. If you do, try removing unused keys.

I generated and registered an SSH key but can’t perform Git operations using it via the mirror

If you receive the Permission denied (Public Key) error while performing a Git command with a registered key, the mirror you’re using might not have been updated to version 8.13. Contact the administrator about the issue.

Do I have to tap the key every time I perform a Git operation?

Yes, you do. While OpenSSH has the option to generate a key that doesn’t require a tap, Bitbucket Data Center doesn’t support such keys. We also don’t recommend using the keys that don’t require a tap on a hardware authenticator because their security is comparably low.

Bitbucket Support

Knowledge base

Products

Jira Software

Jira Service Management

Jira Work Management

Confluence

Bitbucket

Resources

Documentation

Community

Suggestions and bugs

Marketplace

Billing and licensing

Creating SSH keys

Using SSH keys to secure Git operations

On this page

Still need help?

Creating an SSH key on Windows

1. Check for existing SSH keys

2. Back up old SSH keys

3. Generate a new SSH key

Creating an SSH key on Linux & macOS

1. Check for existing SSH keys

2. Back up old SSH keys

3. Generate a new key

Creating a new SSH key for a hardware security key

1. Before you start

OpenSSH

Bitbucket Data Center

Hardware authenticator

2. Generate the key

FAQ

I receive an error while performing Git operations with these keys. How do I resolve it?

I generated and registered an SSH key but can’t perform Git operations using it via the mirror

Do I have to tap the key every time I perform a Git operation?

Page

Viewport

Confluence

Versions

Creating SSH keys

Using SSH keys to secure Git operations

On this page

Related content

Still need help?

Creating an SSH key on Windows

1. Check for existing SSH keys

2. Back up old SSH keys

3. Generate a new SSH key

Creating an SSH key on Linux & macOS

1. Check for existing SSH keys

2. Back up old SSH keys

3. Generate a new key

Creating a new SSH key for a hardware security key

1. Before you start

OpenSSH

Bitbucket Data Center

Hardware authenticator

2. Generate the key

FAQ

I receive an error while performing Git operations with these keys. How do I resolve it?

I generated and registered an SSH key but can’t perform Git operations using it via the mirror

Do I have to tap the key every time I perform a Git operation?

Related content