apartment_acme_client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: df3fe0ce816007d23a0fbbdfbdffba71e2239cb5
+  data.tar.gz: 03a37c82154522be994c86a27e070231b13d131a
+SHA512:
+  metadata.gz: 39d796e4b59aa6e5b2773bac1e0eda6e7bce36b88aaf6ed77c474322b303b8ec4b0c36d8a27a084b60c8f279e8b74818833c59a1331031e99b402cc7c72a91ed
+  data.tar.gz: 3ab79be5d12515ecad5f305c6eea795325755c1450ddb34cc7ee2e05ecfc203285ed7b8b1fe2b81765334f615aa53cb9b225a083c735327ac0581395c62dc278

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2017 Robin Dunlop
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,305 @@
+# ApartmentAcmeClient
+
+Let's Encrypt interface for Multi-tenancy applications which respond by on many domains/subdomains (like Apartment)
+
+If you have a single server which responds to many different domains, getting Let's Encrypt to provide you with a multi-domain Certificate is possible, but a lot of work.
+
+
+**Note**: This only works up to 100 domains (https://letsencrypt.org/docs/rate-limits/)
+Reference: https://community.letsencrypt.org/t/host-multiple-domains-with-a-single-certificate/20917/2
+
+**Note**: Example usage with real server. Apartment gem with subdomains.
+Reference: https://github.com/influitive/apartment#switch-on-subdomain
+
+The goal of this gem is to solve the following problems:
+
+1) Make it easy to start using let's encrypt for multiple domains on one server
+1) Make it easy to periodically refresh a certificate which handles many domains
+1) Make it possible to add a new DNS entry which refers to the server, and request a cert which now also covers that new domain.
+1) Make it resilient, if a DNS record is removed, handle that by removing that domain from list requested for the cert.
+
+**Example Situation**:
+
+- Your application is known as example.com
+- You allow users to create new accounts, and assign each account a separate subdomain,
+  - e.g. alice.example.com, bob.example.com, charlie.example.com
+- You allow users to also whitelabel the service by buying their own domains, and setting up CNAME records:
+  - e.g. www.alice.com -> CNAME: alice.example.com
+  - e.g. bobrocks.com -> CNAME: bob.example.com
+
+**What can ApartmentAcmeClient do?**
+
+- Create a single Let's Encrypt SSL Certificate which covers all of:
+  - example.com
+  - alice.example.com
+  - bob.example.com
+  - charlie.example.com
+  - www.alice.com
+  - bobrocks.com
+
+
+SSL Certificates
+----------------
+
+In order to provide a secure connection, we are using [letsencrypt.org](https://letsencrypt.org) to
+automatically create ssl certificates for the various domains which the server will run on. But, we are doing the validation/registration through the `acme-client` gem instead of using the lets-encrypt binary.
+
+Periodically, we check all configured domains, and re-configure the nginx server to properly respond to any newly configured domain names. If we have a new domain name, we also request a new SSL certificate, enabling HTTPS for that domain.
+
+How the Encryption process works:
+---------------------------------
+
+1. A list of domains which are served by this server is created.
+2. The list of all these domains is used to determine which ones are properly configured in DNS.
+3. We `authorize` each domain with LetsEncrypt
+4. A new SSL certificate is requested and installed3
+5. Nginx is restarted to pick up the new certificate.
+
+Setting up crypto the first time:
+---------------------------------
+
+1. `rake encryption:create_crypto_client` - Register an account with LetsEncrypt
+2. `rake encryption:renew_and_update_certificate` - Authorize/create certificates
+3. `rake encryption:update_nginx_config` - re-write the nginx file to point at the certificates
+
+At this point, the only thing necessary is to run `rake renew_and_update_certificate` on a regular basis, which will find new domains, authorize them, and get new SSL certs for them.
+
+See below for a detailed explanation of "First Time Setup"
+
+## Testing things out
+
+When setting this up the first time, it is recommended that you enable test-mode:
+```ruby
+ApartmentAcmeClient.lets_encrypt_test_server_enabled = true
+```
+
+so that all your requests are made against the test Let's Encrypt server.
+
+This will also cause your DER and PEM files to be prefixed with "test_" to make it possible to have REAL and FAKE certs in parallel
+
+Once you have an SSL Cert installed which is doing everything correctly (except not from the "REAL" server) you can restart the process.
+- Set `ApartmentAcmeClient.lets_encrypt_test_server_enabled = false`
+
+start at step 1 (`rake encryption:create_crypto_client`)....
+
+-----------------------------------
+## Pre-requisites
+
+In order for the application to function properly, it is assumed that the application is running in the following configuration:
+
+- Nginx running as a service with a socket tunnel to the rails application
+- Nginx can be restarted by `sudo service nginx restart`
+- Rails application running, which can serve files from a `/public`-like directory
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'apartment_acme_client'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apartment_acme_client
+
+## Usage
+
+### Mount the engine
+
+We do this so that we can verify the site responds to a URL before we ask Lets Encrypt to verify the site.
+
+```ruby
+mount ApartmentAcmeClient::Engine => '/aac' # you can define whatever path you want to mount the engine
+```
+
+### Configure the client
+
+Create an initializer for the client. Usually `config/initializers/apartment_acme_client.rb`
+
+Add the following configuration entries
+
+#### Specify the domains to be checked
+
+Define the code which will list the domains to check.
+
+```ruby
+# Should return an array of domains (without http/https prefixes)
+
+# It can be a straight array, or a callable object
+ApartmentAcmeClient.domains_to_check = -> { SomeModel.all.map(&:subdomain) }
+
+# e.g.
+# ApartmentAcmeClient.domains_to_check = ["example.com", "alice.example.com", "alice.com"]
+```
+
+#### Specify the common-name domain
+
+This is used to identify the certificate requested, and should be the same from week-to-week.
+
+This should be a URL which you control the DNS for, ensuring that it will ALWAYS be pointing at your application. (ie: not subject to the whims of your users).
+
+Note: The nginx configuration will be configured to respond to `common_name` and `*.common_name` sources.
+
+```ruby
+ApartmentAcmeClient.common_name = "example.com"
+```
+
+#### Specify public folder
+
+Specify where to put the "challenge" files which can be fetched by let's encrypt when validating the domains
+
+**Note**: this folder should be not be derived from Rails.root, because that is a sym-link, which changes release to release.
+
+```ruby
+ApartmentAcmeClient.public_folder = "/home/ec2-user/app/current/public" # not: Rails.root.join('public')
+```
+
+#### Where to store the certificates on the server
+
+Directory where to store certificates locally. This folder must persist between deployments, so that nginx can reference it permanently.
+```ruby
+ApartmentAcmeClient.certificate_storage_folder = "/home/ec2-user/app/current/public/system" # not: Rails.root.join("public", "system")
+```
+
+If you are using capistrano for deployments, add public/system to your `linked_dirs`
+
+```ruby
+# deploy.rb
+set :linked_dirs, %w[public/system]
+```
+
+#### S3 Backup Storage settings
+
+Each time a certificate is requested from Let's Encrypt, we also store it in S3 in case something happens to the server/filesystem.
+
+In order for this to work, you must specify the aws_region and aws_bucket
+
+```ruby
+ApartmentAcmeClient.aws_region = Rails.application.secrets.aws_region
+ApartmentAcmeClient.aws_bucket = Rails.application.secrets.aws_bucket
+```
+
+#### Nginx configuration settings
+
+It is assumed that the /etc/nginx/nginx.conf file has a line like:
+```
+http {
+    # Many lines....
+
+    include /etc/nginx/conf.d/*.conf;
+}
+```
+
+Then, the site's configuration is actually stored in /etc/nginx/conf.d/site.conf
+
+So, the nginx_config_path would be
+```ruby
+ApartmentAcmeClient.nginx_config_path = "/etc/nginx/conf.d/site.conf"
+```
+
+Assuming that your application is running unicorn with a socket.
+
+Example:
+```
+# workers
+worker_processes 1
+
+# listen
+listen "/tmp/unicorn-application.socket", backlog: 64
+
+# Many more lines....
+```
+
+```ruby
+ApartmentAcmeClient.socket_path = "/tmp/unicorn-application.socket"
+```
+
+#### Force-SSL Options
+
+If you ever choose to enable force-ssl on your server, you will need to set
+the `ApartmentAcmeClient.verify_over_https = true` so that verification checks occur
+over https instead of http
+
+------------------------------------------------------
+## First Time Setup
+
+1) Register with Let's Encrypt
+
+Before we can make requests to Let's encrypt, we need to create a private key, which we will use for all future requests to Let's encrypt. To do this, run `rake encryption::create_crypto_client[my_email@example.com]` (replacing the email address with yours)
+
+This will create a new private key, store it on S3, and register that key with let's encrypt for your e-mail address.
+
+2) Create your initial certificate
+
+Initially, your nginx configuration will not reference any ssl certificate files, because you don't have any.
+So the first thing you must do is request an initial certificate using `rake encryption:renew_and_update_certificate`
+
+Once this is done, the newly acquired certificate will be stored on the server, for use by nginx in step 3.
+
+3) Tell Nginx where to get it's SSL certificates
+
+The Nginx configuration must be updated to point to the SSL Certificate location.
+
+run `rake encryption:update_nginx_config` in order to write the ngnix configuration file, and restart the nginx service.
+
+At this point, the only thing necessary is to run `rake renew_and_update_certificate` on a regular basis, which will find new domains, authorize them, and get new SSL certs for them. It will also restart nginx, to have it pick up the new certificate.
+
+------------------------------------------------------
+### Schedule a weekly task to be run.
+
+Each week, the certificates should be renewed. We have provided 2 ways to do this.
+
+a rake task:
+```ruby
+rake "encryption:renew_and_update_certificate"
+```
+
+straight invocation:
+
+```ruby
+ApartmentAcmeClient::RenewalService.run!
+```
+
+Please use whatever scheduling service you wish in order to ensure that this runs periodically.
+e.g. [whenever](https://github.com/javan/whenever)
+
+----------------------------------------------------------------------
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rdunlop/apartment_acme_client.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).
+
+--------------------------------------------
+
+## Known issues
+
+- Depends on the `aws-sdk-s3` S3 gem version "~> 1".
+- It expects the hosting application has configured the AWS credentials.
+
+e.g.:
+```ruby
+Aws.config.update(
+  region: Rails.application.secrets.aws_region,
+  credentials: Aws::Credentials.new(
+    Rails.application.secrets.aws_access_key,
+    Rails.application.secrets.aws_secret_access_key
+  )
+)
+```
+
+TODO
+- Get CI running

