[JENKINS-73851] Add SHA-256 HMAC webhook signature validation

.gitignore

@@ -11,3 +11,4 @@ target
 
 # autogenerated resources
 src/main/webapp/css/*
+.vscode/

src/main/java/org/jenkinsci/plugins/github/config/HookSecretConfig.java

@@ -12,6 +12,7 @@
 import hudson.util.ListBoxModel;
 import hudson.util.Secret;
 import jenkins.model.Jenkins;
+import org.jenkinsci.plugins.github.webhook.SignatureAlgorithm;
 import org.jenkinsci.plugins.plaincredentials.StringCredentials;
 import org.kohsuke.stapler.DataBoundConstructor;
 
@@ -25,10 +26,19 @@
 public class HookSecretConfig extends AbstractDescribableImpl<HookSecretConfig> {
 
     private String credentialsId;
+    private SignatureAlgorithm signatureAlgorithm;
 
     @DataBoundConstructor
-    public HookSecretConfig(String credentialsId) {
+    public HookSecretConfig(String credentialsId, String signatureAlgorithm) {
         this.credentialsId = credentialsId;
+        this.signatureAlgorithm = parseSignatureAlgorithm(signatureAlgorithm);
+    }
+
+    /**
+     * Legacy constructor for backwards compatibility.
+     */
+    public HookSecretConfig(String credentialsId) {
+        this(credentialsId, null);
     }
 
     /**
@@ -45,15 +55,62 @@
         return credentialsId;
     }
 
+    /**
+     * Gets the signature algorithm to use for webhook validation.
+     *
+     * @return the configured signature algorithm, defaults to SHA-256
+     * @since 1.45.0
+     */
+    public SignatureAlgorithm getSignatureAlgorithm() {
+        return signatureAlgorithm != null ? signatureAlgorithm : SignatureAlgorithm.getDefault();
+    }
+
+    /**
+     * Gets the signature algorithm name for UI binding.
+     *
+     * @return the algorithm name as string (e.g., "SHA256", "SHA1")
+     * @since 1.45.0
+     */
+    public String getSignatureAlgorithmName() {
+        return getSignatureAlgorithm().name();
+    }
+
     /**
      * @param credentialsId a new ID
      * @deprecated rather treat this field as final and use {@link GitHubPluginConfig#setHookSecretConfigs}
      */
     @Deprecated
     public void setCredentialsId(String credentialsId) {
         this.credentialsId = credentialsId;
     }
 
+    /**
+     * Ensures backwards compatibility during deserialization.
+     * Sets default algorithm to SHA-256 for existing configurations.
+     */
+    private Object readResolve() {
+        if (signatureAlgorithm == null) {
+            signatureAlgorithm = SignatureAlgorithm.getDefault();
+        }
+        return this;
+    }
+
+    /**
+     * Parses signature algorithm from UI string input.
+     */
+    private SignatureAlgorithm parseSignatureAlgorithm(String algorithmName) {
+        if (algorithmName == null || algorithmName.trim().isEmpty()) {
+            return SignatureAlgorithm.getDefault();
+        }
+
+        try {
+            return SignatureAlgorithm.valueOf(algorithmName.trim().toUpperCase());
+        } catch (IllegalArgumentException e) {
+            // Default to SHA-256 for invalid input
+            return SignatureAlgorithm.getDefault();
+        }
+    }
+
     @Extension
     public static class DescriptorImpl extends Descriptor<HookSecretConfig> {
 
@@ -62,6 +119,16 @@
             return "Hook secret configuration";
         }
 
