dkim 0.0.1 → 0.0.2

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# dkim Changelog
+
+## 2011.06.01, Version 0.0.2
+
+* add convenience method Dkim.sign
+* support for the simple canonicalization algorithm
+* domain now must be specified as an option
+* correct handling of an empty message body
+
+
+## 2011.05.10, Version 0.0.1
+
+* Initial release
+

data/README.md

@@ -0,0 +1,123 @@
+dkim
+====
+
+A DKIM signing library in ruby.
+
+Installation
+============
+
+    sudo gem install dkim
+
+Usage
+=====
+
+Calling `Dkim.sign` on a string representing an email message returns the message with a DKIM signature inserted.
+
+For example
+
+    mail = <<eos
+    To: someone@example.com
+    From: john@example.com
+    Subject: hi
+    
+    Howdy
+    eos
+
+    Dkim.sign(mail)
+
+    # =>
+    # To: someone@example.com
+    # From: john@example.com
+    # Subject: hi
+    # DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com; q=dns/txt; s=mail; t=1305917829;
+    #  	bh=qZxwTnSM1ywsrq0Ag9UhQSOtVIG+sW5zDkB+hPbuX08=; h=from:subject:to;
+    #  	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
+
+    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 => 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
+
+    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.
+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'
+
+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
+===========
+
+* Strictly a DKIM signing library. No support for signature verification. *(none planned)*
+* 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)
+* Inspired by perl's [Mail-DKIM](http://dkimproxy.sourceforge.net/)
+
+Copyright
+=========
+
+(The MIT License)
+
+Copyright (c) 2011 [John Hawthorn](http://www.johnhawthorn.com/)
+
+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

data/Rakefile

@@ -1,2 +1,14 @@
+require 'rake/testtask'
 require 'bundler'
+
+task :default => [:test]
+
+desc 'Run tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
 Bundler::GemHelper.install_tasks
+

data/bin/dkimsign.rb

@@ -1,13 +1,13 @@
 #!/usr/bin/ruby
 
 if ARGV.length != 2 && ARGV.length != 3
-  puts "Usage: dkimsign.rb SELECTOR KEYFILE [MAILFILE]"
+  puts "Usage: dkimsign.rb DOMAIN SELECTOR KEYFILE [MAILFILE]"
   exit 0
 end
 
 require 'dkim'
 
-selector, keyfile,mailfile = ARGV
+domain, selector, keyfile, mailfile = ARGV
 
 keyfile  = File.open(keyfile)
 mailfile = mailfile ? File.open(mailfile) : STDIN
@@ -15,7 +15,8 @@ mailfile = mailfile ? File.open(mailfile) : STDIN
 mail = mailfile.read.gsub(/\r?\n/, "\r\n")
 key  = keyfile.read
 
-Dkim::selector    = selector
+Dkim::domain = domain
+Dkim::selector = selector
 Dkim::private_key = key
 
 print Dkim::SignedMail.new(mail).to_s

data/dkim.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.rubyforge_project = "dkim"
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  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"]
 end

data/lib/dkim.rb

@@ -1,7 +1,4 @@
 
-require 'dkim/header'
-require 'dkim/header_list'
-require 'dkim/body'
 require 'dkim/signed_mail'
 
 module Dkim
@@ -16,19 +13,25 @@ module Dkim
     List-Post List-Owner List-Archive}
 
   class << self
-    attr_accessor :signing_algorithm, :signable_headers, :domain, :selector
+    attr_accessor :signing_algorithm, :signable_headers, :domain, :selector, :header_canonicalization, :body_canonicalization
 
     attr_reader :private_key
     def private_key= key
       key = OpenSSL::PKey::RSA.new(key) if key.is_a?(String)
       @private_key = key
     end
+
+    def sign message, options={}
+      SignedMail.new(message, options).to_s
+    end
   end
 end
 
-Dkim::signable_headers  = Dkim::DefaultHeaders
-Dkim::domain            = nil
-Dkim::selector          = nil
-Dkim::signing_algorithm = 'rsa-sha256'
-Dkim::private_key       = nil
+Dkim::signable_headers        = Dkim::DefaultHeaders
+Dkim::domain                  = nil
+Dkim::selector                = nil
+Dkim::signing_algorithm       = 'rsa-sha256'
+Dkim::private_key             = nil
+Dkim::header_canonicalization = 'relaxed'
+Dkim::body_canonicalization   = 'relaxed'
 

data/lib/dkim/body.rb

@@ -1,20 +1,32 @@
+require 'dkim/canonicalizable'
+
 module Dkim
   class Body < Struct.new(:body)
-    def to_canonical
-      body = self.body.dup
+    include Canonicalizable
 
