saml_tools 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    M2Q5NTdiZmZmM2FkZTAwNDE4MTg5OTczNWEyODA5ZDNmOTE5ZmMzOQ==
+  data.tar.gz: !binary |-
+    ZjE1NGRlYzdhMmQzZDg4N2ZiMTZlY2RkZGFjZWViMDNlOWJkOWI5Ng==
+SHA512:
+  metadata.gz: !binary |-
+    ZjkwNjQyOTQxNTA4YjAwNmJjZDJjMzBiMTBhZGYxZWYzZDhmNzAzMmI0ZjZh
+    NTNlNzY4ODM0MDZmNjg0MGRkOTdhMDIxYjEwYWRhNjUyMTBmZDRlMjNkNGM4
+    NzQ2OThjZDcxN2NmNjVkZTM1MTFhNDZjMzk5OGIzN2RlOWI3ODE=
+  data.tar.gz: !binary |-
+    ZWY0OTc2Y2JiODhlYjIwYjdmY2Y2ZDhkM2Y4MjEzYThiMDAxY2YyNWNmODBl
+    ZjVlNWMxZWVlOWM3NTc1YjZkNjM1ZmQyODQxNjE5YzQ4M2UxZTMzOTUxOWIw
+    YWUwNjg2ZDk3MDNiNDg5NjFmMmRhYzA4Y2Y4NDVlNWYyNDI2MDI=

data/LICENSE

@@ -0,0 +1,24 @@
+SAML Tools
+
+Copyright (c) 2014 Rob Nichols, Warwickshire County Council
+
+MIT License
+
+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.rdoc