+        /**
+         * Provides dropdown items for signature algorithm selection.
+         */
+        public ListBoxModel doFillSignatureAlgorithmItems() {
+            ListBoxModel items = new ListBoxModel();
+            items.add("SHA-256 (Recommended)", "SHA256");
+            items.add("SHA-1 (Legacy)", "SHA1");
+            return items;
+        }
+
         @SuppressWarnings("unused")
         public ListBoxModel doFillCredentialsIdItems(@QueryParameter String credentialsId) {
             if (!Jenkins.getInstance().hasPermission(Jenkins.MANAGE)) {

src/main/java/org/jenkinsci/plugins/github/webhook/GHWebhookSignature.java

@@ -23,6 +23,7 @@
 
     private static final Logger LOGGER = LoggerFactory.getLogger(GHWebhookSignature.class);
     private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";
+    private static final String HMAC_SHA256_ALGORITHM = "HmacSHA256";
     public static final String INVALID_SIGNATURE = "COMPUTED_INVALID_SIGNATURE";
 
     private final String payload;
@@ -47,19 +48,42 @@
     /**
      * Computes a RFC 2104-compliant HMAC digest using SHA1 of a payloadFrom with a given key (secret).
      *
+     * @deprecated Use {@link #sha256()} for enhanced security
      * @return HMAC digest of payloadFrom using secret as key. Will return COMPUTED_INVALID_SIGNATURE
      * on any exception during computation.
      */
+    @Deprecated
     public String sha1() {
+        return computeSignature(HMAC_SHA1_ALGORITHM);
+    }
+
+    /**
+     * Computes a RFC 2104-compliant HMAC digest using SHA256 of a payload with a given key (secret).
+     * This is the recommended method for webhook signature validation.
+     *
+     * @return HMAC digest of payload using secret as key. Will return COMPUTED_INVALID_SIGNATURE
+     * on any exception during computation.
+     * @since 1.45.0
+     */
+    public String sha256() {
+        return computeSignature(HMAC_SHA256_ALGORITHM);
+    }
+    /**
+     * Computes HMAC signature using the specified algorithm.
+     *
+     * @param algorithm The HMAC algorithm to use (e.g., "HmacSHA1", "HmacSHA256")
+     * @return HMAC digest as hex string, or INVALID_SIGNATURE on error
+     */
+    private String computeSignature(String algorithm) {
         try {
-            final SecretKeySpec keySpec = new SecretKeySpec(secret.getPlainText().getBytes(UTF_8), HMAC_SHA1_ALGORITHM);
-            final Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
+            final SecretKeySpec keySpec = new SecretKeySpec(secret.getPlainText().getBytes(UTF_8), algorithm);
+            final Mac mac = Mac.getInstance(algorithm);
             mac.init(keySpec);
             final byte[] rawHMACBytes = mac.doFinal(payload.getBytes(UTF_8));
 
             return Hex.encodeHexString(rawHMACBytes);
         } catch (Exception e) {
-            LOGGER.error("", e);
+            LOGGER.error("Error computing {} signature", algorithm, e);
             return INVALID_SIGNATURE;
         }
     }
@@ -68,15 +92,44 @@
      * @param digest computed signature from external place (GitHub)
      *
      * @return true if computed and provided signatures identical
+     * @deprecated Use {@link #matches(String, SignatureAlgorithm)} for explicit algorithm selection
      */
+    @Deprecated
     public boolean matches(String digest) {
-        String computed = sha1();
-        LOGGER.trace("Signature: calculated={} provided={}", computed, digest);
+        return matches(digest, SignatureAlgorithm.SHA1);
+    }
+
+    /**
+     * Validates a signature using the specified algorithm.
+     * Uses constant-time comparison to prevent timing attacks.
+     *
+     * @param digest the signature to validate (without algorithm prefix)
+     * @param algorithm the signature algorithm to use
+     * @return true if computed and provided signatures match
+     * @since 1.45.0
+     */
+    public boolean matches(String digest, SignatureAlgorithm algorithm) {
+        String computed;
+        switch (algorithm) {
+            case SHA256:
+                computed = sha256();
+                break;
+            case SHA1:
+                computed = sha1();
+                break;
+            default:
+                LOGGER.warn("Unsupported signature algorithm: {}", algorithm);
+                return false;
+        }
+
+        LOGGER.trace("Signature validation: algorithm={} calculated={} provided={}",
+                    algorithm, computed, digest);
         if (digest == null && computed == null) {
             return true;
         } else if (digest == null || computed == null) {
             return false;
         } else {
+            // Use constant-time comparison to prevent timing attacks
             return MessageDigest.isEqual(computed.getBytes(UTF_8), digest.getBytes(UTF_8));
         }
     }

src/main/java/org/jenkinsci/plugins/github/webhook/RequirePostWithGHHookPayload.java

@@ -27,8 +27,6 @@
 import java.nio.charset.StandardCharsets;
 import java.security.interfaces.RSAPublicKey;
 import java.util.List;
-import java.util.Objects;
-import java.util.stream.Collectors;
 
 import static com.cloudbees.jenkins.GitHubWebHook.X_INSTANCE_IDENTITY;
 import static com.google.common.base.Charsets.UTF_8;
@@ -61,12 +59,23 @@
     class Processor extends Interceptor {
         private static final Logger LOGGER = getLogger(Processor.class);
         /**
-         * Header key being used for the payload signatures.
+         * Header key being used for the legacy SHA-1 payload signatures.
          *
          * @see <a href=https://developer.github.com/webhooks/>Developer manual</a>
+         * @deprecated Use SHA-256 signatures with X-Hub-Signature-256 header
          */
+        @Deprecated
         public static final String SIGNATURE_HEADER = "X-Hub-Signature";
-        private static final String SHA1_PREFIX = "sha1=";
+        /**
+         * Header key being used for the SHA-256 payload signatures (recommended).
+         *
+         * @see <a href="https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks">
+         *      GitHub Documentation</a>
+         * @since 1.45.0
+         */
+        public static final String SIGNATURE_HEADER_SHA256 = "X-Hub-Signature-256";
+        public static final String SHA1_PREFIX = "sha1=";
+        public static final String SHA256_PREFIX = "sha256=";
 
         @Override
         public Object invoke(StaplerRequest2 req, StaplerResponse2 rsp, Object instance, Object[] arguments)
@@ -139,25 +148,66 @@
          * if a hook secret is specified in the GitHub plugin config.
          * If no hook secret is configured, then the signature is ignored.
          *
+         * Uses the configured signature algorithm (SHA-256 by default, SHA-1 for legacy support).
+         *
          * @param req Incoming request.
          * @throws InvocationTargetException if any of preconditions is not satisfied
          */
         protected void shouldProvideValidSignature(StaplerRequest2 req, Object[] args)
                 throws InvocationTargetException {
-            List<Secret> secrets = GitHubPlugin.configuration().getHookSecretConfigs().stream().
-                    map(HookSecretConfig::getHookSecret).filter(Objects::nonNull).collect(Collectors.toList());
-
-            if (!secrets.isEmpty()) {
-                Optional<String> signHeader = Optional.fromNullable(req.getHeader(SIGNATURE_HEADER));
-                isTrue(signHeader.isPresent(), "Signature was expected, but not provided");
-
-                String digest = substringAfter(signHeader.get(), SHA1_PREFIX);
-                LOGGER.trace("Trying to verify sign from header {}", signHeader.get());
-                isTrue(
-                        secrets.stream().anyMatch(secret ->
-                                GHWebhookSignature.webhookSignature(payloadFrom(req, args), secret).matches(digest)),
-                        String.format("Provided signature [%s] did not match to calculated", digest)
-                );
+            List<HookSecretConfig> secretConfigs = GitHubPlugin.configuration().getHookSecretConfigs();
+
+            if (!secretConfigs.isEmpty()) {
+                boolean validSignatureFound = false;
+
+                for (HookSecretConfig config : secretConfigs) {
+                    Secret secret = config.getHookSecret();
+                    if (secret == null) {
+                        continue;
+                    }
+
+                    SignatureAlgorithm algorithm = config.getSignatureAlgorithm();
+                    String headerName = algorithm.getHeaderName();
+                    String expectedPrefix = algorithm.getSignaturePrefix();
+
+                    Optional<String> signHeader = Optional.fromNullable(req.getHeader(headerName));
+                    if (!signHeader.isPresent()) {
+                        LOGGER.debug("No signature header {} found for algorithm {}", headerName, algorithm);
+                        continue;
+                    }
+
+                    String fullSignature = signHeader.get();
+                    if (!fullSignature.startsWith(expectedPrefix)) {
+                        LOGGER.debug("Signature header {} does not start with expected prefix {}",
+                                   fullSignature, expectedPrefix);
+                        continue;
+                    }
+
+                    String digest = substringAfter(fullSignature, expectedPrefix);
+                    LOGGER.trace("Verifying {} signature from header {}", algorithm, fullSignature);
+
+                    boolean isValid = GHWebhookSignature.webhookSignature(payloadFrom(req, args), secret)
+                                                        .matches(digest, algorithm);
+
+                    if (isValid) {
+                        validSignatureFound = true;
+                        // Log deprecation warning for SHA-1 usage
+                        if (algorithm == SignatureAlgorithm.SHA1) {
+                            LOGGER.warn("Using deprecated SHA-1 signature validation. "
+                                      + "Consider upgrading webhook configuration to use SHA-256 "
+                                      + "for enhanced security.");
+                        } else {
+                            LOGGER.debug("Successfully validated {} signature", algorithm);
+                        }
+                        break;
+                    } else {
+                        LOGGER.debug("Signature validation failed for algorithm {}", algorithm);
+                    }
+                }
+
+                isTrue(validSignatureFound,
+                       "No valid signature found. Ensure webhook is configured with a supported signature algorithm "
+                       + "(SHA-256 recommended, SHA-1 for legacy compatibility).");
             }
         }