-      # Ignores all whitespace at the end of lines.  Implementations MUST NOT remove the CRLF at the end of the line.
-      body.gsub!(/[ \t]+(?=\r\n|\z)/, '')
+    def canonical_relaxed
+      # special case from errata 1377
+      return "" if self.body.empty?
+
+      body = self.body.dup
 
       # Reduces all sequences of WSP within a line to a single SP character.
       body.gsub!(/[ \t]+/, ' ')
 
+      # Ignores all whitespace at the end of lines.  Implementations MUST NOT remove the CRLF at the end of the line.
+      body.gsub!(/ \r\n/, "\r\n")
+
       # Ignores all empty lines at the end of the message body.
-      body.gsub!(/(\r?\n)*\z/, '')
+      body.gsub!(/[ \r\n]*\z/, '')
+
       body += "\r\n"
     end
-    def to_s
-      self.body.dup
+    def canonical_simple
+      body = self.body.dup
+
+      # Ignores all empty lines at the end of the message body.
+      body.gsub!(/(\r?\n)*\z/, '')
+      body += "\r\n"
     end
   end
 end

data/lib/dkim/canonicalizable.rb

@@ -0,0 +1,14 @@
+module Dkim
+  module Canonicalizable
+    def to_s form='simple'
+      case form
+      when 'simple'
+        canonical_simple
+      when 'relaxed'
+        canonical_relaxed
+      else
+        raise "Unknown canonicalization: #{form}"
+      end
+    end
+  end
+end

data/lib/dkim/dkim_header.rb

@@ -0,0 +1,28 @@
+
+require 'dkim/header'
+
+module Dkim
+  class DkimHeader < Header
+    def initialize values={}
+      self.key = 'DKIM-Signature'
+      @values = values.to_a.flatten.each_slice(2).to_a
+    end
+    def value
+      @values.map do |(k, v)|
+        " #{k}=#{v}"
+      end.join(';')
+    end
+    def [] k
+      value = @values.detect {|(a,b)| a == k }
+      value && value[1]
+    end
+    def []= k, v
+      value = @values.detect {|(a,b)| a == k }
+      if !value
+        value = [k, nil]
+        @values << value
+      end
+      value[1] = v
+    end
+  end
+end

data/lib/dkim/header.rb

@@ -1,12 +1,23 @@
+require 'dkim/canonicalizable'
+
 module Dkim
   class Header < Struct.new(:key, :value)
-    def to_canonical
-      key    = self.key.dup
-      value  = self.value.dup
+    include Canonicalizable
+
+    def relaxed_key
+      key = self.key.dup
 
       #Convert all header field names (not the header field values) to lowercase.  For example, convert "SUBJect: AbC" to "subject: AbC".
       key.downcase!
 
+      # Delete any WSP characters remaining before the colon separating the header field name from the header field value.
+      key.gsub!(/[ \t]*\z/, '')
+
+      key
+    end
+    def relaxed_value
+      value  = self.value.dup
+
       # Unfold all header field continuation lines as described in [RFC2822]
       value.gsub!(/\r?\n[ \t]+/, ' ')
 
@@ -16,13 +27,15 @@ module Dkim
       # Delete all WSP characters at the end of each unfolded header field value.
       value.gsub!(/[ \t]*\z/, '')
       
-      # Delete any WSP characters remaining before and after the colon separating the header field name from the header field value.
+      # Delete any WSP characters remaining after the colon separating the header field name from the header field value.
       value.gsub!(/\A[ \t]*/, '')
-      key.gsub!(/[ \t]*\z/, '')
 
-      "#{key}:#{value}"
+      value
+    end
+    def canonical_relaxed
+      "#{relaxed_key}:#{relaxed_value}"
     end
-    def to_s
+    def canonical_simple
       "#{key}:#{value}"
     end
   end

data/lib/dkim/header_list.rb

@@ -9,7 +9,7 @@ module Dkim
     end
     def [](key)
       @headers.detect do |header|
-        header.key == key
+        header.relaxed_key == key
       end
     end
     def each(&block)

data/lib/dkim/signed_mail.rb

@@ -1,10 +1,12 @@
 require 'openssl'
-require 'base64'
+
+require 'dkim/body'
+require 'dkim/dkim_header'
+require 'dkim/header'
+require 'dkim/header_list'
 
 module Dkim
   class SignedMail
-    EMAIL_REGEX = /[A-Z0-9._%+-]+@([A-Z0-9.-]+\.[A-Z]{2,6})/i
-
     def initialize message, options={}
       message = message.gsub(/\r?\n/, "\r\n")
       headers, body = message.split(/\r?\n\r?\n/, 2)
