• Stars
    star
    112
  • Rank 312,240 (Top 7 %)
  • Language
    Ruby
  • License
    Apache License 2.0
  • Created almost 9 years ago
  • Updated 12 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Chef cookbook to request SSL certificates at Let's Encrypt

ACME cookbook

Build Status Cookbook Version

Automatically get/renew free and trusted certificates from Let's Encrypt (letsencrypt.org). ACME is the Automated Certificate Management Environment protocol used by Let's Encrypt.

Starting with v4.0.0 of the acme cookbook the acme_ssl_certificate provider has been removed! The TLS-SNI-01 validation method used by this provider been disabled by Let's Encrypt due to security concerns. Please switch to the acme_certificate provider in this cookbook to request and renew your certificate using the supported HTTP-01 validation method.

Attributes

Attribute Description Default
contact Contact information, default empty. Set to mailto:[email protected] []
dir ACME server endpoint, Set to https://acme-staging-v02.api.letsencrypt.org/directory if you want to use the Let's Encrypt staging environment and corresponding certificates. https://acme-v02.api.letsencrypt.org/directory
renew Days before the certificate expires at which the certificate will be renewed 30
source_ips IP addresses used by Let's Encrypt to verify the TLS certificates, it will change over time. This attribute is for firewall purposes. Allow these IPs for HTTP (tcp/80). ['66.133.109.36']
private_key Private key content of registered account. Private keys identify the ACME client with the endpoint and are not transferable between staging and production endpoints. nil
private_key_file Filename where private key will be saved. If this file exists, the contents take precedence over the value set in private_key. /etc/acme/account_private_key.pem
key_size Default private key size used when resource property is not. Must be one out of: 2048, 3072, 4096. 2048

Recipes

default

Installs the required acme-client rubygem.

Usage

Use the acme_certificate resource to request a certificate with the http-01 challenge. The webserver for the domain for which you are requesting a certificate must be running on the local server. This resource only supports the http validation method. To use the tls-sni-01 challenge, please see the resource below. Provide the path to your wwwroot for the specified domain.

acme_certificate 'test.example.com' do
  crt               '/etc/ssl/test.example.com.crt'
  key               '/etc/ssl/test.example.com.key'
  wwwroot           '/var/www'
end

If your webserver needs an existing certificate already when installing a new server, you will have a bootstrap problem: The web server cannot start without a certificate, but the certificate cannot be requested without the running web server. To overcome this, a temporary self-signed certificate can be generated with the acme_selfsigned resource, allowing the web server to start.

acme_selfsigned 'test.example.com' do
  crt     '/etc/ssl/test.example.com.crt'
  chain   '/etc/ssl/test.example.com-chain.crt'
  key     '/etc/ssl/test.example.com.key'
end

A working example can be found in the included acme_client test cookbook.

Providers

certificate

Property Type Default Description
cn string name The common name for the certificate
alt_names array [] The common name for the certificate
crt string nil File path to place the certificate
key string nil File path to place the private key
key_size integer 2048 Private key size. Must be one out of: 2048, 3072, 4096
owner string,integer root Owner of the created files
group string,integer root Group of the created files
wwwroot string /var/www Path to the wwwroot of the domain
ignore_failure boolean false Whether to continue chef run if issuance fails
retries integer 0 Number of times to catch exceptions and retry
retry_delay integer 2 Number of seconds to wait between retries
endpoint string nil The Let's Encrypt endpoint to use
contact array [] The contact to use

selfsigned

Property Type Default Description
cn string name The common name for the certificate
crt string nil File path to place the certificate
key string nil File path to place the private key
key_size integer 2048 Private key size. Must be one out of: 2048, 3072, 4096
chain string nil File path to place the certificate chain
owner string,integer root Owner of the created files
group string,integer root Group of the created files

Example

To generate a certificate for an apache2 website you can use code like this:

# Include the recipe to install the gems
include_recipe 'acme'

# Set up contact information. Note the mailto: notation
node.override['acme']['contact'] = ['mailto:[email protected]']
# Real certificates please...
node.override['acme']['endpoint'] = 'https://acme-v01.api.letsencrypt.org'

site = "example.com"
sans = ["www.#{site}"]

# Generate a self-signed if we don't have a cert to prevent bootstrap problems
acme_selfsigned "#{site}" do
  crt     "/etc/httpd/ssl/#{site}.crt"
  key     "/etc/httpd/ssl/#{site}.key"
  chain    "/etc/httpd/ssl/#{site}.pem"
  owner   "apache"
  group   "apache"
  notifies :restart, "service[apache2]", :immediate
end

# Set up your web server here...

# Get and auto-renew the certificate from Let's Encrypt
acme_certificate "#{site}" do
  crt               "/etc/httpd/ssl/#{site}.crt"
  key               "/etc/httpd/ssl/#{site}.key"
  wwwroot           "/var/www/#{site}/htdocs/"
  notifies :restart, "service[apache2]"
  alt_names sans
