saml2 2.0.2 → 2.1.0

data/lib/saml2/endpoint.rb

@@ -1,23 +1,32 @@
+# frozen_string_literal: true
+
 require 'saml2/bindings/http_post'
 
 module SAML2
   class Endpoint < Base
+    # @return [String]
     attr_reader :location, :binding
 
+    # @param location [String]
+    # @param binding [String]
     def initialize(location = nil, binding = Bindings::HTTP_POST::URN)
       @location, @binding = location, binding
     end
 
+    # @param rhs [Endpoint]
+    # @return [Boolean]
     def ==(rhs)
       location == rhs.location && binding == rhs.binding
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       @location = node['Location']
       @binding = node['Binding']
     end
 
+    # (see Base#build)
     def build(builder, element)
       builder['md'].__send__(element, 'Location' => location, 'Binding' => binding)
     end
@@ -25,6 +34,10 @@ module SAML2
     class Indexed < Endpoint
       include IndexedObject
 
+      # @param location [String]
+      # @param index [Integer]
+      # @param is_default [true, false, nil]
+      # @param binding [String]
       def initialize(location = nil, index = nil, is_default = nil, binding = Bindings::HTTP_POST::URN)
         super(location, binding)
         @index, @is_default = index, is_default

data/lib/saml2/engine.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module SAML2
   class Engine < Rails::Engine
   end

data/lib/saml2/entity.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'nokogiri'
 
 require 'saml2/base'
@@ -11,8 +13,13 @@ module SAML2
     include OrganizationAndContacts
     include Signable
 
+    # @return [String]
     attr_writer :entity_id
 
+    # Parse a metadata file, and return an appropriate object.
+    #
+    # @param xml [String, IO] Anything that can be passed to +Nokogiri::XML+
+    # @return [Entity, Group, nil]
     def self.parse(xml)
       document = Nokogiri::XML(xml)
 
@@ -46,6 +53,7 @@ module SAML2
         @valid_until = nil
       end
 
+      # (see Base#from_xml)
       def from_xml(node)
         super
         @id = nil
@@ -55,14 +63,17 @@ module SAML2
                 'EntitiesDescriptor' => Group)
       end
 
+      # (see Message#valid_schema?)
       def valid_schema?
         Schemas.federation.valid?(xml.document)
       end
 
+      # (see Message#id)
       def id
         @id ||= xml['ID']
       end
 
+      # @return [Time, nil]
       def valid_until
         unless instance_variable_defined?(:@valid_until)
           @valid_until = xml['validUntil'] && Time.parse(xml['validUntil'])
@@ -79,6 +90,7 @@ module SAML2
       @id = "_#{SecureRandom.uuid}"
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       @id = nil
@@ -86,18 +98,22 @@ module SAML2
       @roles = nil
     end
 
+    # (see Message#valid_schema?)
     def valid_schema?
       Schemas.federation.valid?(xml.document)
     end
 
+    # @return [String]
     def entity_id
       @entity_id || xml && xml['entityID']
     end
 
+    # (see Message#id)
     def id
       @id ||= xml['ID']
     end
 
+    # @return [Time, nil]
     def valid_until
       unless instance_variable_defined?(:@valid_until)
         @valid_until = xml['validUntil'] && Time.parse(xml['validUntil'])
@@ -105,19 +121,23 @@ module SAML2
       @valid_until
     end
 
+    # @return [Array<IdentityProvider>]
     def identity_providers
       roles.select { |r| r.is_a?(IdentityProvider) }
     end
 
+    # @return [Array<ServiceProvider>]
     def service_providers
       roles.select { |r| r.is_a?(ServiceProvider) }
     end
 
+    # @return [Array<Role>]
     def roles
       @roles ||= load_object_array(xml, 'md:IDPSSODescriptor', IdentityProvider) +
           load_object_array(xml, 'md:SPSSODescriptor', ServiceProvider)
     end
 
