[JENKINS-73923] Add javadoc for SSH host key verification strategies (#…

…1237)

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

@@ -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::

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}.
+ *
+ * <p>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<AcceptFirstConnectionVerifier> {
 
+    /**
+     * 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();

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}.
+ *
+ * <p>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<KnownHostsFileVerifier> {
 
+    /**
+     * 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();

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}.
+ *
+ * <p>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<ManuallyProvidedKeyVerifier> {
 
     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);

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}.
+ *
+ * <p>Disables all verification of ssh host keys.
+ * <strong>Not recommended</strong> 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.
+     * <strong>Not recommended</strong> because it provides no protection from "man-in-the-middle" attacks.
+     */
     @Override
     public AbstractCliGitHostKeyVerifier forCliGit(TaskListener listener) {
         return tempKnownHosts -> "-o StrictHostKeyChecking=no";

src/main/java/org/jenkinsci/plugins/gitclient/verifier/SshHostKeyVerificationStrategy.java

@@ -8,21 +8,72 @@
 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
+ * <a href="https://superuser.com/questions/1657387/how-does-host-key-checking-prevent-man-in-the-middle-attack">man in the middle attack</a>.
+ *
+ * <p>Host key verifications strategies allow the Jenkins administrator
+ * to choose the level of host key verification that will be
+ * performed.
+ *
+ * <p>Host key verification strategies include:
+ *
+ * <dl>
+ * <dt>{@link AcceptFirstConnectionStrategy Accept first connection}</dt>
+ * <dd>
+ * 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
+ * </dd>
+ *
+ * <dt>{@link KnownHostsFileVerificationStrategy Known hosts file}</dt>
+ * <dd>
+ * 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
+ * </dd>
+ *
+ * <dt>{@link ManuallyProvidedKeyVerifier Manually provided keys}</dt>
+ * <dd>
+ * 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
+ * </dd>
+ *
+ * <dt>{@link NoHostKeyVerificationStrategy No verification}</dt>
+ * <dd>
+ * Disables all verification of ssh host keys.
+ * <strong>Not recommended</strong> because it provides no protection from "man-in-the-middle" attacks
+ * </dd>
+ * </dl>
+ *
+ * Configure the host key verification strategy from "Manage Jenkins" / "Security" / "Git Host Key Verification Configuration".
+ * More details are available in the <a href="https://plugins.jenkins.io/git-client/#plugin-content-ssh-host-key-verification">plugin documentation</a>.
+ */
 public abstract class SshHostKeyVerificationStrategy<T extends HostKeyVerifierFactory>
         extends AbstractDescribableImpl<SshHostKeyVerificationStrategy<T>> 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 <code>JGIT_KNOWN_HOSTS_PROPERTY</code> property is
+     * set.
+     */
     public static final File JGIT_KNOWN_HOSTS_FILE = new File(JGIT_KNOWN_HOSTS_FILE_PATH);
 
     @Override
     public Descriptor<SshHostKeyVerificationStrategy<T>> getDescriptor() {
         return (Descriptor<SshHostKeyVerificationStrategy<T>>) 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();
 }