cookbooks/ssl_cert/README.md

   1 ssl_cert Cookbook
   2 =================
   3
   4 This cookbook deploys CA certificates, SSL server keys and/or certificates from Chef Vault items.
   5
   6 ## Contents
   7
   8 - [Requirements](#requirements)
   9   - [packages](#packages)
  10 - [Attributes](#attributes)
  11   - [ssl_cert::default](#ssl_certdefault)
  12 - [Usage](#usage)
  13   - [recipes](#recipes)
  14   - [Vault items creation and cookbook attribute settings (with default attributes)](#vault-items-creation-and-cookbook-attribute-settings-with-default-attributes)
  15     - [CA certificates](#ca-certificates)
  16     - [CA public keys (0.2.0 or later)](#ca-public-keys-020-or-later)
  17     - [SSH-CA KRL (0.3.0 or later)](#ssh-ca-krl-030-or-later)
  18     - [SSL server keys and certificates](#ssl-server-keys-and-certificates)
  19   - [References of deployed key and certificate file paths (with default attributes)](#references-of-deployed-key-and-certificate-file-paths-with-default-attributes)
  20   - [Helper methods](#helper-methods)
  21 - [License and Authors](#license-and-authors)
  22
  23 ## Requirements
  24
  25 ### packages
  26 - none.
  27
  28 ## Attributes
  29
  30 ### ssl_cert::default
  31
  32 |Key|Type|Description, example|Default|
  33 |:--|:--|:--|:--|
  34 |`['ssl_cert']['ca_names']`|Array|deployed CA certificates from chef-vault|empty|
  35 |`['ssl_cert']['ca_name_symlinks']`|Hash|Key: ca_name, value: array of symbolic link names to the CA certificate file.|empty|
  36 |`['ssl_cert']['ca_pubkey_names']`|Array|deployed CA public keys from chef-vault (0.2.0 or later)|empty|
  37 |`['ssl_cert']['ssh_ca_krl_name']`|String|deployed SSH-CA KRL (Key Revocation List) from chef-vault (0.3.0 or later)|`nil`|
  38 |`['ssl_cert']['common_names']`|Array|deployed server keys and/or certificates from chef-vault|empty|
  39 |`['ssl_cert']['debian']['key_access_mode']`|Private key file mode (ver. 0.3.4 or later).|`0640`|
  40 |`['ssl_cert']['rhel']['key_access_mode']`|Private key file mode (ver. 0.3.4 or later).|`0400`|
  41 |`['ssl_cert']['rhel']['key_access_group']`|String|RHEL family's key access group (ver. 0.1.5 or later)|`'ssl-cert'`|
  42 |`['ssl_cert']['chef_gem']['clear_sources']`|Boolean|chef_gem resource's clear_sources property.|`false`|
  43 |`['ssl_cert']['chef_gem']['source']`|String|chef_gem resource's source property.|`nil`|
  44 |`['ssl_cert']['chef_gem']['options']`|String|chef_gem resource's options property.|`nil`|
  45 |`['ssl_cert']['chef-vault']['version']`|String|chef-vault installation version.|`'~> 2.6'`|
  46 |`['ssl_cert']['env_context']`|String|node's environment or nil/empty.|`node.chef_environment`|
  47 |`['ssl_cert']['vault_item_suffix']`|String|vault item name's suffix.|`".#{node['ssl_cert']['env_context']}"`|
  48 |`['ssl_cert']['ca_cert_vault']`|String|CA certificate stored vault name.|`'ca_certs'`|
  49 |`['ssl_cert']['ca_cert_vault_item_key']`|String|CA certificate stored vault item key name. (single key or nested hash key path delimited by slash)|`'public'`|
  50 |`['ssl_cert']['ca_cert_file_prefix']`|String|CA certificate file name's prefix.|`''`|
  51 |`['ssl_cert']['ca_cert_file_extension']`|String|CA certificate file name's extension. (0.3.0 or later)|`'crt'`|
  52 |`['ssl_cert']['ca_pubkey_vault']`|String|CA public key stored vault name. (0.2.0 or later)|`'ca_pubkeys'`|
  53 |`['ssl_cert']['ca_pubkey_vault_item_key']`|String|CA public key stored vault item key name. (single key or nested hash key path delimited by slash. 0.2.0 or later)|`'public'`|
  54 |`['ssl_cert']['ca_pubkey_file_prefix']`|String|CA public key file name's prefix. (0.2.0 or later)|`''`|
  55 |`['ssl_cert']['ca_pubkey_file_extension']`|String|CA public key file name's extension. (0.3.0 or later)|`'pub'`|
  56 |`['ssl_cert']['ssh_ca_krl_vault']`|String|SSH-CA KRL stored vault name. (0.3.0 or later)|`'ssh_ca_krls'`|
  57 |`['ssl_cert']['ssh_ca_krl_vault_item_key']`|String|SSH-CA KRL stored vault item key name. (single key or nested hash key path delimited by slash. 0.3.0 or later)|`'public'`|
  58 |`['ssl_cert']['ssh_ca_krl_file_prefix']`|String|SSH-CA KRL file name's prefix. (0.3.0 or later)|`''`|
  59 |`['ssl_cert']['ssh_ca_krl_file_extension']`|String|SSH-CA KRL file name's extension. (0.3.0 or later)|`'krl'`|
  60 |`['ssl_cert']['server_key_vault']`|String|SSL server key stored vault name.|`'ssl_server_keys'`|
  61 |`['ssl_cert']['server_key_vault_item_key']`|String|SSL server key stored vault item key name. (single key or nested hash key path delimited by slash)|`'private'`|
  62 |`['ssl_cert']['server_key_file_prefix']`|String|SSL server key file name's prefix.|`''`|
  63 |`['ssl_cert']['server_key_file_extension']`|String|SSL server key file name's extension. (0.3.0 or later)|`'key'`|
  64 |`['ssl_cert']['server_cert_vault']`|String|SSL server certificate stored vault name.|`'ssl_server_certs'`|
  65 |`['ssl_cert']['server_cert_vault_item_key']`|String|SSL server certificate stored vault item key name. (single key or nested hash key path delimited by slash)|`'public'`|
  66 |`['ssl_cert']['server_cert_file_prefix']`|String|SSL server certificate file name's prefix.|`''`|
  67 |`['ssl_cert']['server_cert_file_extension']`|String|SSL server certificate file name's extension. (0.3.0 or later)|`'crt'`|
  68 |`['ssl_cert']['certs_src_dir']`|String||See `attributes/default.rb`.|
  69 |`['ssl_cert']['certs_dir']`|String||See `attributes/default.rb`.|
  70 |`['ssl_cert']['private_dir']`|String||See `attributes/default.rb`.|
  71 |`['ssl_cert']["#{ca}_cert_src_path"]`|String|CA certificate source file path. (0.3.3 or later)|See `attributes/default.rb`.|
  72 |`['ssl_cert']["#{ca}_cert_path"]`|String|deployed CA certificate file path.|See `attributes/default.rb`.|
  73 |`['ssl_cert']["#{ca}_pubkey_path"]`|String|deployed CA public key file path. (0.2.0 or later)|`"#{node['ssl_cert']['certs_dir']}/#{node['ssl_cert']['ca_pubkey_file_prefix']}#{ca}.#{node['ssl_cert']['ca_pubkey_file_extension']}"`|
  74 |`['ssl_cert']["#{undotted_cn}_key_path"]`|String|deployed SSL server key file path.|`"#{node['ssl_cert']['private_dir']}/#{node['ssl_cert']['server_key_file_prefix']}#{undotted_cn}.#{node['ssl_cert']['server_key_file_extension']}"`|
  75 |`['ssl_cert']["#{undotted_cn}_cert_path"]`|String|deployed SSL server certificate file path.|`"#{node['ssl_cert']['certs_dir']}/#{node['ssl_cert']['server_cert_file_prefix']}#{undotted_cn}.#{node['ssl_cert']['server_cert_file_extension']}"`|
  76
  77 ## Usage
  78
  79 ### recipes
  80 - `ssl_cert::default` - deploys CA certificates, SSL server keys and/or certificates.
  81 - `ssl_cert::ca_certs` - deploys CA certificates.
  82 - `ssl_cert::ca_pubkeys` - deploys CA public keys for SSH-CA, ... (0.2.0 or later)
  83 - `ssl_cert::ssh_ca_krl` - deploys a SSH-CA KRL (Key Revocation List) file. (0.3.0 or later)
  84 - `ssl_cert::server_key_pairs` - deploys SSL server keys and certificates.
  85 - `ssl_cert::server_keys` - deploys SSL server keys.
  86 - `ssl_cert::server_certs` - deploys SSL server certificates.
  87
  88 ### Vault items creation and cookbook attribute settings (with default attributes)
  89
  90 #### CA certificates
  91
  92 - create vault items.
  93
  94 ```text
  95 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("grid_ca.prod.crt")})' \
  96 > > ~/tmp/grid_ca.prod.crt.json
  97
  98 $ cd $CHEF_REPO_PATH
  99
 100 $ knife vault create ca_certs grid_ca.prod \
 101 > --json ~/tmp/grid_ca.prod.crt.json
 102 ```
 103
 104 - grant reference permission to the appropriate nodes
 105
 106 ```text
 107 $ knife vault update ca_certs grid_ca.prod -S 'name:*.example.com'
 108 ```
 109
 110 - add cookbook attributes.
 111
 112 ```ruby
 113 override_attributes(
 114   'ssl_cert' => {
 115     'ca_names' => [
 116       'grid_ca',
 117       # ...
 118     ],
 119   },
 120 )
 121 ```
 122
 123 #### CA public keys (0.2.0 or later)
 124
 125 - create vault items.
 126
 127 ```text
 128 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("grid_ssh_ca.prod.pub")})' \
 129 > > ~/tmp/grid_ssh_ca.prod.pub.json
 130
 131 $ cd $CHEF_REPO_PATH
 132
 133 $ knife vault create ca_pubkeys grid_ssh_ca.prod \
 134 > --json ~/tmp/grid_ssh_ca.prod.pub.json
 135 ```
 136
 137 - grant reference permission to the appropriate nodes
 138
 139 ```text
 140 $ knife vault update ca_pubkeys grid_ssh_ca.prod -S 'name:*.example.com'
 141 ```
 142
 143 - add cookbook attributes.
 144
 145 ```ruby
 146 override_attributes(
 147   'ssl_cert' => {
 148     'ca_pubkey_names' => [
 149       'grid_ssh_ca',
 150       # ...
 151     ],
 152   },
 153 )
 154 ```
 155
 156 #### SSH-CA KRL (0.3.0 or later)
 157
 158 - create vault items.
 159
 160 ```text
 161 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("grid_ssh_ca.prod.krl")})' \
 162 > > ~/tmp/grid_ssh_ca.prod.krl.json
 163
 164 $ cd $CHEF_REPO_PATH
 165
 166 $ knife vault create ssh_ca_krls grid_ssh_ca.prod \
 167 > --json ~/tmp/grid_ssh_ca.prod.krl.json
 168 ```
 169
 170 - grant reference permission to the appropriate nodes
 171
 172 ```text
 173 $ knife vault update ssh_ca_krls grid_ssh_ca.prod -S 'name:*.example.com'
 174 ```
 175
 176 - add cookbook attributes.
 177
 178 ```ruby
 179 override_attributes(
 180   'ssl_cert' => {
 181     'ssh_ca_krl_name' => 'grid_ssh_ca',
 182   },
 183 )
 184 ```
 185
 186 #### SSL server keys and certificates
 187
 188 - create vault items.
 189
 190 ```text
 191 $ ruby -rjson -e 'puts JSON.generate({"private" => File.read("node_example_com.prod.key")})' \
 192 > > ~/tmp/node_example_com.prod.key.json
 193
 194 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("node_example_com.prod.crt")})' \
 195 > > ~/tmp/node_example_com.prod.crt.json
 196
 197 $ cd $CHEF_REPO_PATH
 198
 199 $ knife vault create ssl_server_keys node.example.com.prod \
 200 > --json ~/tmp/node_example_com.prod.key.json
 201
 202 $ knife vault create ssl_server_certs node.example.com.prod \
 203 > --json ~/tmp/node_example_com.prod.crt.json
 204 ```
 205
 206 - grant reference permission to the appropriate nodes
 207
 208 ```text
 209 $ knife vault update ssl_server_keys node.example.com.prod -S 'name:node.example.com'
 210 $ knife vault update ssl_server_certs node.example.com.prod -S 'name:node.example.com'
 211 ```
 212
 213 - add cookbook attributes
 214
 215 ```ruby
 216 override_attributes(
 217   'ssl_cert' => {
 218     'common_names' => [
 219       'node.example.com',
 220       # ...
 221     ],
 222   },
 223 )
 224 ```
 225
 226 ### References of deployed key and certificate file paths (with default attributes)
 227
 228 - `node['ssl_cert']["#{ca}_cert_path"]`: e.g. `node['ssl_cert']['grid_ca_cert_path']`
 229 - `node['ssl_cert']["#{ca}_pubkey_path"]`: e.g. `node['ssl_cert']['grid_ssh_ca_pubkey_path']`
 230 - `node['ssl_cert']["#{ca}_krl_path"]`: e.g. `node['ssl_cert']['grid_ssh_ca_krl_path']`
 231 - `node['ssl_cert']["#{undotted_cn}_key_path"]`: e.g. `node['ssl_cert']['node_example_com_key_path']`
 232 - `node['ssl_cert']["#{undotted_cn}_cert_path"]`: e.g. `node['ssl_cert']['node_example_com_cert_path']`
 233
 234 ### Helper methods
 235
 236 - `SSLCert::Helper.get_vault_item_value(vault, name)`: return vault item value string.
 237 - `SSLCert::Helper.append_ca_name(ca_name)`: append CA name which certificate is deployed.
 238 - `SSLCert::Helper.ca_cert_path(ca_name)`: return CA certificate file path string.
 239 - `SSLCert::Helper.ca_pubkey_path(ca_name)`: return CA public key file path string.
 240 - `SSLCert::Helper.ca_krl_path(ca_name)`: return CA KRL file path string.
 241 - `SSLCert::Helper.append_server_ssl_cn(common_name)`: append server common name which key and certificate are deployed.
 242 - `SSLCert::Helper.server_key_content(common_name)`: return server private key content string.
 243 - `SSLCert::Helper.server_cert_content(common_name)`: return server certificate content string.
 244 - `SSLCert::Helper.server_key_path(common_name)`: return server private key file path string.
 245 - `SSLCert::Helper.server_cert_path(common_name)`: return server certificate file path string.
 246 - `SSLCert::Helper.append_members_to_key_access_group(members_array)`: append members to the key access group (default: `ssl-cert`).
 247
 248 ```ruby
 249 ::Chef::Recipe.send(:include, SSLCert::Helper)
 250
 251 append_members_to_key_access_group(['openldap'])
 252 grid_ca_cert_path = ca_cert_path('grid_ca')
 253 ldap_key_path = server_key_path('ldap.grid.example.com')
 254 ldap_cert_path = server_cert_path('ldap.grid.example.com')
 255 ```
 256
 257 ## License and Authors
 258
 259 - Author:: whitestar at osdn.jp
 260
 261 ```text
 262 Copyright 2016, whitestar
 263
 264 Licensed under the Apache License, Version 2.0 (the "License");
 265 you may not use this file except in compliance with the License.
 266 You may obtain a copy of the License at
 267
 268     http://www.apache.org/licenses/LICENSE-2.0
 269
 270 Unless required by applicable law or agreed to in writing, software
 271 distributed under the License is distributed on an "AS IS" BASIS,
 272 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 273 See the License for the specific language governing permissions and
 274 limitations under the License.
 275 ```