anchor-pki 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc0b9b7fe9893fc5d4f23157bbb2a18c4a15066e929024c197b610ef5f6ffd80
-  data.tar.gz: 5cc3e63d7acbc16531c9abf60d04d205fe5ed0b638e595653a8aed74d8abc49a
+  metadata.gz: 30508321e074e903d3e8328cc7b2e32fad03b696a32dbb2f16014e92f7636ede
+  data.tar.gz: 7705acb22177288ac5de11a37c62080504efef41a82c7337673c84dadc90fd28
 SHA512:
-  metadata.gz: 7d5d6bb50ee250800df59aa17ecca780cddc08293ff4bb609a4b944fcc611ef76ec916d5d6b75026694b0740addeabf592533c4117ea90cd3a1032c21c816f5e
-  data.tar.gz: 4e2c6f2a836c59319a6cab2a6f48204d75ae7e8fb1b721e6177c2ec75be57c1f8271a18fef02afc847dc822b1db8e70c228c4cbd90ec023fd54bd8ecd620d87c
+  metadata.gz: 392139d7eea3518ba1d9f9915e628050818e3855494b55876e8fc63ffa4aff45e6434918f8fabae4bd6fe042210ac56fc7b1e0fe6093ee558013b85cb0d15551
+  data.tar.gz: e8f674f66082121873997074914a619205b9375608a6db2f1bd4afe6199d43c96f9874d3d584811f251143cd3c559f90b30ec5ca70ef1c42f01c043da4c3d5ef

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [Unreleased]
+
+## [0.3.0] - 2023-06-02
+
+- improve gem packaging
+- extract out a configuration class for Acme
+- add tests
+
+## [0.2.0] - 2023-04-18
+
+-
+
+## [0.1.0] - 2021-11-05
+
+- Initial release

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in anchor-pki.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,94 @@
+PATH
+  remote: .
+  specs:
+    anchor-pki (0.2.1)
+      acme-client (~> 2.0.13)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    acme-client (2.0.13)
+      faraday (>= 1.0, < 3.0.0)
+      faraday-retry (>= 1.0, < 3.0.0)
+    addressable (2.8.4)
+      public_suffix (>= 2.0.2, < 6.0)
+    ast (2.4.2)
+    crack (0.4.5)
+      rexml
+    diff-lcs (1.5.0)
+    faraday (2.7.5)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    faraday-retry (2.2.0)
+      faraday (~> 2.0)
+    hashdiff (1.0.1)
+    json (2.6.3)
+    minitest (5.18.0)
+    parallel (1.23.0)
+    parser (3.2.2.1)
+      ast (~> 2.4.1)
+    public_suffix (5.0.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.8.0)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.51.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.28.1)
+      parser (>= 3.2.1.0)
+    rubocop-capybara (2.18.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.23.1)
+      rubocop (~> 1.33)
+    rubocop-rspec (2.22.0)
+      rubocop (~> 1.33)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    unicode-display_width (2.4.2)
+    vcr (6.1.0)
+    webmock (3.18.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  aarch64-linux
+  arm64-darwin-21
+  x86_64-darwin-22
+
+DEPENDENCIES
+  anchor-pki!
+  minitest (~> 5.14)
+  rake (~> 13.0)
+  rspec (~> 3.9)
+  rubocop (~> 1.50)
+  rubocop-rspec (~> 2.22)
+  vcr (~> 6.1)
+  webmock (~> 3.8)
+
+BUNDLED WITH
+   2.3.26

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Anchor Security, Inc.
+
+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,48 @@
+# Anchor
+
+Ruby client for Anchor PKI. See https://anchor.dev/ for details.
+
+## Configuration
+
+The Following environment variables are available to configure the default
+[`AutoCert::Manager`](./lib/anchor/auto_cert/manager.rb).
+
+* `HTTPS_PORT` - the TCP numerical port to bind SSL to.
+* `ACME_ALLOW_IDENTIFIERS` - A comma separated list of hostnames for provisioning certs
+* `ACME_DIRECTORY_URL` - the ACME provider's directory
+* `ACME_KID` - your External Account Binding (EAB) KID for authenticating with the ACME directory above with an
+* `ACME_HMAC_KEY` - your EAB HMAC_KEY for authenticating with the ACME directory above
+* `ACME_RENEW_BEFORE_SECONDS` - **optional** Start a renewal this number number of seconds before the cert expires. This defaults to 30 days (2592000 seconds)
+* `ACME_RENEW_BEFORE_FRACTION` - **optional** Start the renewal when this fraction of a cert's valid window is left. This defaults to 0.5, which means when the cert is in the last 50% of its lifespan a renewal is attempted.
+
+If both `ACME_RENEW_BEFORE_SECONDS` and `ACME_RENEW_BEFORE_FRACTION` are set,
+the one that causes the renewal to take place earlier is used.
+
+Example:
+
+* Cert start (not_before) moment is : `2023-05-24 20:53:11 UTC`
+* Cert expiration (not_after) moment is : `2023-06-21 20:53:10 UTC`
+* `ACME_RENEW_BEFORE_SECONDS` is `1209600` (14 days)
+* `ACME_RENEW_BEFORE_FRACTION` is `0.25` - which equates to a before seconds value of `604799` (~7 days)
+
+The possible moments to start renewing are:
+
+* 14 days before expiration moment - `2023-06-07 20:53:10 UTC`
+* when 25% of the valid time is left - `2023-06-14 20:53:11 UTC`
+
+Currently the `AutoCert::Manager` will use whichever is earlier.
+
+### Example configuration
+
+```sh
+HTTPS_PORT=44300
+ACME_ALLOW_IDENTIFIERS=my.lcl.host,*.my.lcl.host
+ACME_DIRECTORY_URL=https://acme-v02.api.letsencrypt.org/directory
+ACME_KID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ACME_HMAC_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](./LICENSE.txt)

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'minitest/test_task'
+Minitest::TestTask.create(:test)
+
+task default: %i[spec test]

data/lib/anchor/auto_cert/configuration.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Anchor
+  module AutoCert
+    # AutoCert Configuration provides a way to configure the AutoCert Manager.
+    #
+    class Configuration
+      DEFAULT_BEFORE_SECONDS  = 60 * 60 * 24 * 30 # 30 days in seconds
+      DEFAULT_BEFORE_FRACTION = 0.5 # when in the last 50% of the validity window, renew
+
+      # Note - although it is possible to set change the name of a config, it is
+      # not recommended. The name is used as the key in the Registry, and if a
+      # Configuration is in the Registry, and its name is changed, it does not
+      # change its registry key.
+      attr_accessor :name,
+                    :allow_identifiers,
+                    :cache,
+                    :contact,
+                    :directory_url,
+                    :external_account_binding,
+                    :renew_before_fraction,
+                    :renew_before_seconds,
+                    :tos_acceptors,
+                    :work_dir
+
+      # rubocop:disable Metrics/ParameterLists
+      # Data defined classes have all required parameters in the initializer, so
+      # override the default initializer to allow for optional parameters and
+      # to pull in the defaults form the environment
+      #
+      def initialize(name:,
+                     allow_identifiers: nil,
+                     cache: nil,
+                     contact: nil,
+                     directory_url: nil,
+                     external_account_binding: nil,
+                     renew_before_fraction: DEFAULT_BEFORE_FRACTION,
+                     renew_before_seconds: DEFAULT_BEFORE_SECONDS,
+                     tos_acceptors: nil,
+                     work_dir: nil)
+
+        @name                     = name
+
+        @allow_identifiers        = allow_identifiers
+        @cache                    = cache
+        @contact                  = contact
+        @directory_url            = directory_url
+        @external_account_binding = external_account_binding
+        @renew_before_fraction    = renew_before_fraction
+        @renew_before_seconds     = renew_before_seconds
+        @tos_acceptors            = tos_acceptors
+        @work_dir                 = work_dir
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def account
+        {
+          contact: contact,
+          external_account_binding: external_account_binding
+        }
+      end
+
+      # Enabled means that the configuration has both allow_identifiers and a
+      # directory url set.
+      def enabled?
+        allow_identifiers && directory_url
+      end
+
+      def validate!
+        @allow_identifiers        = prepare_allow_identifiers(@allow_identifiers)
+        @cache                    = prepare_cache(@cache)
+        @directory_url            = prepare_directory_url(@directory_url)
+        @external_account_binding = prepare_external_account_binding(@external_account_binding)
+        @renew_before_fraction    = prepare_renew_before_fraction(@renew_before_fraction)
+        @renew_before_seconds     = prepare_renew_before_seconds(@renew_before_seconds)
+        @tos_acceptors            = prepare_tos_acceptors(@tos_acceptors)
+        @work_dir                 = prepare_work_dir(@work_dir)
+
+        self
+      end
+
+      private
+
+      def prepare_allow_identifiers(allow_identifiers)
+        prepared = case allow_identifiers
+                   when Array
+                     allow_identifiers
+                   when String
+                     allow_identifiers.split(',')
+                   when nil
+                     ENV.fetch('ACME_ALLOW_IDENTIFIERS', nil)&.split(',')
+                   end
+
+        if prepared.nil? || prepared.empty?
+          raise ConfigurationError,
+                "The '#{name}' #{self.class} instance has a misconfigured `allow_identifiers` value. " \
+                'Set it to a string, or an array of strings, ' \
+                'or set the ACME_ALLOW_IDENTIFIERS environment variable to a comma separated list of identifiers.'
+        end
+
+        prepared
+      end
+
+      def prepare_cache(cache)
+        return nil if cache.nil?
+
+        unless cache.respond_to?(:read) && cache.respond_to?(:write) && cache.respond_to?(:fetch)
+          raise ConfigurationError,
+                "The '#{name}' #{self.class} instance has a misconfigured `cache` value. " \
+                'It must be set to an object that responds to `read`, `write`, and `fetch`.'
+        end
+
+        cache
+      end
+
+      def prepare_directory_url(directory_url)
+        directory_url ||= ENV.fetch('ACME_DIRECTORY_URL', nil)
+        if directory_url.nil?
+          raise ConfigurationError,
+                "The '#{name}' #{self.class} instance has a misconfigured `directory_url` value. " \
+                'It must be set to a string, or set the ACME_DIRECTORY_URL environment variable.'
+        end
+
+        directory_url
+      end
+
+      def prepare_external_account_binding(external_account_binding)
+        kid = ENV.fetch('ACME_KID', nil)
+        hmac_key = ENV.fetch('ACME_HMAC_KEY', nil)
+
+        if kid && hmac_key
+          external_account_binding = {
+            kid: kid,
+            hmac_key: hmac_key
+          }
+        end
+        external_account_binding
+      end
+
+      def prepare_renew_before_seconds(renew_before_seconds)
+        renew_before_seconds ||= ENV.fetch('ACME_RENEW_BEFORE_SECONDS', nil)
+        if renew_before_seconds
+          renew_before_seconds = renew_before_seconds.to_i
+          unless renew_before_seconds.positive?
+            raise ConfigurationError,
+                  "The '#{name}' #{self.class} instance has a misconfigured `before_seconds` value. " \
+                  'It must be set to an integer > 0, or set the ACME_RENEW_BEFORE_SECONDS environment variable.'
+          end
+        end
+        renew_before_seconds
+      end
+
+      def prepare_renew_before_fraction(renew_before_fraction)
+        renew_before_fraction ||= ENV.fetch('ACME_RENEW_BEFORE_FRACTION', nil)
+        if renew_before_fraction
+          renew_before_fraction = renew_before_fraction.to_f
+          unless (0..1).cover?(renew_before_fraction)
+            raise ConfigurationError,
+                  "The '#{name}' #{self.class} instance has a misconfigured `before_fraction` value. " \
+                  'It must be set to a float > 0 and < 1, or set the ACME_RENEW_BEFORE_FRACTION environment variable.'
+          end
+        end
+        renew_before_fraction
+      end
+
+      def prepare_tos_acceptors(tos_acceptors)
+        tos_acceptors = Array(tos_acceptors)
+
+        if tos_acceptors.empty? || tos_acceptors.any? { |tos| !tos.respond_to?(:accept?) }
+          raise ConfigurationError,
+                "The '#{name}' #{self.class} instance has a misconfigured `tos_acceptors` value. " \
+                'It must be set to an object or an array of objects that respond to `accept?`.'
+        end
+
+        tos_acceptors
+      end
+
+      def prepare_work_dir(work_dir)
+        return nil if work_dir.nil?
+
+        work_dir = Pathname.new(work_dir) unless work_dir.is_a?(Pathname)
+
+        begin
+          work_dir.mkpath
+        rescue StandardError => e
+          raise ConfigurationError, "#{self.class}#work_dir : #{e.message}"
+        end
+
+        unless work_dir.directory? && work_dir.writable?
+          raise ConfigurationError, "#{self.class}#work_dir '#{work_dir}' must be a writable directory."
+        end
+
+        work_dir
+      end
+    end
+  end
+end

data/lib/anchor/auto_cert/identifier_policy.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Anchor
+  module AutoCert
+    #
+    # IdentifierPolicy is a class used to check that the identifiers used in
+    # certs would be valid.
+    #
+    # Each IdentierPolicy is initialized with a 'policy_description' which is used to
+    # derive the policy check.
+    #
+    # Current Policy Checks are:
+    # - ForHostname - checks that the identifier matches hostname exactly
+    # - ForWildcardHostname - checks that the identifier matches hostname with a wildcard prefix
+    # - ForIpAddress - checks that the identifier matches an IP address or subnet
+    #
+    class IdentifierPolicy
+      attr_reader :description, :check
+
+      # Given an individual, or an array of IdentifierPolicy or Strings build
+      # IdentifierPolicy objects
+      def self.build(policy_descriptions)
+        Array(policy_descriptions).map do |description|
+          IdentifierPolicy.new(description)
+        end
+      end
+
+      def self.new(description)
+        return description if description.is_a?(IdentifierPolicy)
+
+        super
+      end
+
+      # The list of policy checks that are available, the ordering here is
+      # important as the first one that matches is the one that is used for the
+      # check. So if a policy description would be matched by multiple checks,
+      # the one that it should match should be first.
+      def self.policy_checks
+        @policy_checks ||= [
+          PolicyCheck::ForIPAddr,
+          PolicyCheck::ForHostname,
+          PolicyCheck::ForWildcardHostname
+        ]
+      end
+
+      def initialize(description)
+        check_klass = self.class.policy_checks.find do |klass|
+          klass.handles?(description)
+        end
+        raise UnknownPolicyCheckError, "Unable to create a policy check based upon '#{description}'" if check_klass.nil?
+
+        @description = description
+        @check = check_klass.new(description)
+      end
+
+      def allow?(identifier)
+        raise ArgumentError, 'identifier must be a String' unless identifier.is_a?(String)
+
+        @check.allow?(identifier)
+      end
+
+      def deny?(identifier)
+        !allow?(identifier)
+      end
+    end
+  end
+end
+require_relative 'policy_check'

data/lib/anchor/auto_cert/integration/puma.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Anchor
+  module AutoCert
+    module Integration
+      # Puma integration
+      class Puma
+        def self.ssl_bind_options(manager:, identifiers: nil)
+          identifiers ||= manager.configuration.allow_identifiers
+          cert, key = manager.certificate_paths(identifiers: identifiers)
+
+          { cert: cert, key: key }
+        end
+      end
+    end
+  end
+end

data/lib/anchor/auto_cert/integration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Anchor
+  module AutoCert
+    # Integration module
+    module Integration
+    end
+  end
+end
+
+require_relative 'integration/puma'