end

DNS verification

Letsencrypt supports DNS validation. Depending on the setup there may be different ways to deploy an acme challenge to your infrastructure. If you want to use DSN validation, you have to provide two block arguments to the acme_certificate resource.

Implement 2 methods in a library in your cookbook, each returning a Proc object. The following example uses a HTTP API to provide challenges to the DNS infrastructure.

# my_cookbook/libraries/acme_dns.rb

class Chef
  class Recipe
    def install_dns_challenge(apitoken)
      Proc.new do |authorization, new_resource|
        # use DNS authorization
        authz = authorization.dns
        fqdn = authorization.identifier['value']
        r = Net::HTTP.post(URI("https://my_awesome_dns_api/#{fqdn}"), authz.record_content, {'Authorization' => "Token #{apitoken}"})
        if r.code != '200'
          fail "DNS API does not want to install Challenge for #{fqdn}"
        else
          # do some validation that the challenge has propagated to the infrastructure
        end
        # it is important that the authz and fqdn is passed back, so it can be passed to the remove_dns_challenge method
        [authz, fqdn]
      end
    end
    def remove_dns_challenge(apitoken)
      Proc.new do |authz, fqdn|
        uri = URI("https://my_awesome_dns_api/#{fqdn}")
        Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme=='https') do |http|
          http.delete(uri, {'Authorization' => "Token #{apitoken}"})
        end
      end
    end
  end
end

Use it in your recipe the following way:

apitoken = chef_vault_item(vault, item)['dns_api_token']
acme_certificate node['fqdn'] do
  key '/path/to/key'
  crt '/path/to/crt'
  install_authz_block install_dns_challenge(apitoken)
  remove_authz_block remove_dns_challenge(apitoken)
end

Testing

The kitchen includes a pebble server to run the integration tests with, so testing can run locally without interaction with the online APIs.

Contributing

  1. Fork the repository on Github
  2. Create a named feature branch (like add_component_x)
  3. Write your change
  4. Write tests for your change (if applicable)
  5. Run the tests, ensuring they all pass
  6. Submit a Pull Request using Github

License and Authors

Authors: Thijs Houtenbos [email protected]

Credits

Let’s Encrypt is a trademark of the Internet Security Research Group. All rights reserved.

More Repositories

1

vagrant-chef-zero

Vagrant Plugin for Chef Zero
Ruby
91
star
2

awsapilib

A python library exposing services that are not covered by the official boto3 library but are driven by undocumented APIs.
Python
60
star
3

towerlib

A python library to interface with ansible tower's (awx) api.
Python
42
star
4

mercury

Mercury Global Loadbalancer
Go
36
star
5

terraform-aws-mcaf-landing-zone

Terraform module to setup and manage various components of the AWS Landing Zone.
HCL
29
star
6

mod_security

Cookbook for mod_security deployment
HTML
24
star
7

packer-cloudstack

Packer plugin to support Apache Cloudstack
Go
16
star
8

custom-nessus-plugins

Custom Nessus Plugins
15
star
9

data-migrator

A declarative data-migration package
Python
15
star
10

terraform-aws-mcaf-securityhub-findings-manager

Terraform module to suppress specific events from security hub based on a dynamodb based configuration.
HCL
15
star
11

tableau-confluence-plugin

Plugin for confluence to show Tableau graphs within Confluence
Java
14
star
12

sensu-plugins-prometheus-checks

Ruby
14
star
13

awsssolib

A library to help automate AWS SSO activities as it is still not supported by Boto
Python
10
star
14

blu

Blu is a new way to leverage Chef methods in Windows using PowerShell.
C#
8
star
15

RHEL6-CIS

Ansible role for Red Hat 6 CIS Baseline
Makefile
8
star
16

shadowserver_downloader

Download abuse reports from Shadowservers
Python
8
star
17

SLES12-CIS

Ansible role for Suse Linux Enterprise Server 12 Baseline
Jinja
8
star
18

ivil

Intermediate Vulnerability Information Language is is an XML schema for the exchange of vulnerability information from one tool handling vulnerability information to the other.
Perl
7
star
19

keyVault-monitoring-framework

Azure Key Vault Monitoring framework based on Azure Function, Powershell, and Event Grid.
PowerShell
7
star
20

microchassis

Framework to build microservice using GRPC and REST
TypeScript
6
star
21

sensu-plugins-k8s

Additional Sensu plugin to check Kubernetes resources
Ruby
5
star
22

nexenta_base

Cookbook to manage configuration settings of NexentaStor ZFS based storage systems
Ruby
5
star
23

vp-pubsub

VP PubSub is a publish/subscribe library that supports message filtering
JavaScript
5
star
24

Check_Nexenta

Nagios plugin to monitor Nexenta systems.
Python
5
star
25

