Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status

RSS

letsencryptaws (27) Versions 1.0.8

Procures Let's Encrypt SSL certificates for Route 53-hosted domains

Policyfile
Berkshelf
Knife
cookbook 'letsencryptaws', '= 1.0.8', :supermarket
cookbook 'letsencryptaws', '= 1.0.8'
knife supermarket install letsencryptaws
knife supermarket download letsencryptaws
README
Dependencies
Changelog
Quality 67%

letsencryptaws Cookbook

This cookbook is for an implementation of SSL certificate generation and fetching via the Let's Encrypt certificate authority. Certificates are synced from local storage to S3, which is then used by nodes to retrieve the generated certificate. Authentication is done via DNS challenges and automated via Ruby scripts to add and remove TXT records from your domain when required.

Nodes do not need to be EC2 instances to retrieve or request certificates. All that is required is AWS credentials or profile to perform Route 53 and S3 operations.

Requirements

  • Python 2.7 (for certbot and awscli)
  • certbot ACME client
  • Domain(s) hosted by AWS Route 53 (only second-level domains, subdomain zones are not supported)
  • S3 bucket for storing/retrieving certificate files
  • Properly stored AWS credentials (see https://github.com/aws/aws-sdk-ruby#configuration)

Platforms

Certificate generation:
- Ubuntu

The goal for certificate retrieval is to support Windows but for now, Ubuntu only.

Cookbooks

  • remote_file_s3 - To grab certificates from S3
  • poise-python - For grabbing awscli for certificate syncing.

Usage

letsencryptaws::default

Set the certs attribute as described below and then include this recipe in your cookbook or run_list.

NOTE You should manually generate a default certificate (self-signed/fake CA) and place the key, certificate and CA certificate at the "/#{node['letsencryptaws']['sync_path']}/default-ssl" path in your S3 sync bucket. These will act as stand-ins for the real certificates/key until they are generated by letsencryptaws::certbot after they are first "requested" by a node. So in theory, your real certificates will take up to (chef interval + splay * 3) until they land on the requesting node.

The flow looks like this:
- First Chef run on requesting node. Attribute (['letsencryptaws']['certs']['example.com'] = []) gets saved to server (probably created dynamically by a cookbook). Default cert/key gets saved to node from S3.
- Chef run on 'certbot' host. Requests certificate and uploads to S3.
- Second Chef run on requesting node overwrites the previously saved default cert/key with real cert/key from S3.

Any service that uses a certificate provided by this recipe should subscribe to one of the certificate file resources so that it can be reloaded when the certificate is renewed. For example:

service 'nginx' do
  action %i[start enable]
  subscribes :restart, "file[#{::File.join(node['letsencryptaws']['ssl_cert_dir'], 'example.com.crt')}]", :delayed
end

letsencryptaws::certbot

This is meant to be run by a single host that manages fetching certificates based on a Chef server search. Make sure the instance profile or AWS access keys in the data bag is granted the following permissions on the domains in which you allow certificates to be requested by nodes:

  • route53:ChangeResourceRecordSets
  • route53:ListHostedZonesByName
  • route53:GetChange

The credentials will also require write access to the S3 bucket and path that you choose to sync to. The authenticator and cleanup scripts do not use the credential information from the data bag, so it is left up to the user to place the .aws/credentials file in the proper location, if not using an instance profile.

If you desire persistent storage on an EBS volume, use the ['letsencryptaws']['ebs_device'] to specify the path to the device. This will device will have an ext4 filesystem created on it if one does not already exist and be mounted at ['letsencryptaws']['config_dir']. This is where certbot will store its configs and certificates. All operations take place locally at this path and at the end of the recipe gets synced to S3.

Certbot operations use the --expand and --cert-name arguments to keep the certificates up-to-date with the requested names. This means the certificate will be renewed appropriately as nodes desire for the certificate name changes.

letsencryptaws::import_keystore

This recipe takes certificates and imports them into a Java keystore.

Attributes

letsencryptaws::default

For certificate retrieval, just specify what certificates you would like by common name
of the certificate and an array of Subject Alternative Names for the cert. The certificate
may have additional SANs if other nodes request them for the same common name.

<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><tt>['letsencryptaws']['certs']</tt></td>
<td>Hash</td>
<td>keys are the common name, values are an array of strings that are the SANs for the cert. These all get merged together in the final certificate.</td>
<td><tt>{}</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['ssl_cert_dir']</tt></td>
<td>string</td>
<td>path where ssl certs will be downloaded to</td>
<td><tt>/etc/ssl/certs</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['ssl_key_dir']</tt></td>
<td>string</td>
<td>path where ssl private keys will be downloaded to</td>
<td><tt>/etc/ssl/private</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['ssl_ca_dir']</tt></td>
<td>string</td>
<td>path where ssl CA certificates will be downloaded to</td>
<td><tt>/etc/ssl/certs</tt></td>
</tr>
</table>

letsencryptaws::import_keystore

This recipe is automatically included if the import_keystore hash is not empty.

<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><tt>['letsencryptaws']['import_keystore']</tt></td>
<td>Hash</td>
<td>keys are full paths to Java keystores, values are an array of primary names of certificates to add to the keystore</td>
<td><tt>{}</tt></td>
</tr>
</table>

letsencryptaws::certbot

<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><tt>['letsencryptaws']['config_dir']</tt></td>
<td>string</td>
<td>dir where all certbot configuration will be stored, including certs</td>
<td><tt>/mnt/letsencrypt</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['scripts_dir']</tt></td>
<td>string</td>
<td>dir to put Ruby script wrappers that will be used for Route 53 certificate validation</td>
<td><tt>/mnt/letsencrypt/scripts</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['data_bag']</tt></td>
<td>string</td>
<td>Name of data bag used for credentials storage</td>
<td><tt>nil</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['data_bag_item']</tt></td>
<td>string</td>
<td>Name of item within data bag for credentials storage</td>
<td><tt>nil</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['email']</tt></td>
<td>string</td>
<td>Email addressed used for certbot during generation</td>
<td><tt>nobody@example.com</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['ebs_device']</tt></td>
<td>string</td>
<td>device of the ebs volume to mount on config_dir (only applies on ec2 instances)</td>
<td><tt>/dev/xvdf</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['test_certs']</tt></td>
<td>boolean</td>
<td>request certs from staging (signed by fake CA, subject to less rate limiting)</td>
<td><tt>false</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['remove_unused_certs']</tt></td>
<td>boolean</td>
<td>remove certificates that are no longer requested by any node</td>
<td><tt>true</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['sync_bucket']</tt></td>
<td>string</td>
<td>s3 bucket to sync local certificate directory to</td>
<td><tt>nil</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['sync_path']</tt></td>
<td>string</td>
<td>path on the sync_bucket to sync certificate directory to</td>
<td><tt>letsencrypt</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['kms_key_id']</tt></td>
<td>string</td>
<td>UUID of the kms key to use for server-side encryption (optional)</td>
<td><tt>nil</tt></td>
</tr>
<tr>
<td><tt>['letsencryptaws']['blacklist']</tt></td>
<td>array of strings</td>
<td>Exact matches of primary certificate name to prevent generation</td>
<td><tt>[]</tt></td>
</tr>
</table>

Data Bags

A data bag is used to store sensitive credential information for AWS and Java keystores. You can arbitrarily specify the name and item name with node['letsencryptaws']['data_bag'] and node['letsencryptaws']['data_bag_item'] attributes.

The keys inside the data bag item can be:

<table>
<tr>
<th>Key</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><tt>aws_access_key_id</tt></td>
<td>string</td>
<td>AWS_ACCESS_KEY_ID for storing/fetching certificates from S3</td>
</tr>
<tr>
<td><tt>aws_secret_access_key</tt></td>
<td>string</td>
<td>AWS_SECRET_ACCESS_KEY for storing/fetching certificates from S3</td>
</tr>
<tr>
<td><tt>keystore_passwords</tt></td>
<td>hash</td>
<td>Keys are paths to Java keystore files, values are the passwords to them. One special key is default which will be used as a catch-all password if a keystore does not have a specific entry.</td>
</tr>
<tr>
<td><tt>p12_password</tt></td>
<td>string</td>
<td>Password to use when generating pkcs12 keyring files.</td>
</tr>
</table>

License and Authors

Authors: Matt Kulka matt@lqx.net

Dependent cookbooks

poise-python ~> 1.6
remote_file_s3 ~> 1.0.5

Contingent cookbooks

There are no cookbooks that are contingent upon this one.

letsencryptaws CHANGELOG

This file is used to list changes made in each version of the letsencryptaws cookbook.

1.0.8

  • [mattlqx] - Add explicit python package version idna 2.6. Yay constaints.

1.0.7

  • [mattlqx] - Bump cryptography module version.

1.0.6

  • [mattlqx] - Loosen poise-python version dependency.

1.0.5

  • [mattlqx] - Switch backend s3 resource to remote_file_s3

1.0.4

  • [mattlqx] - Use --cert-name attribute for certbot.

1.0.3

  • [mattlqx] - Add attribute for root CA path.

1.0.2

  • [mattlqx] - Correct sync_path default to match documentation.

1.0.1

  • [mattlqx] - Bug fixes and additional docs.

1.0.0

  • [mattlqx] - Sanitize and open-source. Initial public release. 🎉

0.4.0

  • [mattlqx] - Add recipe to import .p12s into arbitrary keystores.

0.3.0

  • [mattlqx] - Bump cryptography version.
  • [mattlqx] - Generate PKCS12 keystore for downloaded certificates.

0.2.8

  • [mattlqx] - Fix to prevent duplicate certs from being deleted.
  • [mattlqx] - Add blacklist attribute to prevent certs from being requested.

0.1.0

  • [mattlqx] - Initial release of letsencryptaws

Check the Markdown Syntax Guide for help with Markdown.

The Github Flavored Markdown page describes the differences between markdown on github and standard markdown.

Collaborator Number Metric
            

1.0.8 failed this metric

Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric
            

1.0.8 passed this metric

Foodcritic Metric
            

1.0.8 passed this metric

No Binaries Metric
            

1.0.8 failed this metric

Failure: Cookbook should not contain binaries. Found:
letsencryptaws/coverage/assets/0.10.2/favicon_red.png
letsencryptaws/coverage/assets/0.10.2/colorbox/controls.png
letsencryptaws/coverage/assets/0.10.2/colorbox/border.png
letsencryptaws/coverage/assets/0.10.2/colorbox/loading.gif
letsencryptaws/coverage/assets/0.10.2/colorbox/loading_background.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_glass_95_fef1ec_1x400.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_highlight-soft_75_cccccc_1x100.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_flat_75_ffffff_40x100.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-icons_888888_256x240.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-icons_222222_256x240.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_glass_55_fbf9ee_1x400.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-icons_454545_256x240.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_glass_75_e6e6e6_1x400.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_glass_65_ffffff_1x400.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-icons_2e83ff_256x240.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_glass_75_dadada_1x400.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-icons_cd0a0a_256x240.png
letsencryptaws/coverage/assets/0.10.2/smoothness/images/ui-bg_flat_0_aaaaaa_40x100.png
letsencryptaws/coverage/assets/0.10.2/magnify.png
letsencryptaws/coverage/assets/0.10.2/favicon_green.png
letsencryptaws/coverage/assets/0.10.2/loading.gif
letsencryptaws/coverage/assets/0.10.2/favicon_yellow.png

Testing File Metric
            

1.0.8 passed this metric

Version Tag Metric
            

1.0.8 passed this metric