instructure/canvas-lms · error · HmacHelper::Error

signature doesn't match.

Error message

signature doesn't match.

What it means

HmacHelper#extract_blob verifies an HMAC-SHA1 signature over a JSON payload before parsing. If Canvas::Security.verify_hmac_sha1(hmac, json) fails, the payload was tampered with, truncated, or signed with a different secret, so it raises Error "signature doesn't match.".

Solutions

1. Regenerate the signed URL/payload — do not hand-edit signed json.
2. Confirm the same Canvas security secret is configured on the verifying node (config/canvas_security.yml or equivalent env).
3. Ensure the hmac and json strings are passed raw (no extra URL decode) exactly as received.
4. Log a diff of received json vs expected payload to spot tampering or encoding drift.

Example fix

// before
blob = extract_blob(params[:hmac].tr(' ', '+'), params[:json].gsub('%20', ' '))
// after
blob = extract_blob(params[:hmac], params[:json]) # pass raw values untouched

begin
  blob = HmacHelper.extract_blob(hmac, json, expected)
rescue HmacHelper::Error => e
  Rails.logger.warn("hmac blob rejected: #{e.message}")
  return head :bad_request
end

When it happens

Trigger: Passing a hmac/json pair where json was modified after signing, the hmac was URL-decoded/encoded differently, the canvas signing secret rotated between signing and verification, or the hmac belongs to a different payload.

Common situations: Deep-link/sessionless-launch URLs whose query params were edited; secrets.env differing between app nodes; proxy rewriting the encoded payload; copy-paste dropping trailing '=' padding.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• signature_invalid
• assets_url host for '#
• Attachment verifier token id mismatch. token id: #
• Attachment verifier token invalid: #
• can't build pseudonym_credentials except on just-generated…

AI-assisted analysis of instructure/canvas-lms@1c9f0bb801 (2026-09-15). Data as JSON: /api/errors/93b5f3a02dacf24e. Report an issue: GitHub.

Appendix: source

Thrown at app/helpers/hmac_helper.rb:24

# This file is part of Canvas.
#
# Canvas is free software: you can redistribute it and/or modify it under
# the terms of the GNU Affero General Public License as published by the Free
# Software Foundation, version 3 of the License.
#
# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
# details.
#
# You should have received a copy of the GNU Affero General Public License along
# with this program. If not, see <http://www.gnu.org/licenses/>.

module HmacHelper
  # returns parsed json after verification
  def extract_blob(hmac, json, expected_values = {})
    unless Canvas::Security.verify_hmac_sha1(hmac, json)
      raise Error, "signature doesn't match."
    end

    blob = JSON.parse(json)

    expected_values.each do |k, v|
      raise Error, "invalid value for #{k}" if blob[k] != v
    end

    blob
  end

  class Error < StandardError; end
end

View on GitHub (pinned to 1c9f0bb801)