oktalib

A python library for interfacing with OKTA's api
Python
4
star
26

terraform-aws-mcaf-avm

Terraform module providing an AWS Account Vending Machine (AVM)
HCL
4
star
27

psCloudstack

PowerShell
4
star
28

lastpasslib

Library interacting with lastpass.
Python
4
star
29

terraform-aws-mcaf-matillion

HCL
4
star
30

awsauthenticationlib

A library providing pre signed urls and valid sessions for some aws services that still do not present an api.
Python
3
star
31

twitterwall

Python
3
star
32

terraform-aws-mcaf-account-baseline

Terraform module to setup a baseline configuration for AWS accounts
HCL
3
star
33

jira-workflow-support

Jira plugin for multiproject workflow support - developed by Avisi
Java
3
star
34

okta-terraform-generator

Generate Terraform resources using data from Okta.
Ruby
3
star
35

hashivaultlib

An extension to hvac, implementing recursive removal and retrieval of secrets and models for tokens and policies.
Python
3
star
36

controltowerlib

A library creating a python api on top of contro tower utilizing presigned urls and the undocumented web api.
Python
3
star
37

knife-okta

knife-okta is a knife plugin to interact with the Okta API.
Ruby
2
star
38

tweakers_iot_workshop

PowerShell
2
star
39

datapull

JavaScript
2
star
40

awsenergylabelercli

Python
2
star
41

cloudstack-cookbook

Ruby
2
star
42

grawsp

A command line application to assist engineers manage credentials in an AWS landing zone.
Python
2
star
43

outpost24hiabclient

Python client for Outpost24 HIAB
Python
2
star
44

awsenergylabelerlib

Project energy labeling accounts and landing zones based on findings from a centralized security hub for AWS cloud.
Python
2
star
45

terraformtestinglib

A library that implements linting and testing of terraform resources based on rules.
Python
2
star
46

awsenergylabeler-docker

Dockerfile
2
star
47

mcvs-docker-action

Mission Critical Vulnerability Scanner (MCVS) Docker Action. Build a lean docker image without high and critical vulnerabilities and push it to the GitHub packages.
2
star
48

cloudstack

This is CloudStack 4.4.4
Java
1
star
49

SBPToolkitStarterInfra

1
star
50

outpost24hiablib

Python library for Outpost24 HIAB
Python
1
star
51

terraform-gitlab-mcaf-project

Terraform module to create and manage a GitLab project.
HCL
1
star
52

wiki-challenge

A repo to hold some files for the python challenge
Jupyter Notebook
1
star
53

SUSE15_CIS

Ansible role for Suse & OpenSuse 15 CIS baselining
Jinja
1
star
54

terraform-aws-mcaf-lambda

Terraform module to create an AWS Lambda function
HCL
1
star
55

cue-kube-deploy

CUE
1
star
56

terraform-github-mcaf-repository

Terraform module to create and manage a GitHub repository.
HCL
1
star
57

cue-kube-tenant

Timoni/CUE backed module for Tenant K8s object generation.
CUE
1
star
58

commonutilslib

A library with some common utility methods for python for os functions
Python
1
star
59

terraform_validate_patched

A temporary patched version of GPL versioned project terraform_validate that implements skipping of testing on resource and skipping of empty terraform files.
Python
1
star
60

terraformlintingcli

A cli tool to lint terraform resources based on provided rules
Python
1
star
61

CsFirewall

Opscode Chef cookbook to set cloudstack firewall rules form roles / node attributes
Ruby
1
star
62

seccubus-docker

A docker container for Seccubus
1
star
63

Azure

JavaScript
1
star
64

chef-monitor-cookbook

Chef cookbook to install chef-logmon and chef-worker inside your chef environment.
Ruby
1
star
65

azureenergylabelercli

A cli which uses azureenergylabelerlib to generate energy ratings for Tenants, Subscriptions and Resource Groups
Python
1
star
66

k8s-team-ckad-training

k8s-team-ckad-training
1
star
67

knife-github

Chef knife plugin to interact with the github enterprise appliance
Ruby
1
star
68

awsenergylabeler

Python
1
star
69

terraform-aws-mcaf-vpc

HCL
1
star
70

terraform-aws-mcaf-aurora

Terraform module to create an AWS RDS Aurora cluster
HCL
1
star
71

sbp_packer

A simple Chef cookbook to install Packer
Ruby
1
star
72

qnt-planning

A workshop on a planning problem with a quantum approach and settings on how to execute it on all potential backends.
Jupyter Notebook
1
star
73

qnt-journal-entry-deviation

A workshop on a journal entry deviation using classical ML and quantum ML approaches and run on all possible backends.
Jupyter Notebook
1
star
74

terraform-aws-mcaf-vpc-with-ipam

Terraform module to manage an AWS VPC using the CIDR provided by an IPAM pool.
HCL
1
star