data/Rakefile

@@ -0,0 +1,29 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ApartmentAcmeClien'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/app/assets/config/apartment_acme_client_manifest.js

@@ -0,0 +1,2 @@
+//= link_directory ../javascripts/apartment_acme_client .js
+//= link_directory ../stylesheets/apartment_acme_client .css

data/app/assets/javascripts/apartment_acme_client/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file. JavaScript code in this file should be added after the last require_* statement.
+//
+// Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/app/assets/stylesheets/apartment_acme_client/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/apartment_acme_client/application_controller.rb

@@ -0,0 +1,5 @@
+module ApartmentAcmeClient
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/apartment_acme_client/verifications_controller.rb

@@ -0,0 +1,5 @@
+class ApartmentAcmeClient::VerificationsController < ApartmentAcmeClient::ApplicationController
+  def verify
+    render plain: "TRUE"
+  end
+end

data/app/helpers/apartment_acme_client/application_helper.rb

@@ -0,0 +1,4 @@
+module ApartmentAcmeClient
+  module ApplicationHelper
+  end
+end

data/app/jobs/apartment_acme_client/application_job.rb

@@ -0,0 +1,4 @@
+module ApartmentAcmeClient
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/apartment_acme_client/application_mailer.rb

@@ -0,0 +1,6 @@
+module ApartmentAcmeClient
+  class ApplicationMailer < ActionMailer::Base
+    default from: 'from@example.com'
+    layout 'mailer'
+  end
+end