@@ -0,0 +1,65 @@
+=SAML Tools
+
+Tools to simplify the creation, validation and sending of SAML objects
+
+== SamlTool::Certificate
+Version of OpenSSL::X509::Certificate that adds methods to simplify the retrieval
+of data used in SAML responses.
+
+== SamlTool::Decoder
+Decodes base64 and unzips content.
+
+== SamlTool::Encoder
+Zips content and base64 encodes it.
+
+== SamlTool::ErbBuilder
+Used to build SAML content from erb templates.
+
+    output = SamlTool::ErbBuilder.build(
+      template: '<foo><%= settings %></foo>',
+      settings: 'bar'
+    )
+    output == '<foo>bar</foo>'
+
+== SamlTool::Reader
+Wraps SAML documents and exposes data via methods
+
+    reader = SamlTool::Reader.new(
+               output,
+               {foo: '//foo/text()'}
+             )
+    reader.foo == 'bar'
+
+== SamlTool::Redirect
+Used to construct redirection uris
+
+      redirect = Redirect.uri(
+        to: 'http://example.com',
+        data: {
+          foo: 'bar'
+        }
+      )
+      redirect == "http://example.com?foo=bar"
+
+== SamlTool::ResponseReader
+A version of SamlTool::Reader tailored for handling SAML responses. It includes
+a valid? method that validates the SAML structure and checks the signature is
+correct.
+
+== SamlTool::RsaKey
+Version of OpenSSL::PKey::RSA that adds methods to simplify the retrieval
+of data used in SAML responses.
+
+== SamlTool::SAML
+A wrapper for Nokogiri::XML, that applies defaults that are appropriate for SAML
+
+== SamlTool::Settings
+Packages up settings so that they can be more easily passed to other objects.
+
+== SamlTool::Validator
+Compares documents with SAML schemas to test if they have a valid structure.
+
+== Further reading
+
+I've {blogged here}[http://undervale.co.uk/blog/?p=490] about some of highs and
+lows of building these tools.

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rdoc/task'
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::RDocTask.new do |rdoc|
+  files =['README.rdoc', 'LICENSE', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README.rdoc" # page to start on
+  rdoc.title = "SAML Tools Documentation"
+  rdoc.rdoc_dir = 'doc/rdoc' # rdoc output folder
+  rdoc.options << '--line-numbers'
+end
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require_relative 'lib/saml_tool'
+  ARGV.clear
+  IRB.start
+end

data/lib/saml_tool.rb

@@ -0,0 +1,23 @@
+# Namespace definition
+
+require 'nokogiri'
+require 'hashie'
+require 'securerandom'
+require 'base64'
+require 'zlib'
+require 'openssl'
+require 'xmldsig'
+
+module SamlTool
+  require_relative 'saml_tool/validator'
+  require_relative 'saml_tool/erb_builder'
+  require_relative 'saml_tool/encoder'
+  require_relative 'saml_tool/decoder'
+  require_relative 'saml_tool/redirect'
+  require_relative 'saml_tool/settings'
+  require_relative 'saml_tool/reader'
+  require_relative 'saml_tool/response_reader'
+  require_relative 'saml_tool/saml'
+  require_relative 'saml_tool/certificate'
+  require_relative 'saml_tool/rsa_key'
+end

data/lib/saml_tool/certificate.rb

@@ -0,0 +1,27 @@
+
+module SamlTool
+  class Certificate < OpenSSL::X509::Certificate
+    
+    alias_method :serial_number, :serial
+  
+    def without_leading_and_trailing_labels
+      to_s.lines.to_a[1..-2].join
+    end
+    alias_method :x509_certificate, :without_leading_and_trailing_labels
+    
+    def issuer_name
+      @issuer_name ||= slash_list_to_comma_list(issuer)
+    end
+    
+    def subject_name
+      @subject_name ||= slash_list_to_comma_list(subject)
+    end
+    
+    def slash_list_to_comma_list(string)
+      string = string.to_s
+      string = string[1..-1] if string[0] == '/'
+      string.split('/').reverse.join(',')
+    end
+    
+  end
+end

data/lib/saml_tool/decoder.rb

@@ -0,0 +1,35 @@
+
+module SamlTool
+  class Decoder
+    attr_reader :saml
+    attr_accessor :output
+
+    def self.decode(encoded_saml)
+      new(encoded_saml).decode
+    end
+
+    def initialize(encoded_saml)
+      @saml = encoded_saml
+      @output = @saml.clone
+    end
+
+    def decode
+      base64
+      zlib
+      output
+    end
+
+    def base64
+      self.output = Base64.decode64 output
+    end
+
+    def zlib
+      zstream  = Zlib::Inflate.new(-Zlib::MAX_WBITS) # I have no idea why we're using minus Zlib::MAX_WBITS. Zlib documentation suggests just Zlib::MAX_WBITS should work, but it doesn't
+        self.output = zstream.inflate(output)
+      zstream.finish
+      zstream.close
+      return output
+    end
+
+  end
+end

data/lib/saml_tool/encoder.rb

@@ -0,0 +1,31 @@
+
+module SamlTool
+  class Encoder
+    attr_reader :saml
+    attr_accessor :output
+
+    def self.encode(saml)
+      new(saml).encode
+    end
+
+    def initialize(saml)
+      @saml = saml
+      @output = @saml.clone
+    end
+
+    def encode
+      zlib
+      base64
+      output
+    end
+
+    def base64
+      self.output = Base64.encode64 output
+    end
+
+    def zlib
+      self.output = Zlib::Deflate.deflate(output, Zlib::BEST_COMPRESSION)[2..-5]
+    end
+
+  end
+end

data/lib/saml_tool/erb_builder.rb

@@ -0,0 +1,33 @@
+require 'erb'
+module SamlTool
+  class ErbBuilder
+    
+    attr_reader :args, :settings, :template
+
+    def self.build(args)
+      new(args).to_s
+    end
+
+    def initialize(args)
+      @args = args
+      @settings = args[:settings]
+      @template = args[:template]
+    end
+
+    def to_s
+      output
+    end
+
+    def output
+      @output ||= build_output
+    end
+
+    def build_output
+      erb.result settings.send(:binding)
+    end
+
+    def erb
+      ERB.new(template)
+    end
+  end
+end

data/lib/saml_tool/reader.rb

@@ -0,0 +1,40 @@
+
+module SamlTool
+  class Reader
+    attr_reader :saml, :config, :namespaces
+
+    def initialize(saml, config = {}, namespaces = nil)
+      @saml = SamlTool::SAML(saml)
+      @config = Hashie::Mash.new(config)
+      @namespaces = namespaces
+      build_methods
+    end
+
+    def to_hash
+      config.keys.inject({}){|hash, key| hash[key.to_sym] = send(key.to_sym); hash}
+    end
+
+    private
+    def build_methods
+      @config.each do |key, value|
+        self.class.send :attr_reader, key.to_sym
+        source = saml.xpath(value, namespaces)
+        content = Content.new(source)
+        instance_variable_set("@#{key}".to_sym, content)
+      end
+    end
+    
+    # A string with memory of the element that was the source of its content.
+    # Typically, the source will be a Nokogiri::XML::NodeSet. So:
+    #     content           --> text from an element.
+    #     content.source    --> the Nokogiri NodeSet the text was extracted from.
+    class Content < String    
+      attr_reader :source
+      def initialize(source)
+        @source = source
+        super(source.to_s)
+      end
+    end
+
+  end
+end

data/lib/saml_tool/redirect.rb

@@ -0,0 +1,45 @@
+require 'uri'
+require 'cgi'
+module SamlTool
+
+  class Redirect
+    attr_reader :to, :data
+
+    def self.uri(args)
+      new(args).to_s
+    end
+
+    def initialize(args)
+      @to = args[:to]
+      @data = args[:data]
+    end
+
+    def uri
+      @uri || build_uri
+    end
+
+    def data_string
+      return data if data.kind_of? String
+      data.to_a.collect{|pair| pair.collect{|p| CGI.escape(p.to_s)}.join('=')}.join('&')
+    end
+
+    def append_data
+      uri.query = [uri.query, data_string].compact.join('&')
+    end
+
+    def to_s
+      uri.to_s
+    end
+
+    def build_uri
+      uri_from_to
+      append_data
+      return uri
+    end
+
+    def uri_from_to
+      @uri = URI(to)
+    end
+  end
+
+end

data/lib/saml_tool/response_reader.rb

@@ -0,0 +1,148 @@
+require "openssl"
+
+module SamlTool
+  class ResponseReader < Reader
+    
+    # On creation, the keys for this hash will be converted into methods that
+    # will return the text gathered at the xpath in the matching value.
+    def default_config
+      {
+        base64_cert:             '//ds:X509Certificate/text()',
+        canonicalization_method: '//ds:CanonicalizationMethod/@Algorithm',
+        reference_uri:           '//ds:Reference/@URI',
+        inclusive_namespaces:    '//ec:InclusiveNamespaces/@PrefixList',
+        digest_algorithm:        '//ds:DigestMethod/@Algorithm',
+        digest_value:            '//ds:DigestValue/text()',
+        signature_value:         '//ds:SignatureValue/text()',
+        signature_algorithm:     '//ds:SignatureMethod/@Algorithm',
+        signed_info:             '//ds:SignedInfo'
+      }
+    end 
+    
+    def initialize(saml, config = {}, namespaces = {})    
+      super(
+        saml,
+        config.merge(default_config),
+        namespaces.merge(default_namespaces)
+      )
+    end
+
+    def valid?
+      structurally_valid? && signature_verified? && digests_match?
+    end
+
+    def structurally_valid?
+      Validator.new(saml.to_s).valid?
+    end
+
+    def signature_verified?
+      certificate.public_key.verify(
+        signature_algorithm_class.new,
+        signature,
+        canonicalized_signed_info
+      )
+    end
+
+    def digests_match?
+      digest_hash == decoded_digest_value
+    end
+    
+    def signatureless
+      @signatureless ||= clone_saml_and_remove_signature
+    end
+    
+    def certificate
+      @certificate ||= OpenSSL::X509::Certificate.new(raw_cert)
+    end
+    
+    def raw_cert
+      @raw_cert ||= Base64.decode64(base64_cert)
+    end
+    
+    def fingerprint
+      @fingerprint ||= Digest::SHA1.hexdigest(certificate.to_der)
+    end
+
+    def signature
+      @signature ||= Base64.decode64(signature_value)
+    end
+    
+    def canonicalization_algorithm
+      case canonicalization_method
+        when "http://www.w3.org/TR/2001/REC-xml-c14n-20010315" then Nokogiri::XML::XML_C14N_1_0
+        when "http://www.w3.org/2006/12/xml-c14n11"            then Nokogiri::XML::XML_C14N_1_1
+        else                                                        Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0
+      end
+    end
+    
+    def hashed_element
+      @hashed_element ||= signatureless.at_xpath("//*[@ID='#{reference_uri[1..-1]}']")
+    end
+    
+    def canonicalized_hashed_element
+      hashed_element.canonicalize(
+        canonicalization_algorithm, 
+        inclusive_namespaces.split(' ')
+      )
+    end
+
+    def canonicalized_signed_info
+      signed_info_element.canonicalize(
+        canonicalization_algorithm,
+        inclusive_namespaces.split(' ')
+      )
+    end
+
+    def signed_info_element
+      signed_info.source.first
+    end
+    
+    def digest_algorithm_class
+      @digest_algorithm_class ||= determine_algorithm_class(digest_algorithm)
+    end
+
+    def signature_algorithm_class
+      @signature_algorithm_class ||= determine_algorithm_class(signature_algorithm)
+    end
+  
+    def determine_algorithm_class(method_text)
+      case method_text.slice(/sha(\d+)\s*$/, 1)
+      when '256' then OpenSSL::Digest::SHA256
+      when '384' then OpenSSL::Digest::SHA384
+      when '512' then OpenSSL::Digest::SHA512
+      else
+        OpenSSL::Digest::SHA1
+      end
+    end
+    
+    def digest_hash
+      @digest_hash ||= digest_algorithm_class.digest(canonicalized_hashed_element)
+    end
+    
+    def decoded_digest_value
+      Base64.decode64(digest_value)
+    end
+
+    def clone_saml_and_remove_signature
+      cloned_saml = saml.clone
+      cloned_saml.xpath('//ds:Signature', namespaces).remove
+      return SamlTool::SAML(cloned_saml.to_s)
+    end
+    
+    def default_namespaces
+      {
+        ds: dsig,
+        ec: c14m
+      }
+    end
+    
+    def c14m
+      'http://www.w3.org/2001/10/xml-exc-c14n#'
+    end
+        
+    def dsig
+      'http://www.w3.org/2000/09/xmldsig#'
+    end
+
+  end
+end