acmesmith 2.2.0 → 2.3.0

data/acmesmith.gemspec

@@ -6,7 +6,7 @@ require 'acmesmith/version'
 Gem::Specification.new do |spec|
   spec.name          = "acmesmith"
   spec.version       = Acmesmith::VERSION
-  spec.authors       = ["sorah (Shota Fukumori)"]
+  spec.authors       = ["Sorah Fukumori"]
   spec.email         = ["her@sorah.jp"]
 
   spec.summary       = %q{ACME client (Let's encrypt client) to manage certificate in multi server environment with cloud services (e.g. AWS)}

data/config.sample.yml

@@ -1,6 +1,15 @@
+###
+### ACME Endpoint Configuration
+###
+
 directory: https://acme-staging-v02.api.letsencrypt.org/directory
 # directory: https://acme-v02.api.letsencrypt.org/directory
 
+###
+### Storage
+###
+
+# Check README and ./docs/storages/* for details
 storage:
   type: s3
   region: 'ap-northeast-1'
@@ -12,8 +21,38 @@ storage:
 #   type: filesystem
 #   path: ./storage
 
+###
+### Challenge responders
+###
+
+# Check README and ./docs/challenge_responders/* for details
 challenge_responders:
+  # Use dns_manual for subjects under ".manual-domain.example.org"
+  - dns_manual: {}
+    filter:
+      subject_name_suffix:
+        - .manual-domain.example.org
+      # subject_name_exact:
+      # subject_name_regexp:
+
+  # Last resort
   - route53: {}
 
-account_key_passphrase: password
-certificate_key_passphrase: secret
+###
+### advanced options
+###
+
+## Passphrase to encrypt key files (optional)
+# account_key_passphrase: password
+# certificate_key_passphrase: secret
+
+## Instead, read passphrases from $ACMESMITH_ACCOUNT_KEY_PASSPHRASE, $ACMESMITH_CERTIFICATE_KEY_PASSPHRASE
+# passphrase_from_env: true
+
+## ACME connection options (Faraday)
+# connection_options:
+#   :tls:
+#     :ca_file: custom_ca_bundle.pem
+
+## acme-client bad_nonce_retry
+# bad_nonce_retry: 2

data/docs/challenge_responders/route53.md

@@ -0,0 +1,28 @@
+# Challenge Responder: Route 53
+
+`route53` responder supports `dns-01` challenge type. This assumes domain NS are managed under Route53 hosted zone.
+
+```yaml
+challenge_responders:
+  - route53:
+      ### AWS Access key (optional, default to aws-sdk standard)
+      aws_access_key:
+        access_key_id:
+        secret_access_key:
+        # session_token:
+
+      ### Assume IAM role to access Route 53
+      # Available options are https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/AssumeRoleCredentials.html
+      assume_role:
+        role_arn: "arn:aws:iam:::..."
+
+      ### Hosted zone map (optional)
+      ##  This specifies an exact hosted zone ID for each domain name.
+      ##  Required when you have multiple hosted zones for the same domain name.
+      hosted_zone_map: 
+        "example.org.": "/hostedzone/DEADBEEF"
+```
+
+## IAM Policy
+
+- [docs/vendor/aws.md](../vendor/aws.md): IAM and KMS key policies, and some tips

data/docs/examples/UpdateWindowsCertificate.ps1

@@ -0,0 +1,58 @@
+#Requires -RunAsAdministrator
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+$PSDefaultParameterValues['*:ErrorAction']='Stop'
+
+Set-Location -Path cert:\LocalMachine\My
+
+$region = "ap-northeast-1"
+$bucket = "your-s3-bucket"
+$prefix = "certs/"
+$cn = "example.com"
+$pfxPassword = ConvertTo-SecureString -String "your-p12-password" -AsPlainText -Force
+$lastCertificateMarkFile = "C:\AcmesmithCert.txt"
+
+if (Test-Path $lastCertificateMarkFile) {
+  $lastCertificate = Get-ChildItem -Path (Get-Content -Path $lastCertificateMarkFile)
+} else {
+  $lastCertificate = $null
+}
+
+Import-Module AWSPowershell
+
+# In powershell 4.x or earlier
+# [System.IO.FileInfo]([System.IO.Path]::GetTempFileName())
+$currentFile = New-TemporaryFile
+Read-S3Object -Region $region -BucketName $bucket -Key ("{0}{1}/current" -f $prefix,$cn) -File $currentFile
+$current =  Get-Content $currentFile
+
+$pfxKey = "{0}{1}/{2}/cert.p12" -f $prefix,$cn,$current
+$chainKey = "{0}{1}/{2}/chain.pem" -f $prefix,$cn,$current
+
+$pfxFile = New-TemporaryFile
+Read-S3Object -Region $region -BucketName $bucket -Key $pfxKey -File $pfxFile
+
+$chainFile = New-TemporaryFile
+Read-S3Object -Region $region -BucketName $bucket -Key $chainKey -File $chainFile
+
+$cert = Import-PfxCertificate -Password $pfxPassword -FilePath $pfxFile.FullName -CertStoreLocation 'cert:\LocalMachine\My'
+Remove-Item $pfxFile
+
+$intermediate = Import-Certificate -FilePath $chainFile.FullName -CertStoreLocation 'cert:\LocalMachine\CA'
+Write-Output $intermediate
+Write-Output $cert
+
+if ($lastCertificate) {
+  Write-Output "Switching"
+  if ($lastCertificate.Thumbprint -ne $cert.Thumbprint) {
+    Switch-Certificate -OldCert $lastCertificate -NewCert $cert
+  }
+}
+$cert.Thumbprint | Out-File $lastCertificateMarkFile
+
+$expiredCerts = Get-ChildItem -Path 'Cert:\LocalMachine\My' -SSLServerAuthentication -ExpiringInDays 0 -DnsName $cert.DnsNameList[0].Unicode
+$expiredCerts | Remove-Item -DeleteKey
+
+## http.sys
+$appid = "{existing-uuid}" # or "{{{0}}}" -f [GUID]::NewGuid().Guid
+netsh http update sslcert ipport=0.0.0.0:443 ("certhash={0}" -f $cert.Thumbprint) ("appid={0}" -f $appid)

data/docs/post_issuing_hooks/acm.md

@@ -0,0 +1,16 @@
+# Post issuing hook: Amazon Certificate Manager
+
+`acm` imports certificate into AWS ACM.
+
+```yaml
+post_issuing_hooks:
+  "test.example.com":
+    - acm:
+        region: us-east-1 # required
+        certificate_arn: arn:aws:acm:... # (optional)
+```
+
+When `certificate_arn` is not present, `acm` hook attempts to find the certificate ARN from existing certificate list. Certificate with same common name ("domain name" on ACM), and `Acmesmith` tag
+ will be used. Otherwise, `acm` hook imports as a new certificate with `Acmesmith` tag.
+
+

data/docs/post_issuing_hooks/shell.md

@@ -0,0 +1,17 @@
+# Post Issuing Hook: Shell
+
+Execute specified command on a shell. Environment variable `${COMMON_NAME}` is available.
+
+```yaml
+post_issuing_hooks:
+  "test.example.com":
+    - shell:
+        command: mail -s "New cert for ${COMMON_NAME} has been issued" user@example.com < /dev/null
+    - shell:
+        command: touch /tmp/certs-has-been-issued-${COMMON_NAME}
+  "admin.example.com":
+    - shell:
+        command: /usr/bin/dosomethingelse ${COMMON_NAME}
+```
+
+

data/docs/storages/filesystem.md

@@ -0,0 +1,11 @@
+# Storage: Filesystem
+
+This is not recommended for production use. If you're planning to use this, make sure backing up the keys.
+
+```yaml
+storage:
+  type: filesystem
+  path: /path/to/directory/to/store/keys
+```
+
+

data/docs/storages/s3.md

@@ -0,0 +1,32 @@
+# Storage: S3
+
+```yaml
+storage:
+  type: s3
+  region:
+  bucket:
+  # prefix:
+  # aws_access_key: # aws credentials (optional); If omit, default configuration of aws-sdk use will be used.
+  #   access_key_id:
+  #   secret_access_key:
+  #   session_token:
+  # use_kms: true
+  # kms_key_id: # KMS key id (optional); if omit, default AWS managed key for S3 will be used
+  # kms_key_id_account: # KMS key id for account key (optional); This overrides kms_key_id
+  # kms_key_id_certificate_key: # KMS key id for private keys for certificates (optional); This oveerides kms_key_id
+  # pkcs12_passphrase: # (optional) Set passphrase to generate PKCS#12 file (for scripts that reads S3 bucket directly)
+  # pkcs12_common_names: ['example.org'] # (optional) List of common names to limit certificates for generating PKCS#12 file.
+```
+
+This saves certificates and keys in the following S3 keys:
+
+- `{prefix}/account.pem`: Account private key in pem
+- `{prefix}/certs/{common_name}/current`: text file contains current version name
+- `{prefix}/certs/{common_name}/{version}/cert.pem`: certificate in pem
+- `{prefix}/certs/{common_name}/{version}/key.pem`: private key in pem
+- `{prefix}/certs/{common_name}/{version}/chain.pem`: CA chain in pem
+- `{prefix}/certs/{common_name}/{version}/fullchain.pem`: certificate + CA chain in pem. This is suitable for some server softwares like nginx.
+
+## IAM/KMS Policy
+
+- [docs/vendor/aws.md](../vendor/aws.md): IAM and KMS key policies, and some tips

data/lib/acmesmith/account_key.rb

@@ -3,11 +3,16 @@ require 'openssl'
 module Acmesmith
   class AccountKey
     class PassphraseRequired < StandardError; end
+    class PrivateKeyDecrypted < StandardError; end
 
+    # @param bit_length [Integer]
+    # @return [Acmesmith::AccountKey]
     def self.generate(bit_length = 2048)
       new OpenSSL::PKey::RSA.new(bit_length)
     end
 
+    # @param private_key [String, OpenSSL::PKey::RSA]
+    # @param passphrase [String, nil]
     def initialize(private_key, passphrase = nil)
       case private_key
       when String
@@ -28,8 +33,11 @@ module Acmesmith
       end
     end
 
+    # Try to decrypt private_key if encrypted.
+    # @param pw [String] passphrase for encrypted PEM
+    # @raise [PrivateKeyDecrypted] if private_key is decrypted
     def key_passphrase=(pw)
-      raise 'private_key already given' if @private_key
+      raise PrivateKeyDecrypted, 'private_key already given' if @private_key
 
       @private_key = OpenSSL::PKey::RSA.new(@raw_private_key, pw)
 
@@ -37,11 +45,14 @@ module Acmesmith
       nil
     end
 
+    # @return [OpenSSL::PKey::RSA]
+    # @raise [PassphraseRequired] if private_key is not yet decrypted
     def private_key
       return @private_key if @private_key
       raise PassphraseRequired, 'key_passphrase required'
     end
 
+    # @return [String] PEM
     def export(passphrase, cipher: OpenSSL::Cipher.new('aes-256-cbc'))
       if passphrase
         private_key.export(cipher, passphrase)

data/lib/acmesmith/authorization_service.rb

@@ -0,0 +1,175 @@
+module Acmesmith
+  class AuthorizationService
+    class NoApplicableChallengeResponder < StandardError; end
+    class AuthorizationFailed < StandardError; end
+
+    # @!attribute [r] domain
+    #  @return [String] domain name
+    # @!attribute [r] authorization
+    #  @return [Acme::Client::Resources::Authorization] authz object
+    # @!attribute [r] challenge_responder
+    #  @return [Acmesmith::ChallengeResponders::Base] responder
+    # @!attribute [r] challenge
+    #  @return [Acme::Client::Resources::Challenges::Base] challenge
+    AuthorizationProcess = Struct.new(:domain, :authorization, :challenge_responder, :challenge, keyword_init: true) do
+      def completed?
+        invalid? || valid?
+      end
+
+      def invalid?
+        challenge.status == 'invalid'
+      end
+
+      def valid?
+        challenge.status == 'valid'
+      end
+
+      def responder_id
+        challenge_responder.__id__
+      end
+    end
+
+    # @param challenge_responder_rules [Array<Acmemith::Config::ChallengeReponderRule>] 
+    # @param authorizations [Array<Acme::Client::Resources::Authorization>]
+    def initialize(challenge_responder_rules, authorizations)
+      @challenge_responder_rules = challenge_responder_rules
+      @authorizations = authorizations
+    end
+
+    attr_reader :challenge_responder_rules, :authorizations
+
+    def perform!
+      return if authorizations.empty?
+
+      respond()
+      request_validation()
+      wait_for_validation()
+      cleanup()
+
+      puts "=> Authorized!"
+    end
+
+    def respond
+      processes_by_responder.each do |responder, ps|
+        puts "=> Responsing to the challenges for the following identifier:"
+        puts
+        puts " * Responder: #{responder.class}"
+        puts " * Identifiers:"
+
+        ps.each do |process|
+          puts "     - #{process.domain} (#{process.challenge.challenge_type})"
+        end
+
+        puts
+        responder.respond_all(*ps.map{ |t| [t.domain, t.challenge] })
+      end
+    end
+
+    def request_validation
+      puts "=> Requesting validations..."
+      puts
+      processes.each do |process|
+        print " * #{process.domain} (#{process.challenge.challenge_type}) ..."
+        process.challenge.request_validation()
+        puts " [ ok ]"
+      end
+      puts
+
+    end
+
+    def wait_for_validation
+      puts "=> Waiting for the validation..."
+      puts
+
+      loop do
+        processes.each do |process|
+          next if process.valid?
+
+          process.challenge.reload
+
+          status = process.challenge.status
+          puts " * [#{process.domain}] status: #{status}"
+
+          case
+          when process.valid?
+            next
+          when process.invalid?
+            err = process[:challenge].error
+            puts " ! [#{process[:domain]}] error: #{err.inspect}"
+          end
+        end
+        break if processes.all?(&:completed?)
+        sleep 3
+      end
+
+      puts
+
+      invalid_processes = processes.select(&:invalid?)
+      unless invalid_processes.empty?
+        $stderr.puts ""
+        $stderr.puts "!! Some identitiers failed to challenge"
+        $stderr.puts ""
+        invalid_processes.each do |process|
+          $stderr.puts "   - #{process.domain}: #{process.challenge.error.inspect}"
+        end
+        $stderr.puts ""
+        raise AuthorizationFailed, "Some identifiers failed to challenge: #{invalid_processes.map(&:domain).inspect}"
+      end
+
+    end
+
+    def cleanup
+      processes_by_responder.each do |responder, ps|
+        puts "=> Cleaning the responses the challenges for the following identifier:"
+        puts
+        puts " * Responder:   #{responder.class}"
+        puts " * Identifiers:"
+        ps.each do |process|
+          puts "     - #{process.domain} (#{process.challenge.challenge_type})"
+        end
+        puts
+
+        responder.cleanup_all(*ps.map{ |t| [t.domain, t.challenge] })
+      end
+    end
+
+    # @return [Array<AuthorizationProcess>]
+    def processes
+      @processes ||= authorizations.map do |authz|
+        challenge = nil
+        responder_rule = challenge_responder_rules.select do |rule|
+          rule.filter.applicable?(authz.domain)
+        end.find do |rule|
+          challenge = authz.challenges.find do |c|
+            # OMG, acme-client might return a Hash instead of Acme::Client::Resources::Challenge::* object...
+            challenge_type = case
+            when c.is_a?(Hash)
+              c[:challenge_type]
+            when c.is_a?(Acme::Client::Resources::Challenges::Unsupported)
+              next
+            when c.respond_to?(:challenge_type)
+              c.challenge_type
+            end
+            rule.challenge_responder.support?(challenge_type)
+          end
+        end
+
+        unless responder_rule
+          raise NoApplicableChallengeResponder, "Cannot find a challenge responder for domain #{authz.domain.inspect}"
+        end
+
+        AuthorizationProcess.new(
+          domain: authz.domain,
+          authorization: authz,
+          challenge_responder: responder_rule.challenge_responder,
+          challenge: challenge,
+        )
+      end
+    end
+
+    # @return [Array<(Acmesmith::ChallengeResponders::Base, Array<AuthorizationProcess>)>]
+    def processes_by_responder
+      @processes_by_responder ||= processes.group_by(&:responder_id).map { |_, ps| [ps[0].challenge_responder, ps] }
+    end
+  end
+end