From f684ff9b97a43710eb41aff81ccff46d53324616 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Sat, 4 Jan 2025 08:02:58 -0700 Subject: [PATCH] [JENKINS-73923] Add javadoc for SSH host key verification strategies https://issues.jenkins.io/browse/JENKINS-73923 notes that https://jenkins.io/doc/developer/extensions/git-client/ has no documentation. It says "This extension point has no Javadoc documentation". Provide the documentation for the extension point and the four implementations of the extension point so that extension point documentation will include documentation after the next release of the git client plugin. Much of the text is copied from the README or derived from the text in the README. Testing done Checked that the Javadoc renders as expected in Chrome. --- README.adoc | 2 +- .../AcceptFirstConnectionStrategy.java | 11 ++++ .../KnownHostsFileVerificationStrategy.java | 11 ++++ ...nuallyProvidedKeyVerificationStrategy.java | 17 +++++++ .../gitclient/verifier/NoHostKeyVerifier.java | 10 ++++ .../SshHostKeyVerificationStrategy.java | 51 +++++++++++++++++++ 6 files changed, 101 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 027954f5ea..6ee678403c 100644 --- a/README.adoc +++ b/README.adoc @@ -102,7 +102,7 @@ By default, Git Client plugin uses the "Known hosts file" strategy to verify all Host key verification strategies include: Accept first connection:: -Remembers the first host key encountered for each git server and requires that the same host key must be use for later access. +Remembers the first host key encountered for each git server and requires that the same host key must be used for later access. This is usually the most convenient setting for administrators while still providing ssh host key verification Known hosts file:: diff --git a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/AcceptFirstConnectionStrategy.java b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/AcceptFirstConnectionStrategy.java index 2d805d31e9..b79ad2381c 100644 --- a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/AcceptFirstConnectionStrategy.java +++ b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/AcceptFirstConnectionStrategy.java @@ -5,13 +5,24 @@ import hudson.model.Descriptor; import org.kohsuke.stapler.DataBoundConstructor; +/** + * Accept known hosts strategy for the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}. + * + *

