SSL Certificate Validation in Chef

SSL and Chef

As Chef has grown up, we've found that we've needed to revisit some
decisions we made when Chef was an unruly upstart open source project.
One such decision is how Chef handles HTTPS connections by default.

Currently, Chef defaults to not verifying certificates when it makes
HTTPS connections. There are a number of reasons why this choice made
sense at the time, but now they're either no longer valid or not strong
enough to justify keeping this unsecure default behavior.

Over the next few Chef releases, we'll be introducing changes and
tooling that will enable us to start verifying certificate authenticity
by default. One of the biggest challenges we face is providing a humane
interface to understanding and fixing SSL errors when they occur. We
know from experience and example that when changes like this are done
poorly, some frustrated users react by disabling the added security
protections because it's the simplest path to making the errors stop.
This is counterproductive, so we'll be working hard to make sure the
transition is smooth and users have the tools they need to understand
and fix SSL errors the right way.

For many Chef users, enabling SSL validation by default will be a
breaking change, so it will take time before we can flip the switch. If
you want to enable certificate validation in chef-client right now, you
can simply set ssl_verify_mode :verify_peer in your config file.

Updates in 11.8

Chef 11.8 contains the first batch of changes related to enabling SSL
validation by default. In this release, we've added:

  • verify_api_cert config option: This setting enables SSL validation
    for HTTPS connections between chef-client and chef-server (but does not
    affect other HTTPS connections). This will allow us to automatically
    configure SSL verification for newly bootstrapped nodes in a future
  • trusted_certs directory: Any certificates placed in the
    trusted_certs directory (/etc/chef/trusted_certs by default on UNIX)
    will be used when verifying a server's certificate. This makes it easy
    for users of the open source chef-server to trust a self-signed
  • Automatic use of the embedded root CA bundle on Windows. For several
    releases, we've included a root CA bundle with the chef-client omnibus
    packages. Because of how ruby is built on Windows, you previously needed
    to set the SSL_CERT_FILE environment variable to make ruby use
    the included certs. In 11.8, chef-client will automatically detect when
    the included root certificates are available and use them when
    validating server certificates.

Near Future Updates

The updates in Chef 11.8 prepare us for the next steps.

  • SSL debugging tools: We want to make it easy to figure out what's
    going on when trouble strikes. To that end, we're already working on SSL
    debugging code that will help explain the exact cause of any SSL
    certificate problems you might encounter.
  • Warning for the default configuration: As with any breaking change, we want
    to make sure you have plenty of time to prepare.
  • Bootstrap support for trusted_certs: In order to make SSL validation
    possible for users with self-signed certificates, we'll make knife bootstrap
    automatically copy your self-signed certs to new nodes when
  • Enable SSL validation by default on new nodes: from the workstation
    we'll be able to detect if your chef-server has a valid certificate and
    enable certificate validation on new nodes.
  • chef-client cookbook updates: To help you improve the security of your
    existing machines, we'll add new features to the chef-client cookbook to
    help you configure chef to use your self-signed certificates and enable
    certificate validation.

Future Updates

Once all of the above features are in place, we'll enable certificate
validation by default in the next major release of Chef.


If you'd like to understand Ruby's handling of SSL certificates in
depth, Mislav wrote an excellent post on this topic
and he has also published a set of scripts to help debug SSL issues.

Dan DeLeo