Skip to content

Commit 8167e83

Browse files
IanMaddIanMadd
authored
Update Client security page (#4431)
* Update Client security page Signed-off-by: Ian Maddaus <[email protected]> * Lints Signed-off-by: Ian Maddaus <[email protected]> --------- Signed-off-by: Ian Maddaus <[email protected]>
1 parent 16c1a0d commit 8167e83

File tree

1 file changed

+62
-67
lines changed

1 file changed

+62
-67
lines changed

‎content/chef_client_security.md‎

Lines changed: 62 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
+++
2-
title = "Chef Infra Client Security"
2+
title = "Chef Infra Client security"
33
draft = false
44

55
gh_repo = "chef-web-docs"
@@ -8,7 +8,7 @@ aliases = ["/chef_client_security.html", "/auth.html"]
88

99
[menu]
1010
[menu.infra]
11-
title = "Chef Infra Client Security"
11+
title = "Chef Infra Client security"
1212
identifier = "chef_infra/security/chef_client_security.md Security"
1313
parent = "chef_infra/security"
1414
weight = 10
@@ -27,21 +27,21 @@ aliases = ["/chef_client_security.html", "/auth.html"]
2727

2828
{{< readfile file="content/reusable/md/security_chef_validator_context.md" >}}
2929

30-
## SSL Certificates
30+
## SSL certificates
3131

3232
{{< readfile file="content/server/reusable/md/server_security_ssl_cert_client.md" >}}
3333

34-
### trusted_certs Directory
34+
### trusted_certs directory
3535

36-
Your organization may use a private Certificate Authority (CA) to generate SSL Certificates or they may create self-signed SSL certificates to use on internal networks or during software development and testing.
36+
You can use use a private certificate authority (CA) to generate SSL certificates or they may create self-signed SSL certificates to use on internal networks or during software development and testing.
3737

38-
The `trusted_certs` directory on Chef Workstation and in Chef Infra Client works as a trusted certificate store for all communication in the Chef Infra system. Chef Infra trusts all SSL certificates stored in this directory--including certificates that aren't issued by a trusted Certificate Authority (CA).
38+
The `trusted_certs` directory on Chef Workstation and in Chef Infra Client works as a trusted certificate store for all communication in the Chef Infra system. Chef Infra trusts all SSL certificates stored in this directory---including certificates that aren't issued by a trusted certificate authority (CA).
3939

4040
Place private and self-signed certificates in the `trusted_certs` directory to use them within Chef Infra Client and Workstation tools.
4141

42-
Use the [chef_client_trusted_certificate]({{< relref "/resources/chef_client_trusted_certificate" >}}) Chef Infra Client resource to manage these certificates continuously.
42+
Use the [`chef_client_trusted_certificate`]({{< relref "/resources/chef_client_trusted_certificate" >}}) Chef Infra Client resource to manage these certificates continuously.
4343

44-
#### trusted_certs Locations
44+
#### trusted_certs directory locations
4545

4646
##### Chef Workstation
4747

@@ -50,7 +50,7 @@ When you install Chef Workstation, it creates a `trusted_certs` directory locate
5050
- Windows: `C:\.chef\trusted_certs`
5151
- All other systems: `~/.chef/trusted_certs`
5252

53-
##### Chef Infra Client Nodes
53+
##### Chef Infra Client nodes
5454

5555
When you bootstrap a node, the Chef Infra Client copies the SSL certificates for the Chef Infra Server onto the node. The `trusted_certs` directory on the node is located at:
5656

@@ -68,70 +68,65 @@ A value for `SSL_CERT_FILE` isn't set by default. Unless updated, the locations
6868

6969
To use a custom CA bundle, update the environment variable to specify the path to the custom CA bundle. The first step to troubleshoot a failing SSL certificate is to verify the location of the `SSL_CERT_FILE`.
7070

71-
### client.rb Settings
72-
73-
Use following client.rb settings to manage SSL certificate preferences:
74-
75-
<table>
76-
<colgroup>
77-
<col style="width: 40%" />
78-
<col style="width: 60%" />
79-
</colgroup>
80-
<thead>
81-
<tr class="header">
82-
<th>Setting</th>
83-
<th>Description</th>
84-
</tr>
85-
</thead>
86-
<tbody>
87-
<tr>
88-
<td><code>local_key_generation</code></td>
89-
<td>Whether the Chef Infra Server or Chef Infra Client generates the private/public key pair. When <code>true</code>, Chef Infra Client generates the key pair, and then sends the public key to the Chef Infra Server. Default value: <code>true</code>.</td>
90-
</tr>
91-
<tr>
92-
<td><code>ssl_ca_file</code></td>
93-
<td>The file for the OpenSSL key. Chef Infra Client generates this setting automatically.</td>
94-
</tr>
95-
<tr>
96-
<td><code>ssl_ca_path</code></td>
97-
<td>The location of the OpenSSL key file. Chef Infra Client generates this setting automatically.</td>
98-
</tr>
99-
<tr>
100-
<td><code>ssl_client_cert</code></td>
101-
<td>The OpenSSL X.509 certificate for mutual certificate validation. Required for mutual certificate validation on the Chef Infra Server. Default value: <code>nil</code>.</td>
102-
</tr>
103-
<tr>
104-
<td><code>ssl_client_key</code></td>
105-
<td>The OpenSSL X.509 key used for mutual certificate validation. Required for mutual certificate validation on the Chef Infra Server. Default value: <code>nil</code>.</td>
106-
</tr>
107-
<tr>
108-
<td><p><code>ssl_verify_mode</code></p></td>
109-
<td><p>Set the verification mode for HTTPS requests. The recommended setting is<code>:verify_peer</code>. Depending on your OpenSSL configuration, you may need to set the <code>ssl_ca_path</code>. Default value: <code>:verify_peer</code>.</p>
110-
<ul>
111-
<li>Use <code>:verify_none</code> to run without validating any SSL certificates.</li>
112-
<li>Use <code>:verify_peer</code> to validate all SSL certificates, including the Chef Infra Server connections, S3 connections, and any HTTPS <strong>remote_file</strong> resource URLs used in a Chef Infra Client run.</li>
113-
</ul>
114-
</td>
115-
</tr>
116-
<tr>
117-
<td><code>verify_api_cert</code></td>
118-
<td>Verify the SSL certificate on the Chef Infra Server. Set to <code>true</code>, Chef Infra Client always verifies the SSL certificate. Set to <code>false</code>, Chef Infra Client uses <code>ssl_verify_mode</code> to determine if the SSL certificate requires verification. Default value: <code>false</code>.</td>
119-
</tr>
120-
</tbody>
121-
</table>
122-
123-
### Knife Subcommands
71+
### client.rb file settings
72+
73+
<!-- markdownlint-disable MD006 MD007 -->
74+
75+
Use following [`client.rb` file]({{< relref "config_rb_client" >}}) settings to manage SSL certificate preferences:
76+
77+
`local_key_generation`
78+
: Whether the Chef Infra Server or Chef Infra Client generates the private/public key pair.
79+
When `true`, Chef Infra Client generates the key pair and then sends the public key to the Chef Infra Server.
80+
81+
Default value: `true`.
82+
83+
`ssl_ca_file`
84+
: The file for the OpenSSL key. Chef Infra Client generates this setting automatically.
85+
86+
`ssl_ca_path`
87+
: The location of the OpenSSL key file. Chef Infra Client generates this setting automatically.
88+
89+
`ssl_client_cert`
90+
: The OpenSSL X.509 certificate for mutual certificate validation. Required for mutual certificate validation on the Chef Infra Server.
91+
92+
Default value: `nil`.
93+
94+
`ssl_client_key`
95+
: The OpenSSL X.509 key used for mutual certificate validation. Required for mutual certificate validation on the Chef Infra Server.
96+
97+
Default value: `nil`.
98+
99+
`ssl_verify_mode`
100+
: Set the verification mode for HTTPS requests. The recommended setting is `:verify_peer`. Depending on your OpenSSL configuration, you may need to set the `ssl_ca_path`.
101+
102+
Allowed values:
103+
104+
- Use `:verify_none` to run without validating any SSL certificates.
105+
- Use `:verify_peer` to validate all SSL certificates, including the Chef Infra Server connections, S3 connections, and any HTTPS `remote_file` resource URLs used in a Chef Infra Client run.
106+
107+
Default value: `:verify_peer`.
108+
109+
`verify_api_cert`
110+
: Verify the SSL certificate on the Chef Infra Server.
111+
112+
If `true`, Chef Infra Client always verifies the SSL certificate. If `false`, Chef Infra Client uses `ssl_verify_mode` to determine if the SSL certificate requires verification.
113+
114+
Default value: `false`.
115+
116+
<!-- markdownlint-enable MD006 MD007 -->
117+
118+
### knife CLI subcommands
124119

125120
The Chef Infra Client includes two knife commands for managing SSL certificates:
126121

127-
- Use [knife ssl check](/workstation/knife_ssl_check/) to troubleshoot SSL certificate issues
122+
- Use [knife ssl check](/workstation/knife_ssl_check/) to troubleshoot SSL certificate issues.
128123
- Use [knife ssl fetch](/workstation/knife_ssl_fetch/) to pull down a certificate from the Chef Infra Server to the `/.chef/trusted_certs` directory on the workstation.
129124

130-
After the workstation has the correct SSL certificate, bootstrap operations from that workstation will use the certificate in the `/.chef/trusted_certs` directory during the bootstrap operation.
125+
After the workstation has the correct SSL certificate, bootstrap operations from that workstation uses the certificate in the `/.chef/trusted_certs` directory during the bootstrap operation.
131126

132127
#### knife ssl check
133128

134-
Run the `knife ssl check` subcommand to verify the state of the SSL certificate, and then use the response to help troubleshoot issues that may be present.
129+
Run [`knife ssl check`]({{< relref "/workstation/knife_ssl_check/" >}}) to verify the state of the SSL certificate, and then use the response to help troubleshoot any issues.
135130

136131
##### Verified
137132

@@ -143,8 +138,8 @@ Run the `knife ssl check` subcommand to verify the state of the SSL certificate,
143138

144139
#### knife ssl fetch
145140

146-
Run the `knife ssl fetch` to download the self-signed certificate from the Chef Infra Server to the `/.chef/trusted_certs` directory on a workstation.
141+
Run [`knife ssl fetch`]({{< relref "/workstation/knife_ssl_fetch/" >}}) to download the self-signed certificate from the Chef Infra Server to the `/.chef/trusted_certs` directory on a workstation.
147142

148-
##### Verify Checksums
143+
##### Verify checksums
149144

150145
{{< readfile file="content/workstation/reusable/md/knife_ssl_fetch_verify_certificate.md" >}}

0 commit comments

Comments
 (0)