API Clients
In chef, node data is separate from the identity used to authenticate requests to the Chef server, which is managed by an API client. Each API client has a public/private key pair. The public half of the key is stored in the database on the server, and the private half is kept locally by the client. On a node running the Chef Client, the private key is generally stored in /etc/chef/client.pem; for an administrator using knife, the private key is generally stored in ~/.chef/USERNAME.pem. Each request to the Chef server includes a request signature in the HTTP headers. The request signature is computed from the hash of the request content and encrypted with the client's private key to verify the identity of the user or machine making the request and prevent attempts to tamper with the content.
The Validation Client
When a node runs chef-client for the first time, it generally does not yet have an API client identity, and so cannot make authenticated requests to the server. This is where the validation client—named "chef-validator" by default comes in. When the chef-client runs, it checks if it has a client key. If the client key does not exist, it then attempts to "borrow" the validation client's identity to register itself with the server. In order to do that, the validation client's private key needs to be copied to the host and placed in /etc/chef/validation.pem. Once the client machine has registered itself with the chef server, it no longer uses the validation client for anything. It is recommended that you delete the validation client's private key from the host after the host has registered.
Signed Header Authentication
API Authentication in Chef is done on a per-request basis, where each request is signed by a private key of the API client making the request. At its core, this process is just selecting a deterministic set of HTTP Headers and creating a unique signature for each request. The portions of the request that are used:
- The HTTP Method (GET/PUT/POST/DELETE)
- The Request Body in Base64
- A Timestamp
- Your Client ID
The resulting string is then encrypted by your Private Key, inserted into the Authorization header of your request, and decrypted by the Chef Server. Also, it verifies that the request we received is the same as the one you sent – that the body is the same, the HTTP method has not been altered, and that it is received within a reasonable amount of time (protecting against replay attacks).
 | Use NTP If there's too much time drift between the client and the server, authentication will fail with a 401 unauthorized message. Set up an NTP server!. |
We recommend that all communication with the API happens over HTTPS. This can be done by proxying the Chef Server with Apache.
Each Chef API client is issued its own key-pair (called a client key).
Under the hood
When a new API client is created, Chef creates a public and private key-pair. The public key is stored within the Chef Server, and the private key should be placed on the client itself. When a request comes in, we verify that the signature of the request is valid (through using your public key.)
This mechanism provides several tangible benefits:
- Every request is authenticated
- There is no shared session state
- A compromised Chef server does not mean that requests can be falsified (there is no shared secret)
- We enable end-to-end authentication, through potentially multiple different transport layers.
Below is the cycle that a Chef Client goes through when it starts:
- First, we check to see if we already have a client key.
- If so, we use it to start signing requests.
- If not, we check to see if we have the validation key.
- If so, we request a new API Client Key, signing our request with the validation key.
- If not, we fail.
- If we were issued a new API Client Key, we start using it to sign subsequent requests.
The Web UI key
The Chef Web UI is a client of the API like any other. The difference is that we create its API key at install time (at the same time we create the validation key.)
Creating new API Client Keys with Knife
 | Create your own keys! You do not want to be using the Validation or Web UI key's to perform operations on the Chef Server - you should always be using your own keys! |
If you need to manually create an API key, you can do so with Knife (see the Knife page for setup instructions) as follows:
The private key printed is the one you should use to sign future requests. You can also save the key to a file with the -f option:
Would put the private key into the /tmp/monkey.pem file.