dkim 0.1.0 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9ac50ad199771571d27da93d35d17d404e6cf24b18642856b8d8e3574ecb7f9
+  data.tar.gz: 7d1248e2086cea45176e60867ac15c4de7eb39f8cd5767c04e682f406e7901eb
+SHA512:
+  metadata.gz: 0161d656b0d464c2dced244ce241077181700c42451178bb7e6ccc5af5d63790b993e15f0d7f4cec579830b9e52bbde1aafa80d7ee908ea3310fdaba821884e8
+  data.tar.gz: 9d6d1b6218d2fdf7e1a7935c72de032fe7db7f2178f257f3bfa9ebc2ae810dde46988416e6a40b711616b328b30f2762412b796b403459738f2aa534fdc811f8

data/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Ruby 2.6
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6.x
+    - name: Build and test with Rake
+      run: |
+        gem install bundler
+        bundle install --jobs 4 --retry 3
+        bundle exec rake

data/.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+gemfiles/*.lock

data/Appraisals

@@ -0,0 +1,7 @@
+appraise 'mail-2.6' do
+  gem 'mail', '2.6.6'
+end
+
+appraise 'mail-2.7' do
+  gem 'mail', '2.7.0'
+end

data/CHANGELOG.md

@@ -1,9 +1,34 @@
 # dkim Changelog
 
-## 2011.07.25, Version 0.0.3
+## Unreleased
+
+## 1.1.0 (2021-12-05)
+* Add support for DKIM expiration tag
+
+## 1.0.1 (2013-01-15)
+* Fix Minitest
+* Add support for identity, the "i=" tag
+* Fix problem with `strip_field` in mail gem 2.7.0
+
+## 1.0.0 (2013-01-15)
+* DKIM-Signature header is now prepended rather than appended
+* Headers are signed in the order they appear
+* Correct signing of repeated headers
+* Correct signing of missing headers
+
+## 0.2.0 (2012-04-15)
+* Warn and strip existing signatures in Dkim::Interceptor
+* Dkim options can be accessed and modified using new Dkim.options or signed_mail.options hash
+* Refactoring and better testing
+* Improved documentation
+
+## 0.1.0 (2011-12-10)
+* Ensure header lines are not folded using Dkim::Interceptor
+
+## 0.0.3 (2011-07-25)
 * add Dkim::Interceptor class for integration with rails and [mail](https://github.com/mikel/mail)
 
-## 2011.06.01, Version 0.0.2
+## 0.0.2 (2011-06-01)
 
 * add convenience method Dkim.sign
 * support for the simple canonicalization algorithm
@@ -11,7 +36,7 @@
 * correct handling of an empty message body
 
 
-## 2011.05.10, Version 0.0.1
+## 0.0.1 (2011-05-10)
 
 * Initial release
 

data/Gemfile

@@ -1,4 +1,8 @@
-source "http://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in dkim.gemspec
 gemspec
+
+platforms :jruby do
+  gem 'jruby-openssl'
+end

data/README.md

@@ -1,30 +1,64 @@
 dkim
 ====
-
 A DKIM signing library in ruby.
 
+[Documentation](http://rubydoc.info/github/jhawthorn/dkim)
+
 Installation
 ============
 
     sudo gem install dkim
 
-Usage
-=====
+Necessary configuration
+=======================
+A private key, a domain, and a selector need to be specified in order to sign messages.
+
+These can be specified globally
+
+    Dkim::domain      = 'example.com'
+    Dkim::selector    = 'mail'
+    Dkim::private_key = open('private.pem').read
+
+Options can be overridden per message.
+
+    Dkim.sign(mail, :selector => 'mail2', :private_key => OpenSSL::PKey::RSA.new(open('private2.pem').read))
+
+For more details see {Dkim::Options}
+
+Usage With Rails
+================
+
+Dkim contains `Dkim::Interceptor` which can be used to sign all mail delivered
+by [mail](https://github.com/mikel/mail), which is used by actionmailer in
+rails >= 3.
+
+For rails, create an initializer (for example `config/initializers/dkim.rb`)
+with the following template.
+
+    # Configure dkim globally (see above)
+    Dkim::domain      = 'example.com'
+    Dkim::selector    = 'mail'
+    Dkim::private_key = open('private.pem').read
+
+    # This will sign all ActionMailer deliveries
+    ActionMailer::Base.register_interceptor(Dkim::Interceptor)
+
+Standalone Usage
+================
 
 Calling `Dkim.sign` on a string representing an email message returns the message with a DKIM signature inserted.
 
 For example
 
-    mail = <<eos
+    mail = Dkim.sign(<<EOS)
     To: someone@example.com
     From: john@example.com
     Subject: hi
-    
+
     Howdy
-    eos
+    EOS
 
     Dkim.sign(mail)
-
     # =>
     # To: someone@example.com
     # From: john@example.com
@@ -34,67 +68,25 @@ For example
     #  	b=0mKnNOkxFGiww63Zu4t46J7eZc3Uak3I9km3IH2Le3XcnSNtWJgxiwBX26IZ5yzcT
     # 	VwJzcCnPKCScIJMQ7yfbfXmNsKVIOV6eSUqu1YvJ1fgzlSAXuDEMNFTjoto5rrdA+
     # 	BgX849hEY/bWHDl1JJgNpiwtpl4t0Q7M4BVJUd7Lo=
-    # 
+    #
     # Howdy
 
-Necessary configuration
------------------------
-A private key, a domain, and a selector need to be specified in order to sign messages.
-
-These can be specified globally
+More flexibility can be found using {Dkim::SignedMail} directly.
 
-    Dkim::domain      = 'example.com'
-    Dkim::selector    = 'mail'
-    Dkim::private_key = open('private.pem').read
+Specific configuration
+========================
 
-Options can be overridden per message.
-
-    Dkim.sign(mail, :selector => 'mail2', :private_key => open('private2.pem').read)
-
-Additional configuration
-------------------------
-
-The following is the default configuration
-
-    Dkim::signable_headers        = Dkim::DefaultHeaders # Sign only the specified headers
-    Dkim::signing_algorithm       = 'rsa-sha256' # can be rsa-sha1 or rsa-sha256 (default)
-    Dkim::header_canonicalization = 'relaxed'    # Can be simple or relaxed (default)
-    Dkim::body_canonicalization   = 'relaxed'    # Can be simple or relaxed (default)
-
-The defaults should fit most users needs; however, certain use cases will need them to be customized.
-
-For example, for sending mesages through amazon SES, certain headers should not be signed
+For sending mesages through Amazon SES, certain headers should not be signed
 
     Dkim::signable_headers = Dkim::DefaultHeaders - %w{Message-ID Resent-Message-ID Date Return-Path Bounces-To}
 
-rfc4871 states that signers SHOULD sign using rsa-sha256. For this reason, dkim will *not* use rsa-sha1 as a fallback if the openssl library does not support sha256.
+Some OpenSSL's don't have sha256 support.
+RFC 6376 states that signers SHOULD sign using rsa-sha256.
+For this reason, dkim will *not* use rsa-sha1 as a fallback.
 If you wish to override this behaviour and use whichever algorithm is available you can use this snippet (**not recommended**).
 
     Dkim::signing_algorithm = defined?(OpenSSL::Digest::SHA256) ? 'rsa-sha256' : 'rsa-sha1'
 
-Usage With Rails
-================
-
-Dkim contains `Dkim::Interceptor` which can be used to sign all mail delivered by the [mail gem](https://github.com/mikel/mail) or rails 3, which uses mail.
-For rails, create an initializer (for example `config/initializers/dkim.rb`) with the following template.
-
-    # Configure dkim globally (see above)
-    Dkim::domain      = 'example.com'
-    Dkim::selector    = 'mail'
-    Dkim::private_key = open('private.pem').read
-
-    # This will sign all ActionMailer deliveries
-    ActionMailer::Base.register_interceptor('Dkim::Interceptor')
-
-Example executable
-==================
-
-The library includes a `dkimsign.rb` executable suitable for testing the library or performing simple signatures.
-
-`dkimsign.rb DOMAIN SELECTOR KEYFILE [MAILFILE]`
-
-If MAILFILE is not specified `dkimsign.rb` will read the mail message from standard in.
-
 Limitations
 ===========
 
@@ -102,17 +94,16 @@ Limitations
 * No support for the older Yahoo! DomainKeys standard ([RFC 4870](http://tools.ietf.org/html/rfc4870)) *(none planned)*
 * No support for specifying DKIM identity `i=` *(planned)*
 * No support for body length `l=` *(planned)*
-* No support for signature expiration `x=` *(planned)*
 * No support for copied header fields `z=` *(not immediately planned)*
 
 Resources
 =========
 
-* [RFC 4871](http://tools.ietf.org/html/rfc4871)
+* [RFC 6376](http://tools.ietf.org/html/rfc6376)
 * Inspired by perl's [Mail-DKIM](http://dkimproxy.sourceforge.net/)
 
-Copyright
-=========
+License
+=======
 
 (The MIT License)
 

data/Rakefile

@@ -12,3 +12,15 @@ end
 
 Bundler::GemHelper.install_tasks
 
+desc 'Open an pry (or irb) session preloaded with Dkim'
+task :console do
+  begin
+    require 'pry'
+    sh 'pry -I lib -r dkim.rb'
+  rescue LoadError => _
+    sh 'irb -rubygems -I lib -r dkim.rb'
+  end
+
+end
+
+task c: :console

data/dkim.gemspec

@@ -18,4 +18,9 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- test/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'minitest', '~> 5.0'
+  s.add_development_dependency 'mail'
+  s.add_development_dependency 'appraisal'
 end

data/gemfiles/mail_2.6.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "mail", "2.6.6"
+
+platforms :jruby do
+  gem "jruby-openssl"
+end
+
+gemspec path: "../"

data/gemfiles/mail_2.7.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "mail", "2.7.0"
+
+platforms :jruby do
+  gem "jruby-openssl"
+end
+
+gemspec path: "../"

data/lib/dkim/canonicalized_headers.rb

@@ -0,0 +1,26 @@
+module Dkim
+  class CanonicalizedHeaders
+    include Enumerable
+    def initialize header_list, signed_headers
+      @header_list    = header_list
+      @signed_headers = signed_headers.map(&:downcase)
+    end
+    def each(&block)
+      header_hash = Hash.new {|h,k| h[k] = []}
+      @header_list.each do |header|
+        header_hash[header.relaxed_key] << header
+      end
+
+      @signed_headers.each do |key|
+        if header = header_hash[key].pop
+          yield header
+        end
+      end
+    end
+    def to_s(canonicalization)
+      map do |header|
+        header.to_s(canonicalization) + "\r\n"
+      end.join
+    end
+  end
+end

data/lib/dkim/dkim_header.rb

@@ -1,28 +1,37 @@
 
 require 'dkim/header'
+require 'dkim/tag_value_list'
+require 'dkim/encodings'
 
 module Dkim
   class DkimHeader < Header
+    attr_reader :list
     def initialize values={}
       self.key = 'DKIM-Signature'
-      @values = values.to_a.flatten.each_slice(2).to_a
+      @list = TagValueList.new values
     end
     def value
-      @values.map do |(k, v)|
-        " #{k}=#{v}"
-      end.join(';')
+      " #{@list}"
     end
     def [] k
-      value = @values.detect {|(a,b)| a == k }
-      value && value[1]
+      encoder_for(k).decode(@list[k])
     end
     def []= k, v
-      value = @values.detect {|(a,b)| a == k }
-      if !value
-        value = [k, nil]
-        @values << value
-      end
-      value[1] = v
+      @list[k] = encoder_for(k).encode(v)
+    end
+
+    private
+    def encoder_for key
+      case key
+      when *%w{v a c d h l q s t x}
+        Encodings::PlainText
+      when *%w{i z}
+        Encodings::DkimQuotedPrintable
+      when *%w{b bh}
+        Encodings::Base64
+      else
+        raise "unknown key: #{key}"
+      end.new
     end
   end
 end

data/lib/dkim/encodings/base64.rb

@@ -0,0 +1,12 @@
+module Dkim
+  module Encodings
+    class Base64
+      def decode data
+        data.gsub(/\s/, '').unpack('m0')[0]
+      end
+      def encode data
+        [data].pack('m0').gsub("\n", '')
+      end
+    end
+  end
+end

data/lib/dkim/encodings/dkim_quoted_printable.rb

@@ -0,0 +1,19 @@
+
+module Dkim
+  module Encodings
+    # Implements DKIM-Quoted-Printable as described in rfc6376 section 2.11
+    class DkimQuotedPrintable
+      DkimUnafeChar = /[^\x21-\x3A\x3C\x3E-\x7E]/
+      def encode string
+        string.gsub(DkimUnafeChar) do |char|
+          "=%.2x" % char.unpack('C')
+        end
+      end
+      def decode string
+        string.gsub(/=([0-9A-F]{2})/) do
+          $1.hex.chr
+        end
+      end
+    end
+  end
+end

data/lib/dkim/encodings/plain_text.rb

@@ -0,0 +1,8 @@
+module Dkim
+  module Encodings
+    class PlainText
+      def encode v; v; end
+      alias_method :decode, :encode
+    end
+  end
+end

data/lib/dkim/encodings.rb

@@ -0,0 +1,3 @@
+require 'dkim/encodings/base64.rb'
+require 'dkim/encodings/dkim_quoted_printable.rb'
+require 'dkim/encodings/plain_text.rb'

data/lib/dkim/header.rb

@@ -38,5 +38,12 @@ module Dkim
     def canonical_simple
       "#{key}:#{value}"
     end
+
+    def self.parse header_string
+      header_string.split(/\r?\n(?!([ \t]))/).map do |header|
+        key, value = header.split(':', 2)
+        new(key, value)
+      end
+    end
   end
 end

data/lib/dkim/interceptor.rb

@@ -3,7 +3,19 @@ module Dkim
   class Interceptor
     def self.delivering_email(message)
       require 'mail/dkim_field'
-      message.header.fields << Mail::DkimField.new(SignedMail.new(message.encoded).dkim_header.value)
+
+      # strip any existing signatures
+      if message['DKIM-Signature']
+        warn "WARNING: Dkim::Interceptor given a message with an existing signature, which it has replaced."
+        warn "If you really want to add a second signature to the message, you should be using the dkim gem directly."
+        message['DKIM-Signature'] = nil
+      end
+
+      # generate new signature
+      dkim_signature = SignedMail.new(message.encoded).dkim_header.value
+
+      # prepend signature to message
+      message.header.fields.unshift Mail::DkimField.new(dkim_signature)
       message
     end
   end

data/lib/dkim/options.rb

@@ -0,0 +1,84 @@
+module Dkim
+  module Options
+    private
+    def self.define_option_method attribute_name
+      define_method(attribute_name){options[attribute_name]}
+      define_method("#{attribute_name}="){|value| options[attribute_name] = value}
+    end
+    public
+
+    # @attribute [rw]
+    # Hash of all options
+    # @return [Hash]
+    def options
+      @options ||= {}
+    end
+    attr_writer :options
+
+    # @attribute [rw]
+    # This corresponds to the t= tag in the dkim header.
+    # The default (nil) is to use the current time at signing.
+    # @return [Time,#to_i] A Time object or seconds since the epoch
+    define_option_method :time
+
+    # @attribute [rw]
+    # Signature expiration.
+    # This corresponds to the x= tag in the dkim header.
+    # @return [Time,#to_i] A Time object or seconds since the epoch
+    define_option_method :expire
+
+    # @attribute [rw]
+    # The signing algorithm for dkim. Valid values are 'rsa-sha1' and 'rsa-sha256' (default).
+    # This corresponds to the a= tag in the dkim header.
+    # @return [String] signing algorithm
+    define_option_method :signing_algorithm
+
+    # @attribute [rw]
+    # Configures which headers should be signed.
+    # Defaults to {Dkim::DefaultHeaders Dkim::DefaultHeaders}
+    # @return [Array<String>] signable headers
+    define_option_method :signable_headers
+
+    # @attribute [rw]
+    # The domain used for signing.
+    # This corresponds to the d= tag in the dkim header.
+    # @return [String] domain
+    define_option_method :domain
+
+    # @attribute [rw]
+    # The identity used for signing.
+    # This corresponds to the i= tag in the dkim header.
+    # @return [String] identity
+    define_option_method :identity
+
+    # @attribute [rw]
+    # Selector used for signing.
+    # This corresponds to the s= tag in the dkim header.
+    # @return [String] selector
+    define_option_method :selector
+
+    # @attribute [rw]
+    # Header canonicalization algorithm.
+    # Valid values are 'simple' and 'relaxed' (default)
+    # This corresponds to the first half of the c= tag in the dkim header.
+    # @return [String] header canonicalization algorithm
+    define_option_method :header_canonicalization
+
+    # @attribute [rw]
+    # Body canonicalization algorithm.
+    # Valid values are 'simple' and 'relaxed' (default)
+    # This corresponds to the second half of the c= tag in the dkim header.
+    # @return [String] body canonicalization algorithm
+    define_option_method :body_canonicalization
+
+    # @attribute [rw]
+    # RSA private key for signing.
+    # Can be assigned either an {OpenSSL::PKey::RSA} private key or a valid PEM format string.
+    # @return [OpenSSL::PKey::RSA] private key
+    define_option_method :private_key
+    def private_key= key
+      key = OpenSSL::PKey::RSA.new(key) if key.is_a?(String)
+      options[:private_key] = key
+    end
+  end
+end