cookbook 'certificate', '= 1.0.0'
certificate
(30) Versions
1.0.0
-
Follow6
Installs and configures certificates, private keys, CA root bundles from encrypted data bags.
cookbook 'certificate', '= 1.0.0', :supermarket
knife supermarket install certificate
knife supermarket download certificate
Certificate cookbook
Description
This recipe automates the common task of managing x509 certificates and keys
from encrypted Data Bags. This cookbook provides a flexible and re-usable
LWRP which can be plugged into other recipes, such as the postfix or apache2
cookbooks.
Warning about Vault mode
Vault mode is not supported in chef-solo, and will result in a failure condition. One needs
to select either encrypted, or unencrypted, data_bag_type
for use with chef-solo.
Testing with encrypted data_bags
The KITCHEN.md is a reference document for testing encrypted data_bags with test-kitchen.
The stub files intest/integration
are used to validate the certificate_manage
library.
These stub files in test/integration
should not be used in production. These files include
self-signed "snake oil" certificate/key and an encrypted_data_bag_secret
file
which are not secure to use beyond testing.
Requirements
You do need to prepare an encrypted data bag, containing the certificates,
private keys, and CA bundles you wish to deploy to servers with the LWRP.
I used Joshua Timberman's blog post,
and the Opscode Wiki documentation
as a reference in creating this cookbook.
First, create a data bag secret as follows. You need to manually copy
the encrypted_data_bag_secret to /etc/chef on your servers, or place it
there as part of your bootstrap process. For example, you may choose to
do deploy the secret file with kickstart or preseed as part of the OS
install process.
openssl rand -base64 512 > ~/.chef/encrypted_data_bag_secret
Second, create a data bag, the default data bag within the LWRP is
named certificates. However, you may override this with the
data_bag LWRP attribute.
knife data bag create certificates
You need to convert your certificate, private keys, and CA bundles into
single-line blobs with literal \n
characters. This is so it may be
copy/pasted into your data bag. You can use sed
or you can use a Perl
or Ruby one-liner for this conversion.
cat | sed s/$/\\\\n/ | tr -d '\n'
-OR-
/usr/bin/env ruby -e 'p ARGF.read'
-OR-
perl -pe 's!(\x0d)?\x0a!\\n!g'
What we're trying to accomplish is converting this:
-----BEGIN CERTIFICATE-----
MIIEEDCCA3mgAwIBAgIJAO4rOcmpIFmPMA0GCSqGSIb3DQEBBQUAMIG3MQswCQYD
-----END CERTIFICATE-----
Into this:
-----BEGIN CERTIFICATE-----\nMIIEEDCCA3mgAwIBAgIJAO4rOcmpIFmPMA0GCSqGSIb3DQEBBQUAMIG3MQswCQYD\n-----END CERTIFICATE-----
Finally, you'll want to create the data bag object to contain your certs,
keys, and optionally your CA root chain bundle. The default recipe uses
the OHAI attribute hostname as a search_id. One can use an fqdn as the search_id.
Older versions of Knife have a strict character filter list which prevents the use of .
separators in data bag IDs.
The cookbook also contains an example wildcard recipe to use with wildcard
certificates (*.example.com) certificates.
Hostname mail as data bag search_id:
knife data bag create certificates mail --secret-file ~/.chef/encrypted_data_bag_secret
The resulting encrypted data bag for a hostname should be structured like so.
The chain id may be optional if your CA's root chain is already trusted by the
server.
{
"id": "mail",
"cert": "-----BEGIN CERTIFICATE-----\nMail Certificate Here...",
"key": "-----BEGIN PRIVATE KEY\nMail Private Key Here...",
"chain": "-----BEGIN CERTIFICATE-----\nCA Root Chain Here..."
}
Wildcard certificate as data bag search_id:
knife data bag create certificates wildcard --secret-file ~/.chef/encrypted_data_bag_secret
The resulting encrypted data bag should be structured like so for a wildcard
certificate. The chain id may be optional if your CA's root chain is already
trusted by the server.
{
"id": "wildcard",
"cert": "-----BEGIN CERTIFICATE-----\nWildcard Certificate Here...",
"key": "-----BEGIN PRIVATE KEY\nWildcard Private Key Here...",
"chain": "-----BEGIN CERTIFICATE-----\nCA Root Chain Here..."
}
Recipes
This cookbook comes with three simple example recipes for using the certificate_manage LWRP.
default
Searches the data bag, certificates, for an object with an id matching
node.hostname. Then the recipe places the decrypted certificates and keys
in either /etc/pki/tls (RHEL family), or /etc/ssl (Debian family). The
default owner and group owner of the resulting files are root.
The resulting files will be named {node.fqdn}.pem (cert),
{node.fqdn}.key (key), and {node.hostname}-bundle.crt (CA Root chain).
wildcard
Same as the default recipe, except for the search id is wildcard.
The resulting files will be named wildcard.pem (cert), wildcard.key (key),
and wildcard-bundle.crt (CA Root chain)
manage_by_attributes
Retrieve search keys from attributes "certificate".
Set ID and LWRP attributes to node attribute following...
"certificate": [
{"self": null},
{"mail": {
"cert_path": "/etc/postfix/ssl",
"owner": "postfix",
"group": "postfix"
}
},
]
Resources/Providers
resources
The LWRP resource attributes are as follows.
-
data_bag
- Data bag index to search, defaults to certificates -
data_bag_secret
- Path to the file with the data bag secret -
data_bag_type
- encrypted, unencrypted, vault- vault type data bags are not supported with chef-solo
-
search_id
- Data bag id to search for, defaults to provider name -
cert_path
- Top-level SSL directory, defaults to vendor specific location -
cert_file
- The basename of the x509 certificate, defaults to {node.fqdn}.pem -
key_file
- The basename of the private key file, defaults to {node.fqdn}.key -
chain_file
- The basename of the x509 certificate, defaults to {node.hostname}-bundle.crt -
nginx_cert
- Iftrue
, combines server and CA certificates for nginx. Defaultfalse
-
combined_file
- Iftrue
, combines server cert, CA cert and private key into a single file. Defaultfalse
-
owner
- The file owner, defaults to root -
group
- The file group owner, defaults to root -
cookbook
- The cookbook containing the erb template, defaults to certificate -
create_subfolders
- Enable/disable auto-creation of private/certs subdirectories. Defaults to true
providers
-
certificate_manage
- The reusable LWRP to manage certificates, keys, and CA bundles
Usage
Here is a flushed out example using the LWRP to manage your certificate
items on a Postfix bridgehead. The following example should select the
mail data bag object, from the certificates data bag.
It should then place the managed certificate files in /etc/postfix/ssl,
and change the owner/group to postfix.
certificate_manage "mail" do cert_path "/etc/postfix/ssl" owner "postfix" group "postfix" end
.certificate, .key, .chain helper method usage
Some helper methods are exposed for retrieving key/certificate paths in other recipes:
-
.certificate
- The final path of the certificate file. i.e.#{cert_path}/certs/#{cert_file}
-
.key
- The final path of the key file. i.e.#{cert_path}/private/#{key_file}
-
.chain
- The final path of the chain file. i.e.#{cert_path}/certs/#{chain_file}
# where node.fqdn = 'example.com' tld = certificate_manage 'top_level_domain' tld_cert_location = tld.certificate # => /etc/ssl/certs/example.com.pem # where node.fqdn = 'sub.example.com' sbd = certificate_manage 'sub_domain' do cert_path '/bobs/emporium' create_subfolders false end sbd_cert_location = sbd.key # => /bobs/emporium/sub.example.com.key
Setting FQDN during the converge?
If you are updating the FQDN of the node during converge, be sure to use lazy attribute evaluation when using the LWRP to ensure node['fqdn']
refers to the updated value.
certificate_manage "wildcard" do cert_file lazy { "#{node['fqdn']}.pem" } key_file lazy { "#{node['fqdn']}.key" } chain_file lazy { "#{node['fqdn']}-bundle.crt" } end
License and Author
Author:: Eric G. Wolfe eric.wolfe@gmail.com
Copyright:: 2012, Eric G. Wolfe
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Dependent cookbooks
chef-vault >= 0.0.0 |
Contingent cookbooks
There are no cookbooks that are contingent upon this one.
certificate cookbook changelog
v1.0.0
- #45 @dmlb2000 added
data_bag_type
parameter and support for vault, or unencrypted modes.- Using vault type data bags in chef-solo is not supported, and results in a fatal condition.
- Update documentation for helper methods.
v0.8.2
- #43 @hartfordfive added sensitive mode to hide certificates and keys in console output.
- #47 @fletchowns added documentation note concerning lazy attribute evaluation.
v0.8.1
- Fix bad pick on merge conflict from revert.
v0.8.0
Revert #38
This previous change worked around a bug in Knife that limited use of characters
in data bags. See CHEF-3531 for more information.
This reverts commit 7b091cfe039da729926d12a4e31da2db6aceb007.
v0.7.0
- #33 expose final path of managed objects.
- See for usage.
- #38 normalize dots to underscore in search_id
- #40 chefspec matcher deprecation
- Update travis config
v0.6.3
- #30 Hash rockets
- #34 Rescue version
v0.6.0
- Add thor-scmversion
- Add use_inline_resources, if defined
- Add ignore_missing parameter
v0.5.2
- Update documentation
- Update gitignore
- Rubocop whitespace corrections
v0.5.0
- ChefSpec create_certificate_manage matcher added.
- Added combined_file resource.
- Update build files.
- Added Rubocop.
- Added BATS tests.
v0.4.3
- Issue #16, fix handling of subdir creation
v0.4.2
- Issue #15, Revert FC017 change
v0.4.1
- FC017: LWRP does not notify when updated: ./providers/manage.rb:24
v0.4.0
- Add
nginx_cert
knob for chained certificates
v0.3.0
- Add test-kitchen coverage and documentation.
v0.2.3
- Fix typo in "manage" resource definitions
v0.2.2
- Add :create_subfolders attribute, to toggle off folder creation of private/certs directories.
v0.2.1
- Fixes issue #11, reported by @tmatilia
v0.2.0
Cleaning up the backlog of PRs
- @kechagia added data_bag_secret attribute
- @sawanoboly added smartos paths, and recipe
certificate::manage_by_attributes
- allow specification of data bag secret
- new attribute added: data_bag_secret
- defaults to /etc/chef/encrypted_data_bag_secret
- openssl certs path for smartos
- add recipe manage_by_attributes
- Add :data_bag_keyfile attribute to the LWRP.
v0.1.0
Thanks Teemu, and Kris, for their outstanding work!
-
Teemu Matilainen
- Add whyrun mode support.
- Extract directory and file creation to generic methods.
- Corrected outstanding issues related to updated_by_last_action
-
Kris Kechagia
- Corrected the updated_by_last_action to avoid unneccessary notification.
v0.0.6
- Fix incorrect has_key conditional
- Disable incorrect foodcritic warning about repetition
v0.0.5
- Add foodcritic linting
- Anyone have ideas on testing LWRPs?
v0.0.4
- Fix default action
v0.0.3
- Minor typo fixes
v0.0.2
- LWRP conversion of recipe
v0.0.1
- Recipe prototype
Collaborator Number Metric
1.0.0 passed this metric
Contributing File Metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Foodcritic Metric
1.0.0 failed this metric
FC064: Ensure issues_url is set in metadata: certificate/metadata.rb:1
FC065: Ensure source_url is set in metadata: certificate/metadata.rb:1
FC066: Ensure chef_version is set in metadata: certificate/metadata.rb:1
FC069: Ensure standardized license defined in metadata: certificate/metadata.rb:1
FC074: LWRP should use DSL to define resource's default action: certificate/resources/manage.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: certificate/providers/manage.rb:95
FC085: Resource using new_resource.updated_by_last_action to converge resource: certificate/providers/manage.rb:109
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
No Binaries Metric
1.0.0 passed this metric
Testing File Metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
1.0.0 passed this metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file
Foodcritic Metric
1.0.0 failed this metric
FC064: Ensure issues_url is set in metadata: certificate/metadata.rb:1
FC065: Ensure source_url is set in metadata: certificate/metadata.rb:1
FC066: Ensure chef_version is set in metadata: certificate/metadata.rb:1
FC069: Ensure standardized license defined in metadata: certificate/metadata.rb:1
FC074: LWRP should use DSL to define resource's default action: certificate/resources/manage.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: certificate/providers/manage.rb:95
FC085: Resource using new_resource.updated_by_last_action to converge resource: certificate/providers/manage.rb:109
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
No Binaries Metric
1.0.0 passed this metric
Testing File Metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
1.0.0 failed this metric
FC065: Ensure source_url is set in metadata: certificate/metadata.rb:1
FC066: Ensure chef_version is set in metadata: certificate/metadata.rb:1
FC069: Ensure standardized license defined in metadata: certificate/metadata.rb:1
FC074: LWRP should use DSL to define resource's default action: certificate/resources/manage.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: certificate/providers/manage.rb:95
FC085: Resource using new_resource.updated_by_last_action to converge resource: certificate/providers/manage.rb:109
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
1.0.0 passed this metric
Testing File Metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file
Version Tag Metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number
1.0.0 failed this metric
1.0.0 failed this metric
Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number