data/app/models/apartment_acme_client/application_record.rb

@@ -0,0 +1,5 @@
+module ApartmentAcmeClient
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/apartment_acme_client/verifier.rb

@@ -0,0 +1,38 @@
+require 'net/http'
+
+module ApartmentAcmeClient
+  class Verifier
+    attr_reader :url
+
+    def initialize(url)
+      @url = url
+      @verify_over_https = ApartmentAcmeClient.verify_over_https ? true : false
+    end
+
+    # Determine whether this alias is properly configured
+    # Causes makes a request to a remote server (which should be THIS server)
+    # and determines whether the request was properly received
+    def properly_configured?
+      options = {
+        open_timeout: 5,
+        use_ssl: @verify_over_https,
+        verify_mode: OpenSSL::SSL::VERIFY_NONE # because we might not have a valid cert yet
+      }
+      Net::HTTP.start(url, options) do |http|
+        # Because the engine could be mounted anywhere, we need to get the target
+        # path from the Engine Routes
+        verify_path = ApartmentAcmeClient::Engine.routes.url_helpers.verify_path
+        response = http.get(verify_path)
+
+        return false unless response.is_a?(Net::HTTPSuccess)
+
+        response.body == "TRUE"
+      end
+    rescue SocketError, Net::OpenTimeout, Errno::ECONNREFUSED
+      # SocketError if the server name doesn't exist in DNS
+      # OpenTimeout if no server responds
+      # ECONNREFUSED if the server responds with "No"
+      false
+    end
+  end
+end