saml2 2.0.2 → 2.1.0

data/lib/saml2/authn_statement.rb

@@ -1,22 +1,33 @@
+# frozen_string_literal: true
+
 require 'saml2/base'
 
 module SAML2
   class AuthnStatement < Base
     module Classes
-      INTERNET_PROTOCOL            = "urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol".freeze # IP address
-      INTERNET_PROTOCOL_PASSWORD   = "urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword".freeze # IP address, as well as username/password
-      KERBEROS                     = "urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos".freeze
-      PASSWORD                     = "urn:oasis:names:tc:SAML:2.0:ac:classes:Password".freeze # username/password, NOT over SSL
-      PASSWORD_PROTECTED_TRANSPORT = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport".freeze # username/password over SSL
-      PREVIOUS_SESSION             = "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession".freeze # remember me
-      SMARTCARD                    = "urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard".freeze
-      SMARTCARD_PKI                = "urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI".freeze # smartcard with a private key on it
-      TLS_CLIENT                   = "urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient".freeze # SSL client certificate
-      UNSPECIFIED                  = "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified".freeze
+      INTERNET_PROTOCOL            = "urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol" # IP address
+      INTERNET_PROTOCOL_PASSWORD   = "urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword" # IP address, as well as username/password
+      KERBEROS                     = "urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos"
+      PASSWORD                     = "urn:oasis:names:tc:SAML:2.0:ac:classes:Password" # username/password, NOT over SSL
+      PASSWORD_PROTECTED_TRANSPORT = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" # username/password over SSL
+      PREVIOUS_SESSION             = "urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession" # remember me
+      SMARTCARD                    = "urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard"
+      SMARTCARD_PKI                = "urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI" # smartcard with a private key on it
+      TLS_CLIENT                   = "urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient" # SSL client certificate
+      UNSPECIFIED                  = "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified"
     end
 
-    attr_accessor :authn_instant, :authn_context_class_ref, :session_index, :session_not_on_or_after
+    # @return [Time]
+    attr_accessor :authn_instant
+    # One of the values in {Classes}.
+    # @return [String, nil]
+    attr_accessor :authn_context_class_ref
+    # @return [String, nil]
+    attr_accessor :session_index
+    # @return [Time, nil]
+    attr_accessor :session_not_on_or_after
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       @authn_instant = Time.parse(node['AuthnInstant'])
@@ -25,6 +36,7 @@ module SAML2
       @authn_context_class_ref = node.at_xpath('saml:AuthnContext/saml:AuthnContextClassRef', Namespaces::ALL)&.content&.strip
     end
 
+    # (see Base#build)
     def build(builder)
       builder['saml'].AuthnStatement('AuthnInstant' => authn_instant.iso8601) do |authn_statement|
         authn_statement.parent['SessionIndex'] = session_index if session_index

data/lib/saml2/base.rb

@@ -1,7 +1,14 @@
+# frozen_string_literal: true
+
 require 'saml2/namespaces'
 
 module SAML2
+  # @abstract
   class Base
+    # Create an appropriate object to represent the given XML element.
+    #
+    # @param node [Nokogiri::XML::Element, nil]
+    # @return [Base, nil]
     def self.from_xml(node)
       return nil unless node
       result = new
@@ -9,16 +16,31 @@ module SAML2
       result
     end
 
+    # @return [Nokogiri::XML::Element]
     attr_reader :xml
 
     def initialize
       @pretty = true
     end
 
+    # Parse an XML element into this object.
+    #
+    # @param node [Nokogiri::XML::Element]
+    # @return [void]
     def from_xml(node)
       @xml = node
     end
 
+    # Returns the XML of this object as a string.
+    #
+    # If this object came from parsing XML, it will always return it with the
+    # same formatting as it was parsed.
+    #
+    # @param pretty optional [true, false, nil]
+    #   +true+ forces it to format it for easy reading. +nil+ will prefer to
+    #   format it pretty, but won't if e.g. it has been signed, and pretty
+    #   formatting would break the signature.
+    # @return [String]
     def to_s(pretty: nil)
       pretty = @pretty if pretty.nil?
       if xml
@@ -31,10 +53,19 @@ module SAML2
       end
     end
 