+    # (see Base#build)
     def build(builder)
       builder['md'].EntityDescriptor('entityID' => entity_id,
                                      'xmlns:md' => Namespaces::METADATA,

data/lib/saml2/identity_provider.rb

@@ -1,9 +1,13 @@
+# frozen_string_literal: true
+
 require 'saml2/attribute'
 require 'saml2/sso'
 
 module SAML2
   class IdentityProvider < SSO
-    attr_writer :want_authn_requests_signed, :single_sign_on_services, :attribute_profiles, :attributes
+    # @return [Boolean, nil]
+    attr_writer :want_authn_requests_signed
+    attr_writer :single_sign_on_services, :attribute_profiles, :attributes
 
     def initialize
       super
@@ -13,6 +17,7 @@ module SAML2
       @attributes = []
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       super
       remove_instance_variable(:@want_authn_requests_signed)
@@ -21,6 +26,7 @@ module SAML2
       @attributes = nil
     end
 
+    # @return [Boolean, nil]
     def want_authn_requests_signed?
       unless instance_variable_defined?(:@want_authn_requests_signed)
         @want_authn_requests_signed = xml['WantAuthnRequestsSigned'] && xml['WantAuthnRequestsSigned'] == 'true'
@@ -28,18 +34,22 @@ module SAML2
       @want_authn_requests_signed
     end
 
+    # @return [Array<Endpoint>]
     def single_sign_on_services
       @single_sign_on_services ||= load_object_array(xml, 'md:SingleSignOnService', Endpoint)
     end
 
+    # @return [Array<String>]
     def attribute_profiles
       @attribute_profiles ||= load_string_array(xml, 'md:AttributeProfile')
     end
 
+    # @return [Array<Attribute>]
     def attributes
       @attributes ||= load_object_array(xml, 'saml:Attribute', Attribute)
     end
 
+    # (see Base#build)
     def build(builder)
       builder['md'].IDPSSODescriptor do |idp_sso_descriptor|
         super(idp_sso_descriptor)

data/lib/saml2/indexed_object.rb

@@ -1,18 +1,21 @@
+# frozen_string_literal: true
+
 require 'saml2/base'
 
 module SAML2
   module IndexedObject
+    # @return [Integer]
     attr_accessor :index
 
-    def initialize(*args)
+    def initialize(*)
       @is_default = nil
       super
     end
 
     def eql?(rhs)
       index == rhs.index &&
-          default? == rhs.default? &&
-          super
+        default? == rhs.default? &&
+        super
     end
 
     def default?
@@ -23,13 +26,18 @@ module SAML2
       !@is_default.nil?
     end
 
+    # (see Base#from_xml)
     def from_xml(node)
       @index = node['index'] && node['index'].to_i
       @is_default = node['isDefault'] && node['isDefault'] == 'true'
       super
     end
 
+    # Keeps an Array of {IndexedObject}s in their +index+ed order.
     class Array < ::Array
+      # Returns the first object which is set as the default, or the first
+      # object if none are set as the default.
+      # @return [IndexedObject]
       attr_reader :default
 
       def self.from_xml(nodes)
@@ -68,6 +76,7 @@ module SAML2
       end
     end
 
+    # (see Base#build)
     def build(builder, *)
       super
       builder.parent.children.last['index'] = index
@@ -75,6 +84,7 @@ module SAML2
     end
 
     private
+
     def self.included(klass)
       klass.const_set(:Array, Array.dup)
     end

data/lib/saml2/key.rb

@@ -1,23 +1,86 @@
+# frozen_string_literal: true
+
+require 'saml2/base'
 require 'saml2/namespaces'
 
 module SAML2
-  class Key
+  # This represents the XML Signatures <KeyInfo> element, and actually contains a
+  # reference to an X.509 certificate, not solely a public key.
+  class KeyInfo < Base
+    # @return [String] The PEM encoded certificate.
+    attr_reader :x509
+
+    # @param x509 [String] The PEM encoded certificate.
+    def initialize(x509 = nil)
+      self.x509 = x509
+    end
+
+    # (see Base#from_xml)
+    def from_xml(node)
+      self.x509 = node.at_xpath('dsig:KeyInfo/dsig:X509Data/dsig:X509Certificate', Namespaces::ALL)&.content&.strip
+    end
+
+    def x509=(value)
+      @x509 = value&.gsub(/\w*-+(BEGIN|END) CERTIFICATE-+\w*/, "")&.strip
+    end
+
+    # @return [OpenSSL::X509::Certificate]
+    def certificate
+      @certificate ||= OpenSSL::X509::Certificate.new(Base64.decode64(x509))
+    end
+
+    # Formats a fingerprint as all lowercase, with a : every two characters.
+    # @param fingerprint [String]
+    # @return [String]
+    def self.format_fingerprint(fingerprint)
+      fingerprint.downcase.gsub(/(\h{2})(?=\h)/, '\1:')
+    end
+
+    # @return [String]
+    def fingerprint
+      @fingerprint ||= self.class.format_fingerprint(Digest::SHA1.hexdigest(certificate.to_der))
+    end
+
+    # (see Base#build)
+    def build(builder)
+      builder['dsig'].KeyInfo do |key_info|
+        key_info['dsig'].X509Data do |x509_data|
+          x509_data['dsig'].X509Certificate(x509)
+        end
+      end
+    end
+  end
+
+  class KeyDescriptor < KeyInfo
     module Type
-      ENCRYPTION = 'encryption'.freeze
-      SIGNING    = 'signing'.freeze
+      ENCRYPTION = 'encryption'
+      SIGNING    = 'signing'
     end
 
-    class EncryptionMethod
+    class EncryptionMethod < Base
       module Algorithm
-        AES128_CBC = 'http://www.w3.org/2001/04/xmlenc#aes128-cbc'.freeze
+        AES128_CBC = 'http://www.w3.org/2001/04/xmlenc#aes128-cbc'
       end
 
-      attr_accessor :algorithm, :key_size
+      # @see Algorithm
+      # @return [String]
+      attr_accessor :algorithm
+      # @return [Integer]
+      attr_accessor :key_size
 
+      # @param algorithm [String]
+      # @param key_size [Integer]
       def initialize(algorithm = Algorithm::AES128_CBC, key_size = 128)
         @algorithm, @key_size = algorithm, key_size
       end
 
+      # (see Base#from_xml)
+      def from_xml(node)
+        self.algorithm = node['Algorithm']
+        self.key_size = node.at_xpath('xenc:KeySize', Namespaces::ALL)&.content&.to_i
+      end
+
+      # (see Base#build)
       def build(builder)
         builder['md'].EncryptionMethod('Algorithm' => algorithm) do |encryption_method|
           encryption_method['xenc'].KeySize(key_size) if key_size
@@ -25,18 +88,24 @@ module SAML2
       end
     end
 
-    attr_accessor :use, :x509, :encryption_methods
+    # @see Type
+    # @return [String]
+    attr_accessor :use
+    # @return [Array<EncryptionMethod>]
+    attr_accessor :encryption_methods
 
-    def self.from_xml(node)
-      return nil unless node
-
-      x509 = node.at_xpath('dsig:KeyInfo/dsig:X509Data/dsig:X509Certificate', Namespaces::ALL)
-      methods = node.xpath('xenc:EncryptionMethod', Namespaces::ALL)
-      new(x509 && x509.content.strip, node['use'], methods.map { |m| m['Algorithm'] })
+    # (see Base#from_xml)
+    def from_xml(node)
+      super
+      self.use = node['use']
+      self.encryption_methods = load_object_array(node, 'md:EncryptionMethod', EncryptionMethod)
     end
 
-    def initialize(x509, use = nil, encryption_methods = [])
-      @use, @x509, @encryption_methods = use, x509.gsub(/\w*-+(BEGIN|END) CERTIFICATE-+\w*/, "").strip, encryption_methods
+    # @param x509 [String] The PEM encoded certificate.
+    # @param use optional [String] See {Type}
+    # @param encryption_methods [Array<EncryptionMethod>]
+    def initialize(x509 = nil, use = nil, encryption_methods = [])
+      @use, self.x509, @encryption_methods = use, x509, encryption_methods
     end
 
     def encryption?
@@ -47,30 +116,18 @@ module SAML2
       use.nil? || use == Type::SIGNING
     end
 
-    def certificate
-      @certificate ||= OpenSSL::X509::Certificate.new(Base64.decode64(x509))
-    end
-
-    def self.format_fingerprint(fingerprint)
-      fingerprint.downcase.gsub(/(\h{2})(?=\h)/, '\1:')
-    end
-
-    def fingerprint
-      @fingerprint ||= self.class.format_fingerprint(Digest::SHA1.hexdigest(certificate.to_der))
-    end
-
+    # (see Base#build)
     def build(builder)
       builder['md'].KeyDescriptor do |key_descriptor|
         key_descriptor.parent['use'] = use if use
-        key_descriptor['dsig'].KeyInfo do |key_info|
-          key_info['dsig'].X509Data do |x509_data|
-            x509_data['dsig'].X509Certificate(x509)
-          end
-        end
+        super(key_descriptor)
         encryption_methods.each do |method|
           method.build(key_descriptor)
         end
       end
     end
   end
+
+  # @deprecated Deprecated alias for KeyDescriptor
+  Key = KeyDescriptor
 end

data/lib/saml2/localized_name.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'saml2/base'
 require 'saml2/namespaces'
 
@@ -16,6 +18,11 @@ module SAML2
       end
     end
 
+    # @param lang [String, Symbol, :all, nil]
+    #   The language to retrieve the localized string for.
+    #   +:all+ will return the hash itself, and +nil+ will return the first
+    #   localized string regardless of language.
+    # @return [String]
     def [](lang)
       case lang
       when :all
@@ -27,6 +34,7 @@ module SAML2
       end
     end
 
+    # @return [String] The first localized string regardless of language
     def to_s
       self[nil].to_s
     end

data/lib/saml2/logout_request.rb

@@ -1,11 +1,18 @@
+# frozen_string_literal: true
+
 require 'saml2/name_id'
 require 'saml2/request'
 
 module SAML2
   class LogoutRequest < Request
-    attr_accessor :name_id, :session_index
-
-    def self.initiate(sso, issuer, name_id, session_index = nil)
+    attr_writer :name_id, :session_index
+
+    # @param sso [SSO]
+    # @param issuer [NameID]
+    # @param name_id [NameID]
+    # @param session_index optional [String, Array<String>]
+    # @return [LogoutRequest]
+    def self.initiate(sso, issuer, name_id, session_index = [])
       logout_request = new
       logout_request.issuer = issuer
       logout_request.destination = sso.single_logout_services.first.location
@@ -15,10 +22,12 @@ module SAML2
       logout_request
     end
 
+    # @return [NameID]
     def name_id
       @name_id ||= (NameID.from_xml(xml.at_xpath('saml:NameID', Namespaces::ALL)) if xml)
     end
 
+    # @return [String, Array<String>]
     def session_index
       @session_index ||= (load_string_array(xml,'samlp:SessionIndex') if xml)
     end