Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EGit/New and Noteworthy/5.11"

(Known problems)
m (Known problems)
Line 17: Line 17:
 
** Work-arounds:
 
** Work-arounds:
 
*** Install '''[https://download.eclipse.org/egit/updates-nightly/ EGit nightly]''', or
 
*** Install '''[https://download.eclipse.org/egit/updates-nightly/ EGit nightly]''', or
*** Use an '''ed25519''' key, or
+
*** Use an '''ed25519''' key, or an ECDSA key, or
 
*** Use an external SSH via environment variable '''GIT_SSH'''.
 
*** Use an external SSH via environment variable '''GIT_SSH'''.
 
: We're in the process of putting together an EGit/JGit 5.11.1 release that will work around this problem in Apache MINA sshd 2.6.0. '''[https://download.eclipse.org/egit/updates-nightly/ EGit nightly]''' contains this work-around already.
 
: We're in the process of putting together an EGit/JGit 5.11.1 release that will work around this problem in Apache MINA sshd 2.6.0. '''[https://download.eclipse.org/egit/updates-nightly/ EGit nightly]''' contains this work-around already.

Revision as of 06:36, 8 April 2021

EGit

Git Protocol

The git protocol is the application-layer protocol git uses for communication between a git client and an upstream (git server). It is implemented atop the transport protocol (like HTTPS or SSH). Git has two different protocols for communicating with an upstream. EGit 5.11 by default tries to use the more efficient protocol V2 for fetching and uses the older protocol V0 only if the server does not support protocol V2. Most git servers nowadays do support protocol V2. See also the information about JGit's use of protocol V2.

SSH

EGit 5.11 no longer supports the JSch library for SSH connections. By default EGit now always uses the Apache MINA sshd SSH library. The preference setting that allowed users to choose which library to use has been removed.

If environment variable GIT_SSH is set to the path of an SSH executable, EGit uses that external SSH program instead.

Known problems

  • Bug 572056: Connecting with an RSA key: the SSH library used has changed in JGit from Apache MINA sshd 2.4.0 to 2.6.0. sshd 2.6.0 by default does public-key authentication for RSA keys using the rsa-sha2-512 signature algorithm only. Servers that do not understand that mechanism but only the older ssh-rsa signature algorithm will then refuse the log-in.
    • Known affected git servers: bitbucket.org, AWS Code Commit, Azure DevOps
    • Work-arounds:
      • Install EGit nightly, or
      • Use an ed25519 key, or an ECDSA key, or
      • Use an external SSH via environment variable GIT_SSH.
We're in the process of putting together an EGit/JGit 5.11.1 release that will work around this problem in Apache MINA sshd 2.6.0. EGit nightly contains this work-around already.
The work-around in EGit/JGit 5.11.1 and in EGit nightly consists of several things:
  1. For RSA keys, try all available signature algorithms (rsa-sha2-512, rsa-sha2-256, ssh-rsa).
  2. Some SSH servers announce which algorithms they know or prefer. Try those algorithms first.
  3. If this still doesn't help, the user can re-order the sequence of algorithms in the ~/.ssh/config file. To do so, add a configuration for PubkeyAcceptedAlgorithms (or PubkeyAcceptedKeyTypes, which is the older name for the same configuration) to the host entry of an affected host. Example:
Host git.somehost.org
Hostname git.somehost.org
Port 22
User git
IdentityFile ~/.ssh/id_rsa.somehost
IdentitiesOnly yes
PubkeyAcceptedAlgorithms ^ssh-rsa
The last line says to change the order to (ssh-rsa, rsa-sha2-512, rsa-sha2-256), so that the old "ssh-rsa" signature algorithm is used first. Note that the ^ operator supported by EGit/JGit is available in openSSH only as of version openSSH 8.1 (October 2019). PubkeyAcceptedKeyTypes was renamed to PubkeyAcceptedAlgorithms in openSSH 8.5 (March 2021). If the same ssh config file is to be used with EGit and openSSH, install a recent openSSH version.
The old "ssh-rsa" signature algorithm is deprecated and on some systems already no longer available in SSH servers.

Properties View

As of EGit 5.11, the Eclipse Properties view shows information about a selected tag from the Git Repositories view.

"Screenshot show a selected tag in the Git Repositories view and the information shown in the Properties view."

The properties view shows information about the tag itself and also about the git object the tag points to. When the "Tag message" or "Commit message" property is selected, the full message is shown in a focusable pop-up. When the tag target is a commit and is selected, buttons to open the commit in the History view or in the Commit Viewer are shown.

In a similar manner the properties view also shows information about a commit opened in the Commit Viewer when the Commit Viewer is active.

Signatures

Creating Signed Tags

Functionality to sign commits has been available since EGit 5.3. With version 5.11 it is now also possible to create OpenPGP-signed tags:

"Screenshot of the EGit 5.11 tag creation dialog with the new checkbox for creating a signed commit highlighted."

If signing is set up, there is a new checkbox in the "Create Tag..." dialog for creating a signed tag. A signed tag will always be an annotated tag, i.e., a separate tag object recording the creator of the tag, the time the tag was created, and a tag message, even if it is empty. Lightweight tags, which are just git references pointing to a commit, cannot be signed.

The checkbox initially shows the state as determined from the git configuration. There are two options in the git config that govern whether tags are signed. They are tag.gpgSign and tag.forceSignAnnotated, respectively.

The user can override this selection by explicitly checking or unchecking the checkbox.

The checkbox is available only if signing is set up at all, i.e., if a signing key matching either git configs user.email or user.signingKey can be found. If git config user.signingKey is set but no matching GPG key can be found, the dialog displays a warning instead of the checkbox, otherwise, the checkbox is simply not present when no GPG signing key can be found.

Verifying Commit Signatures

EGit 5.11 can also verify OpenPGP signatures of commits. If switched on in the Git preferences, EGit will verify commit signatures and show the information in the Git History view:

"Screenshot showing the Git/History preference page and the signature verification information in the Git History view."

The information shown is similar to what git log --show-signature shows, but is not identical. EGit uses the Bouncy Castle Java library to verify signatures (even if an external GPG is used to sign commits), so there are minor differences.

Currently EGit only verifies commit signatures. There is no UI (yet) for showing verification information for tag signatures.

Using GPG to Sign Commits and Tags

EGit by default uses the signing support that is provided by JGit, the Java git library it uses for all git functionality. This uses the Bouncy Castle Java crypto library to find and read GPG keys and to sign commits.

In EGit 5.11, the user also has the option to use the GPG executable installed on the system instead. There are new settings in the Git→Committing preference page:

"Screenshot of the EGit 5.11 Git/Committing preference page showing the new GPG-related settings"

The user can choose between using the "Bouncy Castle library" or the "External GPG" for signing commits and tags. If "External GPG" is chosen, EGit will launch the GPG executable for signing commits or tags. It finds the GPG executable using the following rules:

  • If the preference for "GPG Executable" is also set, it uses the path defined there. (This preference is shown disabled in the screenshot. It is enabled when "External GPG" is chosen.) Setting this is optional; see below.
  • Otherwise, if the git config gpg.program (or gpg.openpgp.program) is set, it uses that path from the git config.
  • Otherwise, it looks for an executable named "gpg" (or "gpg.exe" on Windows) on the paths listed in the environment variable PATH.


Normally it is not necessary to set the path to the GPG executable in the Eclipse preferences. Doing so may help if for some reason the value defined in the git config is not appropriate for Eclipse, or if Eclipse cannot find the GPG executable on the PATH. (On OS X, the PATH for GUI programs started via the Finder is not the same as the PATH in a bash shell, and is typically much shorter. EGit uses the PATH as defined in bash on OS X.)

Note: Eclipse needs a GPG that interacts with the user via GUI dialogs, for instance to ask for a passphrase for a protected GPG key. If GPG is configured to ask for user input in a terminal, Eclipse cannot interact with GPG. In that case, an error dialog is shown with a "Help" button, which links to a help page with some additional hints about where the problem might be and how it might be corrected.

Out of the box, the standard GPG distributions from GnuPG are set up to use GUI dialogs and are thus usable by Eclipse.

When an external GPG executable is used, Eclipse leaves all key handling for signing commits or tags to GPG. GPG will use the gpg-agent, and it will automatically prompt for smartcard PINs or key passphrases, and it may on some systems provide integration with the system's global key chain to avoid repeated passphrase entry. Eclipse and EGit are not involved in any of these steps. EGit only tells GPG what to sign (the raw data of the commit or tag) with which key, identified by git config user.signingKey or the committer's e-mail address, if not set.

Other Changes

EGit 5.11 includes some less noticeable improvements in the UI, plus a number of bug fixes. The complete list of new features and bug fixes is available in the release notes.

Contributors

The following 7 developers worked on this release:

Alexander Nittka, Jörg Kubitz, Matthias Sohn, Max Hohenegger, Michael Keppler, Simeon Andreev, Thomas Wolf

Video

You can see many of the changes in action in the Eclipse 2021-03 Java IDE Improvements video.

See Also

See also the new features in JGit for additional information.

Back to the top