+    # Inspect the object
+    #
+    # The +@xml+ instance variable is omitted, keeping this useful. However, if
+    # an object lazily parses sub-objects, then their instance variables will
+    # not be created until their attribute is accessed.
+    # @return [String]
     def inspect
       "#<#{self.class.name} #{instance_variables.map { |iv| next if iv == :@xml; "#{iv}=#{instance_variable_get(iv).inspect}" }.compact.join(", ") }>"
     end
 
+    # Serialize this object to XML
+    #
+    # @return [Nokogiri::XML::Document]
     def to_xml
       unless instance_variable_defined?(:@document)
         builder = Nokogiri::XML::Builder.new
@@ -47,6 +78,10 @@ module SAML2
       @document
     end
 
+    # Serialize this object to XML, as part of a larger document
+    #
+    # @param builder [Nokogiri::XML::Builder] The builder helper object to serialize to.
+    # @return [void]
     def build(builder)
     end
 
@@ -56,6 +91,7 @@ module SAML2
       end
     end
 
+
     def self.load_object_array(node, element, klass = nil)
       node.xpath(element, Namespaces::ALL).map do |element_node|
         if klass.nil?

data/lib/saml2/bindings.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module SAML2
   module Bindings
     module Encodings
-      DEFLATE = 'urn:oasis:names:tc:SAML:2.0:bindings:URL-Encoding:DEFLATE'.freeze
+      DEFLATE = 'urn:oasis:names:tc:SAML:2.0:bindings:URL-Encoding:DEFLATE'
     end
   end
 end

data/lib/saml2/bindings/http_post.rb

@@ -1,11 +1,20 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module SAML2
   module Bindings
     module HTTP_POST
-      URN ="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST".freeze
+      URN ="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
 
       class << self
+        # Decode and parse a Base64 encoded SAML message.
+        #
+        # @param post_params [Hash<String => String>]
+        #   The POST params. Will check for both +SAMLRequest+ and
+        #   +SAMLResponse+ params.
+        # @return [[Message, String]]
+        #   The Message and the RelayState.
         def decode(post_params)
           base64 = post_params['SAMLRequest'] || post_params['SAMLResponse']
           raise MissingMessage unless base64
@@ -22,6 +31,13 @@ module SAML2
           [message, post_params['RelayState']]
         end
 
+        # Encode a SAML message into Base64 POST params.
+        #
+        # @param message [Message]
+        # @param relay_state optional [String]
+        # @return [Hash<String => String>]
+        #   The POST params, including +RelayState+, and +SAMLRequest+ vs.
+        #   +SAMLResponse+ chosen appropriately.
         def encode(message, relay_state: nil)
           xml = message.to_s(pretty: false)
           key = message.is_a?(Request) ? 'SAMLRequest' : 'SAMLResponse'

data/lib/saml2/bindings/http_redirect.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 require 'uri'
 require 'zlib'
@@ -8,16 +10,39 @@ require 'saml2/message'
 module SAML2
   module Bindings
     module HTTPRedirect
-      URN ="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect".freeze
+      URN ="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
 
       module SigAlgs
-        DSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#dsa-sha1".freeze
-        RSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#rsa-sha1".freeze
+        DSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#dsa-sha1"
+        RSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
+        RSA_SHA256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
 
-        RECOGNIZED = [DSA_SHA1, RSA_SHA1].freeze
+        RECOGNIZED = [DSA_SHA1, RSA_SHA1, RSA_SHA256].freeze
       end
 
       class << self
+        # Decode, validate signature, and parse a compressed and Base64 encoded
+        # SAML message.
+        #
+        # A signature, if present, will be verified only if +public_key+ is
+        # passed.
+        #
+        # @param url [String]
+        #   The full URL to decode. Will check for both +SAMLRequest+ and
+        #   +SAMLResponse+ params.
+        # @param public_key optional [Array<OpenSSL::PKey>, OpenSSL::PKey, Proc]
+        #   Keys to use to check the signature. If a +Proc+ is provided, it is
+        #   called with the parsed {Message}, and the +SigAlg+ in order for the
+        #   caller to find an appropriate key based on the {Message}'s issuer.
+        # @param public_key_used optional [Proc]
+        #   Is called with the actual key that was used to validate the
+        #   signature.
+        # @return [[Message, String]]
+        #   The Message and the RelayState.
+        # @raise [UnsignedMessage] If a public_key is provided, but the message
+        #   is not signed.
+        # @yield [message, sig_alg]
+        #   The same as a +Proc+ provided to +public_key+. Deprecated.
         def decode(url, public_key: nil, public_key_used: nil)
           uri = begin
             URI.parse(url)