@@ -17,10 +19,12 @@ module Dkim
       @time              = options[:time]
       @signing_algorithm = options[:signing_algorithm]
       @private_key       = options[:private_key]
+      @header_canonicalization = options[:header_canonicalization]
+      @body_canonicalization   = options[:body_canonicalization]
     end
 
     # options for signatures
-    attr_writer :signing_algorithm, :signable_headers, :domain, :selector, :time
+    attr_writer :signing_algorithm, :signable_headers, :domain, :selector, :time, :header_canonicalization, :body_canonicalization
 
     def private_key= key
       key = OpenSSL::PKey::RSA.new(key) if key.is_a?(String)
@@ -36,57 +40,65 @@ module Dkim
       @signable_headers || Dkim::signable_headers
     end
     def domain
-      @domain || Dkim::domain || (@headers['From'].value =~ EMAIL_REGEX && $1)
+      @domain || Dkim::domain
     end
     def selector
       @selector || Dkim::selector
     end
     def time
-      @time ||= Time.now
+      @time
+    end
+    def header_canonicalization
+      @header_canonicalization || Dkim::header_canonicalization
+    end
+    def body_canonicalization
+      @body_canonicalization || Dkim::body_canonicalization
     end
 
     def signed_headers
-      (@headers.map(&:key) & signable_headers).sort
-    end
-    def dkim_header_values(b)
-      [
-        'v',  1,
-        'a',  signing_algorithm,
-        'c',  'relaxed/relaxed',
-        'd',  domain,
-        'q',  'dns/txt',
-        's',  selector,
-        't',  time.to_i,
-        'bh', body_hash,
-        'h',  signed_headers.join(':'),
-        'b',  b
-      ]
-    end
-    def dkim_header(b=nil)
-      b ||= header_signature
-      v = dkim_header_values(b).each_slice(2).map do |(key, value)|
-        "#{key}=#{value}"
-      end.join('; ')
-      Header.new('DKIM-Signature', v)
+      (@headers.map(&:relaxed_key) & signable_headers.map(&:downcase)).sort
     end
     def canonical_header
       headers = signed_headers.map do |key|
-        @headers[key]
-      end
-      headers << dkim_header('')
-      headers.map(&:to_canonical).join("\r\n")
+        @headers[key].to_s(header_canonicalization) + "\r\n"
+      end.join
     end
     def canonical_body
-      @body.to_canonical
+      @body.to_s(body_canonicalization)
     end
 
-    def header_signature
-      base64_encode private_key.sign(digest_alg, canonical_header)
-    end
-    def body_hash
-      base64_encode digest_alg.digest(canonical_body)
+    def dkim_header
+      dkim_header = DkimHeader.new
+
+      raise "A private key is required" unless private_key
+      raise "A domain is required"      unless domain
+      raise "A selector is required"    unless selector
+
+      # Add basic DKIM info
+      dkim_header['v'] = '1'
+      dkim_header['a'] = signing_algorithm
+      dkim_header['c'] = "#{header_canonicalization}/#{body_canonicalization}"
+      dkim_header['d'] = domain
+      dkim_header['q'] = 'dns/txt'
+      dkim_header['s'] = selector
+      dkim_header['t'] = (time || Time.now).to_i
+
+      # Add body hash and blank signature
+      dkim_header['bh']= base64_encode digest_alg.digest(canonical_body)
+      dkim_header['h'] = signed_headers.join(':')
+      dkim_header['b'] = ''
+
+      # Calculate signature based on intermediate signature header
+      headers = canonical_header
+      headers << dkim_header.to_s(header_canonicalization)
+      signature = base64_encode private_key.sign(digest_alg, headers)
+      dkim_header['b'] = signature
+
+      dkim_header
     end
+
     def to_s
+      # Return the original message with the calculated header
       headers = @headers.to_a + [dkim_header]
       headers.map(&:to_s).join("\r\n") +
         "\r\n\r\n" +
@@ -95,7 +107,7 @@ module Dkim
 
     private
     def base64_encode data
-      Base64.encode64(data).gsub("\n",'')
+      [data].pack('m0*').gsub("\n",'')
     end
     def digest_alg
       case signing_algorithm

data/lib/dkim/version.rb

@@ -1,3 +1,3 @@
 module Dkim
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/canonicalization_test.rb