Remembers the first host key encountered for each git server and requires that the same host key must be used for later access. + * This is usually the most convenient setting for administrators while still providing ssh host key verification + */ public class AcceptFirstConnectionStrategy extends SshHostKeyVerificationStrategy { + /** + * Creates a secure shell host key verification strategy that accepts known hosts on first connection. + * Remembers the first host key encountered for each git server and requires that the same host key must be used for later access. + */ @DataBoundConstructor public AcceptFirstConnectionStrategy() { // stapler needs @DataBoundConstructor } + /** {@inheritDoc} */ @Override public AcceptFirstConnectionVerifier getVerifier() { return new AcceptFirstConnectionVerifier(); diff --git a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/KnownHostsFileVerificationStrategy.java b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/KnownHostsFileVerificationStrategy.java index dfbacb6af1..bab2e7bef2 100644 --- a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/KnownHostsFileVerificationStrategy.java +++ b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/KnownHostsFileVerificationStrategy.java @@ -5,13 +5,24 @@ import hudson.model.Descriptor; import org.kohsuke.stapler.DataBoundConstructor; +/** + * Known hosts strategy for the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}. + * + *

Uses the existing 'known_hosts' file on the controller and on the agent. + * This assumes the administrator has already configured this file on the controller and on all agents + */ public class KnownHostsFileVerificationStrategy extends SshHostKeyVerificationStrategy { + /** + * Creates a secure shell host key verification strategy that uses the existing 'known_hosts' file on the controller and on the agent. + * This assumes the administrator has already configured this file on the controller and on all agents + */ @DataBoundConstructor public KnownHostsFileVerificationStrategy() { // stapler needs @DataBoundConstructor } + /** {@inheritDoc} */ @Override public KnownHostsFileVerifier getVerifier() { return new KnownHostsFileVerifier(); diff --git a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/ManuallyProvidedKeyVerificationStrategy.java b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/ManuallyProvidedKeyVerificationStrategy.java index b0dcc3d290..1c26c85e1a 100644 --- a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/ManuallyProvidedKeyVerificationStrategy.java +++ b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/ManuallyProvidedKeyVerificationStrategy.java @@ -8,21 +8,36 @@ import org.kohsuke.stapler.DataBoundConstructor; import org.kohsuke.stapler.QueryParameter; +/** + * Manually provided host key strategy for the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}. + * + *

Provides a form field where the administrator inserts the host keys for the git repository servers. + * This works well when a small set of repository servers meet the needs of most users + */ public class ManuallyProvidedKeyVerificationStrategy extends SshHostKeyVerificationStrategy { private final String approvedHostKeys; + /** + * Creates a secure shell host key verification strategy that uses the host keys provided by the Jenkins administrator. + * This works well when a small set of repository servers meet the needs of most users + */ @DataBoundConstructor public ManuallyProvidedKeyVerificationStrategy(String approvedHostKeys) { this.approvedHostKeys = approvedHostKeys.trim(); } + /** {@inheritDoc} */ @Override public ManuallyProvidedKeyVerifier getVerifier() { return new ManuallyProvidedKeyVerifier(approvedHostKeys); } + /** + * Returns the approved host keys. + * @return approved host keys + */ public String getApprovedHostKeys() { return approvedHostKeys; } @@ -42,6 +57,7 @@ public FormValidation doCheckApprovedHostKeys(@QueryParameter String approvedHos } } + /** {@inheritDoc} */ @Override public boolean equals(Object o) { if (this == o) { @@ -54,6 +70,7 @@ public boolean equals(Object o) { return Objects.equals(approvedHostKeys, that.approvedHostKeys); } + /** {@inheritDoc} */ @Override public int hashCode() { return Objects.hash(approvedHostKeys); diff --git a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/NoHostKeyVerifier.java b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/NoHostKeyVerifier.java index 2b27a5729b..d849a1aea1 100644 --- a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/NoHostKeyVerifier.java +++ b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/NoHostKeyVerifier.java @@ -5,10 +5,20 @@ import java.util.logging.Logger; import org.eclipse.jgit.transport.sshd.ServerKeyDatabase; +/** + * Disable all host key verification by the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}. + * + *

Disables all verification of ssh host keys. + * Not recommended because it provides no protection from "man-in-the-middle" attacks + */ public class NoHostKeyVerifier extends HostKeyVerifierFactory { private static final Logger LOGGER = Logger.getLogger(NoHostKeyVerifier.class.getName()); + /** + * Creates a secure shell host key verification strategy that performs no host key verification. + * Not recommended because it provides no protection from "man-in-the-middle" attacks. + */ @Override public AbstractCliGitHostKeyVerifier forCliGit(TaskListener listener) { return tempKnownHosts -> "-o StrictHostKeyChecking=no"; diff --git a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/SshHostKeyVerificationStrategy.java b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/SshHostKeyVerificationStrategy.java index b14b1a6ad0..dc71b5a3f2 100644 --- a/src/main/java/org/jenkinsci/plugins/gitclient/verifier/SshHostKeyVerificationStrategy.java +++ b/src/main/java/org/jenkinsci/plugins/gitclient/verifier/SshHostKeyVerificationStrategy.java @@ -8,15 +8,62 @@ import jenkins.model.Jenkins; import org.apache.commons.lang.StringUtils; +/** + * Secure shell host key verification strategy extension point for SSH connections from the git client plugin. + * Secure shell (ssh) host key verification protects an SSH client from a + * man in the middle attack. + * + *

Host key verifications strategies allow the Jenkins administrator + * to choose the level of host key verification that will be + * performed. + * + *

Host key verification strategies include: + * + *

+ *
{@link AcceptFirstConnectionStrategy Accept first connection}
+ *
+ * Remembers the first host key encountered for each git server and requires that the same host key must be used for later access. + * This is usually the most convenient setting for administrators while still providing ssh host key verification + *
+ * + *
{@link KnownHostsFileVerificationStrategy Known hosts file}
+ *
+ * Uses the existing 'known_hosts' file on the controller and on the agent. + * This assumes the administrator has already configured this file on the controller and on all agents + *
+ * + *
{@link ManuallyProvidedKeyVerifier Manually provided keys}
+ *
+ * Provides a form field where the administrator inserts the host keys for the git repository servers. + * This works well when a small set of repository servers meet the needs of most users + *
+ * + *
{@link NoHostKeyVerificationStrategy No verification}
+ *
+ * Disables all verification of ssh host keys. + * Not recommended because it provides no protection from "man-in-the-middle" attacks + *
+ *
+ * + * Configure the host key verification strategy from "Manage Jenkins" / "Security" / "Git Host Key Verification Configuration". + * More details are available in the plugin documentation. + */ public abstract class SshHostKeyVerificationStrategy extends AbstractDescribableImpl> implements ExtensionPoint { + /** Default path to the known hosts file for the current user. */ public static final String KNOWN_HOSTS_DEFAULT = Path.of(System.getProperty("user.home"), ".ssh", "known_hosts").toString(); + private static final String JGIT_KNOWN_HOSTS_PROPERTY = SshHostKeyVerificationStrategy.class.getName() + ".jgit_known_hosts_file"; private static final String JGIT_KNOWN_HOSTS_FILE_PATH = StringUtils.defaultIfBlank(System.getProperty(JGIT_KNOWN_HOSTS_PROPERTY), KNOWN_HOSTS_DEFAULT); + /** JGit known hosts file path for the current user. + * Uses the {@link #KNOWN_HOSTS_DEFAULT default path} to the known hosts file for the current user + * unless the JGIT_KNOWN_HOSTS_PROPERTY property is + * set. + */ public static final File JGIT_KNOWN_HOSTS_FILE = new File(JGIT_KNOWN_HOSTS_FILE_PATH); @Override @@ -24,5 +71,9 @@ public Descriptor> getDescriptor() { return (Descriptor>) Jenkins.get().getDescriptorOrDie(getClass()); } + /** + * Returns the ssh host key verifier for this strategy. + * @return ssh host key verifier for this strategy. + */ public abstract T getVerifier(); }