@@ -51,7 +76,7 @@ module SAML2
           end
 
           zstream = Zlib::Inflate.new(-Zlib::MAX_WBITS)
-          xml = ''
+          xml = String.new
           begin
             # do it in 1K slices, so we can protect against bombs
             (0..deflated.bytesize / 1024).each do |i|
@@ -69,6 +94,7 @@ module SAML2
           # if a block is provided, it's to fetch the proper certificate
           # based on the contents of the message
           public_key ||= yield(message, sig_alg) if block_given?
+          public_key = public_key.call(message, sig_alg) if public_key.is_a?(Proc)
           if public_key
             raise UnsignedMessage unless signature
             raise UnsupportedSignatureAlgorithm unless SigAlgs::RECOGNIZED.include?(sig_alg)
@@ -86,7 +112,8 @@ module SAML2
             valid_signature = false
             # there could be multiple certificates to try
             Array(public_key).each do |key|
-              if key.verify(OpenSSL::Digest::SHA1.new, signature, base_string)
+              hash = (sig_alg == SigAlgs::RSA_SHA256 ? OpenSSL::Digest::SHA256 : OpenSSL::Digest::SHA1)
+              if key.verify(hash.new, signature, base_string)
                 # notify the caller which certificate was used
                 public_key_used&.call(key)
                 valid_signature = true
@@ -98,7 +125,22 @@ module SAML2
           [message, relay_state]
         end
 
-        def encode(message, relay_state: nil, private_key: nil)
+        # Encode a SAML message into Base64, compressed query params.
+        #
+        # @param message [Message]
+        #   Note that the base URI is taken from {Message#destination}.
+        # @param relay_state optional [String]
+        # @param private_key optional [OpenSSL::PKey::RSA]
+        #   A key to use to sign the encoded message.
+        # @param sig_alg optional [String]
+        #   The signing algorithm to use. Defaults to RSA-SHA1, as it's the
+        #   most compatible, and explicitly mentioned in the SAML specs, but
+        #   you may want to use RSA-SHA256. Values must come from {SigAlgs}.
+        # @return [String]
+        #   The full URI to redirect to, including +RelayState+, and
+        #   +SAMLRequest+ vs. +SAMLResponse+ chosen appropriately, and
+        #   +Signature+ + +SigAlg+ query params if signing.
+        def encode(message, relay_state: nil, private_key: nil, sig_alg: SigAlgs::RSA_SHA1)
           result = URI.parse(message.destination)
           original_query = URI.decode_www_form(result.query) if result.query
           original_query ||= []
@@ -117,9 +159,12 @@ module SAML2
           query << [message.is_a?(Request) ? 'SAMLRequest' : 'SAMLResponse', base64]
           query << ['RelayState', relay_state] if relay_state
           if private_key
-            query << ['SigAlg', SigAlgs::RSA_SHA1]
+            raise ArgumentError, "Unsupported signature algorithm #{sig_alg}" unless SigAlgs::RECOGNIZED.include?(sig_alg)
+
+            query << ['SigAlg', sig_alg]
             base_string = URI.encode_www_form(query)
-            signature = private_key.sign(OpenSSL::Digest::SHA1.new, base_string)
+            hash = (sig_alg == SigAlgs::RSA_SHA256 ? OpenSSL::Digest::SHA256 : OpenSSL::Digest::SHA1)
+            signature = private_key.sign(hash.new, base_string)
             query << ['Signature', Base64.strict_encode64(signature)]
           end
 

data/lib/saml2/conditions.rb

@@ -1,16 +1,22 @@
+# frozen_string_literal: true
+
 require 'active_support/core_ext/array/wrap'
 
 module SAML2
   class Conditions < Array
+    # @return [Time, nil]
     attr_accessor :not_before, :not_on_or_after
+    # (see Base#xml)
     attr_reader :xml
 
+    # (see Base.from_xml)
     def self.from_xml(node)
       result = new
       result.from_xml(node)
       result
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       @xml = node
       @not_before = Time.parse(node['NotBefore']) if node['NotBefore']
@@ -19,20 +25,30 @@ module SAML2
       replace(node.children.map { |restriction| self.class.const_get(restriction.name, false).from_xml(restriction) })
     end
 