@@ -0,0 +1,78 @@
+
+require 'test_helper'
+
+class CanonicalizationTest < Test::Unit::TestCase
+  # from section 3.4.6 of rfc4871
+  def setup
+    @input = <<-eos.rfc_format
+      A: <SP> X <CRLF>
+      B <SP> : <SP> Y <HTAB><CRLF>
+      <HTAB> Z <SP><SP><CRLF>
+      <CRLF>
+      <SP> C <SP><CRLF>
+      D <SP><HTAB><SP> E <CRLF>
+      <CRLF>
+      <CRLF>
+    eos
+    @mail = Dkim::SignedMail.new(@input)
+    @mail.signable_headers = ['A', 'B']
+  end
+  def test_relaxed_header
+    @mail.header_canonicalization = 'relaxed'
+    expected_header = <<-eos.rfc_format
+      a:X <CRLF>
+      b:Y <SP> Z <CRLF>
+    eos
+    assert_equal expected_header, @mail.canonical_header
+  end
+  def test_relaxed_body
+    @mail.body_canonicalization = 'relaxed'
+    expected_body = <<-eos.rfc_format
+      <SP> C <CRLF>
+      D <SP> E <CRLF>
+    eos
+    assert_equal expected_body, @mail.canonical_body
+  end
+
+  def test_simple_header
+    @mail.header_canonicalization = 'simple'
+    expected_header = <<-eos.rfc_format
+      A: <SP> X <CRLF>
+      B <SP> : <SP> Y <HTAB><CRLF>
+      <HTAB> Z <SP><SP><CRLF>
+    eos
+    assert_equal expected_header, @mail.canonical_header
+  end
+  def test_simple_body
+    @mail.body_canonicalization = 'simple'
+    expected_body = <<-eos.rfc_format
+      <SP> C <SP><CRLF>
+      D <SP><HTAB><SP> E <CRLF>
+    eos
+    assert_equal expected_body, @mail.canonical_body
+  end
+
+  # from errata: empty bodies
+  def test_simple_empty_body
+    @mail = Dkim::SignedMail.new("test: test\r\n\r\n")
+    @mail.body_canonicalization = 'simple'
+
+    assert_equal "\r\n", @mail.canonical_body
+  end
+
+  def test_relaxed_empty_body
+    @mail = Dkim::SignedMail.new("test: test\r\n\r\n")
+    @mail.body_canonicalization = 'relaxed'
+
+    assert_equal "", @mail.canonical_body
+  end
+
+  def test_relaxed_errata_1384
+    body = "testing<crlf><sp><sp><cr><lf><cr><lf>".rfc_format
+    @mail = Dkim::SignedMail.new("test: test\r\n\r\n#{body}")
+    @mail.body_canonicalization = 'relaxed'
+
+    assert_equal "testing\r\n", @mail.canonical_body
+  end
+end
+

data/test/test_helper.rb

@@ -0,0 +1,29 @@
+
+require 'test/unit'
+require 'dkim'
+
+class String
+  # Parse the format used in rfc4871
+  #
+  # In the following examples, actual whitespace is used only for
+  # clarity.  The actual input and output text is designated using
+  # bracketed descriptors: "<SP>" for a space character, "<HTAB>" for a
+  # tab character, and "<CRLF>" for a carriage-return/line-feed sequence.
+  # For example, "X <SP> Y" and "X<SP>Y" represent the same three
+  # characters.
+  def rfc_format
+    str = self.dup
+    str.gsub!(/\s/,'')
+    str.gsub!(/<SP>/i,' ')
+    str.gsub!(/<CR>/i,"\r")
+    str.gsub!(/<LF>/i,"\n")
+    str.gsub!(/<CRLF>/i,"\r\n")
+    str.gsub!(/<HTAB>/i,"\t")
+    str
+  end
+end
+
+# examples used in rfc
+Dkim::domain = 'example.com'
+
+

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: dkim
 version: !ruby/object:Gem::Version 
+  hash: 27
   prerelease: 
-  version: 0.0.1
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - John Hawthorn
@@ -10,7 +15,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-10 00:00:00 Z
+date: 2011-05-31 00:00:00 -07:00
+default_executable: 
 dependencies: []
 
 description: gem for adding DKIM signatures to email messages
@@ -24,16 +30,23 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- CHANGELOG.md
 - Gemfile
+- README.md
 - Rakefile
 - bin/dkimsign.rb
 - dkim.gemspec
 - lib/dkim.rb
 - lib/dkim/body.rb
+- lib/dkim/canonicalizable.rb
+- lib/dkim/dkim_header.rb
 - lib/dkim/header.rb
 - lib/dkim/header_list.rb
 - lib/dkim/signed_mail.rb
 - lib/dkim/version.rb
+- test/canonicalization_test.rb
+- test/test_helper.rb
+has_rdoc: true
 homepage: https://github.com/jhawthorn/dkim
 licenses: []
 
@@ -47,19 +60,26 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: dkim
-rubygems_version: 1.8.1
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: DKIM library in ruby
-test_files: []
-
+test_files: 
+- test/canonicalization_test.rb
+- test/test_helper.rb