cookbook 'ssl_certificate', '~> 2.1.0'
ssl_certificate
(23) Versions
2.1.0
-
Follow29
The main purpose of this cookbook is to make it easy for other cookbooks to support SSL. With the resource included, you will be able to manage certificates reading them from attributes, data bags or chef-vaults. Exposing its configuration through node attributes.
cookbook 'ssl_certificate', '~> 2.1.0', :supermarket
knife supermarket install ssl_certificate
knife supermarket download ssl_certificate
SSL Certificate Cookbook
The main purpose of this Chef cookbook is to make it easy for other cookbooks to support SSL. With the resource included, you will be able to manage certificates reading them from attributes, data bags or chef-vaults. Exposing its configuration through node attributes.
Much of the code in this cookbook is heavily based on the SSL implementation from the owncloud cookbook.
Table of Contents
- Requirements
-
Usage
- Including the Cookbook
- A Short Example
- Namespaces
- Examples
- Apache Examples
- Nginx Example
- Reading the Certificate from Attributes
- Reading the Certificate from a Data Bag
- Reading the Certificate from Chef Vault
- Reading the Certificate from Files
- Reading the Certificate from Different Places
- Creating a Certificate with Subject Alternate Names
- Reading Key, Certificate and Intermediary from a Data Bag
- Creating a PKCS12 Containing Both the Certificate and the Private Key
- Creating a Certificate from a Certificate Authority
- Reading the CA Certificate from a Chef Vault Bag
- Managing Certificates Via Attributes
- Real-world Examples
- Attributes
- Resources
- Templates
- Testing
- Contributing
- TODO
- License and Author
Requirements
Supported Platforms
This cookbook has been tested on the following platforms:
- Amazon Linux
- CentOS
- Debian
- Fedora
- FreeBSD
- Oracle Linux
- RedHat
- Scientific Linux
- Ubuntu
- Windows
Please, let us know if you use it successfully on any other platform.
Required Applications
- Chef
12
or higher. - Ruby
2.2
or higher.
Usage
Including the Cookbook
You need to include this recipe in your run_list
before using the ssl_certificate
resource:
{ "name": "example.com", "[...]": "[...]", "run_list": [ "recipe[ssl_certificate]" ] }
You can also include the cookbook as a dependency in the metadata of your cookbook:
# metadata.rb depends 'ssl_certificate'
One of the two is enough. No need to do anything else. Only use the ssl_certificate
resource to create the certificates you need.
A Short Example
cert = ssl_certificate 'webapp1' do namespace node['webapp1'] # optional but recommended end # you can now use the #cert_path and #key_path methods to use in your # web/mail/ftp service configurations log "WebApp1 certificate is here: #{cert.cert_path}" log "WebApp1 private key is here: #{cert.key_path}"
Namespaces
The ssl_certificate
resource namespace parameter is a node attribute path, like for example node['example.com']
, used to configure SSL certificate defaults. This will make easier to integrate the node attributes with the certificate creation matters. This means you can configure the certificate creation through node attributes.
When a namespace is set in the resource, it will try to read the following attributes below the namespace (all attributes are optional):
Attribute | Description |
---|---|
namespace['common_name'] |
Server name or Common Name, used for self-signed certificates (uses node['fqdn'] by default). |
namespace['country'] |
Country, used for self-signed certificates. |
namespace['city'] |
City, used for self-signed certificates. |
namespace['state'] |
State or Province name, used for self-signed certificates. |
namespace['organization'] |
Organization or Company name, used for self-signed certificates. |
namespace['department'] |
Department or Organizational Unit, used for self-signed certificates. |
namespace['email'] |
Email address, used for self-signed certificates. |
namespace['source'] |
Attribute for setting certificate source and key source (both) to a value (key_source and cert_source ). |
namespace['bag'] |
Attribute for setting certificate bag and key bag (both) to a value (key_bag and cert_bag ). |
namespace['item'] |
Attribute for setting certificate item name and key bag item name (both) to a value (key_item and cert_item ). |
namespace['encrypted'] |
Attribute for setting certificate encryption and key encryption (both) to a value (key_encryption and cert_encryption ). |
namespace['secret_file'] |
Attribute for setting certificate chef secret file and key chef secret file (both) to a value (key_secret_file and cert_secret_file ). |
namespace['ssl_key']['source'] |
Source type to get the SSL key from. Can be 'self-signed' , 'attribute' , 'data-bag' , 'chef-vault' or 'file' . |
namespace['ssl_key']['path'] |
File path of the SSL key. |
namespace['ssl_key']['mode'] |
File mode of the SSL key. |
namespace['ssl_key']['bag'] |
Name of the Data Bag where the SSL key is stored. |
namespace['ssl_key']['item'] |
Name of the Data Bag Item where the SSL key is stored. |
namespace['ssl_key']['item_key'] |
Key of the Data Bag Item where the SSL key is stored. |
namespace['ssl_key']['encrypted'] |
Whether the Data Bag where the SSL key is stored is encrypted. |
namespace['ssl_key']['secret_file'] |
Secret file used to decrypt the Data Bag where the SSL key is stored. |
namespace['ssl_key']['content'] |
SSL key content used when reading from attributes. |
namespace['ssl_key']['length'] |
RSA key length used when generating a new key. |
namespace['ssl_cert']['source'] |
Source type to get the SSL cert from. Can be 'self-signed' , 'attribute' , 'data-bag' , 'chef-vault' or 'file' . |
namespace['ssl_cert']['path'] |
File path of the SSL certificate. |
namespace['ssl_cert']['bag'] |
Name of the Data Bag where the SSL cert is stored. |
namespace['ssl_cert']['item'] |
Name of the Data Bag Item where the SSL cert is stored. |
namespace['ssl_cert']['item_key'] |
Key of the Data Bag Item where the SSL cert is stored. |
namespace['ssl_cert']['encrypted'] |
Whether the Data Bag where the SSL cert is stored is encrypted. |
namespace['ssl_cert']['secret_file'] |
Secret file used to decrypt the Data Bag where the SSL cert is stored. |
namespace['ssl_cert']['content'] |
SSL cert content used when reading from attributes. |
namespace['ssl_cert']['subject_alternate_names'] |
An array of Subject Alternate Names for the SSL cert. Needed if your site has multiple domain names on the same cert. |
namespace['ssl_cert']['extended_key_usage'] |
An array of extended key usage attributes. |
namespace['ssl_chain']['name'] |
File name to be used for the intermediate certificate chain file. If this is not present, no chain file will be written. |
namespace['ssl_chain']['source'] |
Source type to get the intermediate certificate chain from. Can be 'attribute' , 'data-bag' , 'chef-vault' or 'file' . |
namespace['ssl_chain']['path'] |
File path of the intermediate SSL certificate chain. |
namespace['ssl_chain']['bag'] |
Name of the Data Bag where the intermediate certificate chain is stored. |
namespace['ssl_chain']['item'] |
Name of the Data Bag Item where the intermediate certificate chain is stored. |
namespace['ssl_chain']['item_key'] |
Key of the Data Bag Item where the intermediate certificate chain is stored. |
namespace['ssl_chain']['encrypted'] |
Whether the Data Bag where the intermediate certificate chain is stored is encrypted. |
namespace['ssl_chain']['secret_file'] |
Secret file used to decrypt the Data Bag where the intermediate certificate chain is stored. |
namespace['ssl_chain']['content'] |
Intermediate certificate chain content used when reading from attributes. |
namespace['ca_cert_path'] |
Certificate Authority full path. |
namespace['ca_key_path'] |
Key Authority full path. |
namespace['ca_key_passphrase'] |
Key Authority passphrase. |
namespace['pkcs12_path'] |
Optional PKCS12 full path. |
namespace['pkcs12_passphrase'] |
Optional PKCS12 passphrase. |
Examples
Apache Examples
Apache web_app
example using community apache2 cookbook and node attributes:
node.default['my-webapp']['common_name'] = 'example.com' node.default['my-webapp']['ssl_cert']['source'] = 'self-signed' node.default['my-webapp']['ssl_key']['source'] = 'self-signed' # we need to save the resource variable to get the key and certificate file # paths cert = ssl_certificate 'my-webapp' do # we want to be able to use node['my-webapp'] to configure the certificate namespace node['my-webapp'] notifies :restart, 'service[apache2]' end include_recipe 'apache2' include_recipe 'apache2::mod_ssl' web_app 'my-webapp' do # this cookbook includes a virtualhost template for apache2 cookbook 'ssl_certificate' server_name cert.common_name docroot # [...] # [...] ssl_key cert.key_path ssl_cert cert.cert_path ssl_chain cert.chain_path end
Using custom paths:
my_key_path = '/etc/keys/my-webapp.key' my_cert_path = '/etc/certs/my-webapp.pem' # there is no need to save the resource in a variable in this case because we # know the paths ssl_certificate 'my-webapp' do key_path my_key_path key_mode 00640 cert_path my_cert_path end # Configure Apache SSL include_recipe 'apache2::mod_ssl' web_app 'my-webapp' do cookbook 'ssl_certificate' # [...] ssl_key my_key_path ssl_cert my_cert_path end
Nginx Example
Minimal nginx
example using community nginx cookbook:
cert = ssl_certificate 'my-webapp' do notifies :restart, 'service[nginx]' end # Create a virtualhost for nginx template ::File.join(node['nginx']['dir'], 'sites-available', 'my-webapp-ssl') do # You need to create a template for nginx to enable SSL support and read the # keys from ssl_key and ssl_chain_combined attributes. # You can use the *nginx.erb* partial template as shown below. source 'nginx_vhost.erb' mode 00644 owner 'root' group 'root' variables( name: 'my-webapp-ssl', server_name: 'ssl.example.com', docroot: '/var/www', # [...] ssl_key: cert.key_path, ssl_cert: cert.chain_combined_path ) notifies :reload, 'service[nginx]' end # Enable the virtualhost nginx_site 'my-webapp-ssl' do enable true end # publish the certificate to an attribute, it may be useful node.set['web-app']['ssl_cert']['content'] = cert.cert_content
Here's a nginx template example using the nginx.erb partial template:
<%# nginx_vhost.erb %> server { server_name <%= @server_name %>; listen 443; # Path to the root of your installation root <%= @docroot %>; access_log <%= node['nginx']['log_dir'] %>/<%= @name %>-access.log combined; error_log <%= node['nginx']['log_dir'] %>/<%= @name %>-error.log; index index.html; <%# [...] %> <%= render 'nginx.erb', cookbook: 'ssl_certificate' %> }
Reading the Certificate from Attributes
The SSL certificate can be read from an attribute directly:
# Setting the attributes node.default['mysite']['ssl_key']['content'] = '-----BEGIN PRIVATE KEY-----[...]' node.default['mysite']['ssl_cert']['content'] = '-----BEGIN CERTIFICATE-----[...]' # Creating the certificate ssl_certificate 'mysite' do common_name 'cloud.mysite.com' namespace node['mysite'] # this will read the node['mysite']['ssl_key']['content'] and # node['mysite']['ssl_cert']['content'] keys source 'attribute' end
Alternative example using a namespace and node attributes:
# Setting the attributes node.default['mysite']['common_name'] = 'cloud.mysite.com' node.default['mysite']['ssl_key']['source'] = 'attribute' node.default['mysite']['ssl_key']['content'] = '-----BEGIN PRIVATE KEY-----[...]' node.default['mysite']['ssl_cert']['source'] = 'attribute' node.default['mysite']['ssl_cert']['content'] = '-----BEGIN CERTIFICATE-----[...]' # Creating the certificate ssl_certificate 'mysite' do namespace node['mysite'] end
Reading the Certificate from a Data Bag
ssl_certificate 'mysite' do common_name 'cloud.mysite.com' source 'data-bag' bag 'ssl_data_bag' key_item 'key' # data bag item key_item_key 'content' # data bag item json key cert_item 'cert' cert_item_key 'content' encrypted true secret_file '/path/to/secret/file' # optional end
Alternative example using a namespace and node attributes:
# Setting the attributes node.default['mysite']['common_name'] = 'cloud.mysite.com' node.default['mysite']['ssl_key']['source'] = 'data-bag' node.default['mysite']['ssl_key']['bag'] = 'ssl_data_bag' node.default['mysite']['ssl_key']['item'] = 'key' node.default['mysite']['ssl_key']['item_key'] = 'content' node.default['mysite']['ssl_key']['encrypted'] = true node.default['mysite']['ssl_key']['secret_file'] = '/path/to/secret/file' node.default['mysite']['ssl_cert']['source'] = 'data-bag' node.default['mysite']['ssl_cert']['bag'] = 'ssl_data_bag' node.default['mysite']['ssl_cert']['item'] = 'key' node.default['mysite']['ssl_cert']['item_key'] = 'content' node.default['mysite']['ssl_cert']['encrypted'] = true node.default['mysite']['ssl_cert']['secret_file'] = '/path/to/secret/file' # Creating the certificate ssl_certificate 'mysite' do namespace node['mysite'] end
Reading the Certificate from Chef Vault
ssl_certificate 'mysite' do common_name 'cloud.mysite.com' source 'chef-vault' bag 'ssl_vault_bag' key_item 'key' # data bag item key_item_key 'content' # data bag item json key cert_item 'cert' cert_item_key 'content' end
The same example, using a namespace and node attributes:
# Setting the attributes node.default['mysite']['common_name'] = 'cloud.mysite.com' node.default['mysite']['ssl_key']['source'] = 'chef-vault' node.default['mysite']['ssl_key']['bag'] = 'ssl_vault_bag' node.default['mysite']['ssl_key']['item'] = 'key' node.default['mysite']['ssl_key']['item_key'] = 'content' node.default['mysite']['ssl_cert']['source'] = 'chef-vault' node.default['mysite']['ssl_cert']['bag'] = 'ssl_vault_bag' node.default['mysite']['ssl_cert']['item'] = 'key' node.default['mysite']['ssl_cert']['item_key'] = 'content' # Creating the certificate ssl_certificate 'mysite' do namespace node['mysite'] end
For testing you can enabled fall back to use unencrypted data bags if chef
vault is not found by setting attribute ['chef-vault']['databag_fallback']
to
true value
Reading the Certificate from Files
ssl_certificate 'mysite' do common_name 'cloud.mysite.com' source 'file' key_path '/path/to/ssl/key' cert_path '/path/to/ssl/cert' end
The same example, using a namespace and node attributes:
# Setting the attributes node.default['mysite']['common_name'] = 'cloud.mysite.com' node.default['mysite']['ssl_key']['source'] = 'file' node.default['mysite']['ssl_key']['path'] = '/path/to/ssl/key' node.default['mysite']['ssl_cert']['source'] = 'file' node.default['mysite']['ssl_cert']['path'] = '/path/to/ssl/cert' # Creating the certificate ssl_certificate 'mysite' do namespace node['mysite'] end
Reading the Certificate from Different Places
You can also read the certificate and the private key from different places each:
ssl_certificate 'mysite' do common_name 'cloud.mysite.com' # Read the private key from chef-vault key_source 'chef-vault' key_bag 'ssl_vault_bag' key_item 'key' # data bag item key_item_key 'content' # data bag item json key # Read the public cert from a non-encrypted data bag cert_source 'data-bag' cert_bag 'ssl_data_bag' cert_item 'cert' cert_item_key 'content' cert_encrypted false end
The same example, using a namespace and node attributes:
# Setting the attributes node.default['mysite']['common_name'] = 'cloud.mysite.com' # Read the private key from chef-vault node.default['mysite']['ssl_key']['source'] = 'chef-vault' node.default['mysite']['ssl_key']['bag'] = 'ssl_vault_bag' node.default['mysite']['ssl_key']['item'] = 'key' node.default['mysite']['ssl_key']['item_key'] = 'content' # Read the public cert from a non-encrypted data bag node.default['mysite']['ssl_cert']['source'] = 'data-bag' node.default['mysite']['ssl_cert']['bag'] = 'ssl_data_bag' node.default['mysite']['ssl_cert']['item'] = 'key' node.default['mysite']['ssl_cert']['item_key'] = 'content' node.default['mysite']['ssl_cert']['encrypted'] = false # Creating the certificate ssl_certificate 'mysite' do namespace node['mysite'] end
Creating a Certificate with Subject Alternate Names
domain = 'mysite.com' # SAN for mysite.com, foo.mysite.com, bar.mysite.com, www.mysite.com node.default[domain]['ssl_cert']['subject_alternate_names'] = [domain, "foo.#{domain}", "bar.#{domain}", "www.#{domain}"] ssl_certificate 'mysite.com' do namespace node[domain] key_source 'self-signed' cert_source 'self-signed' end
The subject_alternate_names parameter adds DNS values by default. You can also include other kind of values using a colon to separate the type from the value:
domain = 'mysite.com' node.default[domain]['email'] = 'email@example.com' node.default[domain]['ssl_cert']['subject_alternate_names'] = [ 'email:copy', "email:my@#{domain}", "URI:http://#{domain}/", 'IP:192.168.7.1', 'IP:13::17', 'RID:1.2.3.4', 'otherName:1.2.3.4;UTF8:some other identifier' ] ssl_certificate 'mysite.com' do namespace node[domain] key_source 'self-signed' cert_source 'self-signed' end
See the x509v3_config manual page for more information.
Reading Key, Certificate and Intermediary from a Data Bag
cert_name = 'chain-data-bag' node.default[cert_name]['ssl_key']['source'] = 'data-bag' node.default[cert_name]['ssl_key']['bag'] = 'ssl' node.default[cert_name]['ssl_key']['item'] = 'key' node.default[cert_name]['ssl_key']['item_key'] = 'content' node.default[cert_name]['ssl_key']['encrypted'] = true node.default[cert_name]['ssl_cert']['source'] = 'data-bag' node.default[cert_name]['ssl_cert']['bag'] = 'ssl' node.default[cert_name]['ssl_cert']['item'] = 'cert' node.default[cert_name]['ssl_cert']['item_key'] = 'content' node.default[cert_name]['ssl_chain']['name'] = 'chain-ca-bundle.pem' node.default[cert_name]['ssl_chain']['source'] = 'data-bag' node.default[cert_name]['ssl_chain']['bag'] = 'ssl' node.default[cert_name]['ssl_chain']['item'] = 'chain' node.default[cert_name]['ssl_chain']['item_key'] = 'content' ssl_certificate 'chain-data-bag' do namespace cert_name end
Creating a PKCS12 Containing Both the Certificate and the Private Key
ssl_certificate 'mysite' do common_name 'cloud.mysite.com' source 'self-signed' key_path '/etc/key/my.key' cert_path '/etc/cert/my.pem' pkcs12_path '/home/me/my.p12' pkcs12_passphrase 'I_Want_To_Secure_My_P12' # optional end
Creating a Certificate from a Certificate Authority
ca_cert = '/usr/share/pki/ca-trust-source/anchors/CA.crt' ca_key = '/usr/share/pki/ca-trust-source/anchors/CA.key' cert = ssl_certificate 'test' do namespace node['test.com'] key_source 'self-signed' cert_source 'with_ca' ca_cert_path ca_cert ca_key_path ca_key ca_key_passphrase ca_key_passphrase end
Reading the CA Certificate from a Chef Vault Bag
In this example, we read the CA certificate from a Chef Vault and use it to generate the shelf-signed certificates:
# Create the CA from a Chef Vault bag ca_cert = ssl_certificate 'ca.example.org' do common_name 'ca.example.org' source 'chef-vault' bag 'ssl' item 'ca_cert' key_item_key 'key_content' cert_item_key 'cert_content' end ssl_certificate 'example.org' do cert_source 'with_ca' ca_cert_path ca_cert.cert_path ca_key_path ca_cert.key_path end
The vault bag content:
{ "id": "ca_cert", "key_content": "-----BEGIN RSA PRIVATE KEY-----\nMIIE [...]", "cert_content": "-----BEGIN CERTIFICATE-----\nMIIE [...]" }
The knife command to create the vault bag item:
$ knife vault create ssl ca_cert [...]
Managing Certificates Via Attributes
Sometimes you may want to use only node attributes to manage some of your SSL Certificates (instead of the ssl_certificate
resource). You can do it using the ssl_certificate::attr_apply
recipe and configuring them inside the node['ssl_certificate']['items']
array:
run_list( 'recipe[ssl_certificate::attr_apply]' ) override_attributes( 'ssl_certificate' => { 'items' => [ { 'name' => 'domain.com', 'dir' => '/etc/nginx/ssl', 'item' => 'domain_com', 'source' => 'chef-vault', 'bag' => 'ssl-vault', 'key_item_key' => 'key', 'cert_item_key' => 'cert', 'chain_item_key' => 'chain', 'chain_source' => 'chef-vault', 'chain_bag' => 'ssl-vault', 'chain_item' => 'domain_com', 'chain_name' => 'domain.com.chain.pem' } ] } )
Real-world Examples
Some cookbooks that use the ssl_certificate
resource to implement SSL/TLS:
-
postfixadmin
cookbook: Uses the certificate for Apache httpd and nginx. -
boxbilling
cookbook: Uses the certificate for Apache httpd and nginx. -
kong
cookbook: Uses the certificate for the embedded nginx server.kong::_configuration
recipe- kong.yml.erb template, which includes the nginx server configuration.
- README.md section
-
postfix-dovecot
cookbook: Creates one certificate for Postfix and another for Dovecot. Uses theSslCertificateCookbook::ServiceHelpers#ssl_config_for_service
helper to set each service SSL configuration (cipher suites, supported protocols, ...).postfix-dovecot::postfix
recipepostfix-dovecot::dovecot
recipe-
postfix-dovecot::ssl_certificate
attributes to set the protocols in the correct format for each service. - README.md section
-
onddo_proftpd
cookbook contains examples to enable TLS:- README.md documentation with a TLS example
-
onddo_proftpd_test::attrs
recipe used fortest-kitchen
integration tests.
Attributes
Attribute | Default | Description |
---|---|---|
node['ssl_certificate']['user'] |
calculated | Default SSL files owner user. |
node['ssl_certificate']['group'] |
calculated | Default SSL files owner group. |
node['ssl_certificate']['key_dir'] |
calculated | Default SSL key directory. |
node['ssl_certificate']['cert_dir'] |
calculated | Default SSL certificate directory. |
Service Attributes
The following attributes are used to integrate SSL specific configurations with different services (Apache, nginx, ...). They are used internally by the apache and nginx templates.
Attribute | Default | Description |
---|---|---|
node['ssl_certificate']['service']['cipher_suite'] |
nil |
Service default SSL cipher suite. |
node['ssl_certificate']['service']['protocols'] |
nil |
Service default SSL protocols. |
node['ssl_certificate']['service']['apache'] |
calculated | Apache web service httpd specific SSL attributes. |
node['ssl_certificate']['service']['nginx'] |
calculated | nginx web service specific SSL attributes. |
node['ssl_certificate']['service']['compatibility'] |
nil |
Service SSL compatibility level (See below). |
node['ssl_certificate']['service']['use_hsts'] |
true |
Whether to enable HSTS in the service. |
node['ssl_certificate']['service']['use_stapling'] |
calculated | Whether to enable OCSP stapling in the service (nginx only, use node['apache']['mod_ssl']['use_stapling'] for apache). |
node['ssl_certificate']['service']['stapling_resolver'] |
calculated | DNS resolver to use for OCSP. Only with Nginx. |
See the ServiceHelpers
class documentation to learn how to integrate them with new services.
Resources
ssl_certificate
Creates a SSL certificate.
By default the resource will create a self-signed certificate, but a custom one can also be used. The custom certificate can be read from several sources:
- Attribute
- Data Bag
- Encrypted Data Bag
- Chef Vault
- File
ssl_certificate Actions
-
create
: Creates the SSL certificate.
ssl_certificate Parameters
Parameter | Default | Description |
---|---|---|
namespace | {} |
Node namespace to read the default values from, something like node['myapp'] . See the documentation above for more information on how to use the namespace. |
common_name | namespace['common_name'] |
Server name or Common Name, used for self-signed certificates. |
domain | namespace['common_name'] |
common_name method alias. |
country | namespace['country'] |
Country, used for self-signed certificates. |
city | namespace['city'] |
City, used for self-signed certificates. |
state | namespace['state'] |
State or Province name, used for self-signed certificates. |
organization | namespace['city'] |
Organization or Company name, used for self-signed certificates. |
department | namespace['city'] |
Department or Organizational Unit, used for self-signed certificates. |
namespace['email'] |
Email address, used for self-signed certificates. | |
time | 10 * 365 * 24 * 60 * 60 |
Attribute for setting self-signed certificate validity time in seconds or Time object instance. |
years | 10 |
Write only attribute for setting self-signed certificate validity period in years. |
owner | calculated | Certificate files owner user. |
group | calculated | Certificate files owner group. |
dir | nil |
Write only attribute for setting certificate path and key path (both) to a directory (key_dir and cert_dir ). |
source | nil |
Write only attribute for setting certificate source and key source (both) to a value (key_source and cert_source ). Can be 'self-signed' , 'attribute' , 'data-bag' , 'chef-vault' or 'file' . |
bag | nil |
Write only attribute for setting certificate bag and key bag (both) to a value (key_bag and cert_bag ). |
item | nil |
Write only attribute for setting certificate item name and key bag item name (both) to a value (key_item and cert_item ). |
encrypted | nil |
Write only attribute for setting certificate encryption and key encryption (both) to a value (key_encrypted and cert_encrypted ). |
secret_file | nil |
Write only attribute for setting certificate chef secret file and key chef secret file (both) to a value (key_secret_file and cert_secret_file ). |
key_path | calculated | Private key full path. |
key_mode | 0600 |
Private key file mode. |
key_name | "#{name}.key" |
Private key file name. |
key_dir | calculated | Private key directory path. |
key_source | 'self-signed' |
Source type to get the SSL key from. Can be 'self-signed' , 'attribute' , 'data-bag' , 'chef-vault' or 'file' . |
key_bag | namespace['ssl_key']['bag'] |
Name of the Data Bag where the SSL key is stored. |
key_item | namespace['ssl_key']['item'] |
Name of the Data Bag Item where the SSL key is stored. |
key_item_key | calculated | Key of the Data Bag Item where the SSL key is stored. |
key_encrypted | false |
Whether the Data Bag where the SSL key is stored is encrypted. |
key_length | 2048 |
Integer that must be a power of 2, with a reasonable maximum of 4096. This defines the length of a generated RSA key. |
key_secret_file | nil |
Secret file used to decrypt the Data Bag where the SSL key is stored. |
key_content | calculated | SSL key file content in clear. Be careful when using it.**** |
cert_path | calculated | Public certificate full path. |
cert_name | "#{name}.pem" |
Public certiticate file name. |
cert_dir | calculated | Public certificate directory path. |
cert_source | 'self-signed' |
Source type to get the SSL cert from. Can be 'self-signed' , 'with_ca' , 'attribute' , 'data-bag' , 'chef-vault' or 'file' . |
cert_bag | namespace['ssl_cert']['bag'] |
Name of the Data Bag where the SSL cert is stored. |
cert_item | calculated | Name of the Data Bag Item where the SSL cert is stored. |
cert_item_key | calculated | Key of the Data Bag Item where the SSL cert is stored. |
cert_encrypted | false |
Whether the Data Bag where the SSL cert is stored is encrypted. |
cert_secret_file | nil |
Secret file used to decrypt the Data Bag where the SSL cert is stored. |
cert_content | calculated | SSL cert file content in clear. |
subject_alternate_names | nil |
Subject Alternate Names for the cert. |
extended_key_usage | nil |
Extended keyUsage flags array |
chain_path | calculated | Intermediate certificate chain full path. |
chain_name | nil |
File name of intermediate certificate chain file. If this is not present, no chain file will be written. |
chain_dir | calculated | Intermediate certificate chain directory path. |
chain_source | nil |
Source type to get the intermediate certificate chain from. Can be 'attribute' , 'data-bag' , 'chef-vault' or 'file' . |
chain_bag | calculated | Name of the Data Bag where the intermediate certificate chain is stored. |
chain_item | calculated | Name of the Data Bag Item where the intermediate certificate chain is stored. |
chain_item_key | calculated | Key of the Data Bag Item where the intermediate certificate chain is stored. |
chain_encrypted | false |
Whether the Data Bag where the intermediate certificate chain is stored is encrypted. |
chain_secret_file | nil |
Secret file used to decrypt the Data Bag where the intermediate certificate chain is stored. |
chain_content | calculated | Intermediate certificate chain file content in clear. |
chain_combined_name | calculated | File name of intermediate certificate chain combined file (for nginx). |
chain_combined_path | calculated | Intermediate certificate chain combined file full path (for nginx). |
ca_cert_path | nil | Certificate Authority full path. |
ca_key_path | nil | Key Authority full path. |
ca_key_passphrase | nil | Key Authority passphrase. |
pkcs12_path | nil | Optional PKCS12 full path. |
pkcs12_passphrase | nil | Optional PKCS12 passphrase. |
Templates
This cookbook includes a simple VirtualHost template which can be used by the web_app
definition from the apache2 cookbook:
cert = ssl_certificate 'my-webapp' do namespace node['my-webapp'] notifies :restart, 'service[apache2]' end include_recipe 'apache2' include_recipe 'apache2::mod_ssl' web_app 'my-webapp' do cookbook 'ssl_certificate' server_name cert.common_name docroot # [...] # [...] ssl_key cert.key_path ssl_cert cert.cert_path ssl_chain cert.chain_path end
Partial Templates
This cookbook contains partial templates that you can include in your virtualhost templates to enable and configure the SSL protocol. These partial templates are available:
- apache.erb: For Apache httpd web server.
- nginx.erb: For nginx web server.
Partial Templates Parameters
Parameter | Default | Description |
---|---|---|
ssl_cert | nil |
Public SSL certificate full path. |
ssl_key | nil |
Private SSL key full path. |
ssl_chain | nil |
Intermediate SSL certificate chain full path (apache only) (optional). |
ssl_compatibility | node attribute | SSL compatibility level (See below). |
Apache Partial Template
Using web_app
Definition
If you are using the web_app
definition, you should pass the @params
variables to the partial template:
web_app 'my-webapp-ssl' do docroot node['apache']['docroot_dir'] server_name cert.common_name # [...] ssl_key cert.key_path ssl_cert cert.cert_path ssl_chain cert.chain_path end
<%# included by web_app definition %> <VirtualHost *:443> ServerName <%= @params[:server_name] %> DocumentRoot <%= @params[:docroot] %> <%# [...] %> <%= render 'apache.erb', cookbook: 'ssl_certificate', variables: @params.merge(node: node) %> </VirtualHost>
Using template
Resource
cert = ssl_certificate 'my-webapp-ssl' template ::File.join(node['apache']['dir'], 'sites-available', 'my-webapp-ssl') do source 'apache_vhost.erb' # [...] variables( # [...] ssl_key: cert.key_path, ssl_cert: cert.chain_combined_path, ssl_chain: cert.chain_path ) end
You can include the partial template as follows:
<%# included by template resource %> <VirtualHost *:443> ServerName <%= @server_name %> DocumentRoot <%= @docroot %> <%# [...] %> <%= render 'apache.erb', cookbook: 'ssl_certificate' %> </VirtualHost>
Nginx Partial Template
If you are using nginx template, we recommended to use the SslCertificate#chain_combined_path
path value to set the ssl_cert
variable instead of SslCertificate#cert_path
. That's to ensure we always include the chained certificate if there is one. This will also work when there is no chained certificate.
cert = ssl_certificate 'my-webapp-ssl' template ::File.join(node['nginx']['dir'], 'sites-available', 'my-webapp-ssl') do source 'nginx_vhost.erb' # [...] variables( # [...] ssl_key: cert.key_path, ssl_cert: cert.chain_combined_path ) end
See the examples above.
Securing Server Side TLS
You can change the SSL compatibility level based on the TLS recommendations in the Mozilla wiki using the ssl_compatibility
template parameter:
cert = ssl_certificate 'my-webapp' do namespace node['my-webapp'] notifies :restart, 'service[apache2]' end include_recipe 'apache2' include_recipe 'apache2::mod_ssl' web_app 'my-webapp' do cookbook 'ssl_certificate' server_name cert.common_name docroot # [...] # [...] ssl_key cert.key_path ssl_cert cert.cert_path ssl_chain cert.chain_path ssl_compatibility :modern # :modern | :intermediate | :old end
You can also use the node['ssl_certificate']['service']['compatibility']
node attribute to change the compatibility level used by default.
Testing
See TESTING.md.
ChefSpec Matchers
ssl_certificate(name)
Helper method for locating a ssl_certificate
resource in the collection.
resource = chef_run.ssl_certificate('postfixadmin') expect(resource).to notify('service[apache2]').to(:restart)
create_ssl_certificate(name)
Assert that the Chef run creates ssl_certificate.
expect(chef_run).to create_ssl_certificate('cloud.mysite.com')
Contributing
Please do not hesitate to open an issue with any questions or problems.
See CONTRIBUTING.md.
TODO
See TODO.md.
License and Author
Author: | Raul Rodriguez (raul@raulr.com) |
Author: | Xabier de Zuazo (xabier@zuazo.org) |
Contributor: | Steve Meinel |
Contributor: | Djuri Baars |
Contributor: | Elliott Davis |
Contributor: | Jeremy MAURO |
Contributor: | Benjamin Nørgaard |
Contributor: | Stanislav Bogatyrev |
Contributor: | Karl Svec |
Contributor: | Nikita Borzykh |
Contributor: | Baptiste Courtois |
Contributor: | Taliesin Sisson |
Contributor: | Alexey Demidov |
Contributor: | Ali Ardestani |
Contributor: | HawkAndBaby |
Contributor: | Andrew J. Brown |
Copyright: | Copyright (c) 2015-2017, Xabier de Zuazo |
Copyright: | Copyright (c) 2014-2015, Onddo Labs, SL. |
License: | Apache License, Version 2.0 |
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
This cookbook has no specified dependencies.
Contingent cookbooks
ssl_certificate CHANGELOG
This file is used to list changes made in each version of the ssl_certificate
cookbook.
v2.1.0 (2017-02-10)
- Adds certificate chain to PKCS12 file (issue #32, thanks Andrew J. Brown).
- Metadata: Remove grouping (RFC-85).
v2.0.0 (2016-11-28)
- Require Chef
12
and Ruby2.2
or higher (breaking change). - Support for extendedKeyUsage and RSA key length (issue #28, thanks Ali Ardestani and HawkAndBaby).
Make resolver changeable on Nginx (issue #29, thanks @runningman84 for reporting).
-
Testing:
- .rubocop.yml: increase some limits.
- Fix unit tests on Travis.
- Gemfile updated.
v1.12.0 (2016-06-06)
- Add support for CA with passphrase (issue #16, thanks Baptiste Courtois).
- Fallback to unencrypted data bag with
node['chef-vault']['databag_fallback']
(issue #25, thanks Alexey Demidov). - Add custom file mode for key file (issue #26, thanks Alexey Demidov).
Update RuboCop to
0.40
.-
Documentation:
- Improve
chain_name
parameter requirement documentation (issue #24, thanks Alexey Demidov). - Improve TESTING documentation.
- README: Add license badge.
- Improve
-
Testing:
- Remove useless test attributes (issue #16, thanks Baptiste Courtois).
- Add a .kitchen.cloud.yml file.
- Fix unit tests.
- Disable some broken integration tests.
- CircleCI update: Use Ruby
2.3
. - Berksfile: Add info link and avoid calculating the cookbook name.
- Gemfile:
- Update kitchen-ec2 to version 1.
- Update foodcritic to
6.3
.
v1.11.0 (2015-12-10)
- Fix some RuboCop offenses.
- Only add internal file resources to the collection when running tests (issue #23, thanks Karl Svec).
- Fix sending notifications from the
ssl_certificate
resource (issue #21, thanks Karl Svec). - .gitignore: remove metadata.json.
v1.10.0 (2015-11-23)
- Fix some certificate errors on Windows due to CRLF conversion (issue #19, thanks Taliesin Sisson).
Fix undefined method pkcs12_path for Chef::Resource::File error.
-
Documentation:
- README: Some typos and improvements.
-
Testing:
- Gemfile updates:
- foodcritic
~>
5.0.0` - RuboCop
~>
0.35.0`. - Berkshelf
~> 4.0
. - guard-foodcritic
~> 2.0
. - Rakefile:
- Fix integration task to allow arguments.
- Check CI.
v1.9.0 (2015-09-06)
- Add support for PKCS12 (issue #17, thanks Baptiste Courtois).
metadata: Add
source_url
andissues_url
links.-
Documentation:
- README: Add Real-world Examples section.
-
Testing:
- Run kitchen tests on CircleCI.
- Travis CI: Use bundle cache.
- Gemfile: Update RuboCop to
0.34.0
. - Rakfile: Use
Kitchen
ruby class instead ofsh
.
v1.8.1 (2015-09-03)
- README: Fix title.
v1.8.0 (2015-09-03)
- Fix Chef Supermarket cookbook links.
- Add Windows support (issue #15, thanks Baptiste Courtois).
- Add Oracle Linux and Scientific Linux support.
Improve platforms support using
node['platform_family']
attribute.-
Documentation:
- README:
- Add ca path documentation to the namespace attributes.
- Improve description.
- TESTING: Add Docker and EC2 documentation.
-
Testing:
- Use
SoloRunner
to run unit tests faster. - Move ChefSpec tests to test/unit.
- Add .kitchen.docker.yml file.
- Travis CI: Run against Ruby
2.2
. - Gemfile: kichen-docker ~>
2.1
. - Rakfile: Add clean task.
- Use
v1.7.0 (2015-08-12)
- Fix README tables.
- Update contact information and links after migration.
- Gemfile: Update RuboCop to
0.33.0
. - Update chef links to use chef.io.
v1.6.0 (2015-08-02)
- Load encrypted secret before passing to the
EncryptedDataBagItem.load
(issue #14, thanks Nikita Borzykh). - Update RuboCop to
0.32.1
. - README:
- Use markdown tables.
- Add GitHub badge.
v1.5.0 (2015-04-25)
- Add sensitive true to the created files (issue #12, thanks Jonathan Chauncey for reporting).
- Add support for different types in Subject Alternative Names (issue #13, thanks Jonathan Chauncey for reporting).
- README: Fix all RuboCop offenses in examples.
- Update Gemfile and kitchen.yml files.
- Gemfile: Update RuboCop to
0.30.1
.
- Gemfile: Update RuboCop to
v1.4.0 (2015-04-05)
- Add
attr_apply
recipe: Create a certificate list from attributes (issue #10, thanks Stanislav Bogatyrev). - Fix invalid metadata (issue #11, thanks Karl Svec).
- Update RuboCop to
0.29.1
(fix some new offenses).
v1.3.0 (2015-02-03)
- Add
namespace['source']
common attribute. - Fix chef vault source:
chef_gem
method not found error. - Fix
#data_bag_read_fail
method name. - README: Fix item_key attribute name.
v1.2.2 (2015-01-16)
- Fix unit tests: Run the tests agains Chef 11 and Chef 12.
v1.2.1 (2015-01-16)
- Fix key content when using
'file'
source.
v1.2.0 (2015-01-07)
- Fix file source path in attributes.
- Fix "stack level too deep" error with CA certificates.
- Nginx template: Add
ssl on;
directive. - Remove setting CA in apache template (bad idea).
- Rename template helpers to service helpers.
- Document ServiceHelpers methods.
- README: Some small fixes.
v1.1.0 (2015-01-02)
- Fix FreeBSD support.
- Allow to change the certificate file owner.
- Web server template improvements:
- Fix Apache 2.4 support.
- Add partial templates for Apache and nginx.
- Add CA certificate file support.
- Add adjustable SSL compatibility level.
- Add OCSP stapling support.
- Enable HSTS and stapling by default.
- Fix all integration tests.
v1.0.0 (2014-12-30)
- Bugfix: Cannot read SSL intermediary chain from data bag.
- Fix Directory Permissions for Apache
2.4
(issue #7, thanks Elliott Davis). - Add CA support for self signed certificates (issue #8, thanks Jeremy MAURO).
- Apache template:
- Disable
SSLv3
by default (breaking change). - Add chained certificate support.
- Allow to change the cipher suite and protocol in the apache template.
- Disable
- Big code clean up:
- Split resource code in multiple files.
- Remove duplicated code.
- Integrate with foodcritic.
- Integrate with RuboCop.
- Integrate with
should_not
gem. - Integrate with travis-ci, codeclimate and gemnasium.
- Homogenize license headers.
- Add ChefSpec unit tests.
- Add integration tests: bats and Serverspec.
- Update Gemfile and Berksfile files.
- Add Guardfile.
- README:
- Multiple fixes and improvements (issue #9, thanks Benjamin Nørgaard).
- Split in multiple files.
- Add TOC.
- Add badges.
- Add LICENSE file.
v0.4.0 (2014-11-19)
- Add Apache 2.4 support (issue #4, thanks Djuri Baars).
- Add supported platform list.
- kitchen.yml completed and updated.
v0.3.0 (2014-11-03)
Special thanks to Steve Meinel for his great contributions.
- Add Subject Alternate Names support for certs (issue #2, thanks Steve Meinel).
- Add support for deploying an intermediate cert chain file (issue #3, thanks Steve Meinel).
- ChefSpec matchers: add helper methods to locate LWRP resources.
- README: Chef
11.14.2
required. - TODO: complete it with more tasks and use checkboxes.
v0.2.1 (2014-09-14)
-
ssl_certificate
resource notifications fixed (issue #1, thanks Matt Graham for reporting)
v0.2.0 (2014-08-13)
- Added ChefSpec ssl_certificate matcher
- Fixed: undefined method "key_path" for nil:NilClass
- README: fixed ruby syntax highlighting in one example
v0.1.0 (2014-04-15)
- Initial release of
ssl_certificate
Collaborator Number Metric
2.1.0 failed this metric
Failure: Cookbook has 1 collaborators. A cookbook must have at least 2 collaborators to pass this metric.
Contributing File Metric
2.1.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
2.1.0 failed this metric
FC069: Ensure standardized license defined in metadata: ssl_certificate/metadata.rb:1
FC072: Metadata should not contain "attribute" keyword: ssl_certificate/metadata.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: ssl_certificate/libraries/provider_ssl_certificate.rb:45
FC085: Resource using new_resource.updated_by_last_action to converge resource: ssl_certificate/libraries/provider_ssl_certificate.rb:67
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
No Binaries Metric
2.1.0 passed this metric
Testing File Metric
2.1.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
2.1.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
2.1.0 failed this metric
2.1.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
2.1.0 failed this metric
FC069: Ensure standardized license defined in metadata: ssl_certificate/metadata.rb:1
FC072: Metadata should not contain "attribute" keyword: ssl_certificate/metadata.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: ssl_certificate/libraries/provider_ssl_certificate.rb:45
FC085: Resource using new_resource.updated_by_last_action to converge resource: ssl_certificate/libraries/provider_ssl_certificate.rb:67
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
No Binaries Metric
2.1.0 passed this metric
Testing File Metric
2.1.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
2.1.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
2.1.0 failed this metric
FC072: Metadata should not contain "attribute" keyword: ssl_certificate/metadata.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: ssl_certificate/libraries/provider_ssl_certificate.rb:45
FC085: Resource using new_resource.updated_by_last_action to converge resource: ssl_certificate/libraries/provider_ssl_certificate.rb:67
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any
2.1.0 passed this metric
Testing File Metric
2.1.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
2.1.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
2.1.0 failed this metric
2.1.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