-    def valid?(options = {})
-      now = options[:now] || Time.now
-      return :invalid if not_before && now < not_before
-      return :invalid if not_on_or_after && now >= not_on_or_after
-
-      result = :valid
+    # Evaluate these conditions.
+    #
+    # @param now optional [Time]
+    # @param options
+    #   Additional options to pass to specific {Condition}s
+    # @return [Boolean, nil]
+    #   It's only valid if every sub-condition is completely valid.
+    #   If any sub-condition is invalid, the whole statement is invalid.
+    #   If the validity can't be determined due to an unsupported condition,
+    #   +nil+ will be returned (which is false-ish)
+    def valid?(now: Time.now.utc, **options)
+      options[:now] ||= now
+      return false if not_before && now < not_before
+      return false if not_on_or_after && now >= not_on_or_after
+
+      result = true
       each do |condition|
-        this_result = condition.valid?(options)
+        this_result = condition.valid?(**options)
         case this_result
-        when :invalid
-          return :invalid
-        when :indeterminate
-          result = :indeterminate
-          when :valid
+        when false
+          return false
+        when nil
+          result = nil
+        when true
         else
           raise "unknown validity of #{condition}"
         end
@@ -40,6 +56,7 @@ module SAML2
       result
     end
 
+    # (see Base#build)
     def build(builder)
       builder['saml'].Conditions do |conditions|
         conditions.parent['NotBefore'] = not_before.iso8601 if not_before
@@ -53,31 +70,37 @@ module SAML2
 
     # Any unknown condition
     class Condition < Base
+      # @return [nil]
       def valid?(_)
-        :indeterminate
+        nil
       end
     end
 
     class AudienceRestriction < Condition
       attr_writer :audience
 
+      # @param audience [Array<String>]
       def initialize(audience = [])
         @audience = audience
       end
 
+      # (see Base#from_xml)
       def from_xml(node)
         super
         @audience = nil
       end
 
+      # @return [Array<String>] Allowed audiences
       def audience
         @audience ||= load_string_array(xml, 'saml:Audience')
       end
 
-      def valid?(options)
-        Array.wrap(audience).include?(options[:audience]) ? :valid : :invalid
+      # @param audience [String]
+      def valid?(audience: nil, **_)
+        Array.wrap(self.audience).include?(audience)
       end
 
+      # (see Base#build)
       def build(builder)
         builder['saml'].AudienceRestriction do |audience_restriction|
           Array.wrap(audience).each do |single_audience|
@@ -88,10 +111,14 @@ module SAML2
     end
 
     class OneTimeUse < Condition
+      # The caller will need to see if this condition exists, and validate it
+      # using their own state store.
+      # @return [true]
       def valid?(_)
-        :valid
+        true
       end
 
+      # (see Base#build)
       def build(builder)
         builder['saml'].OneTimeUse
       end

data/lib/saml2/contact.rb

@@ -1,23 +1,33 @@
+# frozen_string_literal: true
+
 require 'saml2/base'
 
 module SAML2
   class Contact < Base
     module Type
-      ADMINISTRATIVE = 'administrative'.freeze
-      BILLING        = 'billing'.freeze
-      OTHER          = 'other'.freeze
-      SUPPORT        = 'support'.freeze
-      TECHNICAL      = 'technical'.freeze
+      ADMINISTRATIVE = 'administrative'
+      BILLING        = 'billing'
+      OTHER          = 'other'
+      SUPPORT        = 'support'
+      TECHNICAL      = 'technical'
     end
 
-    attr_accessor :type, :company, :given_name, :surname, :email_addresses, :telephone_numbers
+    # @see Type
+    # @return [String]
+    attr_accessor :type
+    # @return [String, nil]
+    attr_accessor :company, :given_name, :surname
+    # @return [Array<String>]
+    attr_accessor :email_addresses, :telephone_numbers
 
+    # @param type [String]
     def initialize(type = Type::OTHER)
       @type = type
       @email_addresses = []
       @telephone_numbers = []
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       self.type = node['contactType']
       company = node.at_xpath('md:Company', Namespaces::ALL)
@@ -31,6 +41,7 @@ module SAML2
       self
     end
 
+    # (see Base#build)
     def build(builder)
       builder['md'].ContactPerson('contactType' => type) do |contact_person|
         contact_person['md'].Company(company) if company