How to Fix Puppet Agent SSL Certificate Signature Verification Failure


2 views

When your Puppet agent reports certificate signature failure for /CN=hostname.domain.com, this indicates a breakdown in TLS trust between agent and master. The error occurs during the SSL handshake when the agent attempts to verify the master's certificate chain.

From troubleshooting dozens of Puppet deployments, I've found these frequent culprits:

  • Mismatched certificate authorities between master and agent
  • Clock skew exceeding Puppet's tolerance (even if in same timezone)
  • DNS resolution inconsistencies
  • Intermediate certificates not properly chained

First, validate certificate fingerprints:

# On master:
sudo puppet cert list --all --digest SHA256

# On agent:
sudo openssl x509 -in /etc/puppetlabs/puppet/ssl/certs/ca.pem -fingerprint -sha256

Check certificate validity periods:

# On both systems:
sudo openssl x509 -in /etc/puppetlabs/puppet/ssl/certs/ca.pem -noout -dates

When standard fixes fail, this nuclear option often works:

# On agent:
sudo rm -rf /etc/puppetlabs/puppet/ssl
sudo puppet agent -t --waitforcert 60

# On master:
sudo puppet cert clean agent-hostname.domain.com
sudo puppet cert sign agent-hostname.domain.com

For persistent issues, enable debug logging:

sudo puppet agent -t --debug --verbose

Check master's Apache/Passenger SSL logs:

sudo tail -f /var/log/apache2/ssl_access.log
sudo tail -f /var/log/apache2/ssl_error.log

Verify the complete chain using OpenSSL:

openssl verify -CAfile /etc/puppetlabs/puppet/ssl/certs/ca.pem \
  /etc/puppetlabs/puppet/ssl/certs/$(hostname -f).pem

Ensure these settings match in /etc/puppetlabs/puppet/puppet.conf:

[main]
certname = agent-hostname.domain.com
server = puppet-master.domain.com
ca_server = puppet-ca.domain.com

When your Puppet agent throws a certificate verify failed: [certificate signature failure] error despite having a signed certificate, it typically indicates a fundamental SSL trust issue between the agent and master. The error suggests the agent cannot validate the master's certificate signature, even though the certificate appears properly signed in the Puppet CA.

From troubleshooting numerous Puppet deployments, I've found these frequent culprits:

  • Clock skew between master and agent (though you've verified this)
  • Certificate chain validation failures
  • Mismatched DNS names in certificates
  • Corrupted certificate files
  • CA certificate not properly distributed to agents

Let's go beyond the basic "clean ssl dir and regenerate" approach:

# On the agent:
sudo rm -rf /etc/puppetlabs/puppet/ssl
sudo puppet agent -t --waitforcert 60

# On the master:
sudo puppet cert clean agent-hostname.domain.com
sudo puppet cert sign agent-hostname.domain.com

Check certificate details on both systems:

# On master:
sudo openssl x509 -in $(puppet config print hostcert) -text -noout

# On agent:
sudo openssl x509 -in $(puppet config print localcacert) -text -noout

Compare the Issuer and Subject fields - they should match exactly between the agent's CA cert and the master's cert.

Sometimes the issue stems from intermediate devices:

  • Check for SSL inspection appliances
  • Verify no proxies are modifying traffic
  • Test with direct connection bypassing load balancers

Add these to puppet.conf if needed:

[main]
ssl_client_header = SSL_CLIENT_S_DN
ssl_client_verify_header = SSL_CLIENT_VERIFY

After fixes, test the SSL handshake directly:

openssl s_client -connect puppetmaster:8140 -CAfile $(puppet config print localcacert) -cert $(puppet config print hostcert) -key $(puppet config print hostprivkey)

Look for "Verify return code: 0 (